diff --git a/README.md b/README.md index 2965999..e24b6ce 100644 --- a/README.md +++ b/README.md @@ -12,37 +12,37 @@ where both data and (logical) domain knowledge are available. Key Features of ABL-Package: -- **Great Flexibility**: Adaptable to a variety of machine learning modules and logical reasoning components. +- **Great Flexibility**: Adaptable to various machine learning modules and logical reasoning components. - **User-Friendly**: Provide data, model, and KB, and get started with just a few lines of code. - **High-Performance**: Optimization for high accuracy and fast training speed. ABL-Package encapsulates advanced ABL techniques, providing users with -an efficient and convenient package to develop dual-driven ABL systems -that leverage both data and knowledge. +an efficient and convenient package to develop dual-driven ABL systems, +which leverage the power of both data and knowledge. -To learn how to use it, please refer to - [document](https://www.lamda.nju.edu.cn/abl_test/docs/build/html/Overview/Abductive-Learning.html). +To learn how to use it, please refer to - [document](https://www.lamda.nju.edu.cn/abl_test/docs/build/html/index.html). ## Installation ABL is distributed on [PyPI](https://pypi.org/) and can be installed with ``pip``: ```bash - # (TODO) - $ pip install abl +# (TODO) +$ pip install abl ``` For testing purposes, you can install it using: ```bash - $ pip install -i https://test.pypi.org/simple/ --extra-index-url https://mirrors.nju.edu.cn/pypi/web/simple/ abl +$ pip install -i https://test.pypi.org/simple/ --extra-index-url https://mirrors.nju.edu.cn/pypi/web/simple/ abl ``` - + Alternatively, to install ABL by source code, sequentially run following commands in your terminal/command line. ```bash - $ git clone https://github.com/AbductiveLearning/ABL-Package.git - $ cd ABL-Package - $ pip install -v -e . +$ git clone https://github.com/AbductiveLearning/ABL-Package.git +$ cd ABL-Package +$ pip install -v -e . ``` (Optional) If the use of a [Prolog-based knowledge base](https://www.lamda.nju.edu.cn/abl_test/docs/build/html/Intro/Reasoning.html#prolog) is necessary, the installation of [Swi-Prolog](https://www.swi-prolog.org/) is also required: @@ -50,7 +50,7 @@ Alternatively, to install ABL by source code, sequentially run following command For Linux users: ```bash - $ sudo apt-get install swi-prolog +$ sudo apt-get install swi-prolog ``` For Windows and Mac users, please refer to the [Swi-Prolog Download Page](https://www.swi-prolog.org/Download.html). @@ -60,7 +60,114 @@ For Windows and Mac users, please refer to the [Swi-Prolog Download Page](https: We provide several examples in `examples/`. Each example is stored in a separate folder containing a README file. + [MNIST Addition](https://github.com/AbductiveLearning/ABL-Package/blob/Dev/examples/mnist_add) -+ [Hand Written Formula](https://github.com/AbductiveLearning/ABL-Package/blob/Dev/examples/hwf) -+ [Hand written Equation Decipherment](https://github.com/AbductiveLearning/ABL-Package/tree/Dev/examples/hed) ++ [Handwritten Formula](https://github.com/AbductiveLearning/ABL-Package/blob/Dev/examples/hwf) ++ [Handwritten Equation Decipherment](https://github.com/AbductiveLearning/ABL-Package/tree/Dev/examples/hed) + [Zoo](https://github.com/AbductiveLearning/ABL-Package/tree/Dev/examples/zoo) +## Quick Start + +We use the MNIST Addition task as a quick start example. In this task, pairs of MNIST handwritten images and their sums are given, alongwith a domain knowledge base which contain information on how to perform addition operations. Our objective is to input a pair of handwritten images and accurately determine their sum. + +### Working with Data + + +ABL-Package requires data in the format of `(X, gt_pseudo_label, Y)` where `X` is a list of input examples containing instances, `gt_pseudo_label` is the ground-truth label of each example in `X` and `Y` is the ground-truth reasoning result of each example in `X`. Note that `gt_pseudo_label` is only used to evaluate the machine learning model's performance but not to train it. + +In the MNIST Addition task, the data loading looks like: + +```python +# The 'datasets' module below is located in 'examples/mnist_add/' +from datasets import get_dataset + +# train_data and test_data are tuples in the format of (X, gt_pseudo_label, Y) +train_data = get_dataset(train=True) +test_data = get_dataset(train=False) +``` + +### Building the Learning Part + +Learning part is constructed by first defining a base model for machine learning. The ABL-Package offers considerable flexibility, supporting any base model that conforms to the scikit-learn style (which requires the implementation of fit and predict methods), or a PyTorch-based neural network (which has defined the architecture and implemented forward method). In this example, we build a simple LeNet5 network as the base model. + +```python +# The 'models' module below is located in 'examples/mnist_add/' +from models.nn import LeNet5 + +cls = LeNet5(num_classes=10) +``` + +To facilitate uniform processing, ABL-Package provides the `BasicNN` class to convert a PyTorch-based neural network into a format compatible with scikit-learn models. To construct a `BasicNN` instance, aside from the network itself, we also need to define a loss function, an optimizer, and the computing device. + +```python +​import torch +​from abl.learning import BasicNN +​ +​loss_fn = torch.nn.CrossEntropyLoss() +​optimizer = torch.optim.RMSprop(cls.parameters(), lr=0.001, alpha=0.9) +​device = torch.device("cuda" if torch.cuda.is_available() else "cpu") +​base_model = BasicNN(model=cls, loss_fn=loss_fn, optimizer=optimizer, device=device) +``` + +The base model built above are trained to make predictions on instance-level data (e.g., a single image), while ABL deals with example-level data. To bridge this gap, we wrap the base_model into an instance of `ABLModel`. This class serves as a unified wrapper for base models, facilitating the learning part to train, test, and predict on example-level data, (e.g., images that comprise an equation). + +```python +from abl.learning import ABLModel +​ +​model = ABLModel(base_model) +``` + +### Building the Reasoning Part + +To build the reasoning part, we first define a knowledge base by creating a subclass of `KBBase`. In the subclass, we initialize the `pseudo_label_list` parameter and override the `logic_forward` method, which specifies how to perform (deductive) reasoning that processes pseudo-labels of an example to the corresponding reasoning result. Specifically for the MNIST Addition task, this `logic_forward` method is tailored to execute the sum operation. + +```python +from abl.reasoning import KBBase +​ +class AddKB(KBBase): + def __init__(self, pseudo_label_list=list(range(10))): + super().__init__(pseudo_label_list) + +​ def logic_forward(self, nums): + return sum(nums) +​ +kb = AddKB() +``` + +Next, we create a reasoner by instantiating the class `Reasoner`, passing the knowledge base as a parameter. Due to the indeterminism of abductive reasoning, there could be multiple candidate pseudo-labels compatible to the knowledge base. In such scenarios, the reasoner can minimize inconsistency and return the pseudo-label with the highest consistency. + +```python +from abl.reasoning import Reasoner +​ +reasoner = Reasoner(kb) +``` + +### Building Evaluation Metrics + +ABL-Package provides two basic metrics, namely `SymbolAccuracy` and `ReasoningMetric`, which are used to evaluate the accuracy of the machine learning model's predictions and the accuracy of the `logic_forward` results, respectively. + +```python +from abl.data.evaluation import ReasoningMetric, SymbolAccuracy +​ +metric_list = [SymbolAccuracy(), ReasoningMetric(kb=kb)] +``` + +### Bridging Learning and Reasoning + +Now, we use `SimpleBridge` to combine learning and reasoning in a +unified ABL framework. + +```python +from abl.bridge import SimpleBridge +​ +bridge = SimpleBridge(model, reasoner, metric_list) +``` + +Finally, we proceed with training and testing. + +```python +​bridge.train(train_data, loops=1, segment_size=0.01) +bridge.test(test_data) +``` + +## References + +For more information about ABL, please refer to: [Zhou, 2019](https://link.springer.com/epdf/10.1007/s11432-018-9801-4?author_access_token=jgJe1Ox3Mk-K7ORSnX7jtfe4RwlQNchNByi7wbcMAY7_PxTx-xNLP7Lp0mIZ04ORp3VG4wioIBHSCIAO3B_TBJkj87YzapmdnYVSQvgBIO3aEpQWppxZG25KolINetygc2W_Cj2gtoBdiG_J1hU3pA==) and [Zhou and Huang, 2022](https://www.lamda.nju.edu.cn/publication/chap_ABL.pdf). \ No newline at end of file diff --git a/docs/Examples/MNISTAdd.rst b/docs/Examples/MNISTAdd.rst index c038349..c05fd85 100644 --- a/docs/Examples/MNISTAdd.rst +++ b/docs/Examples/MNISTAdd.rst @@ -376,6 +376,6 @@ Out: abl - INFO - Eval start: loop(val) [1] abl - INFO - Evaluation ended, mnist_add/character_accuracy: 0.986 mnist_add/reasoning_accuracy: 0.973 abl - INFO - Saving model: loop(save) [1] - abl - INFO - Checkpoints will be saved to results/20231222_22_25_07/weights/model_checkpoint_loop_1.pth + abl - INFO - Checkpoints will be saved to log_dir/weights/model_checkpoint_loop_1.pth abl - INFO - Test start: abl - INFO - Evaluation ended, mnist_add/character_accuracy: 0.983 mnist_add/reasoning_accuracy: 0.967 diff --git a/docs/Intro/Quick-Start.rst b/docs/Intro/Quick-Start.rst index 58b4745..658e0ba 100644 --- a/docs/Intro/Quick-Start.rst +++ b/docs/Intro/Quick-Start.rst @@ -15,32 +15,32 @@ Working with Data ----------------- ABL-Package requires data in the format of ``(X, gt_pseudo_label, Y)`` where ``X`` is a list of input examples containing instances, -``gt_pseudo_label`` is the ground-truth label of each example in ``X`` and ``Y`` is the ground-truth reasoning result of each example in ``X``. Note that ``gt_pseudo_label`` is only used to evaluate the machine learning model's performance but not to train it. If examples in ``X`` are unlabeled, ``gt_pseudo_label`` should be ``None``. +``gt_pseudo_label`` is the ground-truth label of each example in ``X`` and ``Y`` is the ground-truth reasoning result of each example in ``X``. Note that ``gt_pseudo_label`` is only used to evaluate the machine learning model's performance but not to train it. In the MNIST Addition task, the data loading looks like .. code:: python + # The 'datasets' module below is located in 'examples/mnist_add/' from datasets import get_dataset - # train_data and test_data are tuples in the format (X, gt_pseudo_label, Y) - # If get_pseudo_label is set to False, the gt_pseudo_label in each tuple will be None. - train_data = get_dataset(train=True, get_pseudo_label=True) - test_data = get_dataset(train=False, get_pseudo_label=True) + # train_data and test_data are tuples in the format of (X, gt_pseudo_label, Y) + train_data = get_dataset(train=True) + test_data = get_dataset(train=False) Read more about `preparing datasets `_. Building the Learning Part -------------------------- -Learnig part is constructed by first defining a base model for machine learning. The ABL-Package offers considerable flexibility, supporting any base model that conforms to the scikit-learn style (which requires the implementation of ``fit`` and ``predict`` methods), or a PyTorch-based neural network (which has defined the architecture and implemented ``forward`` method). +Learning part is constructed by first defining a base model for machine learning. The ABL-Package offers considerable flexibility, supporting any base model that conforms to the scikit-learn style (which requires the implementation of ``fit`` and ``predict`` methods), or a PyTorch-based neural network (which has defined the architecture and implemented ``forward`` method). In this example, we build a simple LeNet5 network as the base model. .. code:: python + # The 'models' module below is located in 'examples/mnist_add/' from models.nn import LeNet5 - # The number of pseudo-labels is 10 cls = LeNet5(num_classes=10) To facilitate uniform processing, ABL-Package provides the ``BasicNN`` class to convert a PyTorch-based neural network into a format compatible with scikit-learn models. To construct a ``BasicNN`` instance, aside from the network itself, we also need to define a loss function, an optimizer, and the computing device. @@ -51,7 +51,7 @@ To facilitate uniform processing, ABL-Package provides the ``BasicNN`` class to from abl.learning import BasicNN loss_fn = torch.nn.CrossEntropyLoss() - optimizer = torch.optim.RMSprop(cls.parameters(), lr=0.001, alpha=0.9) + optimizer = torch.optim.RMSprop(cls.parameters(), lr=0.001) device = torch.device("cuda" if torch.cuda.is_available() else "cpu") base_model = BasicNN(model=cls, loss_fn=loss_fn, optimizer=optimizer, device=device) @@ -104,7 +104,7 @@ ABL-Package provides two basic metrics, namely ``SymbolAccuracy`` and ``Reasonin from abl.data.evaluation import ReasoningMetric, SymbolAccuracy - metric_list = [SymbolAccuracy(prefix="mnist_add"), ReasoningMetric(kb=kb, prefix="mnist_add")] + metric_list = [SymbolAccuracy(), ReasoningMetric(kb=kb)] Read more about `building evaluation metrics `_ diff --git a/docs/README.rst b/docs/README.rst index 1287302..09280d0 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -8,13 +8,13 @@ where both data and (logical) domain knowledge are available. Key Features of ABL-Package: -- **Great Flexibility**: Adaptable to a variety of machine learning modules and logical reasoning components. +- **Great Flexibility**: Adaptable to various machine learning modules and logical reasoning components. - **User-Friendly**: Provide data, model, and KB, and get started with just a few lines of code. - **High-Performance**: Optimization for high accuracy and fast training speed. ABL-Package encapsulates advanced ABL techniques, providing users with -an efficient and convenient package to develop dual-driven ABL systems -that leverage both data and knowledge. +an efficient and convenient package to develop dual-driven ABL systems, +which leverage the power of both data and knowledge. .. image:: _static/img/ABL.png @@ -52,3 +52,9 @@ For Linux users: $ sudo apt-get install swi-prolog For Windows and Mac users, please refer to the `Swi-Prolog Download Page `_. + +References +---------- + +For more information about ABL, please refer to: `Zhou, 2019 `_ +and `Zhou and Huang, 2022 `_. \ No newline at end of file diff --git a/examples/hed/main.py b/examples/hed/main.py index c672765..f4e7564 100644 --- a/examples/hed/main.py +++ b/examples/hed/main.py @@ -35,12 +35,12 @@ def main(): "--batch-size", type=int, default=32, help="base model batch size (default : 32)" ) parser.add_argument( - "--segment_size", type=int or float, default=1000, help="segment size (default : 1000)" + "--segment_size", type=int, default=1000, help="segment size (default : 1000)" ) parser.add_argument("--save_interval", type=int, default=1, help="save interval (default : 1)") parser.add_argument( "--max-revision", - type=int or float, + type=int, default=10, help="maximum revision in reasoner (default : 10)", ) diff --git a/examples/hwf/main.py b/examples/hwf/main.py index 328e849..963fa15 100644 --- a/examples/hwf/main.py +++ b/examples/hwf/main.py @@ -87,19 +87,19 @@ def main(): "--loops", type=int, default=5, help="number of loop iterations (default : 5)" ) parser.add_argument( - "--segment_size", type=int or float, default=1000, help="segment size (default : 1000)" + "--segment_size", type=int, default=1000, help="segment size (default : 1000)" ) parser.add_argument("--save_interval", type=int, default=1, help="save interval (default : 1)") parser.add_argument( "--max-revision", - type=int or float, + type=int, default=-1, help="maximum revision in reasoner (default : -1)", ) parser.add_argument( "--require-more-revision", type=int, - default=5, + default=0, help="require more revision in reasoner (default : 0)", ) parser.add_argument( diff --git a/examples/mnist_add/datasets/get_dataset.py b/examples/mnist_add/datasets/get_dataset.py index c6d84a9..53423da 100644 --- a/examples/mnist_add/datasets/get_dataset.py +++ b/examples/mnist_add/datasets/get_dataset.py @@ -5,7 +5,7 @@ from torchvision.transforms import transforms CURRENT_DIR = os.path.abspath(os.path.dirname(__file__)) -def get_dataset(train=True, get_pseudo_label=False): +def get_dataset(train=True, get_pseudo_label=True): transform = transforms.Compose( [transforms.ToTensor(), transforms.Normalize((0.1307,), (0.3081,))] ) diff --git a/examples/mnist_add/main.py b/examples/mnist_add/main.py index ab1fa98..b74b82e 100644 --- a/examples/mnist_add/main.py +++ b/examples/mnist_add/main.py @@ -53,12 +53,12 @@ def main(): "--loops", type=int, default=2, help="number of loop iterations (default : 2)" ) parser.add_argument( - "--segment_size", type=int or float, default=0.01, help="segment size (default : 0.01)" + "--segment_size", type=int, default=0.01, help="segment size (default : 0.01)" ) parser.add_argument("--save_interval", type=int, default=1, help="save interval (default : 1)") parser.add_argument( "--max-revision", - type=int or float, + type=int, default=-1, help="maximum revision in reasoner (default : -1)", )