Changeset 1ba8a1

Timestamp:

Jun 27, 2014, 9:32:29 PM (11 years ago)

Author:

Frederik Heber <heber@…>

Branches:

Action_Thermostats, Add_AtomRandomPerturbation, Add_FitFragmentPartialChargesAction, Add_RotateAroundBondAction, Add_SelectAtomByNameAction, Added_ParseSaveFragmentResults, AddingActions_SaveParseParticleParameters, Adding_Graph_to_ChangeBondActions, Adding_MD_integration_tests, Adding_ParticleName_to_Atom, Adding_StructOpt_integration_tests, AtomFragments, Automaking_mpqc_open, AutomationFragmentation_failures, Candidate_v1.5.4, Candidate_v1.6.0, Candidate_v1.6.1, ChangeBugEmailaddress, ChangingTestPorts, ChemicalSpaceEvaluator, CombiningParticlePotentialParsing, Combining_Subpackages, Debian_Package_split, Debian_package_split_molecuildergui_only, Disabling_MemDebug, Docu_Python_wait, EmpiricalPotential_contain_HomologyGraph, EmpiricalPotential_contain_HomologyGraph_documentation, Enable_parallel_make_install, Enhance_userguide, Enhanced_StructuralOptimization, Enhanced_StructuralOptimization_continued, Example_ManyWaysToTranslateAtom, Exclude_Hydrogens_annealWithBondGraph, FitPartialCharges_GlobalError, Fix_BoundInBox_CenterInBox_MoleculeActions, Fix_ChargeSampling_PBC, Fix_ChronosMutex, Fix_FitPartialCharges, Fix_FitPotential_needs_atomicnumbers, Fix_ForceAnnealing, Fix_IndependentFragmentGrids, Fix_ParseParticles, Fix_ParseParticles_split_forward_backward_Actions, Fix_PopActions, Fix_QtFragmentList_sorted_selection, Fix_Restrictedkeyset_FragmentMolecule, Fix_StatusMsg, Fix_StepWorldTime_single_argument, Fix_Verbose_Codepatterns, Fix_fitting_potentials, Fixes, ForceAnnealing_goodresults, ForceAnnealing_oldresults, ForceAnnealing_tocheck, ForceAnnealing_with_BondGraph, ForceAnnealing_with_BondGraph_continued, ForceAnnealing_with_BondGraph_continued_betteresults, ForceAnnealing_with_BondGraph_contraction-expansion, FragmentAction_writes_AtomFragments, FragmentMolecule_checks_bonddegrees, GeometryObjects, Gui_Fixes, Gui_displays_atomic_force_velocity, ImplicitCharges, IndependentFragmentGrids, IndependentFragmentGrids_IndividualZeroInstances, IndependentFragmentGrids_IntegrationTest, IndependentFragmentGrids_Sole_NN_Calculation, JobMarket_RobustOnKillsSegFaults, JobMarket_StableWorkerPool, JobMarket_unresolvable_hostname_fix, MoreRobust_FragmentAutomation, ODR_violation_mpqc_open, PartialCharges_OrthogonalSummation, PdbParser_setsAtomName, PythonUI_with_named_parameters, QtGui_reactivate_TimeChanged_changes, Recreated_GuiChecks, Rewrite_FitPartialCharges, RotateToPrincipalAxisSystem_UndoRedo, SaturateAtoms_findBestMatching, SaturateAtoms_singleDegree, StoppableMakroAction, Subpackage_CodePatterns, Subpackage_JobMarket, Subpackage_LinearAlgebra, Subpackage_levmar, Subpackage_mpqc_open, Subpackage_vmg, Switchable_LogView, ThirdParty_MPQC_rebuilt_buildsystem, TrajectoryDependenant_MaxOrder, TremoloParser_IncreasedPrecision, TremoloParser_MultipleTimesteps, TremoloParser_setsAtomName, Ubuntu_1604_changes, stable

Children:

4e009d

Parents:

1b1fa5

git-author:

Frederik Heber <heber@…> (02/27/14 19:07:56)

git-committer:

Frederik Heber <heber@…> (06/27/14 21:32:29)

Message:

DOCU: Extended documentation on FunctionApproximation and potential fitting.

Location:

src

Files:

• FunctionApproximation/Extractors.hpp (modified) (1 diff)
• FunctionApproximation/FunctionApproximation.hpp (modified) (1 diff)
• Potentials/CompoundPotential.hpp (modified) (2 diffs)
• documentation/constructs/potentials.dox (modified) (1 diff)

src/FunctionApproximation/Extractors.hpp

@@ -22 +22 @@
 
 /** Namespace containing all simple extractor functions.
+ *
+ * Extractor functions extract distances from a given fragment matching with
+ * a given set of particle types (i.e. elements, e.h. H2O).
+ * Filter functions extract a subset of distances from a given set of distances
+ * to be used with a specific model.
+ *
+ * To this end, each FunctionModel has both a filter and an extractor function.
+ *
+ * The functions in this namespace act as helpers or basic building blocks in
+ * constructing such filters and extractors.
  *
  */

src/FunctionApproximation/FunctionApproximation.hpp

@@ -40 +40 @@
  * <a href="http://www.ics.forth.gr/~lourakis/levmar/index.html">LevMar</a>
  * package.
+ *
+ * \section FunctionApproximation-details Details on the inner workings.
+ *
+ *  FunctionApproximation::operator() is the main function that performs the
+ *  non-linear regression. It consists of the following steps:
+ *  -# hand given (initial) parameters over to model.
+ *  -# convert output vector to format suitable to levmar
+ *  -# allocate memory for levmar to work in
+ *  -# depending on whether the model is constrained or not and whether we
+ *   have a derivative, we make use of various levmar functions with prepared
+ *   parameters.
+ *  -# memory is free'd and some final infos is given.
+ *
+ *  levmar needs to evaluate the model. To this end, FunctionApproximation has
+ *  two functions whose signatures is such as to match with the one required
+ *  by the levmar package. Hence,
+ *  -# FunctionApproximation::LevMarCallback()
+ *  -# FunctionApproximation::LevMarDerivativeCallback()
+ *  are used as callbacks by levmar only.
+ *  These hand over the current set of parameters to the model, then both bind
+ *  FunctionApproximation::evaluate() and
+ *  FunctionApproximation::evaluateDerivative(), respectively, and execute
+ *  FunctionModel::operator() or FunctionModel::parameter_derivative(),
+ *  respectively.
  *
  */

src/Potentials/CompoundPotential.hpp

@@ -23 +23 @@
 class TrainingData;
 
-/** CompoundPotential combines several FunctionModel's as one to allow for
- * simultaneous FunctionApproximation to a single fragment/graph.
+/** CompoundPotential combines several EmipiricalPotential's into one
+ * FunctionModel to allow for simultaneous FunctionApproximation to a single
+ * fragment/graph.
  *
  * The CompoundPotential obtains a Graph as parameter to cstor and looks through
@@ -30 +31 @@
  * matches. All of these are placed into an internal vector and used for
  * fitting.
+ *
+ * The main work is then in operator() and parameter_derivative(), where the
+ * contained set of models has to be evaluated one after the other:
+ *
  */
 class CompoundPotential :

src/documentation/constructs/potentials.dox

@@ -72 +72 @@
  *    perform the fit.
  *
+ * \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).
+ *
+ *  Second, the given fragment is used to get a suitable HomologyGraph from
+ *  the World's HomologyContainer. This is given to a CompoundPotential, that in
+ *  turn browses through the PotentialRegistry, picking out those
+ *  EmpiricalPotential's that match with a subset of the FragmentNode's of the
+ *  given graph. These are stored as a list of FunctionModel's within the
+ *  CompoundPotential instance. Here comes the specific fragment into play,
+ *  picking a subset from the available potentials.
+ *
+ *  Third, we need to setup the training data. For this we need vectors of input
+ *  and output data that are obtained from the HomologyContainer with the
+ *  HomologyGraph as key. The output vector in our case is simply a number
+ *  (although the interface allows for more). The input vector is the set of
+ *  distances. In order to pre-process the input data for the specific model
+ *  a filter is required in the TrainingData's constructor. The purpose of the
+ *  filter is to pick out the subset of distance arguments for each model one
+ *  after the other and concatenate them to a list. On evaluation of the model
+ *  this concatenated list of distances is given to the model and it may easily
+ *  dissect the list and hand over each contained potential its subset of
+ *  arguments. See Extractors for more information.
+ *
+ *  Afterwards, training may commence: The goal is to find a set of parameters
+ *  for the model such that it as good as possible reproduces the output vector
+ *  for a given input vector. This non-linear regression is contained in the
+ *  levmar package and its functionality is wrapped in the FunctionApproximation
+ *  class. An instance is initialized with both the gathered training data and
+ *  the model containing a list of potentials. See
+ *  [FunctionApproximation-details] for more details.
+ *
+ *  During the fitting procedure, first the derivatives of the model is checked
+ *  for consistency, then the model is initialized with a sensible guess of
+ *  starting parameters, and afterwards the Levenberg-Marquardt algorithm
+ *  commences that makes numerous calls to evaluate the model and its derivative
+ *  to find the minimum in the L2-norm.
+ *
+ *  This is done more than once as high-dimensional regression is sensititive the
+ *  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
+ *  given number of attempts.
+ *
+ *  Eventually, these parameters of the best model are streamed via
+ *  PotentialSerializer back into a potential file. Each EmpiricalPotential in
+ *  the CompoundPotential making up the whole model is also a
+ *  SerializablePotential. Hence, each in turn writes a single line with its
+ *  respective subset of parameters and particle types, describing this
+ *  particular fit function.
+ *
+ * \section potentials-function-evaluation How does the model evaluation work
+ *
+ *  We now come to the question of how the model and its derivative are actually
+ *  evaluated. We have an input vector from the training data and we have the
+ *  model with a specific set of parameters.
+ *
+ *  FunctionModel is just an abstract interface that is implemented by the
+ *  potential functions, such as CompoundPotential, that combines multiple
+ *  potentials into a single function for fitting, or PairPotential_Harmonic,
+ *  that is a specific fit function for harmonic bonds.
+ *
+ *  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.
+ *
+ *  Initially, the HomologyGraph only contains a list of configurations of a
+ *  specific fragments (i.e. the position of each atom in the fragment) and an
+ *  energy value. These first have to be converted into distances.
+ *
+ *
  * \section potentials-howto-use Howto use the potentials
  *