Add mdp option documentation for density fitting.

Documents the .mdp options for the density fitting module.

refs #2282

Change-Id: Ic2cb616ca13627553a36d739d86192b0fcb0e239

diff --git a/docs/user-guide/mdp-options.rst b/docs/user-guide/mdp-options.rst
index cf5530e518a6722890e75991cefbe8c251801107..b0175ff4ee9e978f47ecf0eedeaa0b240d34bff3 100644 (file)
--- a/docs/user-guide/mdp-options.rst
+++ b/docs/user-guide/mdp-options.rst
@@ -3197,6 +3197,86 @@ Electrophysiology" simulation setups. (See the `reference manual`_ for details).
 
    (1.0) [nm] Lower extension of the split cylinder #1.
 
+Density-guided simulations
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These options enable and control the calculation and application of additional
+forces that are derived from three-dimensional densities, e.g., from cryo
+electron-microscopy experiments. (See the `reference manual`_ for details)
+
+.. mdp:: density-guided-simulation-active
+
+   (no) Activate density-guided simulations.
+
+.. mdp:: density-guided-simulation-group
+
+   (protein) The atoms that are subject to the forces from the density-guided
+   simulation and contribute to the simulated density.
+
+.. mdp:: density-guided-simulation-similarity-measure
+
+   (inner-product) Similarity measure between the density that is calculated
+   from the atom positions and the reference density.
+
+   .. mdp-value:: inner-product
+
+      Takes the sum of the product of reference density and simulated density
+      voxel values.
+
+   .. mdp-value:: relative-entropy
+
+      Uses the negative relative entropy (or Kullback-Leibler divergence)
+      between reference density and simulated density as similarity measure.
+      Negative density values are ignored.
+
+.. mdp:: density-guided-simulation-atom-spreading-weight
+
+   (unity) Determines the multiplication factor for the Gaussian kernel when
+   spreading atoms on the grid.
+
+   .. mdp-value:: unity
+
+      Every atom in the density fitting group is assigned the same unit factor.
+
+   .. mdp-value:: mass
+
+      Atoms contribute to the simulated density proportional to their mass.
+
+   .. mdp-value:: charge
+
+      Atoms contribute to the simulated density proportional to their charge.
+
+.. mdp:: density-guided-simulation-force-constant
+
+   (1e+09) [kJ mol\ :sup:`-1`] The scaling factor for density-guided simulation
+   forces. May also be negative.
+
+.. mdp:: density-guided-simulation-gaussian-transform-spreading-width
+
+   (0.2) [nm] The Gaussian RMS width for the spread kernel for the simulated
+   density.
+
+.. mdp:: density-guided-simulation-gaussian-transform-spreading-range-in-multiples-of-width
+
+   (4) The range after which the gaussian is cut off in multiples of the Gaussian
+   RMS width described above.
+
+.. mdp:: density-guided-simulation-reference-density-filename
+
+   (reference.mrc) Reference density file name using an absolute path or a path
+   relative to the to the folder from which :ref:`gmx mdrun` is called.
+
+.. mdp:: density-guided-simulation-nst
+
+   (1) Interval in steps at which the density fitting forces are evaluated
+   and applied. The forces are scaled by this number when applied (See the
+   `reference manual`_ for details).
+
+.. mdp:: density-guided-simulation-normalize-densities
+
+   (true) Normalize the sum of density voxel values to one for the reference
+   density as well as the simulated density.
+
 
 User defined thingies
 ^^^^^^^^^^^^^^^^^^^^^

diff --git a/src/gromacs/applied_forces/densityfittingamplitudelookup.h b/src/gromacs/applied_forces/densityfittingamplitudelookup.h
index a4e31e04bc401a8c7b2d183f6e19e9c1eedd91c7..3ce659a52bb98bfcef6b517ef19bb8c27d6e9827 100644 (file)
--- a/src/gromacs/applied_forces/densityfittingamplitudelookup.h
+++ b/src/gromacs/applied_forces/densityfittingamplitudelookup.h
@@ -67,7 +67,7 @@ enum class DensityFittingAmplitudeMethod
 
 //! The names of the methods to determine the amplitude of the atoms to be spread on a grid
 const EnumerationArray<DensityFittingAmplitudeMethod, const char * const>
-c_densityFittingAmplitudeMethodNames = {{"unity", "mass", "charges"}};
+c_densityFittingAmplitudeMethodNames = {{"unity", "mass", "charge"}};
 
 class DensityFittingAmplitudeLookupImpl;
 

diff --git a/src/gromacs/applied_forces/densityfittingoptions.h b/src/gromacs/applied_forces/densityfittingoptions.h
index 0d8d4c42a8007b71021eb570030dc4b42e8b3608..d629a7905fac28c463d5e21e84398e04885ee1da 100644 (file)
--- a/src/gromacs/applied_forces/densityfittingoptions.h
+++ b/src/gromacs/applied_forces/densityfittingoptions.h
@@ -112,7 +112,7 @@ class DensityFittingOptions final : public IMdpOptionProvider
 
         const std::string c_similarityMeasureTag_ = "similarity-measure";
 
-        const std::string c_amplitudeMethodTag_ = "amplitude-method";
+        const std::string c_amplitudeMethodTag_ = "atom-spreading-weight";
 
         const std::string c_forceConstantTag_ = "force-constant";
 

diff --git a/src/gromacs/applied_forces/tests/densityfittingoptions.cpp b/src/gromacs/applied_forces/tests/densityfittingoptions.cpp
index 79764008cb344953ed681b41c1e307e8b98545d2..dcfb80cd26740943a4e3043f8da429112a22c204 100644 (file)
--- a/src/gromacs/applied_forces/tests/densityfittingoptions.cpp
+++ b/src/gromacs/applied_forces/tests/densityfittingoptions.cpp
@@ -198,7 +198,7 @@ TEST_F(DensityFittingOptionsTest, OutputDefaultValuesWhenActive)
         "; Similarity measure between densities: inner-product, or relative-entropy\n"
         "density-guided-simulation-similarity-measure = inner-product\n"
         "; Atom amplitude for spreading onto grid: unity, mass, or charges\n"
-        "density-guided-simulation-amplitude-method = unity\n"
+        "density-guided-simulation-atom-spreading-weight = unity\n"
         "density-guided-simulation-force-constant = 1e+09\n"
         "density-guided-simulation-gaussian-transform-spreading-width = 0.2\n"
         "density-guided-simulation-gaussian-transform-spreading-range-in-multiples-of-width = 4\n"

diff --git a/src/programs/mdrun/tests/densityfittingmodule.cpp b/src/programs/mdrun/tests/densityfittingmodule.cpp
index a30535cb49692b7baafc6b68390badb250e20367..39797876eaba44f1fb44c5576c472316c538dc92 100644 (file)
--- a/src/programs/mdrun/tests/densityfittingmodule.cpp
+++ b/src/programs/mdrun/tests/densityfittingmodule.cpp
@@ -104,7 +104,7 @@ class DensityFittingTest : public MdrunTestFixture
         //! Mdp values for steepest-decent energy minimization with density fitting values set to non-defaults.
         const std::string mdpDensiftAllDefaultsChanged_ = formatString(
                     "density-guided-simulation-similarity-measure = relative-entropy\n"
-                    "density-guided-simulation-amplitude-method = mass\n"
+                    "density-guided-simulation-atom-spreading-weight = mass\n"
                     "density-guided-simulation-force-constant = -1\n"
                     "density-guided-simulation-gaussian-transform-spreading-width = 0.8\n"
                     "density-guided-simulation-gaussian-transform-spreading-range-in-multiples-of-width = 6\n"