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