Manual entry and .mdp option for adaptive force scaling

Adds a manual entry and extends the mdp option section to describe the
adpative force scaling parameters.

refs #2282

Change-Id: Ifb2e4af256282340f1111262f91e5d73d93c3208

diff --git a/docs/reference-manual/special/density-guided-simulation.rst b/docs/reference-manual/special/density-guided-simulation.rst
index 301da01260e2019e8047907ec270425814356cd9..8be48bbd82aee3953d463aceca5199fc799f9db5 100644 (file)
--- a/docs/reference-manual/special/density-guided-simulation.rst
+++ b/docs/reference-manual/special/density-guided-simulation.rst
@@ -187,6 +187,23 @@ This is the energy that is added to the system from the density-guided simulatio
 The lower the energy, the higher the similarity between simulated and reference
 density.
 
+Adaptive force constant scaling
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To enable a steady increase in similarity between reference and simulated
+density while using as little force as possible, adaptive force scaling
+decreases the force constant when similarity increases and vice versa. To avoid
+large fluctuations in the force constant, change in similarity is measured
+with an exponential moving average that smoothens the time series of similarity
+measures with a time constant :math:`tau` that is given in ps. If the exponential
+moving average similarity increases, the force constant is scaled down by
+dividing by :math:`1+\delta t_{\mathrm{density}}/tau`, where
+:math:`\delta t_{\mathrm{density}}` is the time between density guided simulation steps.
+Reversely, if similarity between reference and simulated density is decreasing,
+the force constant is increased by multiplying by :math:`1+\delta t_{\mathrm{density}}/tau`.
+Note that adaptive force scaling does not conserve energy and will ultimately lead to very high
+forces when similarity cannot be increased further.
+
 Future developments
 ^^^^^^^^^^^^^^^^^^^
 

diff --git a/docs/user-guide/mdp-options.rst b/docs/user-guide/mdp-options.rst
index b0175ff4ee9e978f47ecf0eedeaa0b240d34bff3..38f47562d5e4ee5251c46927e83595e56168a280 100644 (file)
--- a/docs/user-guide/mdp-options.rst
+++ b/docs/user-guide/mdp-options.rst
@@ -3277,6 +3277,23 @@ electron-microscopy experiments. (See the `reference manual`_ for details)
    (true) Normalize the sum of density voxel values to one for the reference
    density as well as the simulated density.
 
+.. mdp:: density-guided-simulation-adaptive-force-scaling
+
+   (false) Adapt the force constant to ensure a steady increase in similarity
+   between simulated and reference density.
+
+   .. mdp-value: false
+
+      Do not use adaptive force scaling.
+
+   .. mdp-value:: true
+
+      Use adaptive force scaling.
+
+.. mdp:: density-guided-simulation-adaptive-force-scaling-time-constant
+
+   (4) [ps] Couple force constant to increase in similarity with reference density
+   with this time constant. Larger times result in looser coupling.
 
 User defined thingies
 ^^^^^^^^^^^^^^^^^^^^^