diff --git a/docs/Overview/Abductive Learning.rst b/docs/Overview/Abductive Learning.rst
index 9a4e4dc..0bdf87c 100644
--- a/docs/Overview/Abductive Learning.rst
+++ b/docs/Overview/Abductive Learning.rst
@@ -51,6 +51,7 @@ base.
The following figure illustrates this process:
.. image:: ../img/ABL.jpg
+ :width: 800px
We can observe that in the above figure, the left half involves machine
learning, while the right half involves logical reasoning. Thus, the
@@ -78,5 +79,5 @@ consequence of :math:`a`, while abductive reasoning allows inferring
:math:`a` as an explanation of :math:`b` (as a result of this inference,
abduction allows the precondition :math:`a` to be abducted from the
consequence :math:`b`). Put simply, deductive reasoning and abductive
-reasoning differ in which end, left or right, of the proposition
+reasoning differ in which end, right or left, of the proposition
“:math:`a\models b`” serves as conclusion.
diff --git a/docs/Overview/Installation.rst b/docs/Overview/Installation.rst
index 36d7c95..1cea0a1 100644
--- a/docs/Overview/Installation.rst
+++ b/docs/Overview/Installation.rst
@@ -1,19 +1,17 @@
Installation
==================
-Case a: If you develop and run ``abl`` directly, install it from source:
+ABL is distributed on `PyPI `__ and can be installed with ``pip``:
-.. code-block:: bash
+.. code:: console
- git clone https://github.com/AbductiveLearning/ABL-Package.git
- cd ABL-Package
- pip install -v -e .
- # "-v" means verbose, or more output
- # "-e" means installing a project in editable mode,
- # thus any local modifications made to the code will take effect without reinstallation.
+ $ pip install abl
-Case b: If you use ``abl`` as a dependency or third-party package, install it with pip:
+Alternatively, to install ABL by source code,
+sequentially run following commands in your terminal/command line.
-.. code-block:: bash
+.. code:: console
- pip install abl
+ $ git clone https://github.com/AbductiveLearning/ABL-Package.git
+ $ cd ABL-Package
+ $ pip install -v -e .
diff --git a/docs/Overview/Quick Start.rst b/docs/Overview/Quick Start.rst
index 726b523..c6dc2cc 100644
--- a/docs/Overview/Quick Start.rst
+++ b/docs/Overview/Quick Start.rst
@@ -1,83 +1,105 @@
Quick Start
-==================
+===========
-We use the MNIST Add benchmark as a quick start example.
+We use the MNIST Add benchmark as a quick start example. In this task, the inputs are
+pairs of MNIST handwritten images, and the outputs are their sums.
+To complete this task, we first process the images through a machine learning model
+to get their corresponding pseudo labels (the number each image represents).
+Then, the recognized labels undergo logical reasoning which calculates their sum.
+
+Load Data
+---------
+
+ABL-Package assumes data to be in the form of ``(X, gt_pseudo_label, Y)``
+where ``X`` is the input of the machine learning model,
+``Y`` is the ground truth of the reasoning result and
+``gt_pseudo_label`` is the ground truth label of each element in ``X``.
+
+.. code:: python
+
+ from examples.mnist_add.datasets.get_mnist_add import get_mnist_add
+
+ train_data = get_mnist_add(train=True, get_pseudo_label=True)
+ test_data = get_mnist_add(train=False, get_pseudo_label=True)
+
+In the above ``get_mnist_add``, the return values are tuples of ``(X, gt_pseudo_label, Y)``.
+
+Machine Learning (Map input to pseudo labels)
+---------------------------------------------
+
+We use a simple LeNet5 model to recognize the pseudo labels (numbers) in the images.
+We first build the model and define its corresponding criterion and optimizer for training.
.. code:: python
import torch
import torch.nn as nn
-
- from abl.bridge import SimpleBridge
- from abl.evaluation import SemanticsMetric, SymbolMetric
- from abl.learning import ABLModel, BasicNN
- from abl.reasoning import KBBase, ReasonerBase
- from abl.utils import print_log
- from examples.mnist_add.datasets.get_mnist_add import get_mnist_add
from examples.models.nn import LeNet5
- # Build logger
- print_log("Abductive Learning on the MNIST Add example.", logger="current")
-
- # Machine Learning Part
- # Build necessary components for BasicNN
cls = LeNet5(num_classes=10)
criterion = nn.CrossEntropyLoss()
optimizer = torch.optim.Adam(cls.parameters(), lr=0.001, betas=(0.9, 0.99))
device = torch.device("cuda:0" if torch.cuda.is_available() else "cpu")
- # Build BasicNN
+
+Afterward, we wrap it in ``ABLModel``.
+
+.. code:: python
+
+ from abl.learning import ABLModel, BasicNN
+
base_model = BasicNN(cls, criterion, optimizer, device)
- # Build ABLModel
model = ABLModel(base_model)
- # Logic Part
- # Build knowledge base and reasoner
+Reasoning (Map pseudo labels to reasoning results)
+--------------------------------------------------
+
+First, we build a knowledge base that defines how to deduce
+logical results (i.e., calculate summation) from the pseudo labels
+obtained by machine learning.
+
+.. code:: python
+
+ from abl.reasoning import KBBase, ReasonerBase
+
class AddKB(KBBase):
- def __init__(self, pseudo_label_list):
+ def __init__(self, pseudo_label_list=list(range(10))):
super().__init__(pseudo_label_list)
- # Implement the deduction function
def logic_forward(self, nums):
return sum(nums)
kb = AddKB(pseudo_label_list=list(range(10)))
+
+Then we define a reasoner, which defines
+how to minimize the inconsistency between the knowledge base and machine learning.
+
+.. code:: python
+
reasoner = ReasonerBase(kb, dist_func="confidence")
- # Datasets and Evaluation Metrics
- # Get training and testing data
- train_data = get_mnist_add(train=True, get_pseudo_label=True)
- test_data = get_mnist_add(train=False, get_pseudo_label=True)
- # Set up metrics
+Bridge Machine Learning and Reasoning
+-------------------------------------
+
+First, we use `SimpleBridge` to combine machine learning and reasoning together,
+setting the stage for subsequent integrated training, validation, and testing.
+
+.. code:: python
+
+ from abl.bridge import SimpleBridge
+
+
+Next, we define the metrics to measure accuracy during validation and testing.
+
+.. code:: python
+
+ from abl.evaluation import SemanticsMetric, SymbolMetric
+
metric_list = [SymbolMetric(prefix="mnist_add"), SemanticsMetric(kb=kb, prefix="mnist_add")]
- # Bridge Machine Learning and Logic Reasoning
- bridge = SimpleBridge(model, reasoner, metric_list)
+Finally, we proceed with testing and training.
+
+.. code:: python
- # Train and Test
bridge.train(train_data, loops=5, segment_size=10000)
bridge.test(test_data)
-
-
-Training log would be similar to this:
-
-.. code:: text
-
- 2023/11/29 23:14:17 - abl - INFO - Abductive Learning on the MNIST Add example.
- 2023/11/29 23:14:42 - abl - INFO - loop(train) [1/5] segment(train) [1/3] model loss is 1.86793
- 2023/11/29 23:14:44 - abl - INFO - loop(train) [1/5] segment(train) [2/3] model loss is 1.48877
- 2023/11/29 23:14:46 - abl - INFO - loop(train) [1/5] segment(train) [3/3] model loss is 1.26435
- 2023/11/29 23:14:46 - abl - INFO - Evaluation start: loop(val) [1]
- 2023/11/29 23:14:47 - abl - INFO - Evaluation ended, mnist_add/character_accuracy: 0.334 mnist_add/semantics_accuracy: 0.190
- 2023/11/29 23:14:49 - abl - INFO - loop(train) [2/5] segment(train) [1/3] model loss is 1.06395
- 2023/11/29 23:14:51 - abl - INFO - loop(train) [2/5] segment(train) [2/3] model loss is 0.78799
- 2023/11/29 23:14:53 - abl - INFO - loop(train) [2/5] segment(train) [3/3] model loss is 0.33641
- 2023/11/29 23:14:53 - abl - INFO - Evaluation start: loop(val) [2]
- 2023/11/29 23:14:54 - abl - INFO - Evaluation ended, mnist_add/character_accuracy: 0.963 mnist_add/semantics_accuracy: 0.926
- ...
- 2023/11/29 23:15:08 - abl - INFO - loop(train) [5/5] segment(train) [1/3] model loss is 0.04223
- 2023/11/29 23:15:10 - abl - INFO - loop(train) [5/5] segment(train) [2/3] model loss is 0.03444
- 2023/11/29 23:15:12 - abl - INFO - loop(train) [5/5] segment(train) [3/3] model loss is 0.03274
- 2023/11/29 23:15:12 - abl - INFO - Evaluation start: loop(val) [5]
- 2023/11/29 23:15:13 - abl - INFO - Evaluation ended, mnist_add/character_accuracy: 0.991 mnist_add/semantics_accuracy: 0.983
- 2023/11/29 23:15:13 - abl - INFO - Evaluation ended, mnist_add/character_accuracy: 0.985 mnist_add/semantics_accuracy: 0.970
diff --git a/docs/Brief-Introduction/Usage.rst b/docs/Overview/Usage.rst
similarity index 99%
rename from docs/Brief-Introduction/Usage.rst
rename to docs/Overview/Usage.rst
index fd6e76c..f57fe76 100644
--- a/docs/Brief-Introduction/Usage.rst
+++ b/docs/Overview/Usage.rst
@@ -10,7 +10,7 @@ Using ABL-Package for your learning tasks contains five steps
- Use ``Bridge.train`` and ``Bridge.test`` to train and test
Build the machine learning part
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------
First, we build the machine learning part, which needs to be wrapped in the ``ABLModel`` class. We can use machine learning models from scikit-learn or based on PyTorch to create an instance of ``ABLModel``.
@@ -58,7 +58,7 @@ In the MNIST Add example, the machine learning model looks like
model = ABLModel(base_model)
Build the reasoning part
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
Next, we build the reasoning part. In ABL-Package, the reasoning part is wrapped in the ``ReasonerBase`` class. In order to create an instance of this class, we first need to inherit the ``KBBase`` class to customize our knowledge base. Arguments of the ``__init__`` method of the knowledge base should at least contain ``pseudo_label_list`` which is a list of all pseudo labels. The ``logic_forward`` method of ``KBBase`` is an abstract method and we need to instantiate this method in our sub-class to give the ability of deduction to the knowledge base. In general, we can customize our knowledge base by
diff --git a/docs/README.rst b/docs/README.rst
index 1e18c4a..b9344ad 100644
--- a/docs/README.rst
+++ b/docs/README.rst
@@ -13,19 +13,20 @@ model.
Installation
------------
-ABL is distributed on PyPI and can be installed with ``pip``:
+ABL is distributed on `PyPI `__ and can be installed with ``pip``:
.. code:: console
$ pip install abl
-Alternatively, to install ABL by source code, download this project and
+Alternatively, to install ABL by source code,
sequentially run following commands in your terminal/command line.
.. code:: console
- $ python setup.py build
- $ python setup.py install
+ $ git clone https://github.com/AbductiveLearning/ABL-Package.git
+ $ cd ABL-Package
+ $ pip install -v -e .
Releases
diff --git a/docs/index.rst b/docs/index.rst
index 57179ba..ea17e54 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -7,13 +7,7 @@
Overview/Abductive Learning
Overview/Installation
Overview/Quick Start
-
-.. toctree::
- :maxdepth: 1
- :caption: A Brief Introduction
-
- Brief-Introduction/Components
- Brief-Introduction/Usage
+ Overview/Usage
.. toctree::
:maxdepth: 1