Improved VarSet and the GIBBS alias
[libdai.git] / README
diff --git a/README b/README
index 65b534e..068c130 100644 (file)
--- a/README
+++ b/README
@@ -3,7 +3,7 @@ libDAI  -  A free/open source C++ library for Discrete Approximate Inference
 -------------------------------------------------------------------------------
 
 Version:  git HEAD
-Date:     February 11, 2010 - or later
+Date:     May 12, 2010, or later
 See also: http://www.libdai.org
 
 -------------------------------------------------------------------------------
@@ -27,29 +27,26 @@ along with libDAI in the file COPYING. If not, see http://www.gnu.org/licenses/
 Citing libDAI
 
 If you write a scientific paper describing research that made substantive use
-of this program, please:
-
-  * mention the fashion in which this software was used, including the version
-    number, with a citation to the literature, to allow replication;
-  * mention this software in the Acknowledgements section.
+of this program, please cite the software appropriately, by mentioning the
+fashion in which this software was used, including the version number.
 
 An appropriate citation would be:
 
-Joris M. Mooij et al. (2010) "libDAI 0.2.4: A free/open source C++ library for
+Joris M. Mooij et al. (2010) "libDAI 0.2.5: A free/open source C++ library for
 Discrete Approximate Inference", http://www.libdai.org
 
 or in BiBTeX format:
 
   @misc{mooij2010libdai,
     author = "Joris M. Mooij et al.",
-    title = "lib{DAI} 0.2.4: A free/open source {C}++ library for {D}iscrete {A}pproximate {I}nference",
+    title = "lib{DAI} 0.2.5: A free/open source {C}++ library for {D}iscrete {A}pproximate {I}nference",
     howpublished = "http://www.libdai.org/",
     year = 2010
   }
 
 
-Moreover, as a personal note, I would appreciate it if you would email
-(citations of) papers referencing this work to joris dot mooij at libdai dot org.
+Moreover, as a personal note, I would appreciate it to be informed about any
+publications using libDAI at joris dot mooij at libdai dot org.
 
 -------------------------------------------------------------------------------
 
@@ -90,7 +87,8 @@ Currently, libDAI supports the following (approximate) inference methods:
   * Double-loop GBP [HAK03];
   * Various variants of Loop Corrected Belief Propagation [MoK07, MoR05];
   * Gibbs sampler;
-  * Conditioned Belief Propagation [EaG09].
+  * Conditioned Belief Propagation [EaG09];
+  * Decimation algorithm.
 
 These inference methods can be used to calculate partition sums, marginals over
 subsets of variables, and MAP states (the joint state of variables that has
@@ -134,7 +132,7 @@ provides a command line interface and experimental python and octave interfaces
 Compatibility
 
 The code has been developed under Debian GNU/Linux with the GCC compiler suite.
-libDAI compiles successfully with g++ versions 3.4, 4.1, 4.2 and 4.3.
+libDAI compiles successfully with g++ versions 3.4 up to 4.4.
 
 libDAI has also been successfully compiled with MS Visual Studio 2008 under
 Windows (but not all build targets are supported yet) and with Cygwin under
@@ -151,6 +149,7 @@ Mailing list
 
 The Google group "libDAI" (http://groups.google.com/group/libdai) can be used
 for getting support and discussing development issues.
+
 -------------------------------------------------------------------------------
 
 Building libDAI under UNIX variants (Linux / Cygwin / Mac OS X)
@@ -161,16 +160,16 @@ You need:
 
   * a recent version of gcc (at least version 3.4)
   * GNU make
-  * doxygen
-  * graphviz
-  * recent boost C++ libraries (at least version 1.34 if you have a recent
-    version of GCC, otherwise at least version 1.37; however, version 1.37
+  * recent boost C++ libraries (at least version 1.37; however, version 1.37
     shipped with Ubuntu 9.04 is known not to work)
+  * doxygen (only for building the documentation)
+  * graphviz (only for using some of the libDAI command line utilities)
+  * CImg library (only for building the image segmentation example)
 
-On Debian/Ubuntu, you can easily install all these packages with a single
+On Debian/Ubuntu, you can easily install the required packages with a single
 command:
 
-  apt-get install g++ make doxygen graphviz libboost-dev libboost-graph-dev libboost-program-options-dev
+  apt-get install g++ make doxygen graphviz libboost-dev libboost-graph-dev libboost-program-options-dev libboost-test-dev cimg-dev
 
 (root permissions needed).
 
@@ -184,12 +183,20 @@ should be enough to install everything that is needed.
 
 On Cygwin, the prebuilt Cygwin package boost-1.33.1-x is known not to work. You
 can however obtain the latest boost version (you need at least 1.37.0) from
-http://www.boost.org/ and compile/install it with:
+http://www.boost.org/ and build it as described in the next subsection.
 
-  ./configure
-  make
-  make install
+Building boost under Cygwin
+
+  * Download the latest boost libraries from http://www.boost.org
+  * Build the required boost libraries using:
+
+        ./bootstrap.sh --with-libraries=program_options,math,graph,test --prefix=/boost_root/
+        ./bjam
 
+  * In order to use dynamic linking, the boost .dll's should be somewhere in
+    the path. This can be achieved by a command like:
+
+        export PATH=$PATH:/boost_root/stage/lib
 
 Building libDAI
 
@@ -222,11 +229,33 @@ You need:
   * A recent version of MicroSoft Visual Studio (2008 is known to work)
   * recent boost C++ libraries (version 1.37 or higher)
   * GNU make (can be obtained from http://gnuwin32.sourceforge.net)
+  * CImg library (only for building the image segmentation example)
 
 For the regression test, you need:
 
   * GNU diff, GNU sed (can be obtained from http://gnuwin32.sourceforge.net)
 
+Building boost under Windows
+
+Because building boost under Windows is tricky, I provide some guidance here.
+
+  * Download the boost zip file from http://www.boost.org/users/download and
+    unpack it somewhere.
+  * Download the bjam executable from http://www.boost.org/users/download and
+    unpack it somewhere else.
+  * Download Boost.Build (v2) from http://www.boost.org/docs/tools/build/
+    index.html and unpack it yet somewhere else.
+  * Edit the file boost-build.jam in the main boost directory to change the
+    BOOST_BUILD directory to the place where you put Boost.Build (use UNIX /
+    instead of Windows \ in pathnames).
+  * Copy the bjam.exe executable into the main boost directory. Now if you
+    issue "bjam --version" you should get a version and no errors. Issueing
+    "bjam --show-libraries" will show the libraries that will be built.
+  * The following command builds the boost libraries that are relevant for
+    libDAI:
+
+        bjam --with-graph --with-math --with-program_options --with-test link=static runtime-link=shared
+
 Building libDAI
 
 To build the source, copy Makefile.WINDOWS to Makefile.conf. Then, edit
@@ -280,7 +309,7 @@ at the MatLab prompt), which performs exact inference by the junction tree
 algorithm and approximate inference by belief propagation on the ALARM network:
 
   cd path_to_libdai/matlab
-  [psi] = dai_readfg ('../examples/alarm.fg');
+  [psi] = dai_readfg ('../tests/alarm.fg');
   [logZ,q,md,qv,qf] = dai (psi, 'JTREE', '[updates=HUGIN,verbose=0]')
   [logZ,q,md,qv,qf] = dai (psi, 'BP', '[updates=SEQMAX,tol=1e-9,maxiter=10000,logdomain=0]')