[DOC] revise reasoning in quick start, logical-->reasoning result

abl/reasoning/kb.py

@@ -24,8 +24,8 @@ class KBBase(ABC):
         list so that each aligns with its corresponding index in the base model: the first with 
         the 0th index, the second with the 1st, and so forth.
     max_err : float, optional
-        The upper tolerance limit when comparing the similarity between a candidate's logical
-        result and the ground truth. This is only applicable when the logical result is of a numerical type.
+        The upper tolerance limit when comparing the similarity between a candidate's reasoning
+        result and the ground truth. This is only applicable when the reasoning result is of a numerical type.
         This is particularly relevant for regression problems where exact matches might not be
         feasible. Defaults to 1e-10.
     use_cache : bool, optional
@@ -68,7 +68,7 @@ class KBBase(ABC):
     def logic_forward(self, pseudo_label):
         """
         How to perform (deductive) logical reasoning, i.e. matching each pseudo label to
-        their logical result. Users are required to provide this.
+        their reasoning result. Users are required to provide this.
 
         Parameters
         ----------
@@ -86,7 +86,7 @@ class KBBase(ABC):
         pseudo_label : List[Any]
             Pseudo label sample (to be revised by abductive reasoning).
         y : any
-            Ground truth of the logical result for the sample.
+            Ground truth of the reasoning result for the sample.
         max_revision_num : int
             The upper limit on the number of revised labels for each sample.
         require_more_revision : int
@@ -102,7 +102,7 @@ class KBBase(ABC):
 
     def _check_equal(self, logic_result, y):
         """
-        Check whether the logical result of a candidate is equal to the ground truth
+        Check whether the reasoning result of a candidate is equal to the ground truth
         (or, within the maximum error allowed for numerical results).
         
         Returns
@@ -127,7 +127,7 @@ class KBBase(ABC):
         pseudo_label : List[Any]
             Pseudo label sample (to be revised).
         y : Any
-            Ground truth of the logical result for the sample.
+            Ground truth of the reasoning result for the sample.
         revision_idx : array-like
             Indices of where revisions should be made to the pseudo label sample.
         
@@ -172,7 +172,7 @@ class KBBase(ABC):
         pseudo_label : List[Any]
             Pseudo label sample (to be revised).
         y : Any
-            Ground truth of the logical result for the sample.
+            Ground truth of the reasoning result for the sample.
         max_revision_num : int
             The upper limit on the number of revisions.
         require_more_revision : int
@@ -219,7 +219,7 @@ class GroundKB(KBBase):
     """
     Knowledge base with a ground KB (GKB). Ground KB is a knowledge base prebuilt upon
     class initialization, storing all potential candidates along with their respective
-    logical result. Ground KB can accelerate abductive reasoning in `abduce_candidates`.
+    reasoning result. Ground KB can accelerate abductive reasoning in `abduce_candidates`.
 
     Parameters
     ----------
@@ -292,7 +292,7 @@ class GroundKB(KBBase):
         pseudo_label : List[Any]
             Pseudo label sample (to be revised by abductive reasoning).
         y : any
-            Ground truth of the logical result for the sample.
+            Ground truth of the reasoning result for the sample.
         max_revision_num : int
             The upper limit on the number of revised labels for each sample.
         require_more_revision : int, optional
@@ -320,8 +320,8 @@ class GroundKB(KBBase):
 
     def _find_candidate_GKB(self, pseudo_label, y):
         """
-        Retrieve compatible candidates from the prebuilt GKB. For numerical logical results,
-        return all candidates whose logical results fall within the
+        Retrieve compatible candidates from the prebuilt GKB. For numerical reasoning results,
+        return all candidates whose reasoning results fall within the
         [y - max_err, y + max_err] range.
         """
         if isinstance(y, (int, float)):
@@ -397,8 +397,8 @@ class PrologKB(KBBase):
     def logic_forward(self, pseudo_labels):
         """
         Consult prolog with the query `logic_forward(pseudo_labels, Res).`, and set the
-        returned `Res` as the logical results. To use this default function, there must be
-        a Prolog `log_forward` method in the pl file to perform logical. reasoning.
+        returned `Res` as the reasoning results. To use this default function, there must be
+        a `logic_forward` method in the pl file to perform reasoning.
         Otherwise, users would override this function.
         
         Parameters
@@ -437,7 +437,7 @@ class PrologKB(KBBase):
         pseudo_label : List[Any]
             Pseudo label sample (to be revised by abductive reasoning).
         y : any
-            Ground truth of the logical result for the sample.
+            Ground truth of the reasoning result for the sample.
         revision_idx : array-like
             Indices of where revisions should be made to the pseudo label sample.
             
@@ -461,7 +461,7 @@ class PrologKB(KBBase):
         pseudo_label : List[Any]
             Pseudo label sample (to be revised).
         y : Any
-            Ground truth of the logical result for the sample.
+            Ground truth of the reasoning result for the sample.
         revision_idx : array-like
             Indices of where revisions should be made to the pseudo label sample.
         

docs/Intro/Basics.rst

@@ -57,9 +57,9 @@ Use ABL-Package Step by Step
 In a typical Abductive Learning process, as illustrated below, 
 data inputs are first mapped to pseudo labels through a machine learning model. 
 These pseudo labels then pass through a knowledge base :math:`\mathcal{KB}`
-to obtain the logical result by deductive reasoning. During training, 
+to obtain the reasoning result by deductive reasoning. During training, 
 alongside the aforementioned forward flow (i.e., prediction --> deduction reasoning), 
-there also exists a reverse flow, which starts from the logical result and 
+there also exists a reverse flow, which starts from the reasoning result and 
 involves abductive reasoning to generate pseudo labels. 
 Subsequently, these labels are processed to minimize inconsistencies with machine learning, 
 which in turn revise the outcomes of the machine learning model, and then 
@@ -70,7 +70,7 @@ To implement this process, the following five steps are necessary:
 
 1. Prepare datasets
 
-    Prepare the data's input, ground truth for pseudo labels (optional), and ground truth for logical results.
+    Prepare the data's input, ground truth for pseudo labels (optional), and ground truth for reasoning results.
 
 2. Build the learning part
 
@@ -80,7 +80,7 @@ To implement this process, the following five steps are necessary:
 3. Build the reasoning part
 
     Build a knowledge base by building a subclass of ``KBBase``, defining how to 
-    map pseudo labels to logical results.
+    map pseudo labels to reasoning results.
     Also, instantiate a ``ReasonerBase`` for minimizing of inconsistencies 
     between the knowledge base and pseudo labels.
 

docs/Intro/Quick-Start.rst

@@ -123,8 +123,11 @@ Read more about `building the learning part <Learning.html>`_.
 Building the Reasoning Part
 ---------------------------
 
-To build the reasoning part, we first create a class that inherits from ``KBBase`` to define the knowledge base.
-We pass the list of pseudo labels to the ``__init__`` function and specify how to deduce logical results in the ``logic_forward`` function.
+To build the reasoning part, we first Build a knowledge base by
+creating a subclass of ``KBBase``, which defines how to map pseudo 
+labels to reasoning results. In the subclass, we initialize the 
+``pseudo_label_list`` parameter and override the ``logic_forward`` 
+function specifying how to perform (deductive) reasoning.
 
 .. code:: python
 
@@ -146,7 +149,10 @@ Out:
 
    AddKB is a KB with pseudo_label_list=[0, 1, 2, 3, 4, 5, 6, 7, 8, 9], max_err=1e-10, use_cache=True.
 
-Then, we create a reasoner. Aside from the knowledge base, the instantiation of ``ReasonerBase`` also needs to set an extra argument called ``dist_func``, which measures the consistency between the knowledge base and machine learning.
+Then, we create a reasoner by defining an instance of class
+``ReasonerBase`` and passing the knowledge base as an parameter.
+The reasoner can be used to minimize inconsistencies between the 
+knowledge base and the prediction from the learning part. 
 
 .. code:: python
 

docs/Intro/Reasoning.rst

@@ -13,7 +13,7 @@ Reasoning part
 In ABL-Package, constructing the reasoning part involves two steps:
 
 1. Build a knowledge base by creating a subclass of ``KBBase``, which
-   defines how to map pseudo labels to logical results.
+   defines how to map pseudo labels to reasoning results.
 2. Define a reasoner by creating an instance of class ``ReasonerBase``
    to minimize inconsistencies between the knowledge base and pseudo
    labels predicted by the learning part.
@@ -32,7 +32,7 @@ and override the ``logic_forward`` function:
 -  **pseudo_label_list** is the list of possible pseudo labels (also,
    the output of the machine learning model).
 -  **logic_forward** defines how to perform (deductive) reasoning,
-   i.e. matching each pseudo label to their logical result.
+   i.e. matching each pseudo label to their reasoning result.
 
 After that, other operations, including how to perform abductive
 reasoning, will be **automatically** set up.
@@ -65,9 +65,9 @@ You can also initialize the following parameters when building your
 knowledge base:
 
 -  **max_err** (float, optional), specifying the upper tolerance limit
-   when comparing the similarity between a candidate’s logical result
+   when comparing the similarity between a candidate’s reasoning result
    and the ground truth during abductive reasoning. This is only
-   applicable when the logical result is of a numerical type. This is
+   applicable when the reasoning result is of a numerical type. This is
    particularly relevant for regression problems where exact matches
    might not be feasible. Defaults to 1e-10. See :ref:`an example <kb-abd-2>`.
 -  **use_cache** (bool, optional), indicating whether to use cache for
@@ -133,7 +133,7 @@ knowledge base. In this way, the knowledge built will have a Ground KB
 .. admonition:: What is Ground KB?
 
    Ground KB is a knowledge base prebuilt upon class initialization,
-   storing all potential candidates along with their respective logical
+   storing all potential candidates along with their respective reasoning
    result. The key advantage of having a Ground KB is that it may
    accelerate abductive reasoning.
 
@@ -177,7 +177,7 @@ Perform abductive reasoning in your knowledge base
 
 As mentioned in :ref:`What is Abductive Reasoning? <abd>`, abductive reasoning
 enables the inference of candidate pseudo labels as potential
-explanations for the logical result. Also, in Abductive Learning where
+explanations for the reasoning result. Also, in Abductive Learning where
 an observation (a pseudo label predicted by the learning part) is
 available, we aim to let the candidate do not largely revise the
 previously identified pseudo label.
@@ -188,7 +188,7 @@ for conducting abductive reasoning, where the parameters are:
 
 -  **pseudo_label**, the pseudo label sample to be revised by abductive
    reasoning, usually generated by the learning part.
--  **y**, the ground truth of the logical result for the sample. The
+-  **y**, the ground truth of the reasoning result for the sample. The
    returned candidates should be compatible with it.
 -  **max_revision_num**, an int value specifying the upper limit on the
    number of revised labels for each sample.