Skip to content

Commit

Permalink
Release: NS AI Summer School
Browse files Browse the repository at this point in the history
Signed-off-by: KyleErwin <[email protected]>
  • Loading branch information
KyleErwin committed Aug 8, 2022
1 parent 02b11a2 commit a86c478
Show file tree
Hide file tree
Showing 338 changed files with 47,936 additions and 14,488 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/black.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,4 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: psf/black@stable
- uses: psf/black@stable
6 changes: 5 additions & 1 deletion .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,11 @@ jobs:
python-version: ${{ matrix.python-version }}
- name: Upgrade pip
run: python -m pip install --upgrade pip setuptools wheel
- name: Install graphviz
run: sudo apt-get install -y libgraphviz-dev
- name: Install dependencies
run: pip install -e .[test]
- name: Install dependencies
run: pip install pytest
- name: Run tests with ${{ matrix.args }}
run: pytest ${{ matrix.args }}
run: pytest ${{ matrix.args }}
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,9 @@ dmypy.json
# Pyre type checker
.pyre/

# TODO files
TODO

# tmp files
*tmp.*
___*___
Expand Down
12 changes: 12 additions & 0 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v2.3.0
hooks:
- id: check-yaml
- id: end-of-file-fixer
files: '.*\.(py|md|)'
- id: trailing-whitespace
- repo: https://github.com/psf/black
rev: 22.3.0
hooks:
- id: black
134 changes: 134 additions & 0 deletions CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@

# Contributor Covenant Code of Conduct

## Our Pledge

We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, caste, color, religion, or sexual
identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.

## Our Standards

Examples of behavior that contributes to a positive environment for our
community include:

* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
* Focusing on what is best not just for us as individuals, but for the overall
community

Examples of unacceptable behavior include:

* The use of sexualized language or imagery, and sexual attention or advances of
any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email address,
without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting

## Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.

Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.

## Scope

This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.

## Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
[INSERT CONTACT METHOD].
All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the
reporter of any incident.

## Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:

### 1. Correction

**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.

**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.

### 2. Warning

**Community Impact**: A violation through a single incident or series of
actions.

**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or permanent
ban.

### 3. Temporary Ban

**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.

**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.

### 4. Permanent Ban

**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.

**Consequence**: A permanent ban from any sort of public interaction within the
community.

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.1, available at
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].

Community Impact Guidelines were inspired by
[Mozilla's code of conduct enforcement ladder][Mozilla CoC].

For answers to common questions about this code of conduct, see the FAQ at
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
[https://www.contributor-covenant.org/translations][translations].

[homepage]: https://www.contributor-covenant.org
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
[Mozilla CoC]: https://github.com/mozilla/diversity
[FAQ]: https://www.contributor-covenant.org/faq
[translations]: https://www.contributor-covenant.org/translations

96 changes: 96 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@

# Contributing to LNN
Thank you for considering a contribution to Logical Neural Networks, with your assistance we can help grow LNNs as the industry's tool of choice for a true `Neuro = Symbolic` platform.

We commit to growing LNNs functionality, but we'd also love to see your name expanding into `x`, adding to growing our list of contributors:
```python
Contributions = Predicate("Contribution")
Growth = Propostion("LNNs Growth", world=World.TRUE)

Implies(Contributions(x), Growth)
```

## Software Setup

* Due to the complex inference pattern of LNNs upward and downward reasoning strategy, [Pycharm](https://www.jetbrains.com/pycharm/download/) is our recommended IDE of choice for development and debugging.
1. Make sure that the python version you are using corresponds with the [setup](https://github.com/IBM/LNN/blob/master/setup.py) file, using a fresh [conda]() environment is recommended:
```commandline
conda create -n lnn-contrib python=3.9 -y
conda activate lnn-contrib
```
2. Clone the `develop` branch to keep up to date with the latest supported features:
```commandline
git clone https://github.ibm.com/Naweed-Khan/LNN.git -b develop
```
3. Install the LNN module as editable and use the `develop` branch
```commandline
cd LNN
pip install -e .
```
* Install [Black](https://black.readthedocs.io/en/stable/integrations/editors.html) as an external tool/keyboard shortcut to keep to our code style - this automates our pep8 compliance so that you can code without the styling overhead
* Install and run pytest to ensure that the build is working correctly:
```commandline
pip install pytest
pytest
```
You are now ready to contribute changes to the codebase
## Developing in LNN
### Propose a New Issue
1. You want to propose a new feature and implement it.
1. Post about your intended feature in an [issue](https://github.com/IBM/LNN/issues/new), and we shall discuss the design and implementation.
2. Once we agree that the plan looks good, go ahead and implement it.
* You may also want to implement a feature or bug-fix for an outstanding issue:
* Pick an issue
* Comment that you will be working on this issue.
* Add yourself to the assignee list
If you need more context on a particular issue, please ask for guidance.
### Branching
* LNN branches should follow [git flow][git flow] style branching
[<img src="https://wac-cdn.atlassian.com/dam/jcr:34c86360-8dea-4be4-92f7-6597d4d5bfae/02%20Feature%20branches.svg?cdnVersion=296" alt="git flow"/>][git flow]
To create a new feature branch:
```commandline
git checkout develop
git checkout -b feature/my_branch
```

Please be mindful of existing branches when creating a new branch.

### Pull Requests

1. Use `Black` formatting to ensure that code contributions abide by our code style
2. Commits should contain one of the following tags before the commit message: `ADD`, `FIX`, `MAINT`
3. Run `pytest` locally to ensure all changes pass

NB: All code contributions corresponding to `enhancement` issues should have additional tests accompanying the code changes, located in the `tests/` folder.
4. Propose your code changes as a `Pull Request DRAFT` that merge into the `develop` branch.
5. A passed draft can be changed to a formal `Pull Request`.
6. Add a reviewer to your code so that they can get notified of the proposal - the individual should correspond to the those charged with the yellow tag

### Documentation

LNN documentation can be generated by running `generate_docs.sh` in [docsrc][docsrc] folder.

[docsrc]: https://github.com/IBM/LNN/tree/develop/docsrc
[git flow]: https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow

### Handling Circular Imports

A key component in the LNN code base is the `Formula` abstract class. `Formula` is a
class that refers to itself and the classes that inherit from it. As such, this can lead
to circular imports. To overcome circular imports we use dictionaries that are keyed
with the names of the subclasses and the values are the subclasses themselves. These
dictionaries are populated in the `__init__.py` of the logic module. Thus, when one
needs to work with a subclass, the subclass can be accessed by passing in the name of
that subclass to the dictionary. Note that not all classes that inherit from `Formula`
are added to these dictionaries. Please refer to `__init__.py` if you need to add an
existing class or new class to one of the dictionaries.
2 changes: 1 addition & 1 deletion LICENSE
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
Copyright (C) IBM Corporation 2018-2020
Copyright (C) IBM Corporation 2018-2022

Apache License
Version 2.0, January 2004
Expand Down
71 changes: 42 additions & 29 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,45 +1,59 @@
[![Build Status](https://github.com/IBM/LNN/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/IBM/LNN/actions/workflows/build.yml?query=branch%3Amaster)
[![License](https://img.shields.io/github/license/IBM/LNN)](https://github.com/IBM/LNN/blob/master/LICENSE)
[![License](https://img.shields.io/badge/license-Apache%202.0-blueviolet)](https://github.com/IBM/LNN/blob/master/LICENSE)
[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5926/badge)](https://bestpractices.coreinfrastructure.org/projects/5926)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

# Logical Neural Networks
LNNs are a novel `Neuro = symbolic` framework designed to seamlessly provide key
LNNs are a novel `Neuro = Symbolic` framework designed to seamlessly provide key
properties of both neural nets (learning) and symbolic logic (knowledge and reasoning).

- Every neuron has a meaning as a component of a formula in a weighted
real-valued logic, yielding a highly interpretable disentangled representation.
- Every neuron has a meaning as a component of a formula in a weighted
real-valued logic, yielding a highly interpretable disentangled representation.
- Inference is omnidirectional rather than focused on predefined target
variables, and corresponds to logical reasoning, including classical
first-order logic (FOL) theorem proving as a special case.
- The model is end-to-end differentiable, and learning minimizes a novel loss
first-order logic theorem proving as a special case.
- The model is end-to-end differentiable, and learning minimizes a novel loss
function capturing logical contradiction, yielding resilience to inconsistent
knowledge.
knowledge.
- It also enables the open-world assumption by maintaining bounds on truth values
which can have probabilistic semantics, yielding resilience to incomplete
which can have probabilistic semantics, yielding resilience to incomplete
knowledge.

## Quickstart

To install the LNN:
1. Run:
```
pip install git+https://github.com/IBM/LNN.git
```

To install the LNN with graph plot support:
1. Install [GraphViz](https://www.graphviz.org/download/)
2. Run:
```
pip install git+https://github.com/IBM/LNN.git#egg=lnn"[plot]"
```
1. Install [GraphViz](https://www.graphviz.org/download/) and gmp (libgmp3-dev)
<details><summary>Tips for errors "'gmp.h' file not found" and "'graphviz/cgraph.h' file not found" on Mac</summary><div>

## Documentation
```bash
brew install graphviz
# check the graphviz path from `brew info graphviz`
export GRAPHVIZ_DIR="/usr/local/Cellar/graphviz/3.0.0"
pip install pygraphviz --global-option=build_ext --global-option="-I$GRAPHVIZ_DIR/include" --global-option="-L$GRAPHVIZ_DIR/lib"

brew install gmp
env "CFLAGS=-I/usr/local/include -L/usr/local/lib" pip install pycddlib
```
</div></details>

2. Make sure that the python version you use in line with our [setup](https://github.com/IBM/LNN/blob/master/setup.py) file, using a fresh environment is always a good idea:
```commandline
conda create -n lnn-contrib python=3.9 -y
conda activate lnn-contrib
```
3. Install the `develop` branch to keep up to date with the latest supported features:
```commandline
pip install git+https://github.com/IBM/LNN.git@develop
```

## Contribution
Contributions to the LNN codebase are welcome!

Please have a look at the [contribution guide](https://github.com/IBM/LNN/blob/master/CONTRIBUTING.md) for more information on how to set up the LNN for contributing and how to follow our development standards.

## Documentation
| [Read the Docs][Docs] | [Academic Papers][Papers] | [Educational Resources][Education] | [Neuro-Symbolic AI][Neuro-Symbolic AI] | [API Overview][API] | [Python Module][Module] |
|:-----------------------:|:---------------------------:|:-----------------:|:----------:|:-------:|:-------:|
| [<img src=https://raw.githubusercontent.com/IBM/LNN/master/docsrc/images/icons/doc.png alt="Docs" width="60"/>][Docs] | [<img src=https://raw.githubusercontent.com/IBM/LNN/master/docsrc/images/icons/academic.png alt="Academic Papers" width="60"/>][Papers] | [<img src=https://raw.githubusercontent.com/IBM/LNN/master/docsrc/images/icons/help.png alt="Getting Started" width="60"/>][Education] | [<img src=https://raw.githubusercontent.com/IBM/LNN/master/docsrc/images/icons/nsai.png alt="Neuro-Symbolic AI" width="60"/>][Neuro-Symbolic AI] | [<img src=https://raw.githubusercontent.com/IBM/LNN/master/docsrc/images/icons/api.png alt="API" width="60"/>][API] | [<img src=https://raw.githubusercontent.com/IBM/LNN/master/docsrc/images/icons/python.png alt="Python Module" width="60"/>][Module] |


## Citation
If you use Logical Neural Networks for research, please consider citing the
reference paper:
Expand All @@ -52,10 +66,9 @@ reference paper:
}
```


[Docs]: https://ibm.github.io/LNN/
[Papers]: https://ibm.github.io/LNN/papers.html
[Education]: https://ibm.github.io/LNN/education/education.html
[API]: https://ibm.github.io/LNN/usage.html
[Module]: https://ibm.github.io/LNN/lnn/LNN.html
[Docs]: https://pages.github.com/IBM/LNN/introduction.html
[Papers]: https://pages.github.com/IBM/LNN/papers.html
[Education]: https://pages.github.com/IBM/LNN/education/education.html
[API]: https://pages.github.com/IBM/LNN/usage.html
[Module]: https://pages.github.com/IBM/LNN/lnn/LNN.html
[Neuro-Symbolic AI]: https://research.ibm.com/teams/neuro-symbolic-ai
2 changes: 1 addition & 1 deletion docs/.buildinfo
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Sphinx build info version 1
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
config: 976870eaa406da43ff4c506ff5c2007d
config: b84c77634a33cf724ade5aeb967569d8
tags: 645f666f9bcd5a90fca523b33c5a78b7
Binary file modified docs/_images/class_diagram.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_images/raining_implies_wet.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_images/symbolic_class_diagram.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit a86c478

Please sign in to comment.