Package: equibel
Equibelis a Python package for working with consistency-based belief change in a
graph-oriented setting.Currently Supported PlatformsMac OS X (tested on OS X 10.10.5) with Python 2.7.x64-bit Linux (tested on Ubuntu 14.04) with Python 2.7.xNote that while Equibel is distributed as a Python package, the core of the system is
implemented using Answer Set Programming (ASP), and relies on an underlying ASP solver
calledclingo, which is part of thePotsdam Answer Set Solving Collection (Potassco).In particular, Equibel has two ASP-related dependencies: thePython gringo module, which
provides an interface to an ASP solver from within Python, andasprin.parser,
which is a component of theasprinpreference-handling framework.asprinis described
in more detailhere, and can be downloaded
fromhere.ThePythoncomponent of Equibel is highly portable across platforms; however, thegringoandasprin.parserdependencies must be compiled for specific system configurations,
producing system-specific binaries. In order to simplify usage for somecommonsystem
configurations, Equibel includes pre-compiled binaries of these dependencies for
64-bit Ubuntu Linux and Mac OS.If Equibel does not function correctly once it is installed, this is likely due to the fact that the pre-compiled binaries are not compatible with your system.In this case, you must compile the dependencies manually, by downloading the required
components directly fromPotassco.
In order to use your custom binaries with Equibel, it is recommended that you follow the
installation instructions given on theGithub project page, which involve downloading
the source code of Equibel to provide access to directories in which you can overwrite the
included binaries with your own.InstallationThe following steps assume that you have thepipPython package manager
installed. If you don’t havepip, you can get ithere.The pre-compiledgringomodules included with Equibel for
either 64-bit Linux or Mac OS require a dependency called
Threading Building Blocks (tbb).The easiest way to install thetbblibrary onMac OSis to
useHomebrew:$ brew install tbbOnUbuntu Linux, thetbblibrary can be installed using
theaptpackage manager:$ sudo apt-get install libtbb-devInstall Equibel usingpip:$ pip install equibelIf you are installing Equibel system-wide, you may need to usesudo:$ sudo pip install equibelQuickstartTo use Equibel within a Python program, you need to import theequibelpackage. The statementimport equibel as ebimports this package,
and gives it a shorter aliaseb. The following Python script
creates a path graph, assigns formulas to nodes, finds the global
completion, and prints the resulting formulas at each node:importequibelasebif__name__=='__main__':# Create an EquibelGraph object, which represents a graph and# associated scenario.G=eb.EquibelGraph()# Create nodes:G.add_nodes_from([1,2,3,4])# Create edges:G.add_edges_from([(1,2),(2,3),(3,4)])# Add formulas to nodes:G.add_formula(1,"p & q & r")G.add_formula(4,"~p & ~q")# Find the global completion of the G-scenario:R=eb.global_completion(G,simplify=True)# Pretty-print the resulting formulas at each node:eb.print_formulas(R)If the above code is saved in a file calledcompletion.py, then it can be run by typingpython completion.pyat the command line, as follows:$ python completion.py
Node 1:
p ∧ q ∧ r
Node 2:
r
Node 3:
r
Node 4:
r ∧ ¬p ∧ ¬qIf you get an error running this example, it is most likely due to thedependenciesof
Equibel not being compatible with your platform. As noted above, Equibel includes
pre-compiled binaries of the Pythongringomodule, as well as ofasprin.parser,
for 64-bit Linux distributions (tested on Ubuntu 14.04) and for Mac OS (tested on OSX 10.10.5).
If you are not using one of these systems, you will need to manually compile thegringoandasprin.parserdependencies (seethe Github page).Implemented ApproachesEquibel allows for experimentation with several different approaches to
consistency-based belief change in a graph-oriented setting, namely:Global completionSimple iterationExpanding iterationAugmenting iterationRing iterationThe global completion operation is performed on anEquibelGraphGbyeb.global_completion(G); this performs a “one-shot” procedure to update
the information at every node in the graph, and thus is not an iterative approach. All
of the other approaches—simple,expanding,augmenting, andring—can be performed
iteratively, and each one iterates to afixpoint. The table below summarizes the Equibel
functions used to perform single iterations of each approach, as well as to find the fixpoints
reached by each approach:MethodSingle IterationIterate to FixpointSimple Iterationeb.iterate_simple(G)eb.iterate_simple_fixpoint(G)Expanding Iterationeb.iterate_expanding(G)eb.iterate_expanding_fixpoint(G)Augmenting Iterationeb.iterate_augmenting(G)eb.iterate_augmenting_fixpoint(G)Ring Iterationeb.iterate_ring(G)eb.iterate_ring_fixpoint(G)Each of the approaches has two separate implementations, corresponding to its equivalentsemanticandsyntacticcharacterizations. In addition, there are two ways of performing the core optimization
procedure over equivalences, involving eitherinclusion-basedorcardinality-basedmaximization.Each function listed above can take three optional arguments:method, which is a string that is either “semantic” or “syntactic”,
representing the method to use when performing the approach; e.g.
based on either the syntactic or semantic characterizationsThe defaultmethodissemanticTo avoid typos when entering strings, Equibel has constantseb.SEMANTICandeb.SYNTACTICwhich equal the strings “semantic” and “syntactic”, respectively.opt_type, which is a string that is either “inclusion” or “cardinality”,
representing the type of maximization to be performed over equivalencesThe defaultopt_typeisinclusionTo avoid typos when entering strings, Equibel has constantseb.INCLUSIONandeb.CARDINALITYwhich equal the strings “inclusion” and “cardinality”, respectively.simplify, which is a Boolean flag specifying whether to simplify the
final formulas at each node.The default value forsimplifyisFalseBy definition, the semantic and syntactic characterizations of an approach yieldequivalent results; however, depending on the input scenario and type of approach, the
performance of the characterizations may differ significantly. A good example of this is
in the case of expanding iteration, where we have anearly-stoppping conditionover the
radius of the expanding neighbourhood when using the semantic characterization, but not when
using the syntactic characterization (causing the semantic characterization to be significantly
faster for large graphs in practice).Some ExamplesTo show how themethodandopt_typearguments can be combined, we consider the following
(by no means exhaustive) examples.In the following example, we can see the difference between using inclusion-based optimization and
cardinality-based optimization in the global completion:importequibelasebif__name__=='__main__':# Creates a star graph with nodes [0, 1, 2, 3] and undirected edges [(0,1), (0,2), (0,3)]G=eb.star_graph(3)G.add_formula(1,'p')G.add_formula(2,'p')G.add_formula(3,'~p')# Using inclusion-based maximization over equivalencesR_inclusion=eb.global_completion(G,method=eb.SEMANTIC,opt_type=eb.INCLUSION,simplify=False)eb.print_formulas(R_inclusion)# Using cardinality-based maximization over equivalencesR_cardinality=eb.global_completion(G,method=eb.SEMANTIC,opt_type=eb.CARDINALITY,simplify=False)eb.print_formulas(R_cardinality)Saving this code in a fileinclusion_vs_cardinality.pyand running it yields:$ python inclusion_vs_cardinality.py
Node 0:
p ∨ ¬p
Node 1:
p
Node 2:
p
Node 3:
¬p


Node 0:
p
Node 1:
p
Node 2:
p
Node 3:
¬pThe following example function calls for the global completion operation show the flexible way in
which options can be combined in Equibel:R_semantic = eb.global_completion(G)This function call computes the global completion ofG.
With no options explicitly specified, the defaults are used; thus,
this call involves thesemantic characterizationwithinclusion-basedoptimization, and does not simplify the resultant formulas.With all options explicitly specified, the above function call is
equivalent toR_semantic = eb.global_completion(G, method=eb.SEMANTIC, opt_type=eb.INCLUSION, simplify=False)R_syntactic = eb.global_completion(G, method=eb.SYNTACTIC)This finds the global completion ofG, using thesyntactic
characterization, the defaultinclusion-basedoptimization, and no simplification
of formulas.R_syntactic = eb.global_completion(G, method=eb.SYNTACTIC, opt_type=CARDINALITY)This finds the global completion ofG, using thesyntactic
characterization,cardinality-basedoptimization, and no simplification of
formulas.R_syntactic = eb.global_completion(G, method=eb.SYNTACTIC, opt_type=CARDINALITY, simplify=True)This finds the global completion ofG, using thesyntactic
characterizationandcardinality-basedoptimization.
With thesimplify=Trueoption, the resulting scenario
will have simplified formulas for each node in the graph.These options can be similarly combined for each of the iterative approaches, as shown in the
following example calls:R_semantic = eb.iterate_simple(G, method=eb.SEMANTIC, simplify=True)This function call computes the graph and scenario that result
from performing a singlesimple iterationoverG, using thesemantic
characterizationwith defaultinclusion-basedoptimization. With thesimplify=Trueoption, the resulting scenario will have simplified formulas
for each node in the graph.R_syntactic = eb.iterate_simple(G, method=eb.SYNTACTIC, simplify=True)This call is similar to the previous call, except that it uses thesyntactic characterizationof simple iteration, rather than the semantic
characterization.R_semantic_fixpoint = eb.iterate_simple_fixpoint(G, method=eb.SEMANTIC, opt_type=eb.CARDINALITY, simplify=True)This computes the fixpoint reached by a sequence ofsimple
iterationsstarting from the graph and scenario represented byG,
using thesemantic characterizationandcardinality-basedoptimization.R_semantic = eb.iterate_expanding(G, simplify=True)This function call computes the graph and scenario that result
from performing a singleexpanding iterationoverG, using the defaultsemantic
characterizationwith defaultinclusion-basedoptimization. Sincesimplify=True,
the resulting scenario will have simplified formulas for each node in the graph.R_semantic = eb.iterate_augmenting_fixpoint(G, simplify=True)This computes the fixpoint reached by a sequence ofaugmenting
iterationsstarting from the graph and scenario represented byG, using the defaultsemantic characterizationandinclusion-basedoptimization. Sincesimplify=True, the
resulting scenario will have simplified formulas for each node in the graph.