Made alias support official part of the library
authorJoris Mooij <joris.mooij@tuebingen.mpg.de>
Fri, 15 Jan 2010 11:42:14 +0000 (12:42 +0100)
committerJoris Mooij <joris.mooij@tuebingen.mpg.de>
Fri, 15 Jan 2010 11:42:14 +0000 (12:42 +0100)
include/dai/alldai.h
include/dai/doc.h
src/alldai.cpp
tests/testdai.cpp

index ed04ce2..18f276f 100644 (file)
@@ -11,7 +11,6 @@
 
 /// \file
 /// \brief Main libDAI header file. It \#includes all other libDAI headers.
-/// \todo Update documentation about aliases (add a section to the fileformats)
 
 
 #ifndef __defined_libdai_alldai_h
@@ -75,11 +74,18 @@ InfAlg *newInfAlg( const std::string &name, const FactorGraph &fg, const Propert
  *  \param fg The FactorGraph that the algorithm should be applied to.
  *  \return Returns a pointer to the new InfAlg object; it is the responsibility of the caller to delete it later.
  *  \throw UNKNOWN_DAI_ALGORITHM if the requested name is not known/compiled in.
- *  \todo Allow alias substitution
  */
 InfAlg *newInfAlgFromString( const std::string &nameOpts, const FactorGraph &fg );
 
 
+/// Constructs a new inference algorithm.
+/** \param aliases Maps names to strings in the format "name[key1=val1,key2=val2,...,keyn=valn]"; if not empty, alias substitution
+ *  will be performed when parsing \a nameOpts by invoking parseNameProperties(const std::string &,const std::map<std::string,std::string> &)
+ *  \see newInfAlgFromString(const std::string &, const FactorGraph &)
+ */
+InfAlg *newInfAlgFromString( const std::string &nameOpts, const FactorGraph &fg, const std::map<std::string,std::string> &aliases );
+
+
 /// Extracts the name and property set from a string \a s in the format "name[key1=val1,key2=val2,...]" or "name"
 std::pair<std::string, PropertySet> parseNameProperties( const std::string &s );
 
@@ -93,6 +99,10 @@ std::pair<std::string, PropertySet> parseNameProperties( const std::string &s, c
 
 
 /// Reads aliases from file named \a filename
+/** \param filename Name of the alias file
+ *  \return A map that maps aliases to the strings they should be substituted with.
+ *  \see \ref fileformats-aliases
+ */
 std::map<std::string,std::string> readAliasesFile( const std::string &filename );
 
 
index dbc7904..963ba34 100644 (file)
  *  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).
+ *
+ *  \section fileformats-aliases Aliases file format
+ *
+ *  An aliases file is basically a list of "macros" and the strings that they
+ *  should be substituted with.
+ *  
+ *  Each line of the aliases file can be either empty, contain a comment 
+ *  (if the first character is a '#') or contain an alias. In the latter case, 
+ *  the line should contain a colon; the part before the colon contains the 
+ *  name of the alias, the part after the colon the string that it should be 
+ *  substituted with. Any whitespace before and after the colon is ignored.
+ *
+ *  For example, the following line would define the alias \c BP_SEQFIX
+ *  as a shorthand for "BP[updates=SEQFIX,tol=1e-9,maxiter=10000,logdomain=0]":
+ *  <pre>
+ *  BP_SEQFIX:  BP[updates=SEQFIX,tol=1e-9,maxiter=10000,logdomain=0]
+ *  </pre>
+ *
+ *  Aliases files can be used to store default options for algorithms.
  */
 
 /** \page bibliography Bibliography
index 1468bb6..87335eb 100644 (file)
@@ -69,19 +69,14 @@ InfAlg *newInfAlg( const std::string &name, const FactorGraph &fg, const Propert
 
 
 InfAlg *newInfAlgFromString( const std::string &nameOpts, const FactorGraph &fg ) {
-    string::size_type pos = nameOpts.find_first_of('[');
-    string name;
-    PropertySet opts;
-    if( pos == string::npos ) {
-        name = nameOpts;
-    } else {
-        name = nameOpts.substr(0,pos);
+    pair<string,PropertySet> no = parseNameProperties( nameOpts );
+    return newInfAlg( no.first, fg, no.second );
+}
 
-        stringstream ss;
-        ss << nameOpts.substr(pos,nameOpts.length());
-        ss >> opts;
-    }
-    return newInfAlg(name,fg,opts);
+
+InfAlg *newInfAlgFromString( const std::string &nameOpts, const FactorGraph &fg, const std::map<std::string,std::string> &aliases ) {
+    pair<string,PropertySet> no = parseNameProperties( nameOpts, aliases );
+    return newInfAlg( no.first, fg, no.second );
 }
 
 
index ebdd890..e180c2c 100644 (file)
@@ -208,6 +208,7 @@ int main( int argc, char *argv[] ) {
         if( !aliases.empty() )
             Aliases = readAliasesFile( aliases );
 
+        // Read factor graph
         FactorGraph fg;
         fg.ReadFromFile( filename.c_str() );