Changeset 48d20d for src/documentation

Timestamp:

May 3, 2013, 11:58:26 AM (12 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:

661d2d

Parents:

57f14c

git-author:

Frederik Heber <heber@…> (04/09/13 07:44:29)

git-committer:

Frederik Heber <heber@…> (05/03/13 11:58:26)

Message:

Added new action FitPotentialAction to fit empirical potentials.

• moved functionality from levmartester into new Action.
• removed levmartester.
• needs both enable-levmar and path to libs/include with-levmar. This allows checking as distinct enable switch.
• added regression test Fragmentation/FitPotential for morse and harmonic_angle fit to water molecule. Using awk to check on L2 error.
• added take-best-of option such that fits is done as many times and best (in terms of l2 error) is used. This should make regression test FitPotential more stable (right now we take best of 5).
• DOCU: extended construct documentation due to new PotentialTypes construct.
• DOCU: made construct lists items appear alphabetically.
• DOCU: extended installation documentation with VTK and levmar.
• DOCU: also URLs for scafacos, VTK, and levmar.

Location:

src/documentation

Files:

• constructs/constructs.dox (modified) (2 diffs)
• constructs/potentials.dox (modified) (3 diffs)
• install.dox (modified) (5 diffs)

src/documentation/constructs/constructs.dox

@@ -31 +31 @@
  *  \li \ref observers
  *  \li \ref parameters
- *  \li \ref parsers
- *  \li \ref potentials
+ *  \li \ref parsers "Parsers"
+ *  \li \ref potentials "Potentials"
  *  \li \ref qt-gui
  *  \li \ref queries
@@ -47 +47 @@
  *
  *
- * \date 2013-02-07
+ * \date 2013-04-09
  *
  */

src/documentation/constructs/potentials.dox

@@ -71 +71 @@
  *    perform the fit.
  *
- * \section potentials-howto Howto use the potentials
+ * \section potentials-howto-use Howto use the potentials
  *
  *  We just give a brief run-down in terms of code on how to use the potentials.
- *  Here, we just describe what to do in order to perform the fitting.
+ *  Here, we just describe what to do in order to perform the fitting. This is
+ *  basically what is implemented in FragmentationFitPotentialAction.
  *
  *  \code
@@ -102 +103 @@
  *  // give initial parameter
  *  FunctionModel::parameters_t params(PairPotential_Angle::MAXPARAMS, 0.);
- *  ... set some initial parameters
+ *  // ... set some potential-specific initial parameters in params struct
  *  angle.setParameters(params);
  *
@@ -123 +124 @@
  *  // evaluate
  *  FunctionModel::arguments_t args;
- *  .. initialise args to the desired distances
+ *  // .. initialise args to the desired distances
  *  const double value = angle(args)[0]; // output is a vector!
  *  \endcode
  *
- * \date 2012-11-28
+ * \section potentials-stability-of-fit note in stability of fit
+ *
+ *  As we always start from random initial parameters (within a certain sensible
+ *  range at least), the non-linear fit does not always converge. For this 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.
+ *
+ * \section potentials-howto-add Howto add new potentials
+ *
+ *  Adding a new potential requires the following:
+ *  -# Add the new modules to Potentials/Specifics
+ *  -# Add a unit test on the potential in Potentials/Specifics/unittests
+ *  -# Give the potential a type name and add it to PotentialTypes.def. Note
+ *     that the name must not contain white space.
+ *  -# Add the potential name as case to PotentialFactory such that it knows
+ *     how to instantiate your new potential when requested.
+ *
+ * PotentialTypes.def contains a boost::preprocessor sequence of all
+ * potential names. PotentialFactory uses this sequence to build its enum to
+ * type map and inverse which the user sees when specifying the potential to
+ * fit via PotentialTypeValidator.
+ *
+ *
+ * \date 2013-04-09
  */

src/documentation/install.dox

@@ -55 +55 @@
  *    -# MPQC: see below for instructions
  *    -# ScaFaCoS: see below for instructions
+ *    -# VTK: see below for instructions
+ *    -# levmar: see below for instructions
  *
  *  If you are programming with or for MoleCuilder, the following packages are
@@ -109 +111 @@
  *  \subsubsection install-prerequisites-other-scafacos ScaFaCoS
  *
- *  ScaFaCoS is a library of fast Coulomb solvers, created by the same-named BMBF
- *  funded project. The library contains Versatile MultiGrid (vmg) as one of its
- *  solvers which is used in the BOSSANOVA scheme for the calculation of
- *  long-range forces.
+ *  ScaFaCoS (http://www.scafacos.org/) is a library of fast Coulomb solvers,
+ *  created by the same-named BMBF funded project. The library contains Versatile
+ *  MultiGrid (vmg) as one of its solvers which is used in the BOSSANOVA scheme
+ *  for the calculation of long-range forces.
  *
  *  ScaFaCoS requires the following packages to compile:
@@ -118 +120 @@
  *  -# F2C: libf2c2-dev
  *  -# Fortran compiler: gfortan
+ *  -# VTK >=5.10
+ *
+ *  Firstly, you should obtain a recent copy of the visualization tool kit (VTK)
+ *  (http://www.vtk.org/) and compile as
+ *  \code
+ *  export MPI_HOME=$( which mpirun | sed 's#/bin/mpirun##g')
+ *  export CXX_FLAGS=-fPIC
+ *  cmake -DCMAKE_INSTALL_PREFIX:PATH=<install-path> \
+ *        -DBUILD_SHARED_LIBS=TRUE \
+ *        -DCMAKE_BUILD_WITH_INSTALL_RPATH:BOOL=OFF \
+ *        -DCMAKE_INSTALL_RPATH:PATH=<install-path>/lib/vtk-<install-version> \
+ *        -DCMAKE_INSTALL_RPATH_USE_LINK_PATH:BOOL=ON \
+ *        -DCMAKE_SKIP_BUILD_RPATH:BOOL=OFF \
+ *        -DVTK_USE_PARALLEL:BOOL=ON \
+ *        -DVTK_USE_MPI:BOOL=ON \
+ *        -DMPI_LIBRARY:PATH=${MPI_HOME}/lib/libmpi.so \
+ *        -DMPI_EXTRA_LIBRARY:PATH=${MPI_HOME}/lib/libmpi_cxx.so \
+ *        -DMPI_INCLUDE_PATH:PATH=${MPI_HOME}/include/mpi \
+ *        ..
+ *  make -j4
+ *  make install
+ *  \endcode
+ *  where we force rpath-linking and shared libraries (MPI is actually not
+ *  required here).
+ *
  *  Compilation additionally required use of
  *  \code CPPFLAGS="-fPIC" \endcode
@@ -125 +152 @@
  *  for a debug compile you might want to use:
  *  \code
- *  ../configure -C --prefix=<path> --enable-shared BSPLINE_DEG=3 MPICC=mpicc.openmpi
- *  MPICXX=mpicxx.openmpi MPIEXEC=mpirun.openmpi CPPFLAGS="-Wall -g3 -O0 -ggdb -fPIC"
- *  --enable-mpi --with-boost-libdir=/usr/lib --with-boost=/usr --enable-fcs-solvers=vmg
+ *  ../configure \
+ *    -C \
+ *    --prefix=<path> \
+ *    --enable-shared \
+ *    BSPLINE_DEG=3 \
+ *    MPICC=mpicc.openmpi \
+ *    MPICXX=mpicxx.openmpi \
+ *    MPIEXEC=mpirun.openmpi \
+ *    CPPFLAGS="-Wall -g3 -O0 -ggdb -fPIC" \
+ *    --enable-mpi \
+ *    --with-boost-libdir=/usr/lib --with-boost=/usr \
+ *    --with-vtk=<path-to-vtk> --with-vtk-version=<vtk-version path string, i.e. -5.10> \
+ *    --enable-fcs-solvers=vmg
  *  \endcode
+ *  where we specify a recent boost and the installed VTK version from above.
+ *
+ *  \subsubsection install-prerequisites-other-levmar LevMar
+ *
+ *   We also require the levmar (http://www.ics.forth.gr/~lourakis/levmar/) which
+ *   implements a Levenberg-Marquardt for non-linear regression which is employed
+ *   for fitting empirical potentials to energies obtained from calculated
+ *   fragment energies.
+ *
+ *   Compile and install as follows
+ *   \code
+ *    cmake \
+ *      -DCMAKE_INSTALL_PREFIX:PATH=<install-path> \
+ *      -DCMAKE_C_FLAGS="-fPIC" \
+ *      ..
+ *    make
+ *    cp -f liblevmar.a <install-path>/lib
+ *    cp -f levmar.h <install-path>/include
+ *   \endcode
+ *   where we have to copy the stuff by hand as no \a install target exists.
  *
  *  \subsubsection install-prerequisites-other-mpqc MPQC
@@ -276 +333 @@
  *  from a distributed archive. This is checked for each release version.
  *
- * \date 2012-12-20
+ * \date 2013-04-09
  */