Added Makefile.ALL (which I forgot to do at the last commit) and improved documentation
authorJoris Mooij <joris.mooij@tuebingen.mpg.de>
Sun, 7 Feb 2010 16:22:35 +0000 (17:22 +0100)
committerJoris Mooij <joris.mooij@tuebingen.mpg.de>
Sun, 7 Feb 2010 16:22:35 +0000 (17:22 +0100)
ChangeLog
Makefile
Makefile.ALL [new file with mode: 0644]
README
include/dai/alldai.h
include/dai/doc.h
tests/aliases.conf

index 69132e6..40129cf 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,4 @@
+* Improved documentation
 * Documented tests/testdai
 * Moved platform independent build options into Makefile.ALL
 * Windows platform now needs boost 1.37 or higher
index 5a4a690..b592e2c 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -322,9 +322,11 @@ endif
 
 doc : $(INC)/*.h $(SRC)/*.cpp examples/*.cpp doxygen.conf
        doxygen doxygen.conf
-       # DAI_VERSION=$(DAI_VERSION) DAI_DATE=$(DAI_DATE) scripts/makeREADME
 
-TAGS:
+README : doc scripts/makeREADME
+       DAI_VERSION=$(DAI_VERSION) DAI_DATE=$(DAI_DATE) scripts/makeREADME
+
+TAGS :
        etags src/*.cpp include/dai/*.h tests/*.cpp utils/*.cpp
        ctags src/*.cpp include/dai/*.h tests/*.cpp utils/*.cpp
 
diff --git a/Makefile.ALL b/Makefile.ALL
new file mode 100644 (file)
index 0000000..b159a2f
--- /dev/null
@@ -0,0 +1,45 @@
+# 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) 2009-2010  Joris Mooij  [joris dot mooij at libdai dot org]
+
+
+# This file can be used to configure compile time options of libDAI.
+# Here the user can enable or disable various approximate inference 
+# methods and additional build targets (documentation, MatLab interface)
+# and specify whether to build with debug information included.
+#
+# It is platform independent and is included by Makefile.
+#
+# A boolean variable VAR can be set to true ("VAR=true") or to false ("VAR=")
+
+
+# COMPILATION AND BUILD FLAGS
+
+# Enable/disable various approximate inference methods
+WITH_BP=true
+WITH_FBP=true
+WITH_TRWBP=true
+WITH_MF=true
+WITH_HAK=true
+WITH_LC=true
+WITH_TREEEP=true
+WITH_JTREE=true
+WITH_MR=true
+WITH_GIBBS=true
+WITH_CBP=true
+
+# Build doxygen documentation?
+WITH_DOC=true
+
+# Build with debug info?
+DEBUG=true
+
+# Build MatLab interface?
+WITH_MATLAB=
+
+# MatLab version 7.3 (R2006b) or newer?
+NEW_MATLAB=true
diff --git a/README b/README
index d5d4011..58403ae 100644 (file)
--- a/README
+++ b/README
@@ -183,13 +183,14 @@ 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
+directories may differ from system to system. Platform independent build
+options can be set in Makefile.ALL. Finally, run
 
   make
 
 The build includes a regression test, which may take a while to complete.
 
-If the build was successful, you can test the example program:
+If the build is successful, you can test the example program:
 
   examples/example tests/alarm.fg
 
@@ -212,14 +213,14 @@ 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)
+Makefile.conf to adapt it to your local setup. Platform independent build
+options can be set in Makefile.ALL. Finally, run (from the command line)
 
   make
 
 The build includes a regression test, which may take a while to complete.
 
-If the build was successful, you can test the example program:
+If the build is successful, you can test the example program:
 
   examples\example tests\alarm.fg
 
@@ -238,7 +239,7 @@ You need:
 
 First, you need to build the libDAI source as described above for your
 platform. By default, the MatLab interface is disabled, so before compiling the
-source, you have to enable it in the Makefile.conf by setting
+source, you have to enable it in Makefile.ALL by setting
 
   WITH_MATLAB=true
 
index 716b0a7..312cf63 100644 (file)
@@ -9,8 +9,15 @@
  */
 
 
-/// \file
-/// \brief Main libDAI header file. It \#includes all other libDAI headers.
+/** \file
+ *  \brief Main libDAI header file. It \#includes all other libDAI headers.
+ * 
+ *  \todo Replace VarSets by SmallSet<size_t> where appropriate, in order to minimize the use of FactorGraph::findVar().
+ *
+ *  \todo Implement routines for UAI probabilistic inference evaluation data
+ *
+ *  \todo Improve SWIG interfaces and merge their build process with the main build process
+ */
 
 
 #ifndef __defined_libdai_alldai_h
index c315946..254a0b8 100644 (file)
 /** \file
  *  \brief Contains additional doxygen documentation
  *
- *  \todo Write a concept/notations page for the documentation,
- *  explaining the concepts of "state" (index into a 
- *  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
- *
- *  \todo Document tests and utils
- *
- *  \todo Implement routines for UAI probabilistic inference evaluation data
- *
- *  \todo Improve SWIG interfaces
+ *  \todo Document utils/createfg (and clean up the code a bit)
  *
  *  \idea Adapt (part of the) guidelines in http://www.boost.org/development/requirements.html#Design_and_Programming
  *
  *  \idea Use "gcc -MM" to generate dependencies for targets: http://make.paulandlesley.org/autodep.html
  *
- *  \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:
  *  - a BipartiteGraph
@@ -57,7 +44,7 @@
 /** \mainpage Reference manual for libDAI - A free/open source C++ library for Discrete Approximate Inference methods
  *  \author Joris Mooij
  *  \version git HEAD
- *  \date January 12, 2010 - or later
+ *  \date February 4, 2010 - or later
  *
  *  <hr size="1">
  *  \section about About libDAI
  *  To build the libDAI source, first copy a template Makefile.* to Makefile.conf
  *  (for example, copy Makefile.LINUX to Makefile.conf if you use GNU/Linux). 
  *  Then, edit the Makefile.conf template to adapt it to your local setup.
- *  Especially directories may differ from system to system. Finally, run
+ *  Especially directories may differ from system to system. Platform independent
+ *  build options can be set in Makefile.ALL. 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:
+ *  If the build is 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>
  *  - 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)
+ *  Makefile.conf to adapt it to your local setup. Platform independent 
+ *  build options can be set in Makefile.ALL. Finally, run (from the command line)
  *  <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:
+ *  If the build is 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>
  *
  *  First, you need to build the libDAI source as described above for your
  *  platform. By default, the MatLab interface is disabled, so before compiling the
- *  source, you have to enable it in the Makefile.conf by setting
+ *  source, you have to enable it in Makefile.ALL by setting
  *  <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,
  */
 
 
-/** \page inference Graphical models and approximate inference
+/** \page terminology Terminology and conventions
  *
- *  \section inference-graphicalmodels Graphical models
+ *  \section terminology-graphicalmodels Graphical models
  *
  *  Commonly used graphical models are Bayesian networks and Markov random fields.
  *  In libDAI, both types of graphical models are represented by a slightly more 
  *  This is why libDAI uses a factor graph as representation of a 
  *  graphical model, implemented in the dai::FactorGraph class.
  *
- *  \section inference-inference Inference tasks
+ *  \section terminology-inference Inference tasks
  *
  *  Given a factor graph, specified by the variable nodes \f$\{x_i\}_{i\in\mathcal{V}}\f$
  *  the factor nodes \f$ \mathcal{F} \f$, the graph structure, and the factors
  *  is only possible with dai::JTree and dai::BP, calculating partition sums is
  *  not possible with dai::MR, dai::LC and dai::Gibbs.
  *
- *  \section inference-learning Parameter learning
+ *  \section terminology-learning Parameter learning
  *
  *  In addition, libDAI supports parameter learning of conditional probability
  *  tables by Expectation Maximization (or Maximum Likelihood, if there is no
  *  missing data). This is implemented in dai::EMAlg.
  *  
+ *  \section terminology-variables-states Variables and states
+ *
+ *  Linear states are a concept that is used often in libDAI, for example for storing
+ *  and accessing factors, which are functions mapping from states of a set of variables
+ *  to the real numbers. Internally, a factor is stored as an array, and the array index
+ *  of an entry corresponds with the linear state of the set of variables. Below we will
+ *  define variables, states and linear states of (sets of) variables.
+ *
+ *  \subsection terminology-variables Variables
+ *
+ *  Each (random) \a variable has a unique identifier, its \a label (which has
+ *  a non-negative integer value). If two variables have the same
+ *  label, they are considered as identical. A variable can take on a finite
+ *  number of different values or \a states.
+ *  
+ *  We use the following notational conventions. The discrete
+ *  random variable with label \f$l\f$ is denoted as \f$x_l\f$, and the number
+ *  of possible values of this variable as \f$S_{x_l}\f$ or simply \f$S_l\f$. 
+ *  The set of possible values of variable \f$x_l\f$ is denoted 
+ *  \f$X_l := \{0,1,\dots,S_l-1\}\f$ and called its \a state \a space.
+ *
+ *  \subsection terminology-variable-sets Sets of variables and the canonical ordering
+ *  
+ *  Let \f$A := \{x_{l_1},x_{l_2},\dots,x_{l_n}\}\f$ be a set of variables. 
+ *
+ *  The \a canonical \a ordering of the variables in \a A is induced by their labels.
+ *  That is: if \f$l_1 < l_2\f$, then \f$x_{l_1}\f$ occurs before \f$x_{l_2}\f$ in the
+ *  canonical ordering. Below, we will assume that \f$(l_i)_{i=1}^n\f$ is
+ *  ordered according to the canonical ordering, i.e., \f$l_1 < l_2 < \dots < l_n\f$.
+ *
+ *  \subsection terminology-variable-states States and linear states of sets of variables
+ *
+ *  A \a state of the variables in \a A refers to a joint assignment of the 
+ *  variables, or in other words, to an element of the Cartesian product 
+ *  \f$ \prod_{i=1}^n X_{l_i}\f$ of the state spaces of the variables in \a A.
+ *  Note that a state can also be interpreted as a mapping from variables (or
+ *  variable labels) to the natural numbers, which assigns to a variable (or its
+ *  label) the corresponding state of the variable.
+ *
+ *  A state of \a n variables can be represented as an n-tuple of 
+ *  non-negative integers: \f$(s_1,s_2,\dots,s_n)\f$ corresponds to the
+ *  joint assignment \f$x_{l_1} = s_1, \dots, x_{l_n} = s_n\f$.
+ *  Alternatively, a state can be represented compactly as one non-negative integer;
+ *  this representation is called a \a linear \a state. The linear state
+ *  \a s corresponding to the state \f$(s_1,s_2,\dots,s_n)\f$ would be:
+ *  \f[
+ *    s := \sum_{i=1}^n s_i \prod_{j=1}^{i-1} S_{l_j} 
+ *       = s_1 + s_2 S_{l_1} + s_3 S_{l_1} S_{l_2} + \dots + s_n S_{l_1} \cdots S_{l_{n-1}}.
+ *  \f]
+ *
+ *  Vice versa, given a linear state \a s for the variables \a A, the
+ *  corresponding state \f$s_i\f$ of the \a i 'th variable \f$x_{l_i}\f$ (according to
+ *  the canonical ordering of the variables in \a A) is given by
+ *  \f[
+ *    s_i = \left\lfloor\frac{s \mbox { mod } \prod_{j=1}^i S_{l_j}}{\prod_{j=1}^{i-1} S_{l_j}}\right\rfloor.
+ *  \f]
+ *
+ *  Finally, the \a number \a of \a states of the set of variables \a A is simply the 
+ *  number of different joint assignments of the variables, that is, \f$\prod_{i=1}^n S_{l_i}\f$.
  */
 
 
index 4608cc6..0890a29 100644 (file)
@@ -1,3 +1,16 @@
+# This file contains reasonable default settings for various inference
+# algorithms in libDAI. Each non-empty line should either be a comment
+# (starting with #) or contain an alias definition in the format
+#
+# alias:    name[key1=val1,key2=val2,...,keyn=valn]
+#
+# where name should be a valid libDAI algorithm name, and the list of
+# its properties (between rectangular brackets) consists of key=value
+# pairs, seperated by spaces. This defines 'alias' as a shortcut for
+# the rest of the line (more precisely, the contents to the right of 
+# the colon and possible whitespace).
+
+
 # --- EXACT -------------------
 
 EXACT:                          EXACT[verbose=0]