Merge pull request #4488 from ye-luo/doc-update-trial

Document how the trial energy is updated.

docs/methods.rst

@@ -216,8 +216,8 @@ Additional information:
   sufficient number of ``blocks`` to perform statistical analysis.
 
 - ``warmupsteps`` - ``warmupsteps`` are used only for
-  equilibration. Property measurements are not performed during
-  warm-up steps.
+  initial equilibration and do not count against the requested step or block count.
+  Property measurements are not performed during warm-up steps.
 
 - ``steps`` - ``steps`` are the number of energy and other property measurements to perform per block.
 
@@ -381,15 +381,15 @@ Additional information:
   sufficient number of ``blocks`` to perform statistical analysis.
 
 - ``warmupsteps`` - ``warmupsteps`` are used only for
-  equilibration. Property measurements are not performed during
-  warm-up steps.
+  initial equilibration and do not count against the requested step or block count.
+  Property measurements are not performed during warm-up steps.
 
 - ``steps`` - ``steps`` are the number of energy and other property measurements to perform per block.
 
 - ``substeps``  For each substep, an attempt is made to move each of the electrons once only by either particle-by-particle or an
   all-electron move.  Because the local energy is evaluated only at
   each full step and not each substep, ``substeps`` are computationally cheaper
-  and can be used to de-correlation at a low computational cost.
+  and can be used for decorrelation at a low computational cost.
 
 - ``usedrift`` The VMC is implemented in two algorithms with
   or without drift. In the no-drift algorithm, the move of each
@@ -1464,10 +1464,6 @@ Additional information:
 
 -  ``steps``: This is the number of DMC steps in a block.
 
--  ``warmupsteps``: These are the steps at the beginning of a DMC run in
-   which the instantaneous average energy is used to update the trial
-   energy. During regular steps, E\ :math:`_{ref}` is used.
-
 -  ``timestep``: The ``timestep`` determines the accuracy of the
    imaginary time propagator. Generally, multiple time steps are used to
    extrapolate to the infinite time step limit. A good range of time
@@ -1490,24 +1486,35 @@ Additional information:
 
 - ``debug_checks`` valid values are 'no', 'all', 'checkGL_after_moves'. If the build type is `debug`, the default value is 'all'. Otherwise, the default value is 'no'.
 
--  ``energyUpdateInterval``: The default is to update the trial energy
-   at every step. Otherwise the trial energy is updated every
-   ``energyUpdateInterval`` step.
+-  ``warmupsteps``: These are the steps at the beginning of a DMC run in
+   which the instantaneous population average energy is used to update the trial
+   energy and updates happen at every step. The aim is to rapidly equilibrate the population while avoiding overly large population fluctuations.
+   Unlike VMC, these warmupsteps are included in the requested DMC step count.
+
+.. math::
+
+  E_\text{trial} = E_\text{pop_avg}+(\ln \texttt{targetwalkers}-\ln N_\text{pop}) / \texttt{timestep}
+
+where :math:`E_\text{pop_avg}` is the local energy average over the walker population at the current step
+and :math:`N_\text{pop}` is the current walker population size.
+After the warm-up phase, the trial energy is updated as
 
 .. math::
 
-  E_{\text{trial}}=
-  \textrm{refEnergy}+\textrm{feedback}\cdot(\ln\texttt{targetWalkers}-\ln N)\:,
+  E_\text{trial} = E_\text{ref}+\texttt{feedback}\cdot(\ln\texttt{targetWalkers}-\ln N_\text{pop})
+
+where :math:`E_\text{ref}` is the :math:`E_\text{pop_avg}` average over all the post warm-up steps up to the current step. The update frequency is controlled by ``energyUpdateInterval``.
 
-where :math:`N` is the current population.
+-  ``energyUpdateInterval``: Post warm-up, the trial energy is updated every
+   ``energyUpdateInterval`` steps. Default value is 1 (every step).
 
 -  ``refEnergy``: The default reference energy is taken from the VMC run
    that precedes the DMC run. This value is updated to the current mean
    whenever branching happens.
 
 -  ``feedback``: This variable is used to determine how strong to react
-   to population fluctuations when doing population control. See the
-   equation in energyUpdateInterval for more details.
+   to population fluctuations when doing population control. Default value is 1. See the
+   equation in ``warmupsteps`` for more details.
 
 -  ``useBareTau``: The same time step is used whether or not a move is
    rejected. The default is to use an effective time step when a move is