diff --git a/README.md b/README.md index fa208dc..ee65b02 100644 --- a/README.md +++ b/README.md @@ -7,13 +7,13 @@ The dPASP framework provides a high-level declarative language for describing -sophisticated probabilistic reasoning tasks that can combine perception and logical reasoning. -dPASP programs are made of probabilistic choices and logic rules (think of if-then rules), allowing +sophisticated probabilistic reasoning tasks that can combine perception and logical reasoning. +dPASP programs are made of probabilistic choices and logic rules (think of if-then rules), allowing easy specification of uncertain and logic knowledge. Notably, the probabilities in the program -can arise as outputs of neural network classifiers, and both the statistical model and logic program can be jointly optimized +can arise as outputs of neural network classifiers, and both the statistical model and logic program can be jointly optimized by making use of efficient gradient-based learning libraries (e.g. PyTorch). -## Getting Started +## Getting Started dPASP has both a domain-specific language (DSL) and command-line interpreter (parser) for that language, which can be used as a standalone tool. Alternatively, dPASP can be accessed as Python library or more directly through its C backend. @@ -36,7 +36,7 @@ dPASP allows for several semantics by combining logic programming semantics and - Credal semantics; - MaxEnt semantics. -There are two uses of the systems: learning and querying. +There are two uses of the systems: learning and querying. Currently, learning is only available for the MaxEnt-Stable semantics. Learning and querying can either be made by (highly inneficient) enumerative algorithms and (more efficient) approximate inference. @@ -45,37 +45,58 @@ Developing more efficient and accurate approximate algorithms is a current activ ## Example -Here's a simple example of dPASP for inference in probabilistic logic programs (no neural networks and no learning). +Here's a simple example of dPASP for inference in probabilistic logic programs (no neural networks and no learning). Assuming you have dPASP installed and configured (see the [tutorial](http://kamel.ime.usp.br/pages/learn_dpasp) if not), open a Python Shell and load the Python library by: +```bash +pasp examples/earthquake.plp +``` + +One may need to manipulate output probabilities, in which case the Python API can be used instead. + ```python import pasp ``` -We can specify a probabilistic logic program string using dPASP DSL. -Here a program enconding graph 3-coloring property (lines starting with `%` are comments): +To parse the program into dPASP internal's data struct we use + +```python +P = pasp.parse("examples/earthquake.plp") +``` + +We can also specify a probabilistic logic program string using the dPASP DSL. +Here we have a program enconding graph 3-coloring (lines starting with `%` are comments): ``` python program_str = ''' -% DOMAIN +% Build a random graph with n vertices. #const n = 5. -vertex(1..n). -% Specifies a random graph -0.5::edge(X, Y) :- vertex(X), vertex(Y), X < Y. -edge(X, Y) :- e(Y, X). -% Disjunctive specify specify candidate solutions -color(X, red); color(X,blue); color(X,green) :- vertex(X). -% Constraints discard invalid candidate solutions -:- edge(X, Y), color(X, Z), color(Y, Z). -% We use directives to select a semantics (other options are `partial`, `lstable`, `credal`) -#semantics maxent. -% Directive also specify the query, in this case the probability that node 1 is colored red -#query color(1,red). -''' +v(1..n). +% The choice of p reflects the sparsity/density of the random graph. +% A small p produces sparser graphs, while a large p prefers denser graphs. +0.5::e(X, Y) :- v(X), v(Y), X < Y. +e(X, Y) :- e(Y, X). +% A color (here the predicate c/2) defines a coloring of a vertex. +% The next three lines define the uniqueness of a vertex's color. +c(X, r) :- not c(X, g), not c(X, b), v(X). +c(X, g) :- not c(X, r), not c(X, b), v(X). +c(X, b) :- not c(X, r), not c(X, g), v(X). +% Produce a contradiction if two neighbors have the same color. +f :- not f, e(X, Y), c(X, Z), c(Y, Z). + +#semantics lstable. + +% Query the probability of vertex a being red. +#query(c(1, r)). +% Query the probability of the edge e(1, 2) existing given that the graph is not 3-colorable. +#query(e(1, 2) | undef f). +% Query the probability of the graph not being 3-colorable. +#query(undef f).''' ``` -To parse the program into dPASP internal's data struct we use +We may then pass `program_str` to dPASP as a string by using the `from_str=True` keyword. + ```python P = pasp.parse(program_str, from_str=True) ``` @@ -83,18 +104,43 @@ P = pasp.parse(program_str, from_str=True) You can check that the program was correctly parsed by inspecting the object `P` ```python ->>> P() -``` - -To run exact (enumerative) inference, do: -``` -pasp.exact(P) +>>> P + ``` -You can also run inference with a specified semantics: -To run exact (enumerative) inference, do: -``` -pasp.exact(P, psemantics="credal", semantics="stable") +To run the program: +```python +>>> P() +ℙ(c(1,r)) = [0.000000, 1.000000] +ℙ(e(1,2) | undef f) = [0.772727, 0.772727] +ℙ(undef f) = [0.064453, 0.064453] +--- +Querying: 0h00m01s +array([[0. , 1. ], + [0.77272727, 0.77272727], + [0.06445312, 0.06445312]]) ``` ## Acknowledgments @@ -102,4 +148,4 @@ pasp.exact(P, psemantics="credal", semantics="stable") This software is being developed by the [KAMeL group](https://kamel.ime.usp.br) and the [Center for Artificial Intelligence](https://c4ai.inova.usp.br/) of the University of São Paulo. If you use this software, please acknowledge by citing the paper below: - https://arxiv.org/abs/2308.02944 + https://proceedings.kr.org/2024/69/ diff --git a/examples/3coloring.plp b/examples/3coloring.plp index 94e0fe6..86e55db 100644 --- a/examples/3coloring.plp +++ b/examples/3coloring.plp @@ -13,6 +13,8 @@ c(X, b) :- not c(X, r), not c(X, g), v(X). % Produce a contradiction if two neighbors have the same color. f :- not f, e(X, Y), c(X, Z), c(Y, Z). +#semantics lstable. + % Query the probability of vertex a being red. #query(c(1, r)). % Query the probability of the edge e(1, 2) existing given that the graph is not 3-colorable.