[DOC] revise quick start

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.

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 <https://pypi.org/>`__ 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 .

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 

docs/Brief-Introduction/Usage.rst → 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
 

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 <https://pypi.org/>`__ 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

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