documentation

README.md

@@ -27,7 +27,7 @@ Get the latest revision from GitHub:
 Requirements
 ============
 
-- C/C++11 compiler (clang3.5+, gcc4.9+, intel14+, ...)
+- C/C++11 compiler (clang3.5+, gcc4.9+, intel15+, ...)
 - CMake 2.8.5+
 
 Optional:

doc/Doxyfile

@@ -98,7 +98,7 @@ OUTPUT_LANGUAGE        = English
 # documentation (similar to Javadoc). Set to NO to disable this.
 # The default value is: YES.
 
-BRIEF_MEMBER_DESC      = NO
+BRIEF_MEMBER_DESC      = YES
 
 # If the REPEAT_BRIEF tag is set to YES, doxygen will prepend the brief
 # description of a member or function before the detailed description

doc/mainpage.dox

@@ -1,16 +1,7 @@
 namespace Faunus {
 
 /*!
-@page video Video Tutorial
-
-@htmlonly
-<iframe src="https://docs.google.com/file/d/0BzpLUBrTxmurRzN0RnFZc2lhZFE/preview" width="640" height="385"></iframe>
-@endhtmlonly
-
-*/
-
-/*!
-@page jsonyaml Input and output
+@page inputoutput Input and output
 @tableofcontents
 
 # JSON input and output
@@ -53,7 +44,7 @@ for melted NaCl for the `bulk.cpp` program:
 ~~~
 
 Each section is read by a constructor of a C++ class, called
-from the main program:
+from the main program (`bulk.cpp`):
 
  Section       |   Class                        |  Control  |  Notes
 -------------- | ------------------------------ | --------- | --------------------
@@ -160,6 +151,14 @@ the following to `~/.vimrc`:
 
 */
 
+/*!
+@page video Video Tutorial
+
+@htmlonly
+<iframe src="https://docs.google.com/file/d/0BzpLUBrTxmurRzN0RnFZc2lhZFE/preview" width="640" height="385"></iframe>
+@endhtmlonly
+*/
+
 /*!
 @page development Development
 @tableofcontents

include/faunus/mcloop.h

@@ -118,17 +118,37 @@ namespace Faunus
    * :-------| :----------------------------
    * `macro` | Number of steps in outer loop
    * `micro` | Number of steps in inner loop
+   *
+   * Example:
+   *
+   * ~~~{.cpp}
+   * MCLoop loop( R"({"macro":2, "micro":5})"_json );
+   * while ( loop[0] ) // 2 times
+   *     while ( loop[1] ) // 5 times
+   *         ...
+   * ~~~
    */
   class MCLoop : public TimedCounter<int>
   {
   private:
       typedef TimedCounter<int> base;
   public:
-      inline MCLoop( Tmjson &j, string sec = "system" )
+      inline MCLoop( const Tmjson &j, const string &sec = "system" )
       {
-          Tmjson _j = j.at(sec).at("mcloop");
-          base::set( { _j.value("macro", 0), _j.value("micro", 0) } );
-          assert(base::l[0] * base::l[1] >= 0);
+          try
+          {
+              Tmjson _j = j;
+              if (j.count(sec)>0)
+                  if (j[sec].count("mcloop")>0)
+                      _j = j[sec]["mcloop"];
+              base::set( { _j.at("macro"), _j.at("micro") } );
+              assert(base::l[0] * base::l[1] >= 0);
+          }
+          catch (std::exception &e)
+          {
+              std::cerr << "Error initializing MCLoop: " << e.what() << endl;
+              throw;
+          }
       }
 
       inline std::string timing() const

include/faunus/molecule.h

@@ -156,7 +156,7 @@ namespace Faunus
    * `insdir`      | string  | Directions for generation of random position. Default: "1 1 1" = XYZ
    * `insoffset`   | string  | Translate generated random position. Default: "0 0 0" = no translation
    * `keeppos`     | bool    | Keep original positions (`insdir`, `insoffset` ignored. Default: `false`)
-   * `Ninit`       | int     | Initial number of molecules
+   * `Ninit`       | int     | Initial number of molecules to be inserted into the simulation container
    * `checkoverlap`| bool    | Check for overlap while inserting. Default: true
    * `rotate`      | bool    | Randomly rotate molecule or anisotropic atom upon insertion. Default: true
    * `structure`   | string  | Read conformation from PQR/XYZ/AAM file

include/faunus/move.h

@@ -4846,7 +4846,8 @@ namespace Faunus
      *     "_jsonfile" : "move_out.json"
      *
      * If the string is empty, no file will be written.
-     *
+     * See @ref inputoutput for more information about pretty printing
+     * JSON output.
      */
     template<typename Tspace, bool polarise = false, typename base=Movebase<Tspace>>
     class Propagator : public base

include/faunus/physconst.h

@@ -33,8 +33,8 @@ namespace Faunus
           R,                   //!< Molar gas constant [J/(K*mol)]
           Nav;                 //!< Avogadro's number [1/mol]
       static Td lB( Td );      //!< Bjerrum length [Aangstrom]
-      static Td T();         //!< Return temperature [K]
-      static Td kT();        //!< Returns k_bT [J]
+      static Td T();           //!< Temperature [K]
+      static Td kT();          //!< Thermal energy [J]
       static void setT( Td );  //!< Set temperature [K]
   };
 
@@ -68,9 +68,11 @@ namespace Faunus
   template<class Td>
   Td PhysicalConstants<Td>::_T = 298.15;
 
+  /** @param temp Temperature in Kelvin */
   template<class Td>
   PhysicalConstants<Td>::PhysicalConstants( Td temp ) { setT(temp); }
 
+  /** @param temp Temperature in Kelvin */
   template<class Td>
   void PhysicalConstants<Td>::setT( Td temp ) { _T = temp; }
 
@@ -80,6 +82,7 @@ namespace Faunus
   template<class Td>
   Td PhysicalConstants<Td>::kT() { return kB * _T; }
 
+  /** @param e_r Relative dielectric constant */
   template<class Td>
   Td PhysicalConstants<Td>::lB( Td e_r )
   {

include/faunus/space.h

@@ -208,12 +208,33 @@ namespace Faunus
   /**
    * @brief Placeholder for particles and groups
    *
-   * Every simulation must have a `Space` instance as this contains
-   * the particles and information about groups (particle ranges).
-   * Space also contains the geometry as given by the template
-   * parameter.
+   * This is normally the very first class
+   * initialized in a Faunus program as most other classes depend
+   * upon it. Space defines the particle types, molecule types,
+   * geometry of the simulation container, boundary conditions,
+   * and contains the state of all particles and groups.
    *
-   * @todo insert/erase functions are a mess.
+   * This happens upon construction from a JSON object:
+   *
+   * 1. The given geometry, `Tgeometry`, is initialized with
+   *    data from the JSON section `geometry`.
+   *
+   * 2. The system temperature is set with `PhysicalConstants::setT()`
+   *    with data from JSON section `system/temperature`. The default
+   *    value is 298.15 K.
+   *
+   * 3. `AtomMap` is initialized with data found in JSON section
+   *    `atomlist`. If `AtomData::Ninit` is given, atoms will be
+   *    inserted into the simulation container, respecting
+   *    boundary conditions.
+   *
+   * 4. `MoleculeMap` is initialized with data found in JSON section
+   *    `atomlist`. If `MoleculeData::Ninit` is given, molecules will be
+   *    inserted into the simulation container, respecting
+   *    boundary conditions.
+   *
+   * @tparam Tgeometry Simulation container geometry derived from `Geometry::Geometrybase`
+   * @tparam Tparticle Particle type based on `PointParticle`
    */
   template<typename Tgeometry, typename Tparticle=PointParticle>
   class Space

include/faunus/species.h

@@ -222,7 +222,7 @@ namespace Faunus
   class AtomData : public PropertyBase
   {
   public:
-      double sigma,            //!< LJ diameter [angstrom]
+      double sigma,         //!< LJ diameter [angstrom]
           eps,              //!< LJ epsilon [kJ/mol] (pair potentials should convert to kT)
           radius,           //!< Radius [angstrom]
           muscalar,         //!< Dipole momentscalar [e \f$ \unicode{x212B} \f$]
@@ -247,7 +247,7 @@ namespace Faunus
           tfe,              //!< Transfer free energy (J/mol/angstrom^2/M)
           alphax;           //!< Excess polarizability [angstrom^3]
       Point mu;                //!< Dipolemoment vector
-      int Ninit;               //!<
+      int Ninit;               //!< Initial number of atoms to insert into simulation container
       short int patchtype;     //!< If patchy particle, which type of patch
       bool hydrophobic;        //!< Are we hydrophobic?
       Tensor<double>

src/examples/bulk.cpp

@@ -18,19 +18,17 @@ typedef Space<Tgeometry,PointParticle> Tspace;
 int main() {
   cout << textio::splash();           // show faunus banner and credits
 
-  InputMap mcp("bulk.json");          // open user input file
+  Tmjson mcp = openjson("bulk.json"); // open JSON input file
   MCLoop loop(mcp);                   // class for handling mc loops
 
-  // Construct Hamiltonian and Space
-  Tspace spc(mcp);
+  Tspace spc(mcp);                    // simulation space
 
   auto pot = Energy::Nonbonded<Tspace,TpairpotCut>(mcp)
-    + Energy::ExternalPressure<Tspace>(mcp);
+    + Energy::ExternalPressure<Tspace>(mcp); // hamiltonian
 
-  Analysis::CombinedAnalysis analyzer(mcp,pot,spc);
-
-  spc.load("state");                               // load old config. from disk (if any)
+  spc.load("state");                  // load old config. from disk (if any)
 
+  Analysis::CombinedAnalysis analyzer(mcp,pot,spc);
   Move::Propagator<Tspace> mv(mcp,pot,spc);
 
   cout << atom.info() + spc.info() + pot.info()