[ENH] add hwf example

docs/Examples/HWF.rst

@@ -1,5 +1,467 @@
 Handwritten Formula (HWF)
 =========================
 
-.. contents:: Table of Contents
+Below shows an implementation of `Handwritten
+Formula <https://arxiv.org/abs/2006.06649>`__. In this task. In this
+task, handwritten images of decimal formulas and their computed results
+are given, alongwith a domain knowledge base containing information on
+how to compute the decimal formula. The task is to recognize the symbols
+(which can be digits or operators ‘+’, ‘-’, ‘×’, ‘÷’) of handwritten
+images and accurately determine their results.
 
+Intuitively, we first use a machine learning model (learning part) to
+convert the input images to symbols (we call them pseudo-labels), and
+then use the knowledge base (reasoning part) to calculate the results of
+these symbols. Since we do not have ground-truth of the symbols, in
+Abductive Learning, the reasoning part will leverage domain knowledge
+and revise the initial symbols yielded by the learning part through
+abductive reasoning. This process enables us to further update the
+machine learning model.
+
+.. code:: ipython3
+
+    # Import necessary libraries and modules
+    import os.path as osp
+    import numpy as np
+    import torch
+    import torch.nn as nn
+    import matplotlib.pyplot as plt
+    from examples.hwf.datasets import get_dataset
+    from examples.models.nn import SymbolNet
+    from abl.learning import ABLModel, BasicNN
+    from abl.reasoning import KBBase, Reasoner
+    from abl.evaluation import ReasoningMetric, SymbolMetric
+    from abl.utils import ABLLogger, print_log
+    from abl.bridge import SimpleBridge
+
+Working with Data
+-----------------
+
+First, we get the training and testing datasets:
+
+.. code:: ipython3
+
+    train_data = get_dataset(train=True, get_pseudo_label=True)
+    test_data = get_dataset(train=False, get_pseudo_label=True)
+
+Both ``train_data`` and ``test_data`` have the same structures: tuples
+with three components: X (list where each element is a list of images),
+gt_pseudo_label (list where each element is a list of symbols, i.e.,
+pseudo-labels) and Y (list where each element is the computed result).
+The length and structures of datasets are illustrated as follows.
+
+.. note::
+
+    ``gt_pseudo_label`` is only used to evaluate the performance of
+    the learning part but not to train the model.
+
+.. code:: ipython3
+
+    print(f"Both train_data and test_data consist of 3 components: X, gt_pseudo_label, Y")
+    print()
+    train_X, train_gt_pseudo_label, train_Y = train_data
+    print(f"Length of X, gt_pseudo_label, Y in train_data: " +
+          f"{len(train_X)}, {len(train_gt_pseudo_label)}, {len(train_Y)}")
+    test_X, test_gt_pseudo_label, test_Y = test_data
+    print(f"Length of X, gt_pseudo_label, Y in test_data: " +
+          f"{len(test_X)}, {len(test_gt_pseudo_label)}, {len(test_Y)}")
+    print()
+    
+    X_0, gt_pseudo_label_0, Y_0 = train_X[0], train_gt_pseudo_label[0], train_Y[0]
+    print(f"X is a {type(train_X).__name__}, " +
+          f"with each element being a {type(X_0).__name__} of {type(X_0[0]).__name__}.")
+    print(f"gt_pseudo_label is a {type(train_gt_pseudo_label).__name__}, " +
+          f"with each element being a {type(gt_pseudo_label_0).__name__} " +
+          f"of {type(gt_pseudo_label_0[0]).__name__}.")
+    print(f"Y is a {type(train_Y).__name__}, " +
+          f"with each element being a {type(Y_0).__name__}.")
+
+
+Out:
+    .. code:: none
+        :class: code-out
+
+        Both train_data and test_data consist of 3 components: X, gt_pseudo_label, Y
+        
+        Length of X, gt_pseudo_label, Y in train_data: 10000, 10000, 10000
+        Length of X, gt_pseudo_label, Y in test_data: 2000, 2000, 2000
+        
+        X is a list, with each element being a list of Tensor.
+        gt_pseudo_label is a list, with each element being a list of str.
+        Y is a list, with each element being a int.
+    
+
+The ith element of X, gt_pseudo_label, and Y together constitute the ith
+data example. Here we use two of them (the 1001st and the 3001st) as
+illstrations:
+
+.. code:: ipython3
+
+    X_1000, gt_pseudo_label_1000, Y_1000 = train_X[1000], train_gt_pseudo_label[1000], train_Y[1000]
+    print(f"X in the 1001st data example (a list of images):")
+    for i, x in enumerate(X_1000):
+        plt.subplot(1, len(X_1000), i+1)
+        plt.axis('off') 
+        plt.imshow(x.numpy().transpose(1, 2, 0))
+    plt.show()
+    print(f"gt_pseudo_label in the 1001st data example (a list of pseudo-labels): {gt_pseudo_label_1000}")
+    print(f"Y in the 1001st data example (the computed result): {Y_1000}")
+    print()
+    X_3000, gt_pseudo_label_3000, Y_3000 = train_X[3000], train_gt_pseudo_label[3000], train_Y[3000]
+    print(f"X in the 3001st data example (a list of images):")
+    for i, x in enumerate(X_3000):
+        plt.subplot(1, len(X_3000), i+1)
+        plt.axis('off') 
+        plt.imshow(x.numpy().transpose(1, 2, 0))
+    plt.show()
+    print(f"gt_pseudo_label in the 3001st data example (a list of pseudo-labels): {gt_pseudo_label_3000}")
+    print(f"Y in the 3001st data example (the computed result): {Y_3000}")
+
+
+Out:
+    .. code:: none
+        :class: code-out
+
+        X in the 1001st data example (a list of images):
+    
+    .. image:: ../img/hwf_dataset1.png
+        :width: 300px
+
+    .. code:: none
+        :class: code-out
+
+        gt_pseudo_label in the 1001st data example (a list of pseudo-labels): ['5', '-', '3']
+        Y in the 1001st data example (the computed result): 2
+    
+    .. code:: none
+        :class: code-out
+
+        X in the 3001st data example (a list of images):
+    
+    .. image:: ../img/hwf_dataset2.png
+        :width: 500px
+
+    .. code:: none
+        :class: code-out
+
+        gt_pseudo_label in the 3001st data example (a list of pseudo-labels): ['4', '/', '6', '*', '5']
+        Y in the 3001st data example (the computed result): 3.333333333333333
+    
+
+.. note::
+
+    The symbols in the HWF dataset can be one of digits or operators
+    '+', '-', '×', '÷'.
+
+    We may see that, in the 1001st data example, the length of the
+    formula is 3, while in the 3001st data example, the length of the
+    formula is 5. In the HWF dataset, the length of the formula varies from
+    1 to 7.
+
+Building the Learning Part
+--------------------------
+
+To build the learning part, we need to first build a machine learning
+base model. We use SymbolNet, and encapsulate it within a ``BasicNN``
+object to create the base model. ``BasicNN`` is a class that
+encapsulates a PyTorch model, transforming it into a base model with an
+sklearn-style interface.
+
+.. code:: ipython3
+
+    # class of symbol may be one of ['0', '1', ..., '9', '+', '-', '*', '/'], total of 14 classes
+    cls = SymbolNet(num_classes=14, image_size=(45, 45, 1))
+    loss_fn = 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")
+    
+    base_model = BasicNN(
+        model=cls,
+        loss_fn=loss_fn,
+        optimizer=optimizer,
+        device=device,
+        batch_size=128,
+        num_epochs=3,
+    )
+
+``BasicNN`` offers methods like ``predict`` and ``predict_prob``, which
+are used to predict the class index and the probabilities of each class
+for images. As shown below:
+
+.. code:: ipython3
+
+    data_instances = [torch.randn(1, 45, 45).to(device) for _ in range(32)]
+    pred_idx = base_model.predict(X=data_instances)
+    print(f"Predicted class index for a batch of 32 instances: " +
+          f"{type(pred_idx).__name__} with shape {pred_idx.shape}")
+    pred_prob = base_model.predict_proba(X=data_instances)
+    print(f"Predicted class probabilities for a batch of 32 instances: " +
+          f"{type(pred_prob).__name__} with shape {pred_prob.shape}")
+
+
+Out:
+    .. code:: none
+        :class: code-out
+
+        Predicted class index for a batch of 32 instances: ndarray with shape (32,)
+        Predicted class probabilities for a batch of 32 instances: ndarray with shape (32, 14)
+    
+
+However, the base model built above deals with instance-level data
+(i.e., individual images), and can not directly deal with example-level
+data (i.e., a list of images comprising the formula). Therefore, we wrap
+the base model into ``ABLModel``, which enables the learning part to
+train, test, and predict on example-level data.
+
+.. code:: ipython3
+
+    model = ABLModel(base_model)
+
+As an illustration, consider this example of training on example-level
+data using the ``predict`` method in ``ABLModel``. In this process, the
+method accepts data examples as input and outputs the class labels and
+the probabilities of each class for all instances within these data
+examples.
+
+.. code:: ipython3
+
+    from abl.structures import ListData
+    # ListData is a data structure provided by ABL-Package that can be used to organize data examples
+    data_examples = ListData()
+    # We use the first 1001st and 3001st data examples in the training set as an illustration
+    data_examples.X = [X_1000, X_3000]
+    data_examples.gt_pseudo_label = [gt_pseudo_label_1000, gt_pseudo_label_3000]
+    data_examples.Y = [Y_1000, Y_3000]
+    
+    # Perform prediction on the two data examples
+    # Remind that, in the 1001st data example, the length of the formula is 3, 
+    # while in the 3001st data example, the length of the formula is 5.
+    pred_label, pred_prob = model.predict(data_examples)['label'], model.predict(data_examples)['prob']
+    print(f"Predicted class labels for the 100 data examples: a list of length {len(pred_label)}, \n" +
+          f"the first element is a {type(pred_label[0]).__name__} of shape {pred_label[0].shape}, "+
+          f"and the second element is a {type(pred_label[1]).__name__} of shape {pred_label[1].shape}.\n")
+    print(f"Predicted class probabilities for the 100 data examples: a list of length {len(pred_prob)}, \n"
+          f"the first element is a {type(pred_prob[0]).__name__} of shape {pred_prob[0].shape}, " +
+          f"and the second element is a {type(pred_prob[1]).__name__} of shape {pred_prob[1].shape}.")
+
+
+Out:
+    .. code:: none
+        :class: code-out
+
+        Predicted class labels for the 100 data examples: a list of length 2, 
+        the first element is a ndarray of shape (3,), and the second element is a ndarray of shape (5,).
+        
+        Predicted class probabilities for the 100 data examples: a list of length 2, 
+        the first element is a ndarray of shape (3, 14), and the second element is a ndarray of shape (5, 14).
+    
+
+Building the Reasoning Part
+---------------------------
+
+In the reasoning part, we first build a knowledge base which contain
+information on how to perform addition operations. We build it by
+creating a subclass of ``KBBase``. In the derived subclass, we
+initialize the ``pseudo_label_list`` parameter specifying list of
+possible pseudo-labels, and override the ``logic_forward`` function
+defining how to perform (deductive) reasoning.
+
+.. code:: ipython3
+
+    class HwfKB(KBBase):
+        def __init__(self, pseudo_label_list=["1", "2", "3", "4", "5", "6", "7", "8", "9", "+", "-", "*", "/"]):
+            super().__init__(pseudo_label_list)
+    
+        def _valid_candidate(self, formula):
+            if len(formula) % 2 == 0:
+                return False
+            for i in range(len(formula)):
+                if i % 2 == 0 and formula[i] not in ["1", "2", "3", "4", "5", "6", "7", "8", "9"]:
+                    return False
+                if i % 2 != 0 and formula[i] not in ["+", "-", "*", "/"]:
+                    return False
+            return True
+        
+        # Implement the deduction function
+        def logic_forward(self, formula):
+            if not self._valid_candidate(formula):
+                return np.inf
+            return eval("".join(formula))
+    
+    kb = HwfKB()
+
+The knowledge base can perform logical reasoning (both deductive
+reasoning and abductive reasoning). Below is an example of performing
+(deductive) reasoning, and users can refer to :ref:`Performing abductive 
+reasoning in the knowledge base <kb-abd>` for details of abductive reasoning.
+
+.. code:: ipython3
+
+    pseudo_label_example = ["1", "-", "2", "*", "5"]
+    reasoning_result = kb.logic_forward(pseudo_label_example)
+    print(f"Reasoning result of pseudo-label example {pseudo_label_example} is {reasoning_result}.")
+
+
+Out:
+    .. code:: none
+        :class: code-out
+
+        Reasoning result of pseudo-label example ['1', '-', '2', '*', '5'] is -9.
+    
+
+.. note::
+
+    In addition to building a knowledge base based on ``KBBase``, we
+    can also establish a knowledge base with a ground KB using ``GroundKB``.
+    The corresponding code can be found in the ``examples/hwf/main.py`` file. Those
+    interested are encouraged to examine it for further insights.
+
+    Also, when building the knowledge base, we can also set the
+    ``max_err`` parameter during initialization, which is shown in the
+    ``examples/hwf/main.py`` file. This parameter specifies the upper tolerance limit
+    when comparing the similarity between a pseudo-label example’s reasoning
+    result and the ground truth during abductive reasoning, with a default
+    value of 1e-10.
+
+Then, we create a reasoner by instantiating the class ``Reasoner``. Due
+to the indeterminism of abductive reasoning, there could be multiple
+candidates compatible to the knowledge base. When this happens, reasoner
+can minimize inconsistencies between the knowledge base and
+pseudo-labels predicted by the learning part, and then return only one
+candidate that has the highest consistency.
+
+.. code:: ipython3
+
+    reasoner = Reasoner(kb)
+
+.. note::
+
+    During creating reasoner, the definition of “consistency” can be
+    customized within the ``dist_func`` parameter. In the code above, we
+    employ a consistency measurement based on confidence, which calculates
+    the consistency between the data example and candidates based on the
+    confidence derived from the predicted probability. In ``examples/hwf/main.py``, we
+    provide options for utilizing other forms of consistency measurement.
+
+    Also, during process of inconsistency minimization, we can
+    leverage `ZOOpt library <https://github.com/polixir/ZOOpt>`__ for
+    acceleration. Options for this are also available in ``examples/hwf/main.py``. Those
+    interested are encouraged to explore these features.
+
+Building Evaluation Metrics
+---------------------------
+
+Next, we set up evaluation metrics. These metrics will be used to
+evaluate the model performance during training and testing.
+Specifically, we use ``SymbolMetric`` and ``ReasoningMetric``, which are
+used to evaluate the accuracy of the machine learning model’s
+predictions and the accuracy of the final reasoning results,
+respectively.
+
+.. code:: ipython3
+
+    metric_list = [SymbolMetric(prefix="hwf"), ReasoningMetric(kb=kb, prefix="hwf")]
+
+Bridge Learning and Reasoning
+-----------------------------
+
+Now, the last step is to bridge the learning and reasoning part. We
+proceed this step by creating an instance of ``SimpleBridge``.
+
+.. code:: ipython3
+
+    bridge = SimpleBridge(model, reasoner, metric_list)
+
+Perform training and testing by invoking the ``train`` and ``test``
+methods of ``SimpleBridge``.
+
+.. code:: ipython3
+
+    # Build logger
+    print_log("Abductive Learning on the HWF example.", logger="current")
+    log_dir = ABLLogger.get_current_instance().log_dir
+    weights_dir = osp.join(log_dir, "weights")
+    
+    bridge.train(train_data, train_data, loops=3, segment_size=1000, save_dir=weights_dir)
+    bridge.test(test_data)
+
+Out:
+    .. code:: none
+        :class: code-out
+
+        abl - INFO - Abductive Learning on the HWF example.
+        abl - INFO - loop(train) [1/3] segment(train) [1/10] 
+        abl - INFO - model loss: 0.00024
+        abl - INFO - loop(train) [1/3] segment(train) [2/10] 
+        abl - INFO - model loss: 0.00053
+        abl - INFO - loop(train) [1/3] segment(train) [3/10] 
+        abl - INFO - model loss: 0.00260
+        abl - INFO - loop(train) [1/3] segment(train) [4/10] 
+        abl - INFO - model loss: 0.00162
+        abl - INFO - loop(train) [1/3] segment(train) [5/10] 
+        abl - INFO - model loss: 0.00073
+        abl - INFO - loop(train) [1/3] segment(train) [6/10] 
+        abl - INFO - model loss: 0.00055
+        abl - INFO - loop(train) [1/3] segment(train) [7/10] 
+        abl - INFO - model loss: 0.00148
+        abl - INFO - loop(train) [1/3] segment(train) [8/10] 
+        abl - INFO - model loss: 0.00034
+        abl - INFO - loop(train) [1/3] segment(train) [9/10] 
+        abl - INFO - model loss: 0.00167
+        abl - INFO - loop(train) [1/3] segment(train) [10/10] 
+        abl - INFO - model loss: 0.00185
+        abl - INFO - Evaluation start: loop(val) [1]
+        abl - INFO - Evaluation ended, hwf/character_accuracy: 1.000 hwf/reasoning_accuracy: 0.999 
+        abl - INFO - Saving model: loop(save) [1]
+        abl - INFO - Checkpoints will be saved to weights_dir/model_checkpoint_loop_1.pth
+        abl - INFO - loop(train) [2/3] segment(train) [1/10] 
+        abl - INFO - model loss: 0.00219
+        abl - INFO - loop(train) [2/3] segment(train) [2/10] 
+        abl - INFO - model loss: 0.00069
+        abl - INFO - loop(train) [2/3] segment(train) [3/10] 
+        abl - INFO - model loss: 0.00013
+        abl - INFO - loop(train) [2/3] segment(train) [4/10] 
+        abl - INFO - model loss: 0.00013
+        abl - INFO - loop(train) [2/3] segment(train) [5/10] 
+        abl - INFO - model loss: 0.00248
+        abl - INFO - loop(train) [2/3] segment(train) [6/10] 
+        abl - INFO - model loss: 0.00010
+        abl - INFO - loop(train) [2/3] segment(train) [7/10] 
+        abl - INFO - model loss: 0.00020
+        abl - INFO - loop(train) [2/3] segment(train) [8/10] 
+        abl - INFO - model loss: 0.00076
+        abl - INFO - loop(train) [2/3] segment(train) [9/10] 
+        abl - INFO - model loss: 0.00061
+        abl - INFO - loop(train) [2/3] segment(train) [10/10] 
+        abl - INFO - model loss: 0.00117
+        abl - INFO - Evaluation start: loop(val) [2]
+        abl - INFO - Evaluation ended, hwf/character_accuracy: 1.000 hwf/reasoning_accuracy: 1.000 
+        abl - INFO - Saving model: loop(save) [2]
+        abl - INFO - Checkpoints will be saved to weights_dir/model_checkpoint_loop_2.pth
+        abl - INFO - loop(train) [3/3] segment(train) [1/10] 
+        abl - INFO - model loss: 0.00120
+        abl - INFO - loop(train) [3/3] segment(train) [2/10] 
+        abl - INFO - model loss: 0.00114
+        abl - INFO - loop(train) [3/3] segment(train) [3/10] 
+        abl - INFO - model loss: 0.00071
+        abl - INFO - loop(train) [3/3] segment(train) [4/10] 
+        abl - INFO - model loss: 0.00027
+        abl - INFO - loop(train) [3/3] segment(train) [5/10] 
+        abl - INFO - model loss: 0.00017
+        abl - INFO - loop(train) [3/3] segment(train) [6/10] 
+        abl - INFO - model loss: 0.00018
+        abl - INFO - loop(train) [3/3] segment(train) [7/10] 
+        abl - INFO - model loss: 0.00141
+        abl - INFO - loop(train) [3/3] segment(train) [8/10] 
+        abl - INFO - model loss: 0.00099
+        abl - INFO - loop(train) [3/3] segment(train) [9/10] 
+        abl - INFO - model loss: 0.00145
+        abl - INFO - loop(train) [3/3] segment(train) [10/10] 
+        abl - INFO - model loss: 0.00215
+        abl - INFO - Evaluation start: loop(val) [3]
+        abl - INFO - Evaluation ended, hwf/character_accuracy: 1.000 hwf/reasoning_accuracy: 1.000 
+        abl - INFO - Saving model: loop(save) [3]
+        abl - INFO - Checkpoints will be saved to weights_dir/model_checkpoint_loop_2.pth
+        abl - INFO - Evaluation ended, hwf/character_accuracy: 0.996 hwf/reasoning_accuracy: 0.977 
+
+More concrete examples are available in ``examples/hwf/main.py`` and ``examples/hwf/hwf.ipynb``.

docs/Examples/MNISTAdd.rst

@@ -1,7 +1,7 @@
 MNIST Addition
 ==============
 
-This notebook shows an implementation of `MNIST
+Below shows an implementation of `MNIST
 Addition <https://arxiv.org/abs/1805.10872>`__. In this task, pairs of
 MNIST handwritten images and their sums are given, alongwith a domain
 knowledge base containing information on how to perform addition
@@ -12,7 +12,7 @@ Intuitively, we first use a machine learning model (learning part) to
 convert the input images to digits (we call them pseudo-labels), and
 then use the knowledge base (reasoning part) to calculate the sum of
 these digits. Since we do not have ground-truth of the digits, in
-abductive learning, the reasoning part will leverage domain knowledge
+Abductive Learning, the reasoning part will leverage domain knowledge
 and revise the initial digits yielded by the learning part through
 abductive reasoning. This process enables us to further update the
 machine learning model.
@@ -42,11 +42,12 @@ First, we get the training and testing datasets:
     train_data = get_dataset(train=True, get_pseudo_label=True)
     test_data = get_dataset(train=False, get_pseudo_label=True)
 
-Both ``train_data`` and ``test_data`` have the same structures: tuples
-with three components: X (list where each element is a pair of images),
-gt_pseudo_label (list where each element is a pair of digits) and Y
-(list where each element is the sum of each digit pair). The length and
-structures of datasets are illustrated as follows.
+``train_data`` and ``test_data`` share identical structures: 
+tuples with three components: X (list where each element is a 
+list of two images), gt_pseudo_label (list where each element 
+is a list of two digits, i.e., pseudo-labels) and Y (list where 
+each element is the sum of the two digits). The length and structures 
+of datasets are illustrated as follows.
 
 .. note::
 
@@ -55,24 +56,25 @@ structures of datasets are illustrated as follows.
 
 .. code:: ipython3
 
-    def describe_structure(lst):
-        if not isinstance(lst, list):
-            return type(lst).__name__ 
-        return [describe_structure(item) for item in lst]
-    
     print(f"Both train_data and test_data consist of 3 components: X, gt_pseudo_label, Y")
     print("\n")
     train_X, train_gt_pseudo_label, train_Y = train_data
-    print(f"Length of X, gt_pseudo_label, Y in train_data: {len(train_X)}, {len(train_gt_pseudo_label)}, {len(train_Y)}")
+    print(f"Length of X, gt_pseudo_label, Y in train_data: " +
+          f"{len(train_X)}, {len(train_gt_pseudo_label)}, {len(train_Y)}")
     test_X, test_gt_pseudo_label, test_Y = test_data
-    print(f"Length of X, gt_pseudo_label, Y in test_data: {len(test_X)}, {len(test_gt_pseudo_label)}, {len(test_Y)}")
+    print(f"Length of X, gt_pseudo_label, Y in test_data: " +
+          f"{len(test_X)}, {len(test_gt_pseudo_label)}, {len(test_Y)}")
     print("\n")
-    structure_X = describe_structure(train_X[0])
-    structure_gt_pseudo_label = describe_structure(train_gt_pseudo_label[0])
-    structure_Y = describe_structure(train_Y[0])
-    print(f"Type of X: {type(train_X).__name__}, and type of each element in X: {structure_X}.")
-    print(f"Type of gt_pseudo_label: {type(train_gt_pseudo_label).__name__}, and type of each element in gt_pseudo_label: {structure_gt_pseudo_label}.")
-    print(f"Type of Y: {type(train_Y).__name__}, and type of each element in Y: {structure_Y}.")
+
+    X_0, gt_pseudo_label_0, Y_0 = train_X[0], train_gt_pseudo_label[0], train_Y[0]
+    print(f"X is a {type(train_X).__name__}, " +
+          f"with each element being a {type(X_0).__name__} " +
+          f"of {len(X_0)} {type(X_0[0]).__name__}.")
+    print(f"gt_pseudo_label is a {type(train_gt_pseudo_label).__name__}, " +
+          f"with each element being a {type(gt_pseudo_label_0).__name__} " +
+          f"of {len(gt_pseudo_label_0)} {type(gt_pseudo_label_0[0]).__name__}.")
+    print(f"Y is a {type(train_Y).__name__}, " +
+          f"with each element being a {type(Y_0).__name__}.")
 
 
 Out:
@@ -80,15 +82,13 @@ Out:
         :class: code-out
 
         Both train_data and test_data consist of 3 components: X, gt_pseudo_label, Y
-        
-        
+
         Length of X, gt_pseudo_label, Y in train_data: 30000, 30000, 30000
         Length of X, gt_pseudo_label, Y in test_data: 5000, 5000, 5000
-        
-        
-        Type of X: list, and type of each element in X: ['Tensor', 'Tensor'].
-        Type of gt_pseudo_label: list, and type of each element in gt_pseudo_label: ['int', 'int'].
-        Type of Y: list, and type of each element in Y: int.
+
+        X is a list, with each element being a list of 2 Tensor.
+        gt_pseudo_label is a list, with each element being a list of 2 int.
+        Y is a list, with each element being a int.
     
 
 The ith element of X, gt_pseudo_label, and Y together constitute the ith
@@ -97,24 +97,24 @@ training set, we have:
 
 .. code:: ipython3
 
-    first_X, first_gt_pseudo_label, first_Y = train_X[0], train_gt_pseudo_label[0], train_Y[0]
-    print(f"X in the first data example (a pair of images):")
+    X_0, gt_pseudo_label_0, Y_0 = train_X[0], train_gt_pseudo_label[0], train_Y[0]
+    print(f"X in the first data example (a list of two images):")
     plt.subplot(1,2,1)
     plt.axis('off') 
-    plt.imshow(first_X[0].numpy().transpose(1, 2, 0))
+    plt.imshow(X_0[0].numpy().transpose(1, 2, 0))
     plt.subplot(1,2,2)
     plt.axis('off') 
-    plt.imshow(first_X[1].numpy().transpose(1, 2, 0))
+    plt.imshow(X_0[1].numpy().transpose(1, 2, 0))
     plt.show()
-    print(f"gt_pseudo_label in the first data example (a pair of ground truth pseudo-labels): {first_gt_pseudo_label[0]}, {first_gt_pseudo_label[1]}")
-    print(f"Y in the first data example (their sum result): {first_Y}")
+    print(f"gt_pseudo_label in the first data example (a list of two ground truth pseudo-labels): {gt_pseudo_label_0}")
+    print(f"Y in the first data example (their sum result): {Y_0}")
 
 
 Out:
     .. code:: none
         :class: code-out
 
-        X in the first data example (a pair of images):
+        X in the first data example (a list of two images):
     
     .. image:: ../img/mnist_add_datasets.png
         :width: 400px
@@ -122,7 +122,7 @@ Out:
 
     .. parsed-literal::
 
-        gt_pseudo_label in the first data example (a pair of ground truth pseudo-labels): 7, 5
+        gt_pseudo_label in the first data example (a list of two ground truth pseudo-labels): [7, 5]
         Y in the first data example (their sum result): 12
     
 
@@ -193,24 +193,32 @@ examples.
 
     from abl.structures import ListData
     # ListData is a data structure provided by ABL-Package that can be used to organize data examples
-    data_example = ListData()
-    data_example.X = first_X
-    data_example.gt_pseudo_label = first_gt_pseudo_label
-    data_example.Y = first_Y
-    
-    # Perform prediction on the first data examples
-    prediction_result = model.predict(data_example)
-    print(f"Predicted class labels for the first data example: np.array with shape {prediction_result['label'].shape}")
-    print(f"Predicted class probabilities for the first data example: np.array with shape {prediction_result['prob'].shape}")
+    data_examples = ListData()
+    # We use the first 100 data examples in the training set as an illustration
+    data_examples.X = train_X[:100]
+    data_examples.gt_pseudo_label = train_gt_pseudo_label[:100]
+    data_examples.Y = train_Y[:100]
+
+    # Perform prediction on the 100 data examples
+    pred_label, pred_prob = model.predict(data_examples)['label'], model.predict(data_examples)['prob']
+    print(f"Predicted class labels for the 100 data examples: \n" +
+          f"a list of length {len(pred_label)}, and each element is " +
+          f"a {type(pred_label[0]).__name__} of shape {pred_label[0].shape}.\n")
+    print(f"Predicted class probabilities for the 100 data examples: \n" +
+          f"a list of length {len(pred_prob)}, and each element is " +
+          f"a {type(pred_prob[0]).__name__} of shape {pred_prob[0].shape}.")
 
 
 Out:
     .. code:: none
         :class: code-out
 
-        Predicted class labels for the first data example: np.array with shape (2,)
-        Predicted class probabilities for the first data example: np.array with shape (2, 10)
-    
+        Predicted class labels for the 100 data examples: 
+        a list of length 100, and each element is a ndarray of shape (2,).
+
+        Predicted class probabilities for the 100 data examples: 
+        a list of length 100, and each element is a ndarray of shape (2, 10).
+
 
 Building the Reasoning Part
 ---------------------------
@@ -282,7 +290,7 @@ candidate that has the highest consistency.
     confidence derived from the predicted probability. In ``examples/mnist_add/main.py``, we
     provide options for utilizing other forms of consistency measurement.
 
-    Also, during process of inconsistency minimization, one can leverage
+    Also, during process of inconsistency minimization, we can leverage
     `ZOOpt library <https://github.com/polixir/ZOOpt>`__ for acceleration.
     Options for this are also available in ``examples/mnist_add/main.py``. Those interested are
     encouraged to explore these features.

docs/Intro/Reasoning.rst

@@ -45,12 +45,12 @@ and override the ``logic_forward`` function:
 -  ``logic_forward`` defines how to perform (deductive) reasoning,
    i.e. matching each pseudo-label example to its reasoning result. 
 
-.. warnings::
+.. note::
 
    Generally, the overridden function ``logic_forward`` provided by the user accepts 
-   only one parameter, ``pseudo_label`` (a pseudo-label example), However, for certain 
+   only one parameter, ``pseudo_label`` (a pseudo-label example). However, for certain 
    scenarios, deductive reasoning in the knowledge base may necessitate information 
-   from the input. When this happens, ``logic_forward`` can also accept two parameters: 
+   from the input. In these scenarios, ``logic_forward`` can also accept two parameters: 
    ``pseudo_label`` and ``x``.
 
 After that, other operations, including how to perform abductive

examples/hwf/README.md

@@ -0,0 +1,46 @@
+# MNIST Addition Example
+
+This example shows a simple implementation of [Handwritten Formula](https://arxiv.org/abs/2006.06649) task, where handwritten images of decimal formulas and their computed results are given, alongwith a domain knowledge base containing information on how to compute the decimal formula. The task is to recognize the symbols (which can be digits or operators '+', '-', '×', '÷') of handwritten images and accurately determine their results.
+
+## Run
+
+```bash
+pip install -r requirements.txt
+python main.py
+```
+
+## Usage
+
+```bash
+usage: main.py [-h] [--no-cuda] [--epochs EPOCHS] [--lr LR]
+               [--weight-decay WEIGHT_DECAY] [--batch-size BATCH_SIZE]
+               [--loops LOOPS] [--segment_size SEGMENT_SIZE]
+               [--save_interval SAVE_INTERVAL] [--max-revision MAX_REVISION]
+               [--require-more-revision REQUIRE_MORE_REVISION]
+               [--ground] [--max-err MAX_ERR]
+
+MNIST Addition example
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --no-cuda             disables CUDA training
+  --epochs EPOCHS       number of epochs in each learning loop iteration
+                        (default : 1)
+  --lr LR               base learning rate (default : 0.001)
+  --weight-decay WEIGHT_DECAY
+                        weight decay value (default : 0.03)
+  --batch-size BATCH_SIZE
+                        batch size (default : 32)
+  --loops LOOPS         number of loop iterations (default : 5)
+  --segment_size SEGMENT_SIZE
+                        segment size (default : 1/3)
+  --save_interval SAVE_INTERVAL
+                        save interval (default : 1)
+  --max-revision MAX_REVISION
+                        maximum revision in reasoner (default : -1)
+  --require-more-revision REQUIRE_MORE_REVISION
+                        require more revision in reasoner (default : 0)
+  --ground              use GroundKB (default: False)
+  --max-err MAX_ERR     max tolerance during abductive reasoning (default : 1e-10)
+
+```

examples/hwf/main.py

@@ -1,32 +1,26 @@
-# %%
-import torch
-import numpy as np
-import torch.nn as nn
+import os
 import os.path as osp
+import argparse
 
-from abl.reasoning import Reasoner, KBBase
-from abl.learning import BasicNN, ABLModel
-from abl.bridge import SimpleBridge
-from abl.evaluation import SymbolMetric, ReasoningMetric
-from abl.utils import ABLLogger, print_log
+import numpy as np
+import torch
+from torch import nn
 
+from examples.hwf.datasets import get_dataset
 from examples.models.nn import SymbolNet
-from examples.hwf.datasets.get_dataset import get_hwf
-
-# %%
-# Initialize logger and print basic information
-print_log("Abductive Learning on the HWF example.", logger="current")
-
-# Retrieve the directory of the Log file and define the directory for saving the model weights.
-log_dir = ABLLogger.get_current_instance().log_dir
-weights_dir = osp.join(log_dir, "weights")
+from abl.learning import ABLModel, BasicNN
+from abl.reasoning import KBBase, GroundKB, Reasoner
+from abl.evaluation import ReasoningMetric, SymbolMetric
+from abl.utils import ABLLogger, print_log
+from abl.bridge import SimpleBridge
 
-# %% [markdown]
-# ### Logic Part
+class HwfKB(KBBase):
+    def __init__(self, 
+                 pseudo_label_list=["1", "2", "3", "4", "5", "6", "7", "8", "9", "+", "-", "*", "/"],
+                 max_err=1e-10,
+                ):
+        super().__init__(pseudo_label_list, max_err)
 
-# %%
-# Initialize knowledge base and reasoner
-class HWF_KB(KBBase):
     def _valid_candidate(self, formula):
         if len(formula) % 2 == 0:
             return False
@@ -36,76 +30,118 @@ class HWF_KB(KBBase):
             if i % 2 != 0 and formula[i] not in ["+", "-", "*", "/"]:
                 return False
         return True
-
+    
+    # Implement the deduction function
     def logic_forward(self, formula):
         if not self._valid_candidate(formula):
-            return np.info
+            return np.inf
         return eval("".join(formula))
 
+class HwfGroundKB(GroundKB):
+    def __init__(self, 
+                 pseudo_label_list=["1", "2", "3", "4", "5", "6", "7", "8", "9", "+", "-", "*", "/"],
+                 GKB_len_list=[1,3,5,7],
+                 max_err=1e-10,
+                ):
+        super().__init__(pseudo_label_list, GKB_len_list, max_err)
 
-kb = HWF_KB(
-    pseudo_label_list=["1", "2", "3", "4", "5", "6", "7", "8", "9", "+", "-", "*", "/"],
-    max_err=1e-10,
-    use_cache=False,
-)
-reasoner = Reasoner(kb, dist_func="confidence")
-
-# %% [markdown]
-# ### Machine Learning Part
-
-# %%
-# Initialize necessary component for machine learning part
-cls = SymbolNet(num_classes=len(kb.pseudo_label_list), image_size=(45, 45, 1))
-device = torch.device("cuda:0" if torch.cuda.is_available() else "cpu")
-loss_fn = nn.CrossEntropyLoss()
-optimizer = torch.optim.Adam(cls.parameters(), lr=0.001, betas=(0.9, 0.99))
-
-# %%
-# Initialize BasicNN
-# The function of BasicNN is to wrap NN models into the form of an sklearn estimator
-base_model = BasicNN(
-    model=cls,
-    loss_fn=loss_fn,
-    optimizer=optimizer,
-    device=device,
-    save_interval=1,
-    save_dir=weights_dir,
-    batch_size=128,
-    num_epochs=3,
-)
-
-# %%
-# Initialize ABL model
-# The main function of the ABL model is to serialize data and
-# provide a unified interface for different machine learning models
-model = ABLModel(base_model)
-
-# %% [markdown]
-# ### Metric
-
-# %%
-# Add metric
-metric_list = [SymbolMetric(prefix="hwf"), ReasoningMetric(kb=kb, prefix="hwf")]
-
-# %% [markdown]
-# ### Dataset
-
-# %%
-# Get training and testing data
-train_data = get_hwf(train=True, get_pseudo_label=True)
-test_data = get_hwf(train=False, get_pseudo_label=True)
-
-# %% [markdown]
-# ### Bridge Machine Learning and Logic Reasoning
-
-# %%
-bridge = SimpleBridge(model=model, reasoner=reasoner, metric_list=metric_list)
-
-# %% [markdown]
-# ### Train and Test
-
-# %%
-bridge.train(train_data, train_data, loops=3, segment_size=1000, save_interval=1, save_dir=weights_dir)
-bridge.test(test_data)
-
+    def _valid_candidate(self, formula):
+        if len(formula) % 2 == 0:
+            return False
+        for i in range(len(formula)):
+            if i % 2 == 0 and formula[i] not in ["1", "2", "3", "4", "5", "6", "7", "8", "9"]:
+                return False
+            if i % 2 != 0 and formula[i] not in ["+", "-", "*", "/"]:
+                return False
+        return True
+    
+    # Implement the deduction function
+    def logic_forward(self, formula):
+        if not self._valid_candidate(formula):
+            return np.inf
+        return eval("".join(formula))
 
+def main():
+    parser = argparse.ArgumentParser(description='MNIST Addition example')
+    parser.add_argument('--no-cuda', action='store_true', default=False,
+                        help='disables CUDA training')
+    parser.add_argument('--epochs', type=int, default=3,
+                        help='number of epochs in each learning loop iteration (default : 3)')
+    parser.add_argument('--lr', type=float, default=1e-3,
+                        help='base learning rate (default : 0.001)')
+    parser.add_argument('--weight-decay', type=int, default=3e-2,
+                        help='weight decay value (default : 0.03)')
+    parser.add_argument('--batch-size', type=int, default=128,
+                        help='batch size (default : 128)')
+    parser.add_argument('--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)')
+    parser.add_argument('--save_interval', type=int, default=1,
+                        help='save interval (default : 1)')
+    parser.add_argument('--max-revision', type=int or float, default=-1,
+                        help='maximum revision in reasoner (default : -1)')
+    parser.add_argument('--require-more-revision', type=int, default=5,
+                        help='require more revision in reasoner (default : 0)')
+    parser.add_argument("--ground", action="store_true", default=False,
+                        help='use GroundKB (default: False)')
+    parser.add_argument("--max-err", type=float, default=1e-10,
+                        help='max tolerance during abductive reasoning (default : 1e-10)')
+
+    args = parser.parse_args()
+    
+    ### Working with Data
+    train_data = get_dataset(train=True, get_pseudo_label=True)
+    test_data = get_dataset(train=False, get_pseudo_label=True)
+
+    ### Building the Learning Part
+    # Build necessary components for BasicNN
+    cls = SymbolNet(num_classes=14, image_size=(45, 45, 1))
+    loss_fn = nn.CrossEntropyLoss()
+    optimizer = torch.optim.Adam(cls.parameters(), lr=args.lr)
+    use_cuda = not args.no_cuda and torch.cuda.is_available()
+    device = torch.device("cuda" if use_cuda else "cpu")
+
+    # Build BasicNN
+    base_model = BasicNN(
+        cls,
+        loss_fn,
+        optimizer,
+        device=device,
+        batch_size=args.batch_size,
+        num_epochs=args.epochs,
+    )
+
+    # Build ABLModel
+    model = ABLModel(base_model)
+    
+    ### Building the Reasoning Part
+    # Build knowledge base
+    if args.ground:
+        kb = HwfGroundKB()
+    else:
+        kb = HwfKB()
+    
+    # Create reasoner
+    reasoner = Reasoner(kb, max_revision=args.max_revision, require_more_revision=args.require_more_revision)
+
+    ### Building Evaluation Metrics
+    metric_list = [SymbolMetric(prefix="hwf"), ReasoningMetric(kb=kb, prefix="hwf")]
+
+    ### Bridge Learning and Reasoning
+    bridge = SimpleBridge(model, reasoner, metric_list)
+
+    # Build logger
+    print_log("Abductive Learning on the HWF example.", logger="current")
+
+    # Retrieve the directory of the Log file and define the directory for saving the model weights.
+    log_dir = ABLLogger.get_current_instance().log_dir
+    weights_dir = osp.join(log_dir, "weights")
+    
+    #  Train and Test
+    bridge.train(train_data, loops=args.loops, segment_size=args.segment_size, save_interval=args.save_interval, save_dir=weights_dir)
+    bridge.test(test_data)
+
+
+if __name__ == "__main__":
+    main()

examples/hwf/requirements.txt

@@ -1,2 +1,3 @@
 abl
-gdown
+gdown
+matplotlib

examples/mnist_add/README.md

@@ -1,6 +1,6 @@
 # MNIST Addition Example
 
-This example shows a simple implementation of [MNIST Addition](https://link) task, where the inputs are pairs of MNIST handwritten images, and the outputs are their sums.
+This example shows a simple implementation of [MNIST Addition](https://arxiv.org/abs/1805.10872) task, where pairs of MNIST handwritten images and their sums are given, alongwith a domain knowledge base containing information on how to perform addition operations. The task is to recognize the digits of handwritten images and accurately determine their sum.
 
 ## Run
 

examples/mnist_add/mnist_add.ipynb

@@ -8,7 +8,7 @@
     "\n",
     "This notebook shows an implementation of [MNIST Addition](https://arxiv.org/abs/1805.10872). In this task, pairs of MNIST handwritten images and their sums are given, alongwith a domain knowledge base containing information on how to perform addition operations. The task is to recognize the digits of handwritten images and accurately determine their sum.\n",
     "\n",
-    "Intuitively, we first use a machine learning model (learning part) to convert the input images to digits (we call them pseudo-labels), and then use the knowledge base (reasoning part) to calculate the sum of these digits. Since we do not have ground-truth of the digits, in abductive learning, the reasoning part will leverage domain knowledge and revise the initial digits yielded by the learning part through abductive reasoning. This process enables us to further update the machine learning model."
+    "Intuitively, we first use a machine learning model (learning part) to convert the input images to digits (we call them pseudo-labels), and then use the knowledge base (reasoning part) to calculate the sum of these digits. Since we do not have ground-truth of the digits, in Abductive Learning, the reasoning part will leverage domain knowledge and revise the initial digits yielded by the learning part through abductive reasoning. This process enables us to further update the machine learning model."
    ]
   },
   {
@@ -54,7 +54,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Both `train_data` and `test_data` have the same structures: tuples with three components: X (list where each element is a pair of images), gt_pseudo_label (list where each element is a pair of digits) and Y (list where each element is the sum of each digit pair). The length and structures of datasets are illustrated as follows.\n",
+    "`train_data` and `test_data` share identical structures: tuples with three components: X (list where each element is a list of two images), gt_pseudo_label (list where each element is a list of two digits, i.e., pseudo-labels) and Y (list where each element is the sum of the two digits). The length and structures of datasets are illustrated as follows.\n",
     "\n",
     "Note: ``gt_pseudo_label`` is only used to evaluate the performance of the learning part but not to train the model."
    ]
@@ -70,14 +70,12 @@
      "text": [
       "Both train_data and test_data consist of 3 components: X, gt_pseudo_label, Y\n",
       "\n",
-      "\n",
       "Length of X, gt_pseudo_label, Y in train_data: 30000, 30000, 30000\n",
       "Length of X, gt_pseudo_label, Y in test_data: 5000, 5000, 5000\n",
       "\n",
-      "\n",
-      "Type of X: list, and type of each element in X: ['Tensor', 'Tensor'].\n",
-      "Type of gt_pseudo_label: list, and type of each element in gt_pseudo_label: ['int', 'int'].\n",
-      "Type of Y: list, and type of each element in Y: int.\n"
+      "X is a list, with each element being a list of 2 Tensor.\n",
+      "gt_pseudo_label is a list, with each element being a list of 2 int.\n",
+      "Y is a list, with each element being a int.\n"
      ]
     }
    ],
@@ -88,18 +86,24 @@
     "    return [describe_structure(item) for item in lst]\n",
     "\n",
     "print(f\"Both train_data and test_data consist of 3 components: X, gt_pseudo_label, Y\")\n",
-    "print(\"\\n\")\n",
+    "print()\n",
     "train_X, train_gt_pseudo_label, train_Y = train_data\n",
-    "print(f\"Length of X, gt_pseudo_label, Y in train_data: {len(train_X)}, {len(train_gt_pseudo_label)}, {len(train_Y)}\")\n",
+    "print(f\"Length of X, gt_pseudo_label, Y in train_data: \" +\n",
+    "      f\"{len(train_X)}, {len(train_gt_pseudo_label)}, {len(train_Y)}\")\n",
     "test_X, test_gt_pseudo_label, test_Y = test_data\n",
-    "print(f\"Length of X, gt_pseudo_label, Y in test_data: {len(test_X)}, {len(test_gt_pseudo_label)}, {len(test_Y)}\")\n",
-    "print(\"\\n\")\n",
-    "structure_X = describe_structure(train_X[0])\n",
-    "structure_gt_pseudo_label = describe_structure(train_gt_pseudo_label[0])\n",
-    "structure_Y = describe_structure(train_Y[0])\n",
-    "print(f\"Type of X: {type(train_X).__name__}, and type of each element in X: {structure_X}.\")\n",
-    "print(f\"Type of gt_pseudo_label: {type(train_gt_pseudo_label).__name__}, and type of each element in gt_pseudo_label: {structure_gt_pseudo_label}.\")\n",
-    "print(f\"Type of Y: {type(train_Y).__name__}, and type of each element in Y: {structure_Y}.\")"
+    "print(f\"Length of X, gt_pseudo_label, Y in test_data: \" +\n",
+    "      f\"{len(test_X)}, {len(test_gt_pseudo_label)}, {len(test_Y)}\")\n",
+    "print()\n",
+    "\n",
+    "X_0, gt_pseudo_label_0, Y_0 = train_X[0], train_gt_pseudo_label[0], train_Y[0]\n",
+    "print(f\"X is a {type(train_X).__name__}, \" +\n",
+    "      f\"with each element being a {type(X_0).__name__} \" +\n",
+    "      f\"of {len(X_0)} {type(X_0[0]).__name__}.\")\n",
+    "print(f\"gt_pseudo_label is a {type(train_gt_pseudo_label).__name__}, \" +\n",
+    "      f\"with each element being a {type(gt_pseudo_label_0).__name__} \" +\n",
+    "      f\"of {len(gt_pseudo_label_0)} {type(gt_pseudo_label_0[0]).__name__}.\")\n",
+    "print(f\"Y is a {type(train_Y).__name__}, \" +\n",
+    "      f\"with each element being a {type(Y_0).__name__}.\")"
    ]
   },
   {
@@ -118,7 +122,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "X in the first data example (a pair of images):\n"
+      "X in the first data example (a list of two images):\n"
      ]
     },
     {
@@ -135,23 +139,23 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "gt_pseudo_label in the first data example (a pair of ground truth pseudo-labels): 7, 5\n",
+      "gt_pseudo_label in the first data example (a list of two ground truth pseudo-labels): [7, 5]\n",
       "Y in the first data example (their sum result): 12\n"
      ]
     }
    ],
    "source": [
-    "first_X, first_gt_pseudo_label, first_Y = train_X[0], train_gt_pseudo_label[0], train_Y[0]\n",
-    "print(f\"X in the first data example (a pair of images):\")\n",
+    "X_0, gt_pseudo_label_0, Y_0 = train_X[0], train_gt_pseudo_label[0], train_Y[0]\n",
+    "print(f\"X in the first data example (a list of two images):\")\n",
     "plt.subplot(1,2,1)\n",
     "plt.axis('off') \n",
-    "plt.imshow(first_X[0].numpy().transpose(1, 2, 0))\n",
+    "plt.imshow(X_0[0].numpy().transpose(1, 2, 0))\n",
     "plt.subplot(1,2,2)\n",
     "plt.axis('off') \n",
-    "plt.imshow(first_X[1].numpy().transpose(1, 2, 0))\n",
+    "plt.imshow(X_0[1].numpy().transpose(1, 2, 0))\n",
     "plt.show()\n",
-    "print(f\"gt_pseudo_label in the first data example (a pair of ground truth pseudo-labels): {first_gt_pseudo_label[0]}, {first_gt_pseudo_label[1]}\")\n",
-    "print(f\"Y in the first data example (their sum result): {first_Y}\")"
+    "print(f\"gt_pseudo_label in the first data example (a list of two ground truth pseudo-labels): {gt_pseudo_label_0}\")\n",
+    "print(f\"Y in the first data example (their sum result): {Y_0}\")"
    ]
   },
   {
@@ -206,17 +210,19 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Predicted class index for a batch of 32 instances: np.ndarray with shape (32,)\n",
-      "Predicted class probabilities for a batch of 32 instances: np.ndarray with shape (32, 10)\n"
+      "Predicted class index for a batch of 32 instances: ndarray with shape (32,)\n",
+      "Predicted class probabilities for a batch of 32 instances: ndarray with shape (32, 10)\n"
      ]
     }
    ],
    "source": [
     "data_instances = [torch.randn(1, 28, 28).to(device) for _ in range(32)]\n",
     "pred_idx = base_model.predict(X=data_instances)\n",
-    "print(f\"Predicted class index for a batch of 32 instances: np.ndarray with shape {pred_idx.shape}\")\n",
+    "print(f\"Predicted class index for a batch of 32 instances: \" +\n",
+    "      f\"{type(pred_idx).__name__} with shape {pred_idx.shape}\")\n",
     "pred_prob = base_model.predict_proba(X=data_instances)\n",
-    "print(f\"Predicted class probabilities for a batch of 32 instances: np.ndarray with shape {pred_prob.shape}\")"
+    "print(f\"Predicted class probabilities for a batch of 32 instances: \" +\n",
+    "      f\"{type(pred_prob).__name__} with shape {pred_prob.shape}\")"
    ]
   },
   {
@@ -251,23 +257,31 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Predicted class labels for the first data example: np.array with shape (2,)\n",
-      "Predicted class probabilities for the first data example: np.array with shape (2, 10)\n"
+      "Predicted class labels for the 100 data examples: \n",
+      "a list of length 100, and each element is a ndarray of shape (2,).\n",
+      "\n",
+      "Predicted class probabilities for the 100 data examples: \n",
+      "a list of length 100, and each element is a ndarray of shape (2, 10).\n"
      ]
     }
    ],
    "source": [
     "from abl.structures import ListData\n",
     "# ListData is a data structure provided by ABL-Package that can be used to organize data examples\n",
-    "data_example = ListData()\n",
-    "data_example.X = first_X\n",
-    "data_example.gt_pseudo_label = first_gt_pseudo_label\n",
-    "data_example.Y = first_Y\n",
+    "data_examples = ListData()\n",
+    "# We use the first 100 data examples in the training set as an illustration\n",
+    "data_examples.X = train_X[:100]\n",
+    "data_examples.gt_pseudo_label = train_gt_pseudo_label[:100]\n",
+    "data_examples.Y = train_Y[:100]\n",
     "\n",
-    "# Perform prediction on the first data examples\n",
-    "prediction_result = model.predict(data_example)\n",
-    "print(f\"Predicted class labels for the first data example: np.array with shape {prediction_result['label'].shape}\")\n",
-    "print(f\"Predicted class probabilities for the first data example: np.array with shape {prediction_result['prob'].shape}\")"
+    "# Perform prediction on the 100 data examples\n",
+    "pred_label, pred_prob = model.predict(data_examples)['label'], model.predict(data_examples)['prob']\n",
+    "print(f\"Predicted class labels for the 100 data examples: \\n\" +\n",
+    "      f\"a list of length {len(pred_label)}, and each element is \" +\n",
+    "      f\"a {type(pred_label[0]).__name__} of shape {pred_label[0].shape}.\\n\")\n",
+    "print(f\"Predicted class probabilities for the 100 data examples: \\n\" +\n",
+    "      f\"a list of length {len(pred_prob)}, and each element is \" +\n",
+    "      f\"a {type(pred_prob[0]).__name__} of shape {pred_prob[0].shape}.\")"
    ]
   },
   {
@@ -356,7 +370,7 @@
    "source": [
     "Note: During creating reasoner, the definition of \"consistency\" can be customized within the `dist_func` parameter. In the code above, we employ a consistency measurement based on confidence, which calculates the consistency between the data example and candidates based on the confidence derived from the predicted probability. In `main.py`, we provide options for utilizing other forms of consistency measurement.\n",
     "\n",
-    "Also, during process of inconsistency minimization, one can leverage [ZOOpt library](https://github.com/polixir/ZOOpt) for acceleration. Options for this are also available in `main.py`. Those interested are encouraged to explore these features."
+    "Note: Also, during process of inconsistency minimization, one can leverage [ZOOpt library](https://github.com/polixir/ZOOpt) for acceleration. Options for this are also available in `main.py`. Those interested are encouraged to explore these features."
    ]
   },
   {