diff --git a/.gitignore b/.gitignore index 6770abe..ad56f7c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,4 @@ *.pyc -*.jpg *.png *.pk *.pth @@ -8,5 +7,6 @@ results raw/ abl.egg-info/ +examples/**/*.jpg .idea/ build/ \ No newline at end of file diff --git a/docs/Brief-Introduction/Components.rst b/docs/Brief-Introduction/Components.rst index 3f08245..6f0bf96 100644 --- a/docs/Brief-Introduction/Components.rst +++ b/docs/Brief-Introduction/Components.rst @@ -1,5 +1,5 @@ Components -================== +========== .. contents:: Table of Contents diff --git a/docs/Brief-Introduction/Usage.rst b/docs/Brief-Introduction/Usage.rst index 9535484..1d29a4a 100644 --- a/docs/Brief-Introduction/Usage.rst +++ b/docs/Brief-Introduction/Usage.rst @@ -165,4 +165,4 @@ In the MNIST Add example, the code to train and test looks like .. code:: python bridge.train(train_data, loops=5, segment_size=10000, save_interval=1, save_dir=weights_dir) - bridge.test(test_data) \ No newline at end of file + bridge.test(test_data) diff --git a/docs/Overview/Abductive Learning.rst b/docs/Overview/Abductive Learning.rst index 72cd629..9a4e4dc 100644 --- a/docs/Overview/Abductive Learning.rst +++ b/docs/Overview/Abductive Learning.rst @@ -1,27 +1,82 @@ Abductive Learning ================== -Traditional supervised machine learning, e.g. classification, is predominantly data-driven. Here, a set of training examples \left\{\left(x_1, y_1\right), \ldots,\left(x_m, y_m\right)\right\} is given, where x_i \in \mathcal{X} is the i-th training instance, y_i \in \mathcal{Y} is the corresponding ground-truth label. These data are then used to train a classifier model f: \mathcal{X} \mapsto \mathcal{Y} to accurately predict the unseen data. +Integrating the Power of Machine Learning and Logical Reasoning +--------------------------------------------------------------- -（可能加一张图，比如左边是ML，右边是ML+KB） +Traditional supervised machine learning, e.g. classification, is +predominantly data-driven, as shown in the below figure. +Here, a set of training examples :math:`\left\{\left(x_1, y_1\right), +\ldots,\left(x_m, y_m\right)\right\}` is given, +where :math:`x_i \in \mathcal{X}` is the :math:`i`-th training +instance, :math:`y_i \in \mathcal{Y}` is the corresponding ground-truth +label. These data are then used to train a classifier model :math:`f: +\mathcal{X} \mapsto \mathcal{Y}` to accurately predict the unseen data. -In Abductive Learning (ABL), we assume that, in addition to data as examples, there is also a knowledge base \mathcal{KB} containing domain knowledge at our disposal. We aim for the classifier f: \mathcal{X} \mapsto \mathcal{Y} to make correct predictions on unseen data, and meanwhile, the logical facts grounded by \left\{f(\boldsymbol{x}_1), \ldots, f(\boldsymbol{x}_m)\right\} should be compatible with \mathcal{KB}. +.. image:: ../img/ML.jpg + :width: 600px -The process of ABL is as follows: +In **Abductive Learning (ABL)**, we assume that, in addition to data as +examples, there is also a knowledge base :math:`\mathcal{KB}` containing +domain knowledge at our disposal. We aim for the classifier :math:`f: +\mathcal{X} \mapsto \mathcal{Y}` to make correct predictions on unseen +data, and meanwhile, the logical facts grounded by +:math:`\left\{f(\boldsymbol{x}_1), \ldots, f(\boldsymbol{x}_m)\right\}` +should be compatible with :math:`\mathcal{KB}`. -1. Upon receiving data inputs \left\{x_1,\dots,x_m\right\}, pseudo-labels \left\{f(\boldsymbol{x}_1), \ldots, f(\boldsymbol{x}_m)\right\} are obtained, predicted by a data-driven classifier model. -2. These pseudo-labels are then converted into logical facts \mathcal{O} that are acceptable for logical reasoning. -3. Conduct joint reasoning with \mathcal{KB} to find any inconsistencies. -4. If found, the logical facts contributing to minimal inconsistency can be identified and then modified through abductive reasoning, returning modified logical facts \Delta(\mathcal{O}) compatible with \mathcal{KB}. -5. These modified logical facts are converted back to the form of pseudo-labels, and used for further learning of the classifier. -6. As a result, the classifier is updated and replaces the previous one in the next iteration. +The process of ABL is as follows: -This process is repeated until the classifier is no longer updated, or the logical facts \mathcal{O} are compatible with the knowledge base. +1. Upon receiving data inputs :math:`\left\{x_1,\dots,x_m\right\}`, + pseudo-labels + :math:`\left\{f(\boldsymbol{x}_1), \ldots, f(\boldsymbol{x}_m)\right\}` + are predicted by a data-driven classifier model. +2. These pseudo-labels are then converted into logical facts + :math:`\mathcal{O}` that are acceptable for logical reasoning. +3. Conduct joint reasoning with :math:`\mathcal{KB}` to find any + inconsistencies. If found, the logical facts that lead to minimal + inconsistency can be identified. +4. Modify the identified facts through **abductive reasoning** (or, **abduction**), + returning revised logical facts :math:`\Delta(\mathcal{O})` which are + compatible with :math:`\mathcal{KB}`. +5. These revised logical facts are converted back to the form of + pseudo-labels, and used like ground-truth labels in conventional + supervised learning to train a new classifier. +6. The new classifier will then be adopted to replace the previous one + in the next iteration. + +This above process repeats until the classifier is no longer updated, or +the logical facts :math:`\mathcal{O}` are compatible with the knowledge +base. The following figure illustrates this process: -一张图 +.. image:: ../img/ABL.jpg + +We can observe that in the above figure, the left half involves machine +learning, while the right half involves logical reasoning. Thus, the +entire abductive learning process is a continuous cycle of machine +learning and logical reasoning. This effectively forms a paradigm that +is dual-driven by both data and domain knowledge, integrating and +balancing the use of machine learning and logical reasoning in a unified +model. -We can observe that in the above figure, the left half involves machine learning, while the right half involves logical reasoning. Thus, the entire abductive learning process is a continuous cycle of machine learning and logical reasoning. This effectively form a dual-driven (data & knowledge driven) learning system, integrating and balancing the use of machine learning and logical reasoning in a unified model. +What is Abductive Reasoning? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Abductive reasoning, also known as abduction, refers to the process of +selectively inferring certain facts and hypotheses that explain +phenomena and observations based on background knowledge. Unlike +deductive reasoning, which leads to definitive conclusions, abductive +reasoning may arrive at conclusions that are plausible but not conclusively +proven. It is often described as an ‘inference to the best explanation.’ +In Abductive Learning, given :math:`\mathcal{KB}` (typically expressed +in first-order logic clauses), one can perform deductive reasoning as +well as abductive reasoning. Deductive reasoning allows deriving +:math:`b` from :math:`a` only where :math:`b` is a formal logical +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 +“:math:`a\models b`” serves as conclusion. diff --git a/docs/README.rst b/docs/README.rst index 8d5f804..1e18c4a 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -1,9 +1,14 @@ ABL-Package =========== -ABL-Package is an open source library for Abductive Learning that supports building a model leveraging information from both data and (logical) domain knowledge. Using ABL-Package, users may form a dual-driven (data & knowledge driven) learning system, integrating and balancing the use of machine learning and logical reasoning in a unified model. +**ABL-Package** is an open source library for **Abductive Learning** +that supports building a model leveraging information from both data and +(logical) domain knowledge. Using ABL-Package, users may form a +dual-driven (data & knowledge driven) learning system, integrating and +balancing the use of machine learning and logical reasoning in a unified +model. -插一张图片 +.. image:: img/ABL.jpg Installation ------------ @@ -14,7 +19,8 @@ ABL is distributed on PyPI and can be installed with ``pip``: $ pip install abl -Alternatively, to install ABL by source code, download this project and sequentially run following commands in your terminal/command line. +Alternatively, to install ABL by source code, download this project and +sequentially run following commands in your terminal/command line. .. code:: console diff --git a/docs/img/ABL.jpg b/docs/img/ABL.jpg new file mode 100644 index 0000000..290e2c2 Binary files /dev/null and b/docs/img/ABL.jpg differ diff --git a/docs/img/ML.jpg b/docs/img/ML.jpg new file mode 100644 index 0000000..28ea46b Binary files /dev/null and b/docs/img/ML.jpg differ diff --git a/docs/index.rst b/docs/index.rst index a96258a..207afd6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,7 +1,7 @@ .. include:: README.rst .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Overview Overview/Abductive Learning @@ -9,14 +9,14 @@ Overview/Installation .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: A Brief Introduction Brief-Introduction/Components Brief-Introduction/Usage .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Examples Examples/MNISTAdd @@ -37,7 +37,7 @@ API/abl.utils .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: References References