Context Navigation

-              r74459a
+              rcaece4
  * Description: creates and alters molecular systems
  * Copyright (C)  2010 University of Bonn. All rights reserved.
+ * Copyright (C)  2014 Frederik Heber. All rights reserved.
  * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
  */
 …
  *  the Action does.
+ *
+ *  Each Action has thus three types of functionality: do, undo, and redo.
+ *  Each Action has thus three types of functionality: do, undo, and redo. And
+ *  each action has a unique \a token: a name without white space that is
+ *  descriptive.
+ *
+ *  The ActionRegistry contains a prototype of each Action under its token
+ *  such that an instance can be retrieved by knowing this token.
+ *  The ActionRegistry contains a prototype of each Action under its token.
+ *  If an Action is requested via its known token from the ActionQueue
+ *  (that contains the ActionRegistry), this prototype is cloned and added to the
+ *  queue.
+ *
+ *  Each Action can contain multiple \ref parameters in its specific ActionParameters
+ *  structure that represent the options. Executing call() first fills a dialog
+ *  with \ref queries, one for each option. The UI then tries to obtain the
+ *  values from the user. Depending on the type of the UI in use that could mean
+ *  parsing stored command line parameters or displaying a real dialog box with widgets.
+ *  Each Action can contain multiple \ref parameters in its specific
+ *  ActionParameters structure that represent the options. Executing call() first
+ *  fills a dialog with \ref queries, one for each option. The UI then tries to
+ *  obtain the values from the user. Depending on the type of the UI in use that
+ *  could mean parsing stored command line parameters or displaying a real dialog
+ *  box with widgets.
+ *
  *  Also there is a regression test (\ref regression-test) for each Action to
  *  check that it always behaves the same no matter how much the code
+ *  implementing actually has changed.
+ *  implementing actually has changed. In most cases also for testing undo and
+ *  redo.
+ *
  * \section actions-add To add a new action ...
 …
+ *
  * The central points of Actions is that they can be undone and redone. This
  * has to be implemented in two more functions beside the "do".
+ * has to be implemented in two more functions beside the "do" in performCall().
+ *
  * Note that undoing means to get everything back to its original state and by whatever
 …
  * E.g. if your Action creates some new atoms, store their info as \ref AtomicInfo.
  * Then, undo can simply delete the newly created atoms and redo can quickly re-
+ * create them in the state they have been before.
+ * create them in the state they have been before. Types required for storage are
+ * contained in the Action's state and are filled during performCall(). Undo and
+ * redo both get access to this state and may use the information as described.
+ *
  * Have a look at \ref UndoRedoHelpers.hpp for some helper functions on this.
 …
+ *
+ *
  *  \date 2013-02-07
+ *  \date 2014-03-10
+ *
  */

src/documentation/constructs/atoms.dox

-              r74459a
+              rcaece4
  * Description: creates and alters molecular systems
  * Copyright (C)  2010 University of Bonn. All rights reserved.
+ * Copyright (C)  2014 Frederik Heber. All rights reserved.
  * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
  */
 …
  * -# CopyAtoms_Simple: Fills the internal set with true copies.
  * -# CopyAtoms_withBonds: Additionally also adds bonds in between the copies
  *    as they exist in between the original atoms.
+ *    when they exist in between the original atoms.
  * -# CopyAtoms_SaturateDanglingBonds: additionally checks for cut bond that
  *    would now become dangling bonds and inserts additional hydrogens for

src/documentation/constructs/bondgraph.dox

r74459a	rcaece4
19	19	* externally given bond table that gives typical bond lengths per element.
20	20	*
21		* The BondGraph's main work~~ing~~ horse is the BondGraph::CreateAdjacency()
	21	* The BondGraph's main work horse is the BondGraph::CreateAdjacency()
22	22	* function. It is strongly connected to the following graph actions:
23	23	* - GraphCreateAdjacencyAction
24	24	* - GraphSubgraphDissectionAction
25	25	*
26		* Therein, the bond structure is recognized ~~again~~ from scratch or/and the
	26	* Therein, the bond structure is recognized from scratch or/and the
27	27	* molecules afterwards represent disconnected subgraphs.
28	28	*

src/documentation/constructs/filling.dox

r74459a	rcaece4
15	15	/** \page filling Filling a domain
16	16	*
17		* The idea behind filling a domain is to cluster it with a set of nodes,
18		* i.e. a position in space in such a way that e.g. around node is sufficient
	17	* The idea behind filling a domain is to cluster it with a set of \b nodes,
	18	* i.e. a position in space in such a way that e.g. around a node is sufficient
19	19	* space to fill in the desired molecule. The logic of generating the nodes
20	20	* is responsible to create them in such a way as to allow for dense (or
…	…
23	23	* filling the specific domain (sphere, ellipsoid, cuboid, pyramid, ...)
24	24	* in the best possible way.
25		* Whether each node can be filled is then to be decided by a predicate.
	25	* Whether each node can be filled is then to be decided by a \b predicate.
26	26	*
27	27	* The filling routine uses then both to traverse the given nodes and
…	…
40	40	*
41	41	* The node generation is basically just a point or mesh generator that fills
42		* a specified region ~~(best would be based on the class Shape) with a mesh in~~
43		* ~~such a way as to~~ fulfill certain criteria:
	42	* a specified region based on the class Shape with a mesh in such a way as to
	43	* fulfill certain criteria:
44	44	*
45	45	* -# equidistant
…	…
55	55	* be composable via logic operators such as \|\| (or), && (and), ! (not), ...
56	56	*
57		* ~~Note that~~ each predicate receives on construction all the required
	57	* \note each predicate receives on construction all the required
58	58	* information, e.g. LinkedCell_View or Tesselation references or objects, ...
59	59	*
…	…
65	65	*
66	66	* It rejects all nodes that evaluate to false, the list of valid points is
67		* then traversed again and at each node a Cluster is created.
	67	* then traversed again and at each node a Cluster is created by the copy method.
68	68	*
69	69	* Note that we rely on \ref Cluster's, objects containing a set of atomicId_t
70		* and ~~that are inside a contained \ref Shape~~, to fill at each node. We use
	70	* and a \ref Shape, containing all of these atoms, to fill at each node. We use
71	71	* Cluster::clone() to create a copy that is subsequently placed at the desired
72	72	* node via an \ref Inserter functor. This allows to either simply shift the
…	…
75	75	*
76	76	*
77		* \date 201~~2-01-16~~
	77	* \date 2014-03-10
78	78	*/

src/documentation/constructs/fragmentation.dox

-              r74459a
+              rcaece4
  * molecular system into fragments. This is part of the so-called BOSSANOVA
  * (Bond Order diSSection in an ANOVA-like fashion) approach to get linear
+ * scaling complexity for ab-initio quantum chemistry methods.
+ * scaling complexity for ab-initio quantum chemistry methods. This method is
+ * explained in the doctoral thesis of Frederik Heber.
+ *
+ * \secton fragmentation-fragmentation Fragmenting molecules
+ *
+ * Everything starts in the Action FragmentationFragmentationAction. We require
+ * a list of selected atoms. These are browsed and we note down all the associated
+ * molecules (fragmentation is molecule-based). Subsequently, we make sure that
+ * the bond degree has correct bond degress with respect to the selected set.
+ * Then, Fragmentation is created for each molecule in the list.
  * The class Fragmentation contains with Fragmentation::FragmentMolecule()
+ * the main routine that dissect a given system and stores the fragments
+ * as configuration files.
+ * the main routine that dissect a given molecule
+ * Afterwards, all KeySet's are obtained as a Graph from the Fragmentation
+ * instance and combined into a single graph.
+ * Via a depth first search analysis cycles are detected and added as
+ * cycle fragments to this sets of KeySet.
+ * Finally, all fragments are placed in the FragmentationResultContainer.
+ *
+ * After these have been treated with a supported ab-initio solver, the
+ * energies and forces can be put together via \b joiner to approximation
+ * If desired, \b inter-fragments, that fragments are combined if they are only
+ * a certain distance apart from another and their summed fragmentation orders
+ * do not exceed the specified value. This is required for local correlation
+ * calculation. Otherwise correlation is only calculated (if supported by the
+ * solver) within covalently connected fragments, i.e. we do not get any van
+ * der Waals interactions.
+ *
+ * These fragments may be exported to file if output file types \sa fileformats
+ * are given. There, the current FormatParserParameters are used. If none are
+ * given, fragments remain in the FragmentationResultContainer.
+ *
+ * \secton fragmentation-automation Calculating fragments
+ *
+ * If then FragmentationFragmentationAutomationAction is used, these are converted
+ * into MPQCJobs (and VMGJobs) that are passed on via a network connection to a
+ * JobMarket's server as a FragmentJob.
+ * Any idling connected clients will then process each one of the jobs until the
+ * whole bundle is completed. The Action checks on the current tatus of the jobs
+ * and requests any finished jobs (FragmentResult).
+ * After all jobs' results have been received, they are stored in
+ * FragmentationShortRangeResults and FragmentationLongrangeResults.
+ * FragmentationAnalyseFragmentResultsAction will process both these results and
+ * sum up the approximate energy and forces (where these are set as the atoms'
+ * forces for the current time step).
+ *
+ * Alternatively to automation, where everything is done inside MoleCuilder, one
+ * may also use the exported files to calculate an approximation. To this end,
+ * the energies and forces are put together via \b joiner to approximation
  * to the total energy and forces of the whole molecular system. Later,
  * \b analyzer additionally gives data on how good this approximation has
 …
+ *
+ *
  * \date 2011-10-31
+ * \date 2014-03-10
+ *
  */

src/documentation/constructs/potentials.dox

-              r74459a
+              rcaece4
  * bond structure into connected subgraphs, calculating the energies of the
  * fragments (ab-initio) and summing up to a good approximation of the total
  * energy of the whole system.
+ * energy of the whole system, \sa fragmentation.
  * Second, having calculated these energies, there quickly comes up the thought
  * that one actually calculates quite similar systems all time and if one could
 …
  * distances within a molecular fragment (i.e. the bond lengths) in order to
  * give a value for the total energy without the need to solve a complex
+ * ab-initio model.
+ * ab-initio model (essentially, not solving the electronic SchrÃ¶dinger equation
+ * anymore).
+ *
  * Empirical potentials have been thought of by fellows such as Lennard-Jones,
 …
  *  h2o += 8,1,1;
  *  // TrainingData needs so called Extractors to get the required distances
  *  // from the stored fragment. These are functions are bound.
+ *  // from the stored fragment. These functions are bound via boost::bind.
  *  TrainingData AngleData(
  *      boost::bind(&Extractors::gatherDistancesFromFragment,

src/documentation/constructs/serialization.dox

-              r74459a
+              rcaece4
 /** \page serialization Serialization
+ *
  *  Serialization is a mighty concept. The is only possible within an object-
+ *  Serialization is a mighty concept. This is only possible within an object-
  *  oriented framework. The member variables of a class make up its internal
  *  state. By storing this state, creating another instance and restoring
 …
  *  we obtain additional control as to the moment of restoration because the
  *  internal state is stored temporarily. To allow for this storage all of
  *  these variables have to be \e serialized.
+ *  these variables have to be \e serializable.
+ *
  *  Serialization refers to putting one after another into a writable form
 …
  *  again make it a friend).
+ *
+ *  \subsection serialization-add-complicated The more complicated case
+ *
+ *  Noted the additional \a version parameter up there in the serialize functions'
+ *  signature? When classes change, we might still want to be able to parse in
+ *  older states. As as state is always written to a default constructed object.
+ *  this is possible. You can check the version variable like this to make your
+ *  function compatible with older functions.
+ *
+ *  \code
+ *    void serialize(Archive & ar, const unsigned int version) const
+ *    {
+ *      ar & content;
+ *      if (version > 0)
+ *        are & newcontent;
+ *    }
+ *    ...
+ *    double newcontent;
+ *  };
+ *  \endcode
+ *
+ *  The version itself is set as follows,
+ *  \code
+ *    BOOST_CLASS_VERSION(foo, 1)
+ *  \endcode
+ *  where you give the name of your class and the version.
+ *
  *  \subsection serialization-important notes Some important notes
+ *
 …
  *  a stupid mistake is introduced that is trivial once understand but hard
  *  to find otherwise. This is especially so because compiler errors with
  *  respect to the serialization part are always length (whole page) and
+ *  respect to the serialization part are always lengthy (whole page) and
  *  very hard to read:
  *  \li Always obtain the same type from an archive that you put into it!
 …
  *    boost::serialization::base_object<base type>(*this);
  *    \endcode
+ *  \li When you have code in header and implementation module, boost might get
+      confused, use \code BOOST_CLASS_EXPORT_KEY(foo) \endcode and
+          \code BOOST_CLASS_EXPORT_IMPLEMENT(foo) \encode for this.
+ *  \li The only other issues encountered so far is that a class needs to get
+ *    instantiated. Otherwise its (templated) serialization code is not present.
+ *    There are ..._EXPORT keywords in boost::serialization for this. Similarly
+ *    required when just the base class is created/instantiated but you also need
+ *    derived classes.
+ *  \li The boost::serialization documentation is in general quite helpful. Use
+ *    above mentioned keywords to look for more information.
+ *
+ *
  * \date 2011-11-01
+ * \date 2014-03-10
  */

src/documentation/constructs/shaperegistry.dox

-              r74459a
+              rcaece4
  * Project: MoleCuilder
  * Description: creates and alters molecular systems
  * Copyright (C)  2010 University of Bonn. All rights reserved.
+ * Copyright (C)  2013 University of Bonn. All rights reserved.
  * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
  */
 …
  * registry.
+ *
  * It is planned to create a more specialized ShapeTesselation class. Basic
  * shapes (sphere, cube, etc.) would have predefined meshes. For combined
+ * \todo It is planned to create a more specialized ShapeTesselation class.
+ * Basic shapes (sphere, cube, etc.) would have predefined meshes. For combined
  * shaped these basic meshes could then be intersected. That would be faster
  * and allow correct rendering of topologically nontrivial shapes.

src/documentation/constructs/shapes.dox

r74459a	rcaece4
33	33	* space, here via a tesselated mesh.
34	34	*
	35	* \section shapes-constructive-geometry Constructive Geometry
	36	*
35	37	* Again, Shapes can be joined via boolean operators:
36	38	* - add
…	…
38	40	* - not
39	41	*
40		* And thus are a very powerful concept.
	42	* And thus are a very powerful concept called constructive geometry.
41	43	*
42	44	* E.g. a shape can be used like this
…	…
48	50	*
49	51	*
50		* \date 201~~3-02-07~~
	52	* \date 2014-03-10
51	53	*
52	54	*/

src/documentation/constructs/tesselation.dox

-              r74459a
+              rcaece4
+ *
  * In the tesselation all atoms act as possible hindrance to a rolling sphere
  * that moves in from infinity. whenever it rests uniquely on three distinct
  * points (atoms) a triangle is created. The algorithm continues by flipping the
+ * that moves in from infinity. Whenever it rests uniquely on three distinct
+ * points (atoms) a triangle is created. The algorithm continues by pushing the
  * sphere over one of the triangle's edges to eventually obtain a closed,
  * tesselated surface of the molecule.
+ * tesselated surface of the whole molecule.
+ *
  * \note This mesh is different to the usual sense of a molecular surface as
  * atoms are directly located on it. Normally, one considers a so-called
  * Van-der-Waals sphere around the atoms and tesselates over these. However,
  * the mesh can easily be modified and even expanded to match the other
  * (although the code for that is not yet fully implemented).
+ * Van-der-Waals sphere around the atoms and tesselates over these.
+ * \todo However, the mesh can easily be modified and even expanded to match the
+ * other (although the code for that is not yet fully implemented).
+ *
  * \section tesselation-extension
 …
  * van-der-Waals spheres.
+ *
+ * \date 2011-10-31
+ * Note that it is possible to select a number of atoms and create a bounding box
+ * from a combination of spheres with van der Waals radii.
+ *
+ * \date 2014-03-10
+ *
  */

src/documentation/constructs/validators.dox

-              r74459a
+              rcaece4
+ *
  * Validators define constraints for variables. A given variable can be
+ * testet whether or not it fulfills the constraints by executing the
+ * validator's isValid() function. Equivalently the operator::() can be used.
+ * tested whether or not it fulfills the constraints by executing the
+ * validator's isValid() function. Equivalently the Validator::operator()
+ * can be used.
+ *
  * Their main purpose is to constrain user input for \ref parameters in \ref actions.
 …
  * \endcode
+ *
  * The type of the variale is static. The base class Validator has a template parameter
  * to define the type. Some derived validators don't have template parameters because
  * they are derived from a Validator<SomeFixedType>.
+ * The type of the variable is static. The base class Validator has a template
+ * parameter to define the type. Some derived validators don't have template
+ * parameters because they are derived from a Validator<SomeFixedType>.
+ *
  * \date 2013-01-28

Note: See TracChangeset for help on using the changeset viewer.

Context Navigation

Changeset caece4 for src/documentation/constructs

Legend:

Download in other formats: