meta: examples: update citation and example, fix 3coloring example

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,61 +45,107 @@ 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)
 ```
 
 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
+<Logic Program:
+#const n = 5.
+v(1..n).
+e(X, Y) :- e(Y, X).
+_e(X, Y) :- _e(Y, X).
+c(X, r) :- not _c(X, g), not _c(X, b), v(X).
+_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, g) :- not c(X, r), not c(X, b), _v(X).
+c(X, b) :- not _c(X, r), not _c(X, g), v(X).
+_c(X, b) :- not c(X, r), not c(X, g), _v(X).
+f :- not _f, e(X, Y), c(X, Z), c(Y, Z).
+_f :- not f, _e(X, Y), _c(X, Z), _c(Y, Z).
+_c(X, g) :- c(X, g).
+_e(X, Y) :- e(X, Y).
+_c(X, b) :- c(X, b).
+_f :- f.
+_c(X, r) :- c(X, r).
+_v(1..n) :- v(1..n).,
+Probabilistic Rules:
+[0.5::e(X, Y) :- v(X), v(Y), X < Y],
+Queries:
+[ℙ(c(1,r)), ℙ(e(1,2) | undef f), ℙ(undef f)]>
 ```
 
-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
 
 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/

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.