Improve AWH bias sharing documentation
[alexxy/gromacs.git] / docs / reference-manual / special / awh.rst
index faa9f4197900011b55c3b95d91407b26efdaea0c..1cc7e935db70320968d99595a54130b82e8fdc79 100644 (file)
@@ -3,7 +3,7 @@
 Adaptive biasing with AWH
 -------------------------
 
-The accelerated weight histogram method
+The accelerated weight histogram method :ref:`185 <refLidmar2012>`
 :ref:`137 <reflindahl2014accelerated>` calculates the PMF along a reaction coordinate by adding
 an adaptively determined biasing potential. AWH flattens free energy
 barriers along the reaction coordinate by applying a history-dependent
@@ -64,7 +64,7 @@ determined accurately. Thus, AWH adaptively calculates
 toward :math:`\rho(\lambda)`.
 
 It is also possible to directly control the :math:`\lambda` state
-of, e.g., alchemical free energy perturbations. In that case there is no harmonic
+of, e.g., alchemical free energy perturbations :ref:`187 <reflundborg2021>`. In that case there is no harmonic
 potential and :math:`\lambda` changes in discrete steps along the reaction coordinate
 depending on the biased free energy difference between the :math:`\lambda` states.
 N.b., it is not yet possible to use AWH in combination with perturbed masses or
@@ -498,6 +498,17 @@ equal to the length of the sampling interval, the sampling interval is
 considered covered when at least one walker has independently traversed
 the sampling interval.
 
+In practice biases are shared by setting :mdp:`awh-share-multisim` to true
+and :mdp:`awh1-share-group` (for bias 1) to a non-zero value. Here, bias 1
+will be shared between simulations that have the same share group value.
+Sharing can be different for bias 1, 2, etc. (although there are
+few use cases where this is useful). Technically there are no restrictions
+on sharing, apart from that biases that are shared need to have the same
+number of grid points and the update intervals should match.
+Note that biases can not be shared within a simulation.
+The latter could be useful, especially for multimeric proteins, but this
+is more difficult to implement.
+
 .. _awhreweight:
 
 Reweighting and combining biased data
@@ -566,7 +577,7 @@ centered at :math:`\lambda` and
 is the deviation of the force. The factors :math:`\omega(\lambda|x(t))`,
 see :eq:`Eq %s <eqawhomega>`, reweight the samples.
 :math:`\eta_{\mu\nu}(\lambda)` is a friction
-tensor \ :ref:`144 <refsivak2012thermodynamic>`. Its matrix elements are inversely proportional to local
+tensor :ref:`186 <reflindahl2018>` and :ref:`144 <refsivak2012thermodynamic>`. Its matrix elements are inversely proportional to local
 diffusion coefficients. A measure of sampling (in)efficiency at each
 :math:`\lambda` is given by
 
@@ -602,10 +613,16 @@ free energy scales as :math:`\varepsilon^2 \sim 1/(ND)`
 estimate used by AWH to initialize :math:`N` in terms of more meaningful
 quantities
 
-.. math:: \frac{1}{N_0} = \frac{1}{N_0(\varepsilon_0, D)} \sim D\varepsilon_0^2.
+.. math:: \frac{1}{N_0} = \frac{1}{N_0(\varepsilon_0, D)} = \frac{1}{\Delta
+         t_\mathrm{sample}} \max_d \frac{L_d^2}{2D_d} \varepsilon_0^2
           :label: eqawhn0
 
-Essentially, this tells us that a slower system (small :math:`D`)
+where :math:`L_d` is the length of the interval and :math:`D_d` is
+the diffusion constant along dimension :math:`d` of the AWH bias.
+For one dimension, :math:`L^2/2D` is the average time to diffuse
+over a distance of :math:`L`. We then takes the maximum crossing
+time over all dimensions involved in the bias.
+Essentially, this formula tells us that a slower system (small :math:`D`)
 requires more samples (larger :math:`N^0`) to attain the same level of
 accuracy (:math:`\varepsilon_0`) at a given sampling rate. Conversely,
 for a system of given diffusion, how to choose the initial biasing rate
@@ -621,9 +638,10 @@ run a short trial simulation and after the first covering check the
 maximum free energy difference of the PMF estimate. If this is much
 larger than the expected magnitude of the free energy barriers that
 should be crossed, then the system is probably being pulled too hard and
-:math:`D` should be decreased. :math:`\varepsilon_0` on the other hand,
-would only be tweaked when starting an AWH simulation using a fairly
-accurate guess of the PMF as input.
+:math:`D` should be decreased. An accurate estimate of the diffusion
+can be obtaining from an AWH simulation with the :ref:`gmx awh` tool.
+:math:`\varepsilon_0` on the other hand, should be a rough estimate
+of the initial error.
 
 Tips for efficient sampling
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^