diff --git a/docs/Intro/Basics.rst b/docs/Intro/Basics.rst index 46a2c1b..9c73fd0 100644 --- a/docs/Intro/Basics.rst +++ b/docs/Intro/Basics.rst @@ -1,7 +1,7 @@ **Learn the Basics** || -`Quick Start `_ || +`Quick Start `_ || `Dataset & Data Structure `_ || -`Machine Learning Part `_ || +`Learning Part `_ || `Reasoning Part `_ || `Evaluation Metrics `_ || `Bridge `_ @@ -64,7 +64,7 @@ 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 fed back into the machine learning model for further training. -To implement this process, the following four steps are necessary: +To implement this process, the following five steps are necessary: .. image:: ../img/usage.png @@ -75,12 +75,13 @@ To implement this process, the following four steps are necessary: 2. Build machine learning part Build a model that defines how to map input to pseudo labels. - And use ``ABLModel`` to encapsulate the model. + Then, use ``ABLModel`` to encapsulate the model. 3. Build the reasoning part - Build a knowledge base by creating a subclass of ``KBBase``, - and instantiate a ``ReasonerBase`` for minimizing of inconsistencies + Build a knowledge base by building a subclass of ``KBBase``, defining how to + map pseudo labels to logical results. + Also, instantiate a ``ReasonerBase`` for minimizing of inconsistencies between the knowledge base and pseudo labels. 4. Define Evaluation Metrics diff --git a/docs/Intro/Bridge.rst b/docs/Intro/Bridge.rst index 2529ff4..12d59ce 100644 --- a/docs/Intro/Bridge.rst +++ b/docs/Intro/Bridge.rst @@ -1,7 +1,7 @@ `Learn the Basics `_ || -`Quick Start `_ || +`Quick Start `_ || `Dataset & Data Structure `_ || -`Machine Learning Part `_ || +`Learning Part `_ || `Reasoning Part `_ || `Evaluation Metrics `_ || **Bridge** diff --git a/docs/Intro/Datasets.rst b/docs/Intro/Datasets.rst index 0ea1be6..bd5587e 100644 --- a/docs/Intro/Datasets.rst +++ b/docs/Intro/Datasets.rst @@ -1,7 +1,7 @@ `Learn the Basics `_ || -`Quick Start `_ || +`Quick Start `_ || **Dataset & Data Structure** || -`Machine Learning Part `_ || +`Learning Part `_ || `Reasoning Part `_ || `Evaluation Metrics `_ || `Bridge `_ diff --git a/docs/Intro/Evaluation.rst b/docs/Intro/Evaluation.rst index 23e500d..bf06929 100644 --- a/docs/Intro/Evaluation.rst +++ b/docs/Intro/Evaluation.rst @@ -1,7 +1,7 @@ `Learn the Basics `_ || -`Quick Start `_ || +`Quick Start `_ || `Dataset & Data Structure `_ || -`Machine Learning Part `_ || +`Learning Part `_ || `Reasoning Part `_ || **Evaluation Metrics** || `Bridge `_ diff --git a/docs/Intro/Learning.rst b/docs/Intro/Learning.rst index ed6d1d6..4f5197b 100644 --- a/docs/Intro/Learning.rst +++ b/docs/Intro/Learning.rst @@ -1,14 +1,14 @@ `Learn the Basics `_ || -`Quick Start `_ || +`Quick Start `_ || `Dataset & Data Structure `_ || -**Machine Learning Part** || +**Learning Part** || `Reasoning Part `_ || `Evaluation Metrics `_ || `Bridge `_ -Machine Learning Part -===================== +Learning Part +============= ``ABLModel`` class serves as a unified interface to all machine learning models. Its constructor, the ``__init__`` method, takes a singular argument, ``base_model``. This argument denotes the fundamental machine learning model, which must implement the ``fit`` and ``predict`` methods. diff --git a/docs/Intro/QuickStart.rst b/docs/Intro/Quick-Start.rst similarity index 99% rename from docs/Intro/QuickStart.rst rename to docs/Intro/Quick-Start.rst index 5b1c68b..b6615e4 100644 --- a/docs/Intro/QuickStart.rst +++ b/docs/Intro/Quick-Start.rst @@ -1,7 +1,7 @@ `Learn the Basics `_ || **Quick Start** || `Dataset & Data Structure `_ || -`Machine Learning Part `_ || +`Learning Part `_ || `Reasoning Part `_ || `Evaluation Metrics `_ || `Bridge `_ diff --git a/docs/Intro/Reasoning.rst b/docs/Intro/Reasoning.rst index a845c4b..c75fc91 100644 --- a/docs/Intro/Reasoning.rst +++ b/docs/Intro/Reasoning.rst @@ -1,7 +1,7 @@ `Learn the Basics `_ || -`Quick Start `_ || +`Quick Start `_ || `Dataset & Data Structure `_ || -`Machine Learning Part `_ || +`Learning Part `_ || **Reasoning Part** || `Evaluation Metrics `_ || `Bridge `_ @@ -10,3 +10,145 @@ Reasoning part =============== +In ABL-Package, there are two steps to construct the reasoning part: + +1. Build a knowledge base by creating a subclass of ``KBBase``, which + defines how to map pseudo labels to logical results. +2. Define a reasoner by creating an instance of class ``ReasonerBase`` + to minimize inconsistencies between the knowledge base and pseudo + labels. + +Build a knowledge base +---------------------- + +Build your Knowledge base from ``KBBase`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Generally, users can inherit from class ``KBBase`` to build their own +knowledge base. For the user-build KB (an inherited subclass), it's only +required for the user to initialize the ``pseudo_label_list`` parameters +and override the ``logic_forward`` function: + +- ``pseudo_label_list`` is the list of possible pseudo labels (i.e., + the output of the machine learning model). +- ``logic_forward`` is how to perform (deductive) reasoning, + i.e. matching each pseudo label to their logical result. + +After that, other operations, including how to perform abductive +reasoning, will be **automatically** set up. + +As an example, the ``pseudo_label_list`` passed in MNISTAdd is all the +possible digits, namely, ``[0,1,2,...,9]``, and the ``logic_forward`` +is: “Add two pseudo labels to get the result.”. Therefore, the +construction of the KB (``add_kb``) of MNISTAdd would be: + +.. code:: python + + class AddKB(KBBase): + def __init__(self, pseudo_label_list=list(range(10))): + super().__init__(pseudo_label_list) + + def logic_forward(self, pseudo_labels): + return sum(pseudo_labels) + + add_kb = AddKB() + +Other optional parameters +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following parameters can also be passed in when building your +knowledge base: + +- ``max_err`` (float, optional), which is the upper tolerance limit + when comparing the similarity between a candidate's logical result + during abductive reasoning. This is only applicable when the logical + 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), indicates whether to use cache for + previously abduced candidates to speed up subsequent abductive + reasoning operations. Defaults to True. +- ``max_cache_size`` (int, optional), The maximum cache size. This is + only operational when ``use_cache`` is set to True. Defaults to 4096. + +Build your Knowledge base with GKB from ``GroundKB`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Users can also inherit from class ``GroundKB`` to build their own +knowledge base. In this way, the knowledge built will have a Ground KB +(GKB). + +.. admonition:: What is Ground KB? + + Ground KB is a knowledge base prebuilt upon class initialization, + storing all potential candidates along with their respective logical + result. The key advantage of having a Ground KB is that it may + accelerate abductive reasoning. + +Similar to ``KBBase``, users are required to initialize the +``pseudo_label_list`` parameter and override the ``logic_forward`` +function. Additionally, users should initialize the ``GKB_len_list`` +parameter. + +- ``GKB_len_list`` is the list of possible lengths of pseudo label. + +After that, other operations, including auto-construction of GKB, and +how to perform abductive reasoning, will be **automatically** set up. + +As an example, the ``GKB_len_list`` for MNISTAdd should be ``[2]``, +since all pseudo labels in the example consist of two digits. Therefore, +the construction of KB with GKB (``add_ground_kb``) of MNISTAdd would be +as follows. As mentioned, the difference between this and the previously +built ``add_kb`` lies only in the base class from which it is inherited +and whether an extra parameter ``GKB_len_list`` is passed. + +.. code:: python + + class AddGroundKB(GroundKB): + def __init__(self, pseudo_label_list=list(range(10)), + GKB_len_list=[2]): + super().__init__(pseudo_label_list, GKB_len_list) + + def logic_forward(self, nums): + return sum(nums) + + add_ground_kb = AddGroundKB() + +Build your Knowledge base from Prolog file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For users aiming to leverage knowledge base from an external Prolog file +(which contain how to perform reasoning), they may directly creating an +instance of class ``PrologKB``. Specifically, upon instantiation of +``PrologKB``, users are required to provide the ``pseudo_label_list`` +and ``pl_file`` (the Prolog file). + +After the instantiation, other operations, including how to perform +abductive reasoning, will also be **automatically** set up. + +.. attention:: + + Note that in order to use the default logic forward and abductive reasoning + methods in this class ``PrologKB``, the Prolog (.pl) file should contain a rule + with a strict format: ``logic_forward(Pseudo_labels, Res).`` + Otherwise, users might have to override ``logic_forward`` and + ``get_query_string`` to allow for more adaptable usage. + +As an example, one can first write a Prolog file for the MNISTAdd +example as the following code, and then save it as ``add.pl``. + +.. code:: prolog + + pseudo_label(N) :- between(0, 9, N). + logic_forward([Z1, Z2], Res) :- pseudo_label(Z1), pseudo_label(Z2), Res is Z1+Z2. + +Afterwards, the construction of knowledge base from Prolog file +(``add_prolog_kb``) would be as follows: + +.. code:: python + + add_prolog_kb = PrologKB(pseudo_label_list=list(range(10)), + pl_file="add.pl") + +Create a reasoner +----------------- \ No newline at end of file diff --git a/docs/img/image_1.jpg b/docs/img/image_1.jpg deleted file mode 100644 index fdd07fe..0000000 Binary files a/docs/img/image_1.jpg and /dev/null differ diff --git a/docs/img/image_2.jpg b/docs/img/image_2.jpg deleted file mode 100644 index e6b99f4..0000000 Binary files a/docs/img/image_2.jpg and /dev/null differ diff --git a/docs/index.rst b/docs/index.rst index eb0c15b..bd23605 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,7 +12,7 @@ :caption: Introduction to ABL-Package Intro/Basics - Intro/QuickStart + Intro/Quick-Start Intro/Datasets Intro/Learning Intro/Reasoning