From 67fcac93d66e6e7749d4dbf57b2a669c0feab898 Mon Sep 17 00:00:00 2001 From: troyyyyy Date: Thu, 28 Dec 2023 09:13:57 +0800 Subject: [PATCH] [ENH] add quick start in readme --- README.md | 120 ++++++++++++++++++++++++++++++++++--- docs/Intro/Quick-Start.rst | 11 ++-- 2 files changed, 118 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 2965999..95a01e5 100644 --- a/README.md +++ b/README.md @@ -27,22 +27,22 @@ To learn how to use it, please refer to - [document](https://www.lamda.nju.edu.c 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). @@ -64,3 +64,107 @@ We provide several examples in `examples/`. Each example is stored in a separate + [Hand written Equation Decipherment](https://github.com/AbductiveLearning/ABL-Package/tree/Dev/examples/hed) + [Zoo](https://github.com/AbductiveLearning/ABL-Package/tree/Dev/examples/zoo) +## A Simple Example + +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 (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) +``` + +### 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(prefix="mnist_add"), ReasoningMetric(kb=kb, prefix="mnist_add")] +``` + +### 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) +bridge.test(test_data) +``` \ No newline at end of file diff --git a/docs/Intro/Quick-Start.rst b/docs/Intro/Quick-Start.rst index 58b4745..a186371 100644 --- a/docs/Intro/Quick-Start.rst +++ b/docs/Intro/Quick-Start.rst @@ -15,12 +15,13 @@ 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) @@ -33,14 +34,14 @@ 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 +52,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) @@ -123,7 +124,7 @@ Finally, we proceed with training and testing. .. code:: python - bridge.train(train_data, loops=1, segment_size=0.01) + bridge.train(train_data, loops=1) bridge.test(test_data) Read more about `bridging machine learning and reasoning `_.