Forgot to commit ChangeLog in last commit
[libdai.git] / README
diff --git a/README b/README
index 8267941..817a953 100644 (file)
--- a/README
+++ b/README
@@ -2,8 +2,8 @@ libDAI  -  A free/open source C++ library for Discrete Approximate Inference
 
 -------------------------------------------------------------------------------
 
-Version:  0.2.5
-Date:     May 9, 2010
+Version:  0.3.0
+Date:     July 12, 2011
 See also: http://www.libdai.org
 
 -------------------------------------------------------------------------------
@@ -11,40 +11,37 @@ 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 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.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.5: A free/open source {C}++ library for {D}iscrete {A}pproximate {I}nference",
-    howpublished = "http://www.libdai.org/",
-    year = 2010
+of this library, please cite the following paper describing libDAI:
+
+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.
+
+In BiBTeX format (for your convenience):
+
+  @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.
 
@@ -52,10 +49,10 @@ 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.
@@ -72,6 +69,10 @@ 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:
@@ -87,7 +88,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
@@ -131,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 up to 4.4.
+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
@@ -161,13 +163,15 @@ You need:
   * 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 the required packages with a single
 command:
 
-  apt-get install g++ make doxygen graphviz libboost-dev libboost-graph-dev libboost-program-options-dev libboost-test-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).
 
@@ -175,7 +179,7 @@ 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.
 
@@ -200,8 +204,11 @@ 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. Platform independent build
+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
@@ -226,7 +233,9 @@ You need:
 
   * 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:
 
@@ -253,6 +262,12 @@ Because building boost under Windows is tricky, I provide some guidance here.
 
         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