last updated : 22/01/2008
created      : 24/07/2007

DESCRIPTION:
------------

This code implements the TLSBP algorithm [1], a particular way of
correcting the Belief Propagation (BP) solution based on a truncation
of the Loop Series Expansion proposed by Chertkov & Chernyak [2].

Notice that this is just a temporary version of the code.  Currently,
it is being integrated with libDAI [3], a more general library which
provides implementations of various (deterministic) approximate
inference methods for discrete graphical models.

A brief explanation of the TLSBP algorithm follows below. Definitions
to 'fully' understand this brief description can be found in [1,2]:

Given a probabilistic graphical model represented by a factor graph,
the algorithm applies corrections to the Pearl's Belief Propagation
result in the partition function Z and single-node marginals.  Each
correction correspond to a generalized loop in the original graph.  To
compute those generalized loops, TLSBP uses 2 parameters (S and M):

1) obtains the 2-core (subgraph where all nodes have degree two or
   more)

2) finds a set of S simple loops (circuits). B is the length of the
   largest circuit.

3) merges them iteratively using bounded DFS with M to compute complex
   loops and discarding loops with length larger than B.

The resulting set of generalized loops are used to compute corrections
to the partition function Z. Single-node marginals are calculated by
means of rations of different partition functions conditioning the
variables of the model.


REQUIREMENTS:
-------------

- libDAI:

	http://www.snn.ru.nl/~jorism/libDAI/

- Two boost libraries:

	libboost-graph-dev
	libboost_program_options



INSTALLATION:
-------------

Just edit the Makefile properly so libDAI can be found by the linker.
Then type:

$ make

This should generate an executable 'test'.



EXAMPLE:
--------

$ ./test_libDAI --filename sat1.fg --tol 1e-14 --S 100 --C 100 --B 100 --M 1 --methods JTREE[updates=HUGIN,tol=1e-14,verbose=0]

This will call the TLSBP algorithm for S=100 simple loops, a depth
bound of C=100, and with a maximum loop length of 100. Single-node marginals
will be computed using the conditioning method.

The error is computed using the Junction Tree, which is provided by
the libDAI library by means of the argument --methods:
JTREE[updates=HUGIN,verbose=0]

After the above command you should see an output like the following:

-------------------------------------------------------------

(....)

42 loops considered 
Spent 41 time units (0 scnds) computing marginals

logZ_exact  = 10.164571130409 25966.723461498
logZ_tlsbp  = 10.164571130409 25966.723461498
logZ_bp     = 10.171910731719 26158.009983718

err_Z_bp    = 0.0073396013097522
err_b_bp    = 0.025041464950006

err_Z_tlsbp = 1.7763568394003e-15
err_b_tlsbp = 1.942890293094e-15
-------------------------------------------------------------

Which indicates that 42 loops have been found, and that the BP error,
which is 0.007 in the partition function and 0.025 in the single-node
marginals, is corrected up to machine precision (1e-14) after applying
the loop corrections.

There is another example in the context of SAT within the file sat1.fg

$ ./test_libDAI --filename ising3x3.fg --tol 1e-14 --S 100 --C 100 --B 100 --M 1 --methods JTREE[updates=HUGIN,tol=1e-14,verbose=0]

-----------

The code provided here has no warranty. If you do experience problems
using it, please let me know via email.

Vicenç Gomez,
vgomez@iua.upf.edu



REFERENCES:
-----------

[1] "Truncating the loop series expansion for Belief Propagation"
    V. Gómez, J.M. Mooij, H.J. Kappen
		Journal of Machine Learning Research 8(Sep):1987--2016, 2007.
		http://jmlr.csail.mit.edu/papers/v8/gomez07a.html	

[2] "Loop series for discrete statistical models on graphs"
    M. Chertkov, V.Y. Chernyak
		Journal of Statistical Mechanics: Theory and Experiment (2006) P06009
    http://arxiv.org/abs/cond-mat/0603189

[3] "libDAI - A free/open source C++ library for Discrete Approximate
    Inference methods"
    J.M. Mooij
    http://www.snn.ru.nl/~jorism/libDAI/
