Several improvements:
authorJoris Mooij <joris.mooij@tuebingen.mpg.de>
Thu, 12 Nov 2009 15:36:54 +0000 (16:36 +0100)
committerJoris Mooij <joris.mooij@tuebingen.mpg.de>
Thu, 12 Nov 2009 15:36:54 +0000 (16:36 +0100)
- Improved documentation in include/dai/doc.h
- README is now created automatically from doxygen documentation
- Makefile macros DAI_VERSION and DAI_DATE have been introduced,
  in order to store this information in a central place
- Renamed "ConditionalProbEstimation" into "CondProbEstimation"
- Variable labels are now nonnegative (of type size_t)
- Tiny change to .tab file format (added empty line after header)
- Other cleanups

36 files changed:
AUTHORS [new file with mode: 0644]
ChangeLog
Makefile
Makefile.CYGWIN
Makefile.LINUX
Makefile.MACOSX
Makefile.WINDOWS
README
TODO
doxygen.conf
include/dai/bp_dual.h
include/dai/cbp.h
include/dai/daialg.h
include/dai/doc.h
include/dai/emalg.h
include/dai/factorgraph.h
include/dai/hak.h
include/dai/index.h
include/dai/util.h
include/dai/var.h
scripts/makeREADME [new file with mode: 0755]
src/bp.cpp
src/cbp.cpp
src/emalg.cpp
src/evidence.cpp
src/factorgraph.cpp
tests/testem/2var.em
tests/testem/2var_data.tab
tests/testem/3var.em
tests/testem/hoi1_data.tab
tests/testem/hoi1_infer_f2.em
tests/testem/hoi1_share_f0_f1_f2.em
tests/testem/hoi1_share_f0_f2.em
utils/createfg.cpp
utils/fg2dot.cpp
utils/fginfo.cpp

diff --git a/AUTHORS b/AUTHORS
new file mode 100644 (file)
index 0000000..5770abe
--- /dev/null
+++ b/AUTHORS
@@ -0,0 +1,17 @@
+The following people have contributed to libDAI (in order of importance):
+
+Joris Mooij
+Martijn Leisink
+Frederik Eaton
+Charlie Vaske
+Giuseppe Passino
+Bastian Wemmenhove
+Christian Wojek
+Claudio Lima
+Jiuxiang Hu
+Peter Gober
+Patrick Pletscher
+Sebastian Nowozin
+
+This work is part of the Interactive Collaborative Information Systems (ICIS) 
+project, supported by the Dutch Ministry of Economic Affairs, grant BSIK03024.
index 7c5ae06..24b2d5a 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+* README is now created automatically from doxygen documentation
+* Makefile macros DAI_VERSION and DAI_DATE have been introduced,
+  in order to store this information in a central place
+* Renamed "ConditionalProbEstimation" into "CondProbEstimation"
+* Variable labels are now nonnegative (of type size_t)
+* Tiny change to .tab file format (added empty line after header)
 * Renamed Treewidth(const FactorGraph &) into boundTreewidth(const FactorGraph &)
 * Added ExactInf::calcMarginal(const VarSet &)
 * Replaced UEdgeVec by Graph
index 7ff3579..da640c0 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -292,6 +292,7 @@ endif
 
 doc : $(INC)/*.h $(SRC)/*.cpp examples/*.cpp doxygen.conf
        doxygen doxygen.conf
+       DAI_VERSION=$(DAI_VERSION) DAI_DATE=$(DAI_DATE) scripts/makeREADME
 
 TAGS:
        etags src/*.cpp include/dai/*.h tests/*.cpp utils/*.cpp
index 47ec495..f07f7a6 100644 (file)
@@ -87,3 +87,7 @@ SWIG=swig
 INCLUDE_PYTHON=/usr/include/python2.5
 # Location of Boost C++ library header files
 INCLUDE_BOOST=/usr/local/include/boost-1_37
+
+# VERSION AND DATE
+DAI_VERSION="not set"
+DAI_DATE="not set"
index 11bab16..7fe8660 100644 (file)
@@ -86,3 +86,7 @@ SWIG=swig
 INCLUDE_PYTHON=/usr/include/python2.5
 # Location of Boost C++ library header files
 INCLUDE_BOOST=/usr/include/boost
+
+# VERSION AND DATE
+DAI_VERSION="git $(shell git log | head -1)"
+DAI_DATE="$(shell git log | head -3 | tail -1 | sed 's/Date:   //')"
index 2fb813d..c87fb67 100644 (file)
@@ -86,3 +86,7 @@ SWIG=swig
 INCLUDE_PYTHON=/usr/include/python2.5
 # Location of Boost C++ library header files
 INCLUDE_BOOST=/usr/include/boost
+
+# VERSION AND DATE
+DAI_VERSION="not set"
+DAI_DATE="not set"
index 986c086..5a2fa4e 100644 (file)
@@ -88,3 +88,7 @@ SWIG=swig
 INCLUDE_PYTHON=C:\python2.5
 # Location of Boost C++ library header files
 INCLUDE_BOOST=C:\boost_1_36_0
+
+# VERSION AND DATE
+DAI_VERSION="not set"
+DAI_DATE="not set"
diff --git a/README b/README
index f64e8d0..0ea97a6 100644 (file)
--- a/README
+++ b/README
-libDAI - A free/open source C++ library for Discrete Approximate Inference methods
-==================================================================================
+libDAI  -  A free/open source C++ library for Discrete Approximate Inference
 
-v 0.2.2 - September 30, 2008
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-----------------------------------------------------------------------------------
+Version:  git commit 76cf77837c617f54202590125c7a566ae443d0ab
+Date:     Thu Nov 12 10:52:51 2009 +0100
+See also: http://www.libdai.org
 
-This file is part of libDAI - http://www.libdai.org/
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-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.
+License
 
-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.
+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.
 
-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/
-
-----------------------------------------------------------------------------------
+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.
 
-Copyright (C) 2006-2009  Joris Mooij  [joris dot mooij at libdai dot org]
-Copyright (C) 2002-2007  Radboud University Nijmegen, The Netherlands
-Copyright (C) 2002       Martijn Leisink  [martijn@mbfys.kun.nl]
-
-with contributions from:
+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/
 
-Martijn Leisink
-Giuseppe Passino
-Frederik Eaton
-Charlie Vaske
-Bastian Wemmenhove
-Christian Wojek
-Claudio Lima
-Jiuxiang Hu
-Peter Gober
-Patrick Pletscher
-Sebastian Nowozin
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-----------------------------------------------------------------------------------
+Citing libDAI
 
 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: 
+of this program, please:
 
-J. M. Mooij (2008) "libDAI 0.2.2: A free/open source C++ library for Discrete 
-Approximate Inference methods", http://www.libdai.org
+  • 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. An appropriate
+    citation would be:
+    J. M. Mooij (2008) "libDAI 0.2.2: A free/open source C++ library for
+    Discrete Approximate Inference methods", http://www.libdai.org
 
-Moreover, as a personal note, I would appreciate it if you would email me 
-(joris.mooij@libdai.org) with citations of papers referencing this work.
-
-----------------------------------------------------------------------------------
+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.
 
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 About libDAI
-------------
-libDAI is a free/open source C++ library (licensed under GPL) that provides
+
+libDAI is a free/open source C++ library (licensed under GPLv2+) 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
+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;
-    * Conditioned BP [EaG09].
-
-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 maximum probability).
+   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].
+
+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
+maximum probability).
 
 In addition, libDAI supports parameter learning of conditional probability
 tables by Expectation Maximization.
 
+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. The only learning method supported currently is Expectation
+Maximization (or Maximum Likelihood if no data is missing) for learning factor
+parameters.
 
 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 (limited) MatLab interface for easy integration with MatLab.
 
+Compatibility
 
-Releases
---------
-Releases can be obtained from www.libdai.org
-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
+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.
 
-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.
+Finally, libDAI has been compiled successfully on MacOS X.
 
+Downloading libDAI
 
-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!).
+The libDAI sources and documentation can be downloaded from the libDAI website:
+http://www.libdai.org.
 
-A description of the factor graph (.fg) file format can be found in the file FILEFORMAT.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
+Building libDAI under UNIX variants (Linux / Cygwin / Mac OS X)
 
-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.
+You need:
 
-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.
+  • 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)
 
-Finally, libDAI has been compiled successfully on MacOS X.
+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
 
-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;
-  version 1.37 shipped with Ubuntu 9.04 is known not to work)
-
-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"
+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
+
 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:
+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
@@ -175,62 +145,75 @@ from http://www.boost.org/ and compile/install it with:
 
 
 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
-    
-    make
+(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
+
+  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:
 
-    ./example tests/alarm.fg
+  examples/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
+  tests/testdai --aliases tests/aliases.conf --filename tests/alarm.fg --methods JTREE_HUGIN BP_SEQMAX
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
+Building libDAI under Windows
 
-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)
+
+  • 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
+  • 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
+
+The build includes a regression test, which may take a while to complete.
 
 If the build was successful, you can test the example program:
 
-    example tests\alarm.fg
+  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
+  tests\testdai --aliases tests\aliases.conf --filename tests\alarm.fg --methods JTREE_HUGIN BP_SEQMAX
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
+Building the libDAI MatLab interface
 
-Quick start (MatLab)
---------------------
 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
-"WITH_MATLAB=true". Also, you have to configure the MatLab-specific parts of
-Makefile.conf to match your system (in particular, the Makefile variables ME,
-MATLABDIR and MEX). The MEX file extension depends on your platform; for a
-64-bit linux x86_64 system this would be "ME=.mexa64", for a 32-bit linux x86
-system this would be "ME=.mexglx". If you are unsure about your MEX file
-extension: it needs to be the same as what the MatLab command "mexext" returns.
-The required MEX files are built by issuing
 
-    make
+  WITH_MATLAB=true
+
+Also, you have to configure the MatLab-specific parts of Makefile.conf to match
+your system (in particular, the Makefile variables ME, MATLABDIR and MEX). The
+MEX file extension depends on your platform; for a 64-bit linux x86_64 system
+this would be "ME=.mexa64", for a 32-bit linux x86 system "ME=.mexglx". If you
+are unsure about your MEX file extension: it needs to be the same as what the
+MatLab command "mexext" returns. The required MEX files are built by issuing
+
+  make
 
 from the command line. The MatLab interface is much less powerful than using
 libDAI from C++. There are two reasons for this: (i) it is boring to write MEX
@@ -242,11 +225,24 @@ A simple example of how to use the MatLab interface is the following (entered
 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');
-    [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]')
+  cd path_to_libdai/matlab
+  [psi] = dai_readfg ('../examples/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]')
 
 where "path_to_libdai" has to be replaced with the directory in which libDAI
-was installed. For other algorithms and their parameters, see
+was installed. For other algorithms and some default parameters, see the file
 tests/aliases.conf.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Building the documentation
+
+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 and send a
+patch!).
+
diff --git a/TODO b/TODO
index f7b87e6..e5f0c9c 100644 (file)
--- a/TODO
+++ b/TODO
@@ -1,9 +1,5 @@
 To do for the next release (0.2.3):
 
-Improve documentation:
-
-       doc.h
-
 Improve documentation of all .props structs.
 
 Write a concept/notations page for the documentation,
@@ -12,3 +8,19 @@ multi-dimensional array, e.g., one corresponding
 to the Cartesian product of statespaces of variables)
 and "linear index". This should make it easier to
 document index.h and varset.h
+
+Rename VarSet::calcState(), VarSet::calcStates() and make them non-member functions;
+make the State class a more prominent part of libDAI (and document it clearly, explaining
+the concept of state); add more optimized variants of the State class like IndexFor (e.g. for TFactor<>::slice()).
+
+- Merge NIPS MLOSS workshop sheet info
+
+- Merge website info
+
+
+Finally:
+
+- Set DAI_VERSION and DAI_DATE correctly (all occurences)
+- Build documentation and make a copy
+- Find out how to tag the git commit
+- Make a tarball which does not include the .git stuff
index 7bbf0d0..f8018d6 100644 (file)
@@ -431,13 +431,13 @@ GENERATE_TODOLIST      = YES
 # disable (NO) the test list. This list is created by putting \test 
 # commands in the documentation.
 
-GENERATE_TESTLIST      = YES
+GENERATE_TESTLIST      = NO
 
 # The GENERATE_BUGLIST tag can be used to enable (YES) or 
 # disable (NO) the bug list. This list is created by putting \bug 
 # commands in the documentation.
 
-GENERATE_BUGLIST       = YES
+GENERATE_BUGLIST       = NO
 
 # The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or 
 # disable (NO) the deprecated list. This list is created by putting 
@@ -470,7 +470,7 @@ SHOW_USED_FILES        = YES
 # then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy 
 # in the documentation. The default is NO.
 
-SHOW_DIRECTORIES       = YES
+SHOW_DIRECTORIES       = NO
 
 # Set the SHOW_FILES tag to NO to disable the generation of the Files page. 
 # This will remove the Files entry from the Quick Index and from the 
@@ -565,7 +565,10 @@ WARN_LOGFILE           =
 # with spaces.
 
 INPUT                  = src \
-                         include/dai
+                         src/matlab \
+                         include/dai \
+                         include/dai/matlab \
+                         .
 
 # This tag can be used to specify the character encoding of the source files 
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is 
@@ -588,7 +591,7 @@ FILE_PATTERNS          =
 # should be searched for input files as well. Possible values are YES and NO. 
 # If left blank NO is used.
 
-RECURSIVE              = YES
+RECURSIVE              = NO
 
 # The EXCLUDE tag can be used to specify files and/or directories that should 
 # excluded from the INPUT source files. This way you can easily exclude a 
@@ -622,14 +625,14 @@ EXCLUDE_SYMBOLS        =
 # directories that contain example code fragments that are included (see 
 # the \include command).
 
-EXAMPLE_PATH           = examples
+EXAMPLE_PATH           = examples
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the 
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 
 # and *.h) to filter out the source-files in the directories. If left 
 # blank all files are included.
 
-EXAMPLE_PATTERNS       = 
+EXAMPLE_PATTERNS       = *.cpp *.out COPYING README AUTHORS ChangeLog
 
 # If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be 
 # searched for input files to be used with the \include or \dontinclude 
@@ -1257,7 +1260,9 @@ PREDEFINED             = DAI_WITH_BP \
                          DAI_WITH_JTREE \
                          DAI_WITH_MR \
                          DAI_WITH_CBP \
-                         DAI_DEBUG
+                         DAI_DEBUG \
+                         DAI_DATE \
+                         DAI_VERSION
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then 
 # this tag can be used to specify a list of macro names that should be expanded. 
index e13b01a..848c59b 100644 (file)
@@ -10,7 +10,7 @@
 
 /// \file
 /// \brief Defines class BP_dual, which is used primarily by BBP.
-/// \todo This replicates a large part of the functionality of BP; would it not be more efficient to adapt BP instead?
+/// \idea BP_dual replicates a large part of the functionality of BP; would it not be more efficient to adapt BP instead?
 /// \author Frederik Eaton
 
 
index b15e16f..6f252f8 100644 (file)
@@ -211,7 +211,9 @@ class CBP : public DAIAlgFG {
         virtual bool chooseNextClampVar( InfAlg* bp, std::vector<size_t> &clamped_vars_list, size_t &i, std::vector<size_t> &xis, Real *maxVarOut );
 
         /// Return the InfAlg to use at each step of the recursion.
-        /// \todo At present, CBP::getInfAlg() only returns a BP instance
+        /** \todo At present, CBP::getInfAlg() only returns a BP instance; 
+         *  it should be possible to select other inference algorithms via a property
+         */
         InfAlg* getInfAlg();
 
         /// Sets variable beliefs, factor beliefs and log partition sum to the specified values
index 793d039..d3cf52b 100644 (file)
@@ -29,7 +29,7 @@ namespace dai {
 
 
 /// InfAlg is an abstract base class, defining the common interface of all inference algorithms in libDAI.
-/** \todo General marginalization functions like calcMarginal() now copy a complete InfAlg object. Instead,
+/** \idea General marginalization functions like calcMarginal() now copy a complete InfAlg object. Instead,
  *  it would make more sense that they construct a new object without copying the FactorGraph or RegionGraph.
  *  Or they can simply be made methods of the general InfAlg class.
  *  \idea Use a PropertySet as output of an InfAlg, instead of functions like maxDiff() and Iterations().
@@ -177,7 +177,7 @@ class InfAlg {
  *  from a DAIAlg<FactorGraph> or from a DAIAlg<RegionGraph>.
  *
  *  \tparam GRM Should be castable to FactorGraph
- *  \todo A DAIAlg should not inherit from a FactorGraph or RegionGraph, but should
+ *  \idea A DAIAlg should not inherit from a FactorGraph or RegionGraph, but should
  *  store a reference to the graphical model object. This prevents needless copying
  *  of (possibly large) data structures. Disadvantage: the caller must not change
  *  the graphical model between calls to the inference algorithm (maybe a smart_ptr
index a0a6c22..ff48eb8 100644 (file)
 /** \file
  *  \brief Contains additional doxygen documentation
  *
- *  \todo Improve documentation
+ *  \todo Document tests and utils
  *
- *  \todo Merge README into doxygen documentation
- *  \todo Document examples, tests and utils
+ *  \todo Add FAQ
  *
  *  \todo Adapt (part of the) guidelines in http://www.boost.org/development/requirements.html#Design_and_Programming
  *
  *  \todo Use "gcc -MM" to generate dependencies for targets: http://make.paulandlesley.org/autodep.html
- *  \todo Investigate whether switching to cmake as cross-platform build system would be a good idea.
  *
  *  \todo Replace VarSets by SmallSet<size_t> where appropriate, in order to minimize the use of FactorGraph::findVar().
  *
  *  \idea Disentangle structures. In particular, ensure that graphical properties are not
- *  entangled with probabilistic properties. For example, a FactorGraph contains several
- *  components:
+ *  entangled with probabilistic properties. For example, a FactorGraph contains several components:
  *  - a BipartiteGraph
  *  - an array of variable labels
  *  - an array of variable state space sizes
  *  - an array of pointers to factor value vectors
  *  In this way, each factor could be implemented differently, e.g., we could have
  *  some sparse factors, some noisy-OR factors, some dense factors, some arbitrary
- *  precision factors, etc.
+ *  precision factors, etcetera.
  *
- *  \idea Use Boost::uBLAS framework to deal with matrices, especially, with 2D sparse matrices.
+ *  \idea Use boost::uBLAS framework to deal with matrices, especially, with 2D sparse matrices.
  *  See http://www.boost.org/libs/numeric/ublas/doc/matrix_sparse.htm
- *  I read somewhere that boost::uBLAS concentrates more on correct implementation than on performance.
+ *  However: I read somewhere that boost::uBLAS concentrates more on correct implementation than on performance.
  *
  *  \idea Introduce naming scheme:
  *  - all Vars should be named v_..., e.g. v_i instead of i
  **/
 
 
-/** \page discussion Discussion of possible improvements
- *  \section discuss_extendedgraphs Extended factorgraphs/regiongraphs
- *
- *  A FactorGraph and a RegionGraph are often equipped with
- *  additional properties for nodes and edges. The code to initialize those
- *  is often quite similar. Maybe one could abstract this, e.g.:
- *  \code
- *  template <typename Node1Properties, typename Node2Properties, typename EdgeProperties>
- *  class ExtFactorGraph : public FactorGraph {
- *      public:
- *          std::vector<Node1Properties>              node1Props;
- *          std::vector<Node2Properties>              node2Props;
- *          std::vector<std::vector<EdgeProperties> > edgeProps;
- *         // ...
- *  }
- *  \endcode
- *
- *  Advantages:
- *  - Less code duplication.
- *  - Easier maintainability.
- *  - Easier to write new inference algorithms.
- *
- *  Disadvantages:
- *  - Cachability may be worse.
- *  - A problem is the case where there are no properties for either type of nodes or for edges.
- *    Maybe this can be solved using specializations, or using variadac template arguments?
- *    Another possible solution would be to define a "class Empty {}", and add some code
- *    that checks for the typeid, comparing it with Empty, and doing something special in that case
- *    (e.g., not allocating memory).
- *  - The main disadvantage of this approach seems to be that it leads to even more entanglement.
- *    Therefore this is probably a bad idea.
- *
- *  \section discuss_templates Polymorphism by template parameterization
- *  Instead of polymorphism by inheritance, use polymorphism by template parameterization.
- *  For example, the real reason for introducing the complicated inheritance scheme of dai::InfAlg
- *  was for functions like dai::calcMarginal. Instead, one could use a template function:
- *  \code
- *  template<typename InfAlg>
- *  Factor calcMarginal( const InfAlg &obj, const VarSet &ns, bool reInit );
- *  \endcode
- *  This would assume that the type InfAlg supports certain methods. Ideally, one would use
- *  concepts to define different classes of inference algorithms with different capabilities,
- *  for example the ability to calculate logZ, the ability to calculate marginals, the ability to
- *  calculate bounds, the ability to calculate MAP states, etc. Then, one would use traits
- *  classes in order to be able to query the capabilities of the model. For example, one would be
- *  able to query whether the inference algorithm supports calculation of logZ.  Unfortunately,
- *  this is compile-time polymorphism, whereas tests/testdai needs runtime polymorphism.
- *  Therefore this is probably a bad idea.
- */
-
-
-/** \mainpage libDAI reference manual
+/** \mainpage Reference manual for libDAI - A free/open source C++ library for Discrete Approximate Inference methods
  *  \author Joris Mooij
- *  \version git HEAD
- *  \date October 10, 2008
+ *  \version DAI_VERSION
+ *  \date DAI_DATE
  *
+ *  <hr size="1">
  *  \section about About libDAI
  *  libDAI is a free/open source C++ library (licensed under GPLv2+) that provides
  *  implementations of various (approximate) inference methods for discrete
  *  The library is targeted at researchers. To be able to use the library, a
  *  good understanding of graphical models is needed.
  *
- *  \section limitations 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. The only learning method supported currently
- *  is EM for learning factor parameters.
- *
  *  \section features Features
  *  Currently, libDAI supports the following (approximate) inference methods:
  *  - Exact inference by brute force enumeration;
  *  - Various variants of Loop Corrected Belief Propagation
  *    [\ref MoK07, \ref MoR05];
  *  - Gibbs sampler;
- *  - Conditioned BP [\ref EaG09];
+ *  - Conditioned BP [\ref EaG09].
+ *
+ *  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 maximum probability).
  *
  *  In addition, libDAI supports parameter learning of conditional probability
  *  tables by Expectation Maximization.
  *
+ *  \section limitations 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. The only learning method supported currently
+ *  is Expectation Maximization (or Maximum Likelihood if no data is missing)
+ *  for learning factor parameters.
+ *
  *  \section language 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.
+ *  libDAI does provide a (limited) MatLab interface for easy integration with MatLab.
+ *
+ *  \section compatibility 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.
+ *
+ *  \section download Downloading libDAI
+ *  The libDAI sources and documentation can be downloaded from the libDAI website:
+ *  http://www.libdai.org.
  */
 
 
-/** \example example.cpp
+/** \page license License
+ *  <hr size="1">
+ *  \section license-license 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.
+ *
+ *  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.
+ *
+ *  <hr size="1">
+ *  \section license-gpl GNU General Public License version 2
+ * 
+ *  \verbinclude COPYING
  */
 
 
-/** \page quickstart Quick start
- *  An example program illustrating basic usage of libDAI is given in examples/example.cpp.
+/** \page citations Citing libDAI
+ *  <hr size="1">
+ *  \section citations-citations 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. An
+ *      appropriate citation would be:\n
+ *      J. M. Mooij (2008) "libDAI 0.2.2: A free/open source C++ library for Discrete 
+ *      Approximate Inference methods", http://www.libdai.org
+ *
+ *  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.
  */
 
 
-/** \page bibliography Bibliography
- *  \anchor KFL01 \ref KFL01
- *  F. R. Kschischang and B. J. Frey and H.-A. Loeliger (2001):
- *  "Factor Graphs and the Sum-Product Algorithm",
- *  <em>IEEE Transactions on Information Theory</em> 47(2):498-519.
- *  http://ieeexplore.ieee.org/xpl/freeabs_all.jsp?arnumber=910572
+/** \page authors Authors
+ *  \section authors-authors People who contributed to libDAI
  *
- *  \anchor MiQ04 \ref MiQ04
- *  T. Minka and Y. Qi (2004):
- *  "Tree-structured Approximations by Expectation Propagation",
- *  <em>Advances in Neural Information Processing Systems</em> (NIPS) 16.
- *  http://books.nips.cc/papers/files/nips16/NIPS2003_AA25.pdf
- *
- *  \anchor MoR05 \ref MoR05
- *  A. Montanari and T. Rizzo (2005):
- *  "How to Compute Loop Corrections to the Bethe Approximation",
- *  <em>Journal of Statistical Mechanics: Theory and Experiment</em>
- *  2005(10)-P10011.
- *  http://stacks.iop.org/1742-5468/2005/P10011
- *
- *  \anchor YFW05 \ref YFW05
- *  J. S. Yedidia and W. T. Freeman and Y. Weiss (2005):
- *  "Constructing Free-Energy Approximations and Generalized Belief Propagation Algorithms",
- *  <em>IEEE Transactions on Information Theory</em>
- *  51(7):2282-2312.
- *  http://ieeexplore.ieee.org/xpl/freeabs_all.jsp?arnumber=1459044
- *
- *  \anchor HAK03 \ref HAK03
- *  T. Heskes and C. A. Albers and H. J. Kappen (2003):
- *  "Approximate Inference and Constrained Optimization",
- *  <em>Proceedings of the 19th Annual Conference on Uncertainty in Artificial Intelligence (UAI-03)</em> pp. 313-320.
- *  http://www.snn.ru.nl/reports/Heskes.uai2003.ps.gz
- *
- *  \anchor MoK07 \ref MoK07
- *  J. M. Mooij and H. J. Kappen (2007):
- *  "Loop Corrections for Approximate Inference on Factor Graphs",
- *  <em>Journal of Machine Learning Research</em> 8:1113-1143.
- *  http://www.jmlr.org/papers/volume8/mooij07a/mooij07a.pdf
- *
- *  \anchor MoK07b \ref MoK07b
- *  J. M. Mooij and H. J. Kappen (2007):
- *  "Sufficient Conditions for Convergence of the Sum-Product Algorithm",
- *  <em>IEEE Transactions on Information Theory</em> 53(12):4422-4437.
- *  http://ieeexplore.ieee.org/xpl/freeabs_all.jsp?arnumber=4385778
- *
- *  \anchor EaG09 \ref EaG09
- *  F. Eaton and Z. Ghahramani (2009):
- *  "Choosing a Variable to Clamp",
- *  <em>Proceedings of the Twelfth International Conference on Artificial Intelligence and Statistics (AISTATS 2009)</em> 5:145-152
- *  http://jmlr.csail.mit.edu/proceedings/papers/v5/eaton09a/eaton09a.pdf
- *
- *  \anchor StW99 \ref StW99
- *  A. Steger and N. C. Wormald (1999):
- *  "Generating Random Regular Graphs Quickly",
- *  <em>Combinatorics, Probability and Computing</em> Vol 8, Issue 4, pp. 377-396
- *  http://www.math.uwaterloo.ca/~nwormald/papers/randgen.pdf
+ *  \verbinclude AUTHORS
+ */
+
+
+/** \page build Building libDAI
+ *  <hr size="1">
+ *  \section build-unix Building libDAI under UNIX variants (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;
+ *      version 1.37 shipped with Ubuntu 9.04 is known not to work)
+ * 
+ *  On Debian/Ubuntu, you can easily install all these packages with a single command:
+ *  <pre>  apt-get install g++ make doxygen graphviz libboost-dev libboost-graph-dev libboost-program-options-dev</pre>
+ *  (root permissions needed).
+ *
+ *  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 
+ *    <pre>  sudo port install gmake boost doxygen graphviz</pre>
+ *  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:
+ *
+ *  <pre>  ./configure
+ *  make
+ *  make install
+ *  </pre>
  *
- *  \anchor EMK06 \ref EMK06
- *  G. Elidan and I. McGraw and D. Koller (2006):
- *  "Residual Belief Propagation: Informed Scheduling for Asynchronous Message Passing",
- *  <em>Proceedings of the 22nd Annual Conference on Uncertainty in Artificial Intelligence (UAI-06)</em>
- *  http://uai.sis.pitt.edu/papers/06/UAI2006_0091.pdf
+ *  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
+ *  <pre>  make</pre>
+ *  The build includes a regression test, which may take a while to complete.
+ *
+ *  If the build was successful, you can test the example program:
+ *  <pre>  examples/example tests/alarm.fg</pre>
+ *  or the more elaborate test program:
+ *  <pre>  tests/testdai --aliases tests/aliases.conf --filename tests/alarm.fg --methods JTREE_HUGIN BP_SEQMAX</pre>
+ *
+ *
+ *  <hr size="1">
+ *  \section build-windows Building libDAI under 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)
+ *  <pre>  make</pre>
+ *  The build includes a regression test, which may take a while to complete.
+ *
+ *  If the build was successful, you can test the example program:
+ *  <pre>  example tests\alarm.fg</pre>
+ *  or the more elaborate test program:
+ *  <pre>  tests\\testdai --aliases tests\aliases.conf --filename tests\alarm.fg --methods JTREE_HUGIN BP_SEQMAX</pre>
+ *
+ *
+ *  <hr size="1">
+ *  \section build-matlab Building the libDAI MatLab interface
+ *
+ *  You need:
+ *  - 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
+ *  <pre>  WITH_MATLAB=true</pre>
+ *  Also, you have to configure the MatLab-specific parts of
+ *  Makefile.conf to match your system (in particular, the Makefile variables ME,
+ *  MATLABDIR and MEX). The MEX file extension depends on your platform; for a
+ *  64-bit linux x86_64 system this would be "ME=.mexa64", for a 32-bit linux x86
+ *  system "ME=.mexglx". If you are unsure about your MEX file
+ *  extension: it needs to be the same as what the MatLab command "mexext" returns.
+ *  The required MEX files are built by issuing
+ *  <pre>  make</pre>
+ *  from the command line. The MatLab interface is much less powerful than using
+ *  libDAI from C++. There are two reasons for this: (i) it is boring to write MEX
+ *  files; (ii) the large performance penalty paid when large data structures (like
+ *  factor graphs) have to be converted between their native C++ data structure to
+ *  something that MatLab understands.
+ *
+ *  A simple example of how to use the MatLab interface is the following (entered
+ *  at the MatLab prompt), which performs exact inference by the junction tree
+ *  algorithm and approximate inference by belief propagation on the ALARM network:
+ *  <pre>  cd path_to_libdai/matlab
+ *  [psi] = dai_readfg ('../examples/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]')</pre>
+ *  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.
+ *
+ *  <hr size="1">
+ *  \section build-doxygen Building the documentation
+ *
+ *  Install doxygen and use
+ *  <pre>  make doc</pre>
+ *  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 and send a patch!).
+ */
+
+
+/** \page changelog Change Log
+ *  \verbinclude ChangeLog
  */
 
 
  *  to specify which variables occur in the factor, what their respective
  *  cardinalities (i.e., number of possible values) are, and a table listing all
  *  the values of that factor for all possible configurations of these variables.
+ *
  *  A .fg file is not much more than that. It starts with a line containing the
  *  number of factors in that graph, followed by an empty line. Then all factors
- *  are specified, one block for each factor, where the blocks are seperated by
- *  empty lines. Each variable occurring in the factor graph has a unique
- *  identifier, its index (which should be a nonnegative integer). Comment lines
- *  start with #.
- *
- *  Each block starts with a line containing the number of variables in that
- *  factor. The second line contains the indices of these variables, seperated by
- *  spaces (indices are nonnegative integers and to avoid confusion, it is
- *  suggested to start counting at 0). The third line contains the number of
- *  possible values of each of these variables, also seperated by spaces. Note that
- *  there is some redundancy here, since if a variable appears in more than one
- *  factor, the cardinality of that variable appears several times in the .fg file.
- *  The fourth line contains the number of nonzero entries in the factor table.
- *  The rest of the lines contain these nonzero entries; each entry consists of a
- *  table index, followed by white-space, followed by the value corresponding to
- *  that table index. The most difficult part is getting the indexing right. The
- *  convention that is used is that the left-most variables cycle through their
- *  values the fastest (similar to MATLAB indexing of multidimensional arrays). An
- *  example block describing one factor is:
+ *  are specified, using one block for each factor, where the blocks are seperated 
+ *  by empty lines. Each variable occurring in the factor graph has a unique
+ *  identifier, its label (which should be a nonnegative integer). Comment lines
+ *  which start with # are ignored.
+ *
+ *  \subsection fileformats-factorgraph-factor Factor block format
+ *
+ *  Each block describing a factor starts with a line containing the number of 
+ *  variables in that factor. The second line contains the labels of these 
+ *  variables, seperated by spaces (labels are nonnegative integers and to avoid 
+ *  confusion, it is suggested to start counting at 0). The third line contains 
+ *  the number of possible values of each of these variables, also seperated by 
+ *  spaces. Note that there is some redundancy here, since if a variable appears 
+ *  in more than one factor, the cardinality of that variable appears several 
+ *  times in the .fg file; obviously, these cardinalities should be consistent.
+ *  The fourth line contains the number of nonzero entries 
+ *  in the factor table. The rest of the lines contain these nonzero entries; 
+ *  each line consists of a table index, followed by white-space, followed by the 
+ *  value corresponding to that table index. The most difficult part is getting 
+ *  the indexing right. The convention that is used is that the left-most 
+ *  variables cycle through their values the fastest (similar to MatLab indexing 
+ *  of multidimensional arrays). 
+ *
+ *  \subsubsection fileformats-factorgraph-factor-example Example
+ *
+ *  An example block describing one factor is:
  *
  *  <pre>
  *  3
  *
  *  \section fileformats-evidence Evidence (.tab) file format
  *
- *  This page describes the .tab fileformat used in libDAI to store "evidence",
+ *  This section describes the .tab fileformat used in libDAI to store "evidence",
  *  i.e., a data set consisting of multiple samples, where each sample is the 
  *  observed joint state of some variables.
  *
- *  A .tab file is a tabular data file, consisting of a header line followed by
- *  one line for each data sample. Each line should have the same number of columns,
+ *  A .tab file is a tabular data file, consisting of a header line, followed by
+ *  an empty line, followed by the data points, with one line for each data point.
+ *  Each line (apart from the empty one) should have the same number of columns,
  *  where columns are separated by one tab character. Each column corresponds to 
  *  a variable. The header line consists of the variable labels (corresponding to 
- *  Var::label()). The other lines are observed joint states of the variables, i.e.,
+ *  dai::Var::label()). The other lines are observed joint states of the variables, i.e.,
  *  each line corresponds to a joint observation of the variables, and each column
  *  of a line contains the state of the variable associated with that column.
  *  Missing data is handled simply by having two consecutive tab characters, 
  *  without any characters in between.
  *
- *  \par  Example:
+ *  \subsection fileformats-evidence-example Example
  *
  *  <pre>
  *  1       3       2
+ *
  *  0       0       1
  *  1       0       1
  *  1               1
  *  file is useless. Furthermore, one also needs a corresponding .tab file
  *  containing the data used for parameter learning.
  *
- *  An .em file starts with a line specifying the number of maximization steps.
- *  Then, for each maximization step, its description follows in the format
- *  described in the next section.
+ *  An .em file starts with a line specifying the number of maximization steps,
+ *  followed by an empty line. Then, each maximization step is described in a
+ *  block, which should satisfy the format described in the next subsection.
  *
- *  \subsection fileformats-emalg-maximizationstep Maximization Step section in EM file
+ *  \subsection fileformats-emalg-maximizationstep Maximization Step block format
  *
- *  A maximization step section of an .em file starts with a single line
- *  describing the number of shared parameters sections that will follow.
- *  Then, precisely that number of shared parameters sections follow, 
- *  where each of those sections follows the format described in the next
- *  subsection.
+ *  A maximization step block of an .em file starts with a single line
+ *  describing the number of shared parameters blocks that will follow.
+ *  Then, each shared parameters block follows, in the format described in
+ *  the next subsection.
  *
- *  \subsection fileformats-emalg-sharedparameters Shared parameters section in EM file
+ *  \subsection fileformats-emalg-sharedparameters Shared parameters block format
  *
- *  A shared parameters section of an .em file starts with a single line
+ *  A shared parameters block of an .em file starts with a single line
  *  consisting of the name of a ParameterEstimation subclass
  *  and its parameters in the format of a PropertySet. For example:
- *
- *  <pre>
- *  ConditionalProbEstimation [target_dim=2,total_dim=4,pseudo_count=1]
- *  </pre>
- *
+ *  <pre>  CondProbEstimation [target_dim=2,total_dim=4,pseudo_count=1]</pre>
  *  The next line contains the number of factors that share their parameters.
  *  Then, each of these factors is specified on separate lines (possibly 
  *  seperated by empty lines), where each line consists of several fields
  *  changes fastest (in the inner loop), and the corresponding index of the
  *  last variable changes slowest (in the outer loop). By choosing the right
  *  ordering, it is possible to let different factors (depending on different
- *  variables) share parameters in parameter learning using EM.
+ *  variables) share parameters in parameter learning using EM. This convention
+ *  is similar to the convention used in factor blocks in a factor graph .fg 
+ *  file (see \ref fileformats-factorgraph-factor).
  */
 
-/** \page license License
-
-<b>libDAI is licensed under the GNU General Public License version 2, or
-(at your option) any later version. The complete license text is
-included below.</b>
-
-\htmlonly
-<pre>
-                   GNU GENERAL PUBLIC LICENSE
-                      Version 2, June 1991
-
- Copyright (C) 1989, 1991 Free Software Foundation, Inc.
-                       51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
-                           Preamble
-
-  The licenses for most software are designed to take away your
-freedom to share and change it.  By contrast, the GNU General Public
-License is intended to guarantee your freedom to share and change free
-software--to make sure the software is free for all its users.  This
-General Public License applies to most of the Free Software
-Foundation's software and to any other program whose authors commit to
-using it.  (Some other Free Software Foundation software is covered by
-the GNU Library General Public License instead.)  You can apply it to
-your programs, too.
-
-  When we speak of free software, we are referring to freedom, not
-price.  Our General Public Licenses are designed to make sure that you
-have the freedom to distribute copies of free software (and charge for
-this service if you wish), that you receive source code or can get it
-if you want it, that you can change the software or use pieces of it
-in new free programs; and that you know you can do these things.
-
-  To protect your rights, we need to make restrictions that forbid
-anyone to deny you these rights or to ask you to surrender the rights.
-These restrictions translate to certain responsibilities for you if you
-distribute copies of the software, or if you modify it.
-
-  For example, if you distribute copies of such a program, whether
-gratis or for a fee, you must give the recipients all the rights that
-you have.  You must make sure that they, too, receive or can get the
-source code.  And you must show them these terms so they know their
-rights.
-
-  We protect your rights with two steps: (1) copyright the software, and
-(2) offer you this license which gives you legal permission to copy,
-distribute and/or modify the software.
-
-  Also, for each author's protection and ours, we want to make certain
-that everyone understands that there is no warranty for this free
-software.  If the software is modified by someone else and passed on, we
-want its recipients to know that what they have is not the original, so
-that any problems introduced by others will not reflect on the original
-authors' reputations.
-
-  Finally, any free program is threatened constantly by software
-patents.  We wish to avoid the danger that redistributors of a free
-program will individually obtain patent licenses, in effect making the
-program proprietary.  To prevent this, we have made it clear that any
-patent must be licensed for everyone's free use or not licensed at all.
-
-  The precise terms and conditions for copying, distribution and
-modification follow.
-
-                   GNU GENERAL PUBLIC LICENSE
-   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-
-  0. This License applies to any program or other work which contains
-a notice placed by the copyright holder saying it may be distributed
-under the terms of this General Public License.  The "Program", below,
-refers to any such program or work, and a "work based on the Program"
-means either the Program or any derivative work under copyright law:
-that is to say, a work containing the Program or a portion of it,
-either verbatim or with modifications and/or translated into another
-language.  (Hereinafter, translation is included without limitation in
-the term "modification".)  Each licensee is addressed as "you".
-
-Activities other than copying, distribution and modification are not
-covered by this License; they are outside its scope.  The act of
-running the Program is not restricted, and the output from the Program
-is covered only if its contents constitute a work based on the
-Program (independent of having been made by running the Program).
-Whether that is true depends on what the Program does.
-
-  1. You may copy and distribute verbatim copies of the Program's
-source code as you receive it, in any medium, provided that you
-conspicuously and appropriately publish on each copy an appropriate
-copyright notice and disclaimer of warranty; keep intact all the
-notices that refer to this License and to the absence of any warranty;
-and give any other recipients of the Program a copy of this License
-along with the Program.
-
-You may charge a fee for the physical act of transferring a copy, and
-you may at your option offer warranty protection in exchange for a fee.
-
-  2. You may modify your copy or copies of the Program or any portion
-of it, thus forming a work based on the Program, and copy and
-distribute such modifications or work under the terms of Section 1
-above, provided that you also meet all of these conditions:
-
-    a) You must cause the modified files to carry prominent notices
-    stating that you changed the files and the date of any change.
-
-    b) You must cause any work that you distribute or publish, that in
-    whole or in part contains or is derived from the Program or any
-    part thereof, to be licensed as a whole at no charge to all third
-    parties under the terms of this License.
-
-    c) If the modified program normally reads commands interactively
-    when run, you must cause it, when started running for such
-    interactive use in the most ordinary way, to print or display an
-    announcement including an appropriate copyright notice and a
-    notice that there is no warranty (or else, saying that you provide
-    a warranty) and that users may redistribute the program under
-    these conditions, and telling the user how to view a copy of this
-    License.  (Exception: if the Program itself is interactive but
-    does not normally print such an announcement, your work based on
-    the Program is not required to print an announcement.)
-
-These requirements apply to the modified work as a whole.  If
-identifiable sections of that work are not derived from the Program,
-and can be reasonably considered independent and separate works in
-themselves, then this License, and its terms, do not apply to those
-sections when you distribute them as separate works.  But when you
-distribute the same sections as part of a whole which is a work based
-on the Program, the distribution of the whole must be on the terms of
-this License, whose permissions for other licensees extend to the
-entire whole, and thus to each and every part regardless of who wrote it.
-
-Thus, it is not the intent of this section to claim rights or contest
-your rights to work written entirely by you; rather, the intent is to
-exercise the right to control the distribution of derivative or
-collective works based on the Program.
-
-In addition, mere aggregation of another work not based on the Program
-with the Program (or with a work based on the Program) on a volume of
-a storage or distribution medium does not bring the other work under
-the scope of this License.
-
-  3. You may copy and distribute the Program (or a work based on it,
-under Section 2) in object code or executable form under the terms of
-Sections 1 and 2 above provided that you also do one of the following:
-
-    a) Accompany it with the complete corresponding machine-readable
-    source code, which must be distributed under the terms of Sections
-    1 and 2 above on a medium customarily used for software interchange; or,
-
-    b) Accompany it with a written offer, valid for at least three
-    years, to give any third party, for a charge no more than your
-    cost of physically performing source distribution, a complete
-    machine-readable copy of the corresponding source code, to be
-    distributed under the terms of Sections 1 and 2 above on a medium
-    customarily used for software interchange; or,
-
-    c) Accompany it with the information you received as to the offer
-    to distribute corresponding source code.  (This alternative is
-    allowed only for noncommercial distribution and only if you
-    received the program in object code or executable form with such
-    an offer, in accord with Subsection b above.)
-
-The source code for a work means the preferred form of the work for
-making modifications to it.  For an executable work, complete source
-code means all the source code for all modules it contains, plus any
-associated interface definition files, plus the scripts used to
-control compilation and installation of the executable.  However, as a
-special exception, the source code distributed need not include
-anything that is normally distributed (in either source or binary
-form) with the major components (compiler, kernel, and so on) of the
-operating system on which the executable runs, unless that component
-itself accompanies the executable.
-
-If distribution of executable or object code is made by offering
-access to copy from a designated place, then offering equivalent
-access to copy the source code from the same place counts as
-distribution of the source code, even though third parties are not
-compelled to copy the source along with the object code.
-
-  4. You may not copy, modify, sublicense, or distribute the Program
-except as expressly provided under this License.  Any attempt
-otherwise to copy, modify, sublicense or distribute the Program is
-void, and will automatically terminate your rights under this License.
-However, parties who have received copies, or rights, from you under
-this License will not have their licenses terminated so long as such
-parties remain in full compliance.
-
-  5. You are not required to accept this License, since you have not
-signed it.  However, nothing else grants you permission to modify or
-distribute the Program or its derivative works.  These actions are
-prohibited by law if you do not accept this License.  Therefore, by
-modifying or distributing the Program (or any work based on the
-Program), you indicate your acceptance of this License to do so, and
-all its terms and conditions for copying, distributing or modifying
-the Program or works based on it.
-
-  6. Each time you redistribute the Program (or any work based on the
-Program), the recipient automatically receives a license from the
-original licensor to copy, distribute or modify the Program subject to
-these terms and conditions.  You may not impose any further
-restrictions on the recipients' exercise of the rights granted herein.
-You are not responsible for enforcing compliance by third parties to
-this License.
-
-  7. If, as a consequence of a court judgment or allegation of patent
-infringement or for any other reason (not limited to patent issues),
-conditions are imposed on you (whether by court order, agreement or
-otherwise) that contradict the conditions of this License, they do not
-excuse you from the conditions of this License.  If you cannot
-distribute so as to satisfy simultaneously your obligations under this
-License and any other pertinent obligations, then as a consequence you
-may not distribute the Program at all.  For example, if a patent
-license would not permit royalty-free redistribution of the Program by
-all those who receive copies directly or indirectly through you, then
-the only way you could satisfy both it and this License would be to
-refrain entirely from distribution of the Program.
-
-If any portion of this section is held invalid or unenforceable under
-any particular circumstance, the balance of the section is intended to
-apply and the section as a whole is intended to apply in other
-circumstances.
-
-It is not the purpose of this section to induce you to infringe any
-patents or other property right claims or to contest validity of any
-such claims; this section has the sole purpose of protecting the
-integrity of the free software distribution system, which is
-implemented by public license practices.  Many people have made
-generous contributions to the wide range of software distributed
-through that system in reliance on consistent application of that
-system; it is up to the author/donor to decide if he or she is willing
-to distribute software through any other system and a licensee cannot
-impose that choice.
-
-This section is intended to make thoroughly clear what is believed to
-be a consequence of the rest of this License.
-
-  8. If the distribution and/or use of the Program is restricted in
-certain countries either by patents or by copyrighted interfaces, the
-original copyright holder who places the Program under this License
-may add an explicit geographical distribution limitation excluding
-those countries, so that distribution is permitted only in or among
-countries not thus excluded.  In such case, this License incorporates
-the limitation as if written in the body of this License.
-
-  9. The Free Software Foundation may publish revised and/or new versions
-of the General Public License from time to time.  Such new versions will
-be similar in spirit to the present version, but may differ in detail to
-address new problems or concerns.
-
-Each version is given a distinguishing version number.  If the Program
-specifies a version number of this License which applies to it and "any
-later version", you have the option of following the terms and conditions
-either of that version or of any later version published by the Free
-Software Foundation.  If the Program does not specify a version number of
-this License, you may choose any version ever published by the Free Software
-Foundation.
-
-  10. If you wish to incorporate parts of the Program into other free
-programs whose distribution conditions are different, write to the author
-to ask for permission.  For software which is copyrighted by the Free
-Software Foundation, write to the Free Software Foundation; we sometimes
-make exceptions for this.  Our decision will be guided by the two goals
-of preserving the free status of all derivatives of our free software and
-of promoting the sharing and reuse of software generally.
-
-                           NO WARRANTY
-
-  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
-FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
-OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
-PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
-OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
-TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
-PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
-REPAIR OR CORRECTION.
-
-  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
-WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
-REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
-INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
-OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
-TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
-YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
-PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
-POSSIBILITY OF SUCH DAMAGES.
-
-                    END OF TERMS AND CONDITIONS
-
-           How to Apply These Terms to Your New Programs
-
-  If you develop a new program, and you want it to be of the greatest
-possible use to the public, the best way to achieve this is to make it
-free software which everyone can redistribute and change under these terms.
-
-  To do so, attach the following notices to the program.  It is safest
-to attach them to the start of each source file to most effectively
-convey the exclusion of warranty; and each file should have at least
-the "copyright" line and a pointer to where the full notice is found.
-
-    &lt;one line to give the program's name and a brief idea of what it does.&gt;
-    Copyright (C) &lt;year&gt;  &lt;name of author&gt;
-
-    This program 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.
-
-    This program 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 this program; if not, write to the Free Software
-    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-
-
-Also add information on how to contact you by electronic and paper mail.
-
-If the program is interactive, make it output a short notice like this
-when it starts in an interactive mode:
-
-    Gnomovision version 69, Copyright (C) year name of author
-    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
-    This is free software, and you are welcome to redistribute it
-    under certain conditions; type `show c' for details.
-
-The hypothetical commands `show w' and `show c' should show the appropriate
-parts of the General Public License.  Of course, the commands you use may
-be called something other than `show w' and `show c'; they could even be
-mouse-clicks or menu items--whatever suits your program.
+/** \page bibliography Bibliography
+ *  \anchor KFL01 \ref KFL01
+ *  F. R. Kschischang and B. J. Frey and H.-A. Loeliger (2001):
+ *  "Factor Graphs and the Sum-Product Algorithm",
+ *  <em>IEEE Transactions on Information Theory</em> 47(2):498-519.
+ *  http://ieeexplore.ieee.org/xpl/freeabs_all.jsp?arnumber=910572
+ *
+ *  \anchor MiQ04 \ref MiQ04
+ *  T. Minka and Y. Qi (2004):
+ *  "Tree-structured Approximations by Expectation Propagation",
+ *  <em>Advances in Neural Information Processing Systems</em> (NIPS) 16.
+ *  http://books.nips.cc/papers/files/nips16/NIPS2003_AA25.pdf
+ *
+ *  \anchor MoR05 \ref MoR05
+ *  A. Montanari and T. Rizzo (2005):
+ *  "How to Compute Loop Corrections to the Bethe Approximation",
+ *  <em>Journal of Statistical Mechanics: Theory and Experiment</em>
+ *  2005(10)-P10011.
+ *  http://stacks.iop.org/1742-5468/2005/P10011
+ *
+ *  \anchor YFW05 \ref YFW05
+ *  J. S. Yedidia and W. T. Freeman and Y. Weiss (2005):
+ *  "Constructing Free-Energy Approximations and Generalized Belief Propagation Algorithms",
+ *  <em>IEEE Transactions on Information Theory</em>
+ *  51(7):2282-2312.
+ *  http://ieeexplore.ieee.org/xpl/freeabs_all.jsp?arnumber=1459044
+ *
+ *  \anchor HAK03 \ref HAK03
+ *  T. Heskes and C. A. Albers and H. J. Kappen (2003):
+ *  "Approximate Inference and Constrained Optimization",
+ *  <em>Proceedings of the 19th Annual Conference on Uncertainty in Artificial Intelligence (UAI-03)</em> pp. 313-320.
+ *  http://www.snn.ru.nl/reports/Heskes.uai2003.ps.gz
+ *
+ *  \anchor MoK07 \ref MoK07
+ *  J. M. Mooij and H. J. Kappen (2007):
+ *  "Loop Corrections for Approximate Inference on Factor Graphs",
+ *  <em>Journal of Machine Learning Research</em> 8:1113-1143.
+ *  http://www.jmlr.org/papers/volume8/mooij07a/mooij07a.pdf
+ *
+ *  \anchor MoK07b \ref MoK07b
+ *  J. M. Mooij and H. J. Kappen (2007):
+ *  "Sufficient Conditions for Convergence of the Sum-Product Algorithm",
+ *  <em>IEEE Transactions on Information Theory</em> 53(12):4422-4437.
+ *  http://ieeexplore.ieee.org/xpl/freeabs_all.jsp?arnumber=4385778
+ *
+ *  \anchor EaG09 \ref EaG09
+ *  F. Eaton and Z. Ghahramani (2009):
+ *  "Choosing a Variable to Clamp",
+ *  <em>Proceedings of the Twelfth International Conference on Artificial Intelligence and Statistics (AISTATS 2009)</em> 5:145-152
+ *  http://jmlr.csail.mit.edu/proceedings/papers/v5/eaton09a/eaton09a.pdf
+ *
+ *  \anchor StW99 \ref StW99
+ *  A. Steger and N. C. Wormald (1999):
+ *  "Generating Random Regular Graphs Quickly",
+ *  <em>Combinatorics, Probability and Computing</em> Vol 8, Issue 4, pp. 377-396
+ *  http://www.math.uwaterloo.ca/~nwormald/papers/randgen.pdf
+ *
+ *  \anchor EMK06 \ref EMK06
+ *  G. Elidan and I. McGraw and D. Koller (2006):
+ *  "Residual Belief Propagation: Informed Scheduling for Asynchronous Message Passing",
+ *  <em>Proceedings of the 22nd Annual Conference on Uncertainty in Artificial Intelligence (UAI-06)</em>
+ *  http://uai.sis.pitt.edu/papers/06/UAI2006_0091.pdf
+ */
 
-You should also get your employer (if you work as a programmer) or your
-school, if any, to sign a "copyright disclaimer" for the program, if
-necessary.  Here is a sample; alter the names:
 
-  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
-  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+/** \page discussion Ideas not worth exploring
+ *  \section discuss_extendedgraphs Extended factorgraphs/regiongraphs
+ *
+ *  A FactorGraph and a RegionGraph are often equipped with
+ *  additional properties for nodes and edges. The code to initialize those
+ *  is often quite similar. Maybe one could abstract this, e.g.:
+ *  \code
+ *  template <typename Node1Properties, typename Node2Properties, typename EdgeProperties>
+ *  class ExtFactorGraph : public FactorGraph {
+ *      public:
+ *          std::vector<Node1Properties>              node1Props;
+ *          std::vector<Node2Properties>              node2Props;
+ *          std::vector<std::vector<EdgeProperties> > edgeProps;
+ *         // ...
+ *  }
+ *  \endcode
+ *
+ *  Advantages:
+ *  - Less code duplication.
+ *  - Easier maintainability.
+ *  - Easier to write new inference algorithms.
+ *
+ *  Disadvantages:
+ *  - Cachability may be worse.
+ *  - A problem is the case where there are no properties for either type of nodes or for edges.
+ *    Maybe this can be solved using specializations, or using variadac template arguments?
+ *    Another possible solution would be to define a "class Empty {}", and add some code
+ *    that checks for the typeid, comparing it with Empty, and doing something special in that case
+ *    (e.g., not allocating memory).
+ *  - The main disadvantage of this approach seems to be that it leads to even more entanglement.
+ *    Therefore this is probably a bad idea.
+ *
+ *  \section discuss_templates Polymorphism by template parameterization
+ *
+ *  Instead of polymorphism by inheritance, use polymorphism by template parameterization.
+ *  For example, the real reason for introducing the complicated inheritance scheme of dai::InfAlg
+ *  was for functions like dai::calcMarginal. Instead, one could use a template function:
+ *  \code
+ *  template<typename InfAlg>
+ *  Factor calcMarginal( const InfAlg &obj, const VarSet &ns, bool reInit );
+ *  \endcode
+ *  This would assume that the type InfAlg supports certain methods. Ideally, one would use
+ *  concepts to define different classes of inference algorithms with different capabilities,
+ *  for example the ability to calculate logZ, the ability to calculate marginals, the ability to
+ *  calculate bounds, the ability to calculate MAP states, etc. Then, one would use traits
+ *  classes in order to be able to query the capabilities of the model. For example, one would be
+ *  able to query whether the inference algorithm supports calculation of logZ.  Unfortunately,
+ *  this is compile-time polymorphism, whereas tests/testdai needs runtime polymorphism.
+ *  Therefore this is probably a bad idea.
+ */
 
-  &lt;signature of Ty Coon&gt;, 1 April 1989
-  Ty Coon, President of Vice
 
-This General Public License does not permit incorporating your program into
-proprietary programs.  If your program is a subroutine library, you may
-consider it more useful to permit linking proprietary applications with the
-library.  If this is what you want to do, use the GNU Library General
-Public License instead of this License.</pre>
-\endhtmlonly
-  */
index 05b3bf1..9093c78 100644 (file)
@@ -45,7 +45,7 @@ namespace dai {
  *  vector passed to it from a SharedParameters container object.
  *
  *  The default registry only contains CondProbEstimation, named
- *  "ConditionalProbEstimation".
+ *  "CondProbEstimation".
  *
  *  \author Charles Vaske
  */
@@ -293,6 +293,9 @@ class MaximizationStep {
  *  parameters, which may result in faster convergence in some cases.
  *
  *  \author Charles Vaske
+ *
+ *  \todo Expand the sprinkler example such that it generates a sample of the probability distribution,
+ *  and add another example that estimates the factor parameters of the sprinkler network using EM from this sample.
  */
 class EMAlg {
     private:
index 7330e1e..b0a3e32 100644 (file)
@@ -55,10 +55,12 @@ namespace dai {
  *  So basically, a FactorGraph consists of a BipartiteGraph, a vector of Var 's
  *  and a vector of TFactor 's.
  *
- *  \todo Alternative implementation of undo factor changes: the only things that have to be
+ *  \idea Alternative implementation of undo factor changes: the only things that have to be
  *  undone currently are setting a factor to 1 and setting a factor to a Kronecker delta. This
  *  could also be implemented in the TFactor itself, which could maintain its state
- *  (ones/delta/full) and act accordingly.
+ *  (ones/delta/full) and act accordingly. Update: it seems that the proposed functionality 
+ *  would not be enough for CBP, for which it would make more sense to add more levels of
+ *  backup/restore.
  */ 
 class FactorGraph {
     public:
@@ -404,6 +406,13 @@ FactorGraph::FactorGraph(FactorInputIterator fact_begin, FactorInputIterator fac
 }
 
 
+/** \example example.cpp
+ *  This example illustrates how to read a factor graph from a file and how to
+ *  run several inference algorithms (junction tree, loopy belief propagation,
+ *  and the max-product algorithm) on it.
+ */
+
+
 } // end of namespace dai
 
 
index d4c395c..0a00b9b 100644 (file)
@@ -11,6 +11,8 @@
 
 /// \file
 /// \brief Defines class HAK, which implements a variant of Generalized Belief Propagation.
+/// \todo Implement Bethe approximation as a standard region graph choice in HAK.
+/// \idea Implement more general region graphs and corresponding Generalized Belief Propagation updates as described in [\ref YFW05].
 
 
 #ifndef __defined_libdai_hak_h
@@ -28,8 +30,6 @@ namespace dai {
 
 
 /// Approximate inference algorithm: implementation of single-loop ("Generalized Belief Propagation") and double-loop algorithms by Heskes, Albers and Kappen [\ref HAK03]
-/** \todo Optimize HAK with precalculated indices, similarly to BP.
- */
 class HAK : public DAIAlgRG {
     private:
         /// Outer region beliefs
index ee4c081..2283747 100644 (file)
@@ -326,10 +326,6 @@ class multifor {
  *  \note A State is very similar to a \link multifor \endlink, but tailored for Var 's and VarSet 's.
  *
  *  \see VarSet::calcState(), VarSet::calcStates()
- *
- *  \todo Rename VarSet::calcState(), VarSet::calcStates() and make them non-member functions;
- *        make the State class a more prominent part of libDAI (and document it clearly, explaining
- *        the concept of state); add more optimized variants of the State class like IndexFor (e.g. for TFactor<>::slice()).
  */
 class State {
     private:
index 04e65c0..979973b 100644 (file)
@@ -196,7 +196,7 @@ void tokenizeString( const std::string& s, std::vector<std::string>& outTokens,
 
 // OBSOLETE
 /// Used to keep track of the progress made by iterative algorithms.
-/** \deprecated Superfluous, because a simple std::vector<Real> provides the same functionality
+/** \deprecated Redundant, because a simple std::vector<Real> provides the same functionality
  */
 class Diffs : public std::vector<Real> {
     private:
index 202421c..6423390 100644 (file)
@@ -26,9 +26,9 @@ namespace dai {
 
 
 /// Represents a discrete random variable.
-/** A Var stores the \a label of the variable (an integer-valued unique ID)
- *  and the number of possible values (\a states) of that variable. Two
- *  Var objects with the same label are assumed to be identical (i.e., it
+/** A Var stores the \a label of the variable (a nonnegative integer-valued
+ *  unique ID) and the number of possible values (\a states) of that variable. 
+ *  Two Var objects with the same label are assumed to be identical (i.e., it
  *  is assumed that they have the same number of possible states).
  *
  *  In the documentation, we use the following notational conventions. The discrete
@@ -40,7 +40,7 @@ namespace dai {
 class Var {
     private:
         /// Label of the variable (its unique ID)
-        long    _label;
+        size_t  _label;
 
         /// Number of possible values
         size_t  _states;
@@ -49,12 +49,12 @@ class Var {
         /// Default constructor (creates a variable with label -1 and 0 states)
         Var() : _label(-1), _states(0) {}
         /// Constructs a variable with a given label and number of states
-        Var( long label, size_t states ) : _label(label), _states(states) {}
+        Var( size_t label, size_t states ) : _label(label), _states(states) {}
 
         /// Returns the label
-        long label() const { return _label; }
+        size_t label() const { return _label; }
         /// Returns reference to label
-        long & label() { return _label; }
+        size_t& label() { return _label; }
 
         /// Returns the number of states
         size_t states () const { return _states; }
diff --git a/scripts/makeREADME b/scripts/makeREADME
new file mode 100755 (executable)
index 0000000..02e2961
--- /dev/null
@@ -0,0 +1,16 @@
+#!/bin/bash
+echo "libDAI  -  A free/open source C++ library for Discrete Approximate Inference" > README
+echo >> README
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" >> README
+echo >> README
+echo "Version:  $DAI_VERSION" >> README
+echo "Date:     $DAI_DATE" >> README
+echo "See also: http://www.libdai.org" >> README
+echo >> README
+w3m -dump doc/html/license.html | awk 'BEGIN {start=0}; $1 ~ /━/ {start=start+1; if (start<2) print $0}; $1 !~ /━/ {if (start>0 && start<2) print $0}' >> README
+echo "You should have received a copy of the GNU General Public License" >> README
+echo "along with libDAI in the file COPYING. If not, see http://www.gnu.org/licenses/" >> README
+echo >> README
+w3m -dump doc/html/citations.html | awk 'BEGIN {start=0}; $1 ~ /━/ {start=start+1; if (start<2) print $0}; $1 !~ /━/ {if (start>0 && start<2) print $0}' >> README
+w3m -dump doc/html/index.html | awk 'BEGIN {start=0}; $1 ~ /━/ {start=start+1; if (start<2) print $0}; $1 !~ /━/ {if (start>0 && start<2) print $0}' >> README
+w3m -dump doc/html/build.html | awk 'BEGIN {start=0}; $1 ~ /━/ {start=start+1; if (start>0 && start<5) print $0}; $1 !~ /━/ {if (start>0 && start<5) print $0}' >> README
index b1b921c..7786b50 100644 (file)
@@ -249,7 +249,7 @@ Real BP::run() {
                 calcNewMessage( i, I.iter );
     } else {
         update_seq.reserve( nredges );
-        /// \todo Investigate whether performance increases by switching the order of following two loops:
+        /// \todo Investigate whether performance increases by switching the order of the following two loops:
         for( size_t i = 0; i < nrVars(); ++i )
             foreach( const Neighbor &I, nbV(i) )
                 update_seq.push_back( Edge( i, I.iter ) );
index 39bd6ab..4d9a6ce 100644 (file)
@@ -150,7 +150,6 @@ Real CBP::run() {
 }
 
 
-/// \todo Eventually this allow other inference algorithms that BP to be selected, via a property
 InfAlg* CBP::getInfAlg() {
     PropertySet bpProps;
     bpProps.Set("updates", props.updates);
@@ -204,7 +203,9 @@ void CBP::runRecurse( InfAlg *bp, Real orig_logZ, vector<size_t> clamped_vars_li
     // compute complement of 'xis'
     vector<size_t> cmp_xis = complement( xis, clampingVar ? var(i).states() : factor(i).states() );
 
-    /// \todo could do this more efficiently with a nesting version of saveProbs/undoProbs
+    /// \idea dai::CBP::runRecurse() could be implemented more efficiently with a nesting version of backupFactors/restoreFactors
+    // this improvement could also be done locally: backup the clamped factor in a local variable,
+    // and restore it just before we return.
     Real lz;
     vector<Factor> b;
     InfAlg *bp_c = bp->clone();
index e14ebc1..cc03952 100644 (file)
@@ -22,7 +22,7 @@ std::map<std::string, ParameterEstimation::ParamEstFactory> *ParameterEstimation
 
 void ParameterEstimation::loadDefaultRegistry() {
     _registry = new std::map<std::string, ParamEstFactory>();
-    (*_registry)["ConditionalProbEstimation"] = CondProbEstimation::factory;
+    (*_registry)["CondProbEstimation"] = CondProbEstimation::factory;
 }
 
 
@@ -146,7 +146,7 @@ SharedParameters::SharedParameters( std::istream &is, const FactorGraph &fg )
         var_order.reserve( vs.size() );
         for( size_t fi = 1; fi < fields.size(); ++fi ) {
             // Lookup a single variable by label
-            long label;
+            size_t label;
             std::istringstream labelparse( fields[fi] );
             labelparse >> label;
             VarSet::const_iterator vsi = vs.begin();
index f712491..82cdb25 100644 (file)
@@ -53,6 +53,10 @@ void Evidence::addEvidenceTabFile( std::istream &is, std::map<std::string, Var>
         vars.push_back( elem->second );
     }
 
+    getline(is,line);
+    if( is.fail() || line.size() > 0 )
+        DAI_THROWE(INVALID_EVIDENCE_FILE,"Expecting empty line");
+
     // Read samples
     while( getline(is, line) ) {
         line_number++;
index 41088f5..76c1c18 100644 (file)
@@ -116,7 +116,7 @@ std::istream& operator>> ( std::istream& is, FactorGraph &fg ) {
         cerr << "Reading " << nr_Factors << " factors..." << endl;
 
     getline (is,line);
-    if( is.fail() )
+    if( is.fail() || line.size() > 0 )
         DAI_THROWE(INVALID_FACTORGRAPH_FILE,"Expecting empty line");
 
     map<long,size_t> vardims;
index 457ebe1..1894413 100644 (file)
@@ -1,6 +1,6 @@
 1
 
 1
-ConditionalProbEstimation [target_dim=2,total_dim=4,pseudo_count=1]
+CondProbEstimation [target_dim=2,total_dim=4,pseudo_count=1]
 1
 0 1 0
index e59a890..6276467 100644 (file)
@@ -1,4 +1,5 @@
 0      1
+
 0      1
 0      1
 0      1
index dff5410..39a2df3 100644 (file)
@@ -1,6 +1,6 @@
 1
 
 1
-ConditionalProbEstimation [target_dim=2,total_dim=8,pseudo_count=1]
+CondProbEstimation [target_dim=2,total_dim=8,pseudo_count=1]
 1
 0 1 0 2
index ad5f220..4a9417a 100644 (file)
@@ -1,4 +1,5 @@
 0      1       2       4       6       7
+
 0      0       1               1       0
 1                      1       1       0
 0      1       0       0       0       1
index 977eb5b..ff464d8 100644 (file)
@@ -1,6 +1,6 @@
 1
 
 1
-ConditionalProbEstimation [target_dim=2,total_dim=8,pseudo_count=1]
+CondProbEstimation [target_dim=2,total_dim=8,pseudo_count=1]
 1
 2 1 2 4
index 1f7756f..771313d 100644 (file)
@@ -1,7 +1,7 @@
 1
 
 1
-ConditionalProbEstimation [target_dim=2,total_dim=8,pseudo_count=1]
+CondProbEstimation [target_dim=2,total_dim=8,pseudo_count=1]
 3
 2 1 2 4
 1 0 1 6
index fd656c6..db98e0d 100644 (file)
@@ -1,7 +1,7 @@
 1
 
 1
-ConditionalProbEstimation [target_dim=2,total_dim=8,pseudo_count=1]
+CondProbEstimation [target_dim=2,total_dim=8,pseudo_count=1]
 2
 2 1 2 4
 0 6 2 7
index 6ffbf42..421b0c8 100644 (file)
@@ -1,23 +1,12 @@
-/*  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
-
-    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
-*/
+/*  This file is part of libDAI - http://www.libdai.org/
+ *
+ *  libDAI is licensed under the terms of the GNU General Public License version
+ *  2, or (at your option) any later version. libDAI is distributed without any
+ *  warranty. See the file COPYING for more details.
+ *
+ *  Copyright (C) 2006-2009  Joris Mooij  [joris dot mooij at libdai dot org]
+ *  Copyright (C) 2006-2007  Radboud University Nijmegen, The Netherlands
+ */
 
 
 #include <iostream>
index ec4b94c..aefdf3d 100644 (file)
@@ -1,23 +1,12 @@
-/*  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
-
-    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
-*/
+/*  This file is part of libDAI - http://www.libdai.org/
+ *
+ *  libDAI is licensed under the terms of the GNU General Public License version
+ *  2, or (at your option) any later version. libDAI is distributed without any
+ *  warranty. See the file COPYING for more details.
+ *
+ *  Copyright (C) 2006-2009  Joris Mooij  [joris dot mooij at libdai dot org]
+ *  Copyright (C) 2006-2007  Radboud University Nijmegen, The Netherlands
+ */
 
 
 #include <iostream>
index 612b52c..4605297 100644 (file)
@@ -1,23 +1,12 @@
-/*  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
-
-    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
-*/
+/*  This file is part of libDAI - http://www.libdai.org/
+ *
+ *  libDAI is licensed under the terms of the GNU General Public License version
+ *  2, or (at your option) any later version. libDAI is distributed without any
+ *  warranty. See the file COPYING for more details.
+ *
+ *  Copyright (C) 2006-2009  Joris Mooij  [joris dot mooij at libdai dot org]
+ *  Copyright (C) 2006-2007  Radboud University Nijmegen, The Netherlands
+ */
 
 
 #include <iostream>