Changeset 1ba8a1 for src/documentation/constructs

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.

File:

• src/documentation/constructs/potentials.dox (modified) (1 diff)

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
  *