@@ -1,7 +1,7 @@
`Learn the Basics <Basics.html>`_ ||
`Quick Start <QuickStart.html>`_ ||
`Quick Start <Quick- Start.html>`_ ||
`Dataset & Data Structure <Datasets.html>`_ ||
`Machine Learning Part <Learning.html>`_ ||
`Learning Part <Learning.html>`_ ||
**Reasoning Part** ||
`Evaluation Metrics <Evaluation.html>`_ ||
`Bridge <Bridge.html>`_
@@ -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
-----------------
troyyyyy
2 years ago
