Context Navigation

-              rb52710e
+              r3cfb31
  * fragments (ab-initio) and summing up to a good approximation of the total
  * energy of the whole system, \sa fragmentation.
  * Second, having calculated these energies, there quickly comes up the thought
+ * Second, having calculated these energies, there quickly comes up the idea
  * that one actually calculates quite similar systems all time and if one could
  * not cache results in an intelligent (i.e. interpolating) fashion ...
 …
  * give a value for the total energy without the need to solve a complex
  * ab-initio model (essentially, not solving the electronic SchrÃ¶dinger equation
+ * anymore).
+ * anymore). And they are accompanied by a specific binding model that
+ * represents what kind of many-body force is represented by the potential.
+ *
  * Empirical potentials have been thought of by fellows such as Lennard-Jones,
  * Morse, Tersoff, Stillinger and Weber, etc. And in their honor, the
  * potential form is named after its inventor. Hence, we speak e.g. of a
+ * Morse, Tersoff, Stillinger and Weber, etc. And in their honor, most of the
+ * potential forms are named after its inventor. Hence, we speak e.g. of a
  * Lennard-Jones potential.
+ *
 …
  * -# evaluate the potential instead of an ab-initio calculation
+ *
+ * The terms we use, model the classes that are implemented:
+ * However, we need more: What are similar fragments? How do we perform the
+ * fitting procedure? And as the potentials are mathematical functions, what
+ * arguments do they depend on?
+ *
+ * Similar fragments are those that share the same bond graph, i.e. they have
+ * the same number of nodes and the same number of edges. And each edge is
+ * between the same two elements.
+ *
+ * The fitting procedure works by looking at a training set, i.e. a list of
+ * elements where each contains an energy and a number of arguments, namely
+ * pair-wise distances. The error is then the difference between the energies
+ * in the set and all the energy values that we obtain when we feed the
+ * arguments into the fitted potentials. This error is minimized in the
+ * euclidian norm, i.e. least squares regression. But other norms might be
+ * possible in the future, too.
+ *
+ * And the pair-wise distances, we mentioned are the arguments.
+ *
+ * The terms, that we use, model the classes that are implemented:
  * -# EmpiricalPotential: Contains the interface to a function that can be
  *    evaluated given a number of arguments_t, i.e. distances. Also, one might
  *    want to evaluate derivatives.
  * -# FunctionModel: Is a function that can be fitted, i.e. that has internal
  *    parameters to be set and got.
+ * -# FunctionModel: Is a function that can be fitted, i.e. it depends on a
+ *    set of internal parameters that can be set and got.
  * -# argument_t: The Argument stores not only the distance but also the index
  *    pair of the associated atoms and also their charges, to let the potential
 …
  *    class.
  * -# HomologyGraph: "Similar" fragments in our case have to have the same bond
  *    graph. It is stored in the HomologyGraph that acts as representative
  * -# HomologyContainer: This container combines, in multimap fashion, all
+ *    graph. It is stored in the HomologyGraph that acts as representative.
+ * -# HomologyContainer: This container combines, in a ultimap fashion, all
  *    similar fragments with their energies together, with the HomologyGraph
  *    as their "key".
 …
  *    the set of distances required for the FunctionModel (e.g. only a single
  *    distance/argument for a pair potential, three for an angle potential,
  *    etc.) and also the expected OutputVector. This in combination with the
  *    FunctionModel is the basis for the non-linear regression used for the
  *    fitting procedure.
+ *    etc.) and also the expected OutputVector, i.e. the energy of the specific
+ *    configuration in our case. This in combination with the FunctionModel is
+ *    the basis for the non-linear regression used for the fitting procedure.
  * -# Extractors: These set of functions yield the set of distances from a
  *    given fragment that is stored in the HomologyContainer.
 …
  * \section potentials-fit-potential-action What happens in FitPotentialAction.
+ *
  *  First, either a potential file is parsed via PotentialDeserializer or charges
  *  and a potential type from the given options. This is used to instantiate
  *  EmpiricalPotentials via the PotentialFactory, stored within the
  *  PotentialRegistry. This is the available set of potentials (without requiring
  *  any knowledge as to the nature of the fragment employed in fitting).
+ *  First, charges and a potential type is used from the given options. This
+ *  is used to instantiate EmpiricalPotentials via the PotentialFactory, stored
+ *  within the PotentialRegistry. This is the available set of potentials
+ *  (without requiring any knowledge as to the nature of the fragment employed
+ *  in fitting).
+ *
  *  Second, the given fragment is used to get a suitable HomologyGraph from
 …
  *  to find the minimum in the L2-norm.
+ *
  *  This is done more than once as high-dimensional regression is sensititive the
+ *  This is done more than once as high-dimensional regression is sensitive to
  *  the starting values as there are possible numerous local minima. The lowest
  *  of the found minima is taken, either via a given threshold or the best of a
 …
  *  The main issue with the evaluation is picking the right set of distances from
  *  ones given in the input vector and feed it to each potential contained in
+ *  CompoundPotential. Note that the distances have already been prepared by
+ *  the TrainingData instantiation.
+ *  CompoundPotential.
+ *
  *  Initially, the HomologyGraph only contains a list of configurations of a
 …
  *  energy value. These first have to be converted into distances.
+ *
+ *
+ *  These distances are prepared by the TrainingData instantiation, i.e. a
+ *  fragment with all its atomic positions has already been converted to the
+ *  set of all pair-wise interatomic distances.
+ *
+ * \section potentials-distance-picking How does the distance picking work
+ *
+ *  Given a set of pair-wise distances, how do we pick the subset of distances
+ *  needed by a particular potential.
+ *
+ *  Let's make an example first: Imagine a water molecule, i.e. one oxygen and
+ *  and two hydrogen atoms with two O-H bonds. Naturally, we obtain three pair-
+ *  wise distances, OH1, OH2 and H1H2. Now, we would like to fit a Morse
+ *  potential that just depends on a single interatomic distance. We would like
+ *  it to represents the O-H bond energy. Hence, the distance picker, namely
+ *  the Extractor function, needs to pick any subset of distance that contains
+ *  a unique single O-H distance. In effect, it needs to return a list
+ *  containing OH1 and OH2 as the Morse potential needs to represent both bond
+ *  energies together.
+ *
+ *  Now, this is really still quite simple as long as the potential only
+ *  depends on a single distance. However, what if we continue and look at a
+ *  angle potential, requiring three atoms, i.e. H-O-H?
+ *
+ *  Or even more complicated: Imagine an ethane molecule (C2H6) and we would
+ *  to represent the H-C-C angular interaction by a harmonic angle potential.
+ *  Now, there are multiple of these at the same time, namely six angular
+ *  interactions.
+ *
+ *  What have to do is look for subgraphs inside a graph. Each potential comes
+ *  with a small graph that represents the binding structure, in our terms
+ *  the bond model, that we expect. And we need to find the all matching
+ *  subgraphs in the whole graph being the fragment itself. Then, for each
+ *  subgraph the potential tells us in what order the pair-wise distances
+ *  associated with the subgraph are required to be. All of these subset of
+ *  distances are eventually concatenated and fed into the model on evaluation.
+ *
  * \section potentials-howto-use Howto use the potentials
+ *
 …
  *  As we always start from random initial parameters (within a certain sensible
  *  range at least), the non-linear fit does not always converge. Note that the
  *  random values are drawn from the defined distribution and the uniform distributionm
+ *  random values are drawn from the defined distribution and the uniform distribution
  *  engine is obtained from the currently set, see \ref randomnumbers. Hence, you
  *  can manipulate both in order to get different results or to set the seed such that
  *  some "randomly" drawn value always work well (e.g. for testing).
+ *
  *  In any case, For this case the FragmentationFitPotentialAction has the option
+ *  In any case, the FragmentationFitPotentialAction has the option
  *  "take-best-of" to allow for multiple fits where the best (in terms of l2 error)
  *  is taken eventually. Furthermore, you can use the "set-threshold" option to
  *  stop restarting the fit procedure first when the L2 error has dropped below the
  *  given threshold.
+ *  repeat the fit procedure until the L2 error has dropped below the given
+ *  threshold.
+ *
  * \section potentials-howto-add Howto add new potentials
 …
+ *
+ *
  * \date 2013-04-09
+ * \date 2017-05-14
  */

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

Context Navigation

Changeset 3cfb31 for src/documentation/constructs

Legend:

src/documentation/constructs/potentials.dox

Download in other formats: