Forgot to commit ChangeLog in last commit
[libdai.git] / README
diff --git a/README b/README
index 2327a84..817a953 100644 (file)
--- a/README
+++ b/README
@@ -1,54 +1,58 @@
 libDAI  -  A free/open source C++ library for Discrete Approximate Inference
 
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+-------------------------------------------------------------------------------
 
-Version:  0.2.3
-Date:     November 16, 2009
+Version:  0.3.0
+Date:     July 12, 2011
 See also: http://www.libdai.org
 
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+-------------------------------------------------------------------------------
 
 License
 
 libDAI is free software; you can redistribute it and/or modify it under the
-terms of the GNU General Public License as published by the Free Software
-Foundation; either version 2 of the License, or (at your option) any later
-version.
+terms of the BSD 2-clause license (also known as the FreeBSD license), which
+can be found in the accompanying LICENSE file.
 
-libDAI is distributed in the hope that it will be useful, but WITHOUT ANY
-WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-PARTICULAR PURPOSE. See the GNU General Public License for more details.
+[Note: up to and including version 0.2.7, libDAI was licensed under the GNU
+General Public License (GPL) version 2 or higher.]
 
-You should have received a copy of the GNU General Public License
-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:
+of this library, please cite the following paper describing libDAI:
 
-  • 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.
+Joris M. Mooij;
+libDAI: A free & open source C++ library for Discrete Approximate Inference in graphical models;
+Journal of Machine Learning Research, 11(Aug):2169-2173, 2010.
 
-An appropriate citation would be:
-J. M. Mooij (2009) "libDAI 0.2.3: A free/open source C++ library for Discrete
-Approximate Inference", http://www.libdai.org
+In BiBTeX format (for your convenience):
 
-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.
+  @article{Mooij_libDAI_10,
+    author    = {Joris M. Mooij},
+    title     = {lib{DAI}: A Free and Open Source {C++} Library for Discrete Approximate Inference in Graphical Models},
+    journal   = {Journal of Machine Learning Research},
+    year      = 2010,
+    month     = Aug,
+    volume    = 11,
+    pages     = {2169-2173},
+    url       = "http://www.jmlr.org/papers/volume11/mooij10a/mooij10a.pdf"
+  }
 
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+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.
+
+-------------------------------------------------------------------------------
 
 About libDAI
 
-libDAI is a free/open source C++ library (licensed under GPL 2+) that provides
-implementations of various (approximate) inference methods for discrete
-graphical models. libDAI supports arbitrary factor graphs with discrete
-variables; this includes discrete Markov Random Fields and Bayesian Networks.
+libDAI is a free/open source C++ library that provides implementations of
+various (approximate) inference methods for discrete graphical models. libDAI
+supports arbitrary factor graphs with discrete variables; this includes
+discrete Markov Random Fields and Bayesian Networks.
 
 The library is targeted at researchers. To be able to use the library, a good
 understanding of graphical models is needed.
@@ -56,29 +60,36 @@ understanding of graphical models is needed.
 The best way to use libDAI is by writing C++ code that invokes the library; in
 addition, part of the functionality is accessibly by using the
 
-   command line interface
-   (limited) MatLab interface
-   (experimental) python interface
-   (experimental) octave interface.
+  * command line interface
+  * (limited) MatLab interface
+  * (experimental) python interface
+  * (experimental) octave interface.
 
 libDAI can be used to implement novel (approximate) inference algorithms and to
 easily compare the accuracy and performance with existing algorithms that have
 been implemented already.
 
+A solver using libDAI was amongst the three winners of the UAI 2010 Approximate
+Inference Challenge (see http://www.cs.huji.ac.il/project/UAI10/ for more
+information). The full source code is provided as part of the library.
+
 Features
 
 Currently, libDAI supports the following (approximate) inference methods:
 
-  • Exact inference by brute force enumeration;
-  • Exact inference by junction-tree methods;
-  • Mean Field;
-  • Loopy Belief Propagation [KFL01];
-  • Tree Expectation Propagation [MiQ04];
-  • Generalized Belief Propagation [YFW05];
-  • Double-loop GBP [HAK03];
-  • Various variants of Loop Corrected Belief Propagation [MoK07, MoR05];
-  • Gibbs sampler;
-  • Conditioned BP [EaG09].
+  * Exact inference by brute force enumeration;
+  * Exact inference by junction-tree methods;
+  * Mean Field;
+  * Loopy Belief Propagation [KFL01];
+  * Fractional Belief Propagation [WiH03];
+  * Tree-Reweighted Belief Propagation [WJW03];
+  * Tree Expectation Propagation [MiQ04];
+  * Generalized Belief Propagation [YFW05];
+  * Double-loop GBP [HAK03];
+  * Various variants of Loop Corrected Belief Propagation [MoK07, MoR05];
+  * Gibbs sampler;
+  * 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
@@ -122,7 +133,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.6.
 
 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
@@ -140,23 +151,27 @@ 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)
 
+Preparations
+
 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, or 1.37 for cygwin;
-    version 1.37 shipped with Ubuntu 9.04 is known not to work)
+  * a recent version of gcc (at least version 3.4)
+  * GNU make
+  * recent boost C++ libraries (at least version 1.37; however, version 1.37
+    shipped with Ubuntu 9.04 is known not to work)
+  * GMP library (or the Windows port called MPIR)
+  * 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 libgmp-dev cimg-dev
 
 (root permissions needed).
 
@@ -164,78 +179,125 @@ On Mac OS X (10.4 is known to work), these packages can be installed easily via
 MacPorts. If MacPorts is not already installed, install it according to the
 instructions at http://www.macports.org/. Then, a simple
 
-  sudo port install gmake boost doxygen graphviz
+  sudo port install gmake boost gmp doxygen graphviz
 
 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
 
 To build the libDAI source, first copy a template Makefile.* to Makefile.conf
 (for example, copy Makefile.LINUX to Makefile.conf if you use GNU/Linux). Then,
-edit the Makefile.conf template to adapt it to your local setup. Especially
-directories may differ from system to system. Finally, run
+edit the Makefile.conf template to adapt it to your local setup. In case you
+want to use Boost libraries which are installed in non-standard locations, you
+have to tell the compiler and linker about their locations (using the -I, -L
+flags for GCC; also you may need to set the LD_LIBRARY_PATH environment
+variable correctly before running libDAI binaries). Platform independent build
+options can be set in Makefile.ALL. Finally, run
 
   make
 
 The build includes a regression test, which may take a while to complete.
 
-If the build was successful, you can test the example program:
+If the build is successful, you can test the example program:
 
   examples/example tests/alarm.fg
 
-or the more elaborate test program:
+or the more extensive test program:
 
   tests/testdai --aliases tests/aliases.conf --filename tests/alarm.fg --methods JTREE_HUGIN BP_SEQMAX
 
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+-------------------------------------------------------------------------------
 
 Building libDAI under Windows
 
+Preparations
+
 You need:
 
-  • A recent version of MicroSoft Visual Studio (2008 works)
-  • recent boost C++ libraries (version 1.34 or higher)
-  • GNU make (can be obtained from http://gnuwin32.sourceforge.net)
+  * A recent version of MicroSoft Visual Studio (2008 is known to work)
+  * recent boost C++ libraries (version 1.37 or higher)
+  * GMP or MPIR library
+  * 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)
+  * 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 GMP or MPIR under Windows
+
+Information about how to build GPR or MPIR under Windows can be found on the
+internet. The user has to update Makefile.WINDOWS in order to link with the GPR
+/MPIR libraries.
+
+Building libDAI
 
 To build the source, copy Makefile.WINDOWS to Makefile.conf. Then, edit
-Makefile.conf to adapt it to your local setup. Finally, run (from the command
-line)
+Makefile.conf to adapt it to your local setup. Platform independent build
+options can be set in Makefile.ALL. Finally, run (from the command line)
 
   make
 
 The build includes a regression test, which may take a while to complete.
 
-If the build was successful, you can test the example program:
+If the build is successful, you can test the example program:
 
-  example tests\alarm.fg
+  examples\example tests\alarm.fg
 
-or the more elaborate test program:
+or the more extensive test program:
 
   tests\testdai --aliases tests\aliases.conf --filename tests\alarm.fg --methods JTREE_HUGIN BP_SEQMAX
 
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+-------------------------------------------------------------------------------
 
 Building the libDAI MatLab interface
 
 You need:
 
-   MatLab
-   The platform-dependent requirements described above
+  * MatLab
+  * The platform-dependent requirements described above
 
 First, you need to build the libDAI source as described above for your
 platform. By default, the MatLab interface is disabled, so before compiling the
-source, you have to enable it in the Makefile.conf by setting
+source, you have to enable it in Makefile.ALL by setting
 
   WITH_MATLAB=true
 
@@ -259,7 +321,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]')
 
@@ -267,7 +329,7 @@ where "path_to_libdai" has to be replaced with the directory in which libDAI
 was installed. For other algorithms and some default parameters, see the file
 tests/aliases.conf.
 
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+-------------------------------------------------------------------------------
 
 Building the documentation