- [Frederik Eaton]: Misc smaller changes
[libdai.git] / README
diff --git a/README b/README
index 01c35f0..1d5abbf 100644 (file)
--- a/README
+++ b/README
@@ -1,2 +1,200 @@
-Test. First commit...
-Test continues. Second commit.
+libDAI - A free/open source C++ library for Discrete Approximate Inference methods
+==================================================================================
+
+v 0.2.2 - September 30, 2008
+
+
+Copyright (C) 2006-2008  Joris Mooij  [joris dot mooij at tuebingen dot mpg dot de]
+Radboud University Nijmegen, The Netherlands /
+Max Planck Institute for Biological Cybernetics, Germany
+
+with contributions from:
+
+Martijn Leisink
+Giuseppe Passino
+Frederik Eaton
+Bastian Wemmenhove
+Christian Wojek
+Claudio Lima
+Jiuxiang Hu
+Peter Gober
+Patrick Pletscher
+
+
+----------------------------------------------------------------------------------
+This file is part of libDAI.
+
+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.
+
+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.
+
+You should have received a copy of the GNU General Public License
+along with libDAI; if not, write to the Free Software
+Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+----------------------------------------------------------------------------------
+
+
+SCIENTISTS: If you write a scientific paper describing research that made 
+substantive use of this program, please (a) mention the fashion in which 
+this software was used, including the version number, with a citation 
+to the literature, to allow replication; (b) mention this software in the 
+Acknowledgements section.  The appropriate citation is: 
+
+J. M. Mooij (2008) "libDAI 0.2.2: A free/open source C++ library for Discrete 
+Approximate Inference methods", http://mloss.org/software/view/77/.
+
+Moreover, as a personal note, I would appreciate it if you would email me with
+citations of papers referencing this work so I can mention them to my funding
+agent and tenure committee.
+
+
+About libDAI
+------------
+libDAI is a free/open source C++ library (licensed under GPL) 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.
+
+
+Limitations
+-----------
+libDAI is not intended to be a complete package for approximate inference.
+Instead, it should be considered as an "inference engine", providing various
+inference methods. In particular, it contains no GUI, currently only supports
+its own file format for input and output (although support for standard file
+formats may be added later), and provides very limited visualization
+functionalities.
+
+
+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.
+
+
+Why C++?
+--------
+Because libDAI is implemented in C++, it is very fast compared with
+implementations in MatLab (a factor 1000 faster is not uncommon). libDAI does
+provide a MatLab interface for easy integration with MatLab.
+
+
+Releases
+--------
+Releases can be obtained from http://mloss.org/software/view/77/
+License: GNU Public License v2 (or higher).
+
+libDAI-0.2      December 1, 2006
+libDAI-0.2.1    May 26, 2008
+libDAI-0.2.2   September 30, 2008
+
+
+Acknowledgments
+---------------
+This work is part of the Interactive Collaborative Information Systems (ICIS) 
+project, supported by the Dutch Ministry of Economic Affairs, grant BSIK03024. 
+I would like to thank Martijn Leisink for providing the basis on which libDAI has been built.
+
+
+Documentation
+-------------
+Some doxygen documentation is available. Install doxygen and use "make doc" to build the
+documentation. If the documentation is not clear enough, feel free to send me an email 
+(or even better, to improve the documentation!).
+
+A description of the factor graph (.fg) file format can be found in the file FILEFORMAT.
+
+
+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 has also been successfully compiled with MS Visual Studio 2008 under Windows
+(but not all build targets are supported yet) and with Cygwin under Windows.
+
+Finally, libDAI has been compiled successfully on MacOS X.
+
+
+Quick start (linux/cygwin/Mac OS X)
+-----------------------------------
+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)
+
+On Debian/Ubuntu, you can easily install all these packages with a single command:
+"apt-get install g++ make doxygen graphviz libboost-dev libboost-graph-dev libboost-program-options-dev"
+(root permissions needed).
+
+On Mac OS X (10.4 is known to work), these packages can be installed easily via MacPorts.
+First, install MacPorts according to the instructions at http://www.macports.org/
+Then, a simple "sudo port install gmake boost 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:
+
+  ./configure
+  make
+  make install
+
+
+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 change from system to system. Finally, run
+    
+    make
+
+If the build was successful, you can test the example program:
+
+    ./example tests/alarm.fg
+
+or the more elaborate test program:
+
+    tests/testdai --aliases tests/aliases.conf --filename tests/alarm.fg --methods JTREE_HUGIN BP_SEQMAX
+
+
+Quick start (Windows)
+---------------------
+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)
+For the regression test, you need:
+- GNU diff, GNU sed (can be obtained from http://gnuwin32.sourceforge.net)
+
+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)
+    
+    make
+
+If the build was successful, you can test the example program:
+
+    example tests\alarm.fg
+
+or the more elaborate test program:
+
+    tests\testdai --aliases tests\aliases.conf --filename tests\alarm.fg --methods JTREE_HUGIN BP_SEQMAX