Molecular dynamics parameters (.mdp options)
============================================
+.. _mdp-general:
+
General information
-------------------
.. mdp-value:: Linear
- Remove center of mass translation
+ Remove center of mass translational velocity
.. mdp-value:: Angular
- Remove center of mass translation and rotation around the center of mass
+ Remove center of mass translational and rotational velocity around
+ the center of mass
+
+ .. mdp-value:: Linear-acceleration-correction
+
+ Remove center of mass translational velocity. Correct the center of
+ mass position assuming linear acceleration over :mdp:`nstcomm` steps.
+ This is useful for cases where an acceleration is expected on the
+ center of mass which is nearly constant over mdp:`nstcomm` steps.
+ This can occur for example when pulling on a group using an absolute
+ reference.
.. mdp-value:: None
case :mdp:`rcoulomb` > :mdp:`rvdw` is allowed. Currently only
cut-off, reaction-field, PME or Ewald electrostatics and plain
LJ are supported. Some :ref:`gmx mdrun` functionality is not yet
- supported with the :mdp:`Verlet` scheme, but :ref:`gmx grompp`
+ supported with the :mdp-value:`cutoff-scheme=Verlet` scheme, but :ref:`gmx grompp`
checks for this. Native GPU acceleration is only supported with
- :mdp:`Verlet`. With GPU-accelerated PME or with separate PME
+ :mdp-value:`cutoff-scheme=Verlet`. With GPU-accelerated PME or with separate PME
ranks, :ref:`gmx mdrun` will automatically tune the CPU/GPU load
balance by scaling :mdp:`rcoulomb` and the grid spacing. This
- can be turned off with ``mdrun -notunepme``. :mdp:`Verlet` is
- faster than :mdp:`group` when there is no water, or if
- :mdp:`group` would use a pair-list buffer to conserve energy.
+ can be turned off with ``mdrun -notunepme``. :mdp-value:`cutoff-scheme=Verlet` is
+ faster than :mdp-value:`cutoff-scheme=group` when there is no water, or if
+ :mdp-value:`cutoff-scheme=group` would use a pair-list buffer to conserve energy.
.. mdp-value:: group
Frequency to update the neighbor list. When this is 0, the
neighbor list is made only once. With energy minimization the
neighborlist will be updated for every energy evaluation when
- :mdp:`nstlist` is greater than 0. With :mdp:`Verlet` and
+ :mdp:`nstlist` is greater than 0. With :mdp-value:`cutoff-scheme=Verlet` and
:mdp:`verlet-buffer-tolerance` set, :mdp:`nstlist` is actually
a minimum value and :ref:`gmx mdrun` might increase it, unless
it is set to 1. With parallel simulations and/or non-bonded
force calculation on the GPU, a value of 20 or 40 often gives
- the best performance. With :mdp:`group` and non-exact
+ the best performance. With :mdp-value:`cutoff-scheme=group` and non-exact
cut-off's, :mdp:`nstlist` will affect the accuracy of your
simulation and it can not be chosen freely.
.. mdp-value:: simple
Check every atom in the box when constructing a new neighbor
- list every :mdp:`nstlist` steps (only with :mdp:`group`
+ list every :mdp:`nstlist` steps (only with :mdp-value:`cutoff-scheme=group`
cut-off scheme).
.. mdp:: pbc
(0.005) \[kJ/mol/ps\]
- Useful only with the :mdp:`Verlet` :mdp:`cutoff-scheme`. This sets
+ Useful only with the :mdp-value:`cutoff-scheme=Verlet` :mdp:`cutoff-scheme`. This sets
the maximum allowed error for pair interactions per particle caused
by the Verlet buffer, which indirectly sets :mdp:`rlist`. As both
:mdp:`nstlist` and the Verlet buffer size are fixed (for
(1) \[nm\]
Cut-off distance for the short-range neighbor list. With the
- :mdp:`Verlet` :mdp:`cutoff-scheme`, this is by default set by the
+ :mdp-value:`cutoff-scheme=Verlet` :mdp:`cutoff-scheme`, this is by default set by the
:mdp:`verlet-buffer-tolerance` option and the value of
:mdp:`rlist` is ignored.
.. mdp-value:: Reaction-Field-zero
In |Gromacs|, normal reaction-field electrostatics with
- :mdp:`cutoff-scheme` = :mdp:`group` leads to bad energy
- conservation. :mdp:`Reaction-Field-zero` solves this by making
+ :mdp:`cutoff-scheme` = :mdp-value:`cutoff-scheme=group` leads to bad energy
+ conservation. :mdp-value:`coulombtype=Reaction-Field-zero` solves this by making
the potential zero beyond the cut-off. It can only be used with
an infinite dielectric constant (:mdp:`epsilon-rf` =0), because
only for that value the force vanishes at the
:mdp:`rcoulomb` to accommodate for the size of charge groups
and diffusion between neighbor list updates. This, and the fact
that table lookups are used instead of analytical functions make
- :mdp:`Reaction-Field-zero` computationally more expensive than
+ :mdp-value:`coulombtype=Reaction-Field-zero` computationally more expensive than
normal reaction-field.
.. mdp-value:: Shift
Analogous to :mdp-value:`vdwtype=Shift` for :mdp:`vdwtype`. You
- might want to use :mdp:`Reaction-Field-zero` instead, which has
+ might want to use :mdp-value:`coulombtype=Reaction-Field-zero` instead, which has
a similar potential shape, but has a physical interpretation and
has better energies due to the exclusion correction terms.
Analogous to :mdp-value:`vdwtype=Switch` for
:mdp:`vdwtype`. Switching the Coulomb potential can lead to
- serious artifacts, advice: use :mdp:`Reaction-Field-zero`
+ serious artifacts, advice: use :mdp-value:`coulombtype=Reaction-Field-zero`
instead.
.. mdp-value:: User
A combination of PME and a switch function for the direct-space
part (see above). :mdp:`rcoulomb` is allowed to be smaller than
:mdp:`rlist`. This is mainly useful constant energy simulations
- (note that using PME with :mdp:`cutoff-scheme` = :mdp:`Verlet`
+ (note that using PME with :mdp:`cutoff-scheme` = :mdp-value:`cutoff-scheme=Verlet`
will be more efficient).
.. mdp-value:: PME-User
.. mdp-value:: MTTK
Martyna-Tuckerman-Tobias-Klein implementation, only useable with
- :mdp-value:`md-vv` or :mdp-value:`md-vv-avek`, very similar to
+ :mdp-value:`integrator=md-vv` or :mdp-value:`integrator=md-vv-avek`, very similar to
Parrinello-Rahman. As for Nose-Hoover temperature coupling the
time constant :mdp:`tau-p` is the period of pressure
fluctuations at equilibrium. This is probably a better method
(1.5) \[nm\]
the radius of the cylinder for
- :mdp:`pull-coord1-geometry` = :mdp-value:`cylinder`
+ :mdp:`pull-coord1-geometry` = :mdp-value:`pull-coord1-geometry=cylinder`
.. mdp:: pull-constr-tol
.. mdp-value:: direction-periodic
- As :mdp-value:`direction`, but allows the distance to be larger
+ As :mdp-value:`pull-coord1-geometry=direction`, but allows the distance to be larger
than half the box size. With this geometry the box should not be
dynamic (*e.g.* no pressure scaling) in the pull dimensions and
the pull force is not added to virial.
.. mdp-value:: direction-relative
- As :mdp-value:`direction`, but the pull vector is the vector
+ As :mdp-value:`pull-coord1-geometry=direction`, but the pull vector is the vector
that points from the COM of a third to the COM of a fourth pull
group. This means that 4 groups need to be supplied in
:mdp:`pull-coord1-groups`. Note that the pull force will give
.. mdp-value:: angle-axis
- As :mdp-value:`angle` but the second vector is given by :mdp:`pull-coord1-vec`.
+ As :mdp-value:`pull-coord1-geometry=angle` but the second vector is given by :mdp:`pull-coord1-vec`.
Thus, only the two groups that define the first vector need to be given.
.. mdp-value:: dihedral
(Y Y Y)
Selects the dimensions that this pull coordinate acts on and that
are printed to the output files when
- :mdp:`pull-print-components` = :mdp-value:`yes`. With
- :mdp:`pull-coord1-geometry` = :mdp-value:`distance`, only Cartesian
+ :mdp:`pull-print-components` = :mdp-value:`pull-coord1-start=yes`. With
+ :mdp:`pull-coord1-geometry` = :mdp-value:`pull-coord1-geometry=distance`, only Cartesian
components set to Y contribute to the distance. Thus setting this
to Y Y N results in a distance in the x/y plane. With other
geometries all dimensions with non-zero entries in
:mdp:`free-energy` is turned on. The force constant is then (1 -
lambda) * :mdp:`pull-coord1-k` + lambda * :mdp:`pull-coord1-kB`.
+AWH adaptive biasing
+^^^^^^^^^^^^^^^^^^^^
+
+.. mdp:: awh
+
+ .. mdp-value:: no
+
+ No biasing.
+
+ .. mdp-value:: yes
+
+ Adaptively bias a reaction coordinate using the AWH method and estimate
+ the corresponding PMF. The PMF and other AWH data are written to energy
+ file at an interval set by :mdp:`awh-nstout` and can be extracted with
+ the ``gmx awh`` tool. The AWH coordinate can be
+ multidimensional and is defined by mapping each dimension to a pull coordinate index.
+ This is only allowed if :mdp-value:`pull-coord1-type=external-potential` and
+ :mdp:`pull-coord1-potential-provider` = ``awh`` for the concerned pull coordinate
+ indices.
+
+.. mdp:: awh-potential
+
+ .. mdp-value:: convolved
+
+ The applied biasing potential is the convolution of the bias function and a
+ set of harmonic umbrella potentials (see :mdp-value:`awh-potential=umbrella` below). This results
+ in a smooth potential function and force. The resolution of the potential is set
+ by the force constant of each umbrella, see :mdp:`awh1-dim1-force-constant`.
+
+ .. mdp-value:: umbrella
+
+ The potential bias is applied by controlling the position of an harmonic potential
+ using Monte-Carlo sampling. The force constant is set with
+ :mdp:`awh1-dim1-force-constant`. The umbrella location
+ is sampled using Monte-Carlo every :mdp:`awh-nstsample` steps.
+ There are no advantages to using an umbrella.
+ This option is mainly for comparison and testing purposes.
+
+.. mdp:: awh-share-multisim
+
+ .. mdp-value:: no
+
+ AWH will not share biases across simulations started with
+ :ref:`gmx mdrun` option ``-multidir``. The biases will be independent.
+
+ .. mdp-value:: yes
+
+ With :ref:`gmx mdrun` and option ``-multidir`` the bias and PMF estimates
+ for biases with :mdp:`awh1-share-group` >0 will be shared across simulations
+ with the biases with the same :mdp:`awh1-share-group` value.
+ The simulations should have the same AWH settings for sharing to make sense.
+ :ref:`gmx mdrun` will check whether the simulations are technically
+ compatible for sharing, but the user should check that bias sharing
+ physically makes sense.
+
+.. mdp:: awh-seed
+
+ (-1) Random seed for Monte-Carlo sampling the umbrella position,
+ where -1 indicates to generate a seed. Only used with
+ :mdp-value:`awh-potential=umbrella`.
+
+.. mdp:: awh-nstout
+
+ (100000)
+ Number of steps between printing AWH data to the energy file, should be
+ a multiple of :mdp:`nstenergy`.
+
+.. mdp:: awh-nstsample
+
+ (10)
+ Number of steps between sampling of the coordinate value. This sampling
+ is the basis for updating the bias and estimating the PMF and other AWH observables.
+
+.. mdp:: awh-nsamples-update
+
+ (10)
+ The number of coordinate samples used for each AWH update.
+ The update interval in steps is :mdp:`awh-nstsample` times this value.
+
+.. mdp:: awh-nbias
+
+ (1)
+ The number of biases, each acting on its own coordinate.
+ The following options should be specified
+ for each bias although below only the options for bias number 1 is shown. Options for
+ other bias indices are obtained by replacing '1' by the bias index.
+
+.. mdp:: awh1-error-init
+
+ (10.0) \[kJ mol-1\]
+ Estimated initial average error of the PMF for this bias. This value together with the
+ given diffusion constant(s) :mdp:`awh1-dim1-diffusion` determine the initial biasing rate.
+ The error is obviously not known *a priori*. Only a rough estimate of :mdp:`awh1-error-init`
+ is needed however.
+ As a general guideline, leave :mdp:`awh1-error-init` to its default value when starting a new
+ simulation. On the other hand, when there is *a priori* knowledge of the PMF (e.g. when
+ an initial PMF estimate is provided, see the :mdp:`awh1-user-data` option)
+ then :mdp:`awh1-error-init` should reflect that knowledge.
+
+.. mdp:: awh1-growth
+
+ .. mdp-value:: exp-linear
+
+ Each bias keeps a reference weight histogram for the coordinate samples.
+ Its size sets the magnitude of the bias function and free energy estimate updates
+ (few samples corresponds to large updates and vice versa).
+ Thus, its growth rate sets the maximum convergence rate.
+ By default, there is an initial stage in which the histogram grows close to exponentially (but slower than the sampling rate).
+ In the final stage that follows, the growth rate is linear and equal to the sampling rate (set by :mdp:`awh-nstsample`).
+ The initial stage is typically necessary for efficient convergence when starting a new simulation where
+ high free energy barriers have not yet been flattened by the bias.
+
+ .. mdp-value:: linear
+
+ As :mdp-value:`awh1-growth=exp-linear` but skip the initial stage. This may be useful if there is *a priori*
+ knowledge (see :mdp:`awh1-error-init`) which eliminates the need for an initial stage. This is also
+ the setting compatible with :mdp-value:`awh1-target=local-boltzmann`.
+
+.. mdp:: awh1-equilibrate-histogram
+
+ .. mdp-value:: no
+
+ Do not equilibrate histogram.
+
+ .. mdp-value:: yes
+
+ Before entering the initial stage (see :mdp-value:`awh1-growth=exp-linear`), make sure the
+ histogram of sampled weights is following the target distribution closely enough (specifically,
+ at least 80% of the target region needs to have a local relative error of less than 20%). This
+ option would typically only be used when :mdp:`awh1-share-group` > 0
+ and the initial configurations poorly represent the target
+ distribution.
+
+.. mdp:: awh1-target
+
+ .. mdp-value:: constant
+
+ The bias is tuned towards a constant (uniform) coordinate distribution
+ in the defined sampling interval (defined by \[:mdp:`awh1-dim1-start`, :mdp:`awh1-dim1-end`\]).
+
+ .. mdp-value:: cutoff
+
+ Similar to :mdp-value:`awh1-target=constant`, but the target
+ distribution is proportional to 1/(1 + exp(F - :mdp-value:`awh1-target=cutoff`)),
+ where F is the free energy relative to the estimated global minimum.
+ This provides a smooth switch of a flat target distribution in
+ regions with free energy lower than the cut-off to a Boltzmann
+ distribution in regions with free energy higher than the cut-off.
+
+ .. mdp-value:: boltzmann
+
+ The target distribution is a Boltzmann distribtution with a scaled beta (inverse temperature)
+ factor given by :mdp:`awh1-target-beta-scaling`. *E.g.*, a value of 0.1
+ would give the same coordinate distribution as sampling with a simulation temperature
+ scaled by 10.
+
+ .. mdp-value:: local-boltzmann
+
+ Same target distribution and use of :mdp:`awh1-target-beta-scaling`
+ but the convergence towards the target distribution is inherently local *i.e.*, the rate of
+ change of the bias only depends on the local sampling. This local convergence property is
+ only compatible with :mdp-value:`awh1-growth=linear`, since for
+ :mdp-value:`awh1-growth=exp-linear` histograms are globally rescaled in the initial stage.
+
+.. mdp:: awh1-target-beta-scaling
+
+ [0] \[\]
+ For :mdp-value:`awh1-target=boltzmann` and :mdp-value:`awh1-target=local-boltzmann`
+ it is the unitless beta scaling factor taking values in (0,1).
+
+.. mdp:: awh1-target-cutoff
+
+ [0] \[kJ mol-1\]
+ For :mdp-value:`awh1-target=cutoff` this is the cutoff, should be > 0.
+
+.. mdp:: awh1-user-data
+
+ .. mdp-value:: no
+
+ Initialize the PMF and target distribution with default values.
+
+ .. mdp-value:: yes
+
+ Initialize the PMF and target distribution with user provided data. For :mdp:`awh-nbias` = 1,
+ :ref:`gmx mdrun` will expect a file ``awhinit.xvg`` to be present in the run directory.
+ For multiple biases, :ref:`gmx mdrun` expects files ``awhinit1.xvg``, ``awhinit2.xvg``, etc.
+ The file name can be changed with the ``-awh`` option.
+ The first :mdp:`awh1-ndim` columns of
+ each input file should contain the coordinate values, such that each row defines a point in
+ coordinate space. Column :mdp:`awh1-ndim` + 1 should contain the PMF value for each point.
+ The target distribution column can either follow the PMF (column :mdp:`awh1-ndim` + 2) or
+ be in the same column as written by :ref:`gmx awh`.
+
+.. mdp:: awh1-share-group
+
+ .. mdp-value:: 0
+
+ Do not share the bias.
+
+ .. mdp-value:: positive
+
+ Share the bias and PMF estimates within and/or between simulations.
+ Within a simulation, the bias will be shared between biases that have the
+ same :mdp:`awh1-share-group` index (note that the current code does not support this).
+ With :mdp-value:`awh-share-multisim=yes` and
+ :ref:`gmx mdrun` option ``-multidir`` the bias will also be shared across simulations.
+ Sharing may increase convergence initially, although the starting configurations
+ can be critical, especially when sharing between many biases.
+ Currently, positive group values should start at 1 and increase
+ by 1 for each subsequent bias that is shared.
+
+.. mdp:: awh1-ndim
+
+ (1) \[integer\]
+ Number of dimensions of the coordinate, each dimension maps to 1 pull coordinate.
+ The following options should be specified for each such dimension. Below only
+ the options for dimension number 1 is shown. Options for other dimension indices are
+ obtained by replacing '1' by the dimension index.
+
+.. mdp:: awh1-dim1-coord-provider
+
+ .. mdp-value:: pull
+
+ The module providing the reaction coordinate for this dimension.
+ Currently AWH can only act on pull coordinates.
+
+.. mdp:: awh1-dim1-coord-index
+
+ (1)
+ Index of the pull coordinate defining this coordinate dimension.
+
+.. mdp:: awh1-dim1-force-constant
+
+ (0) \[kJ/mol/nm^2\] or \[kJ/mol/rad^2\]
+ Force constant for the (convolved) umbrella potential(s) along this
+ coordinate dimension.
+
+.. mdp:: awh1-dim1-start
+
+ (0.0) \[nm\]/\[rad\]
+ Start value of the sampling interval along this dimension. The range of allowed
+ values depends on the relevant pull geometry (see :mdp:`pull-coord1-geometry`).
+ For periodic geometries :mdp:`awh1-dim1-start` greater than :mdp:`awh1-dim1-end`
+ is allowed. The interval will then wrap around from +period/2 to -period/2.
+
+.. mdp:: awh1-dim1-end
+
+ (0.0) \[nm\]/\[rad\]
+ End value defining the sampling interval together with :mdp:`awh1-dim1-start`.
+
+.. mdp:: awh1-dim1-period
+
+ (0.0) \[nm\]/\[rad\]
+ The period of this reaction coordinate, use 0 when the coordinate is not periodic.
+
+.. mdp:: awh1-dim1-diffusion
+
+ (1e-5) \[nm^2/ps\]/\[rad^2/ps\]
+ Estimated diffusion constant for this coordinate dimension determining the initial
+ biasing rate. This needs only be a rough estimate and should not critically
+ affect the results unless it is set to something very low, leading to slow convergence,
+ or very high, forcing the system far from equilibrium. Not setting this value
+ explicitly generates a warning.
+
+.. mdp:: awh1-dim1-cover-diameter
+
+ (0.0)) \[nm\]/\[rad\]
+ Diameter that needs to be sampled by a single simulation around a coordinate value
+ before the point is considered covered in the initial stage (see :mdp-value:`awh1-growth=exp-linear`).
+ A value > 0 ensures that for each covering there is a continuous transition of this diameter
+ across each coordinate value.
+ This is trivially true for independent simulations but not for for multiple bias-sharing simulations
+ (:mdp:`awh1-share-group`>0).
+ For a diameter = 0, covering occurs as soon as the simulations have sampled the whole interval, which
+ for many sharing simulations does not guarantee transitions across free energy barriers.
+ On the other hand, when the diameter >= the sampling interval length, covering occurs when a single simulation
+ has independently sampled the whole interval.
Enforced rotation
^^^^^^^^^^^^^^^^^
.. mdp-value:: yes
- Apply the rotation potential specified by :mdp:`rot-type` to the group of atoms given
- under the :mdp:`rot-group` option.
+ Apply the rotation potential specified by :mdp:`rot-type0` to the group of atoms given
+ under the :mdp:`rot-group0` option.
.. mdp:: rot-ngroups
Electric fields
-^^^^^^^^^^^^^^^
-
-.. mdp:: E-x ; E-y ; E-z
+.. mdp:: electric-field-x ; electric-field-y ; electric-field-z
- If you want to use an electric field in a direction, enter 3
- numbers after the appropriate E-direction, the first number: the
- number of cosines, only 1 is implemented (with frequency 0) so
- enter 1, the second number: the strength of the electric field in V
- nm^-1, the third number: the phase of the cosine, you can enter any
- number here since a cosine of frequency zero has no phase.
-
-.. mdp:: E-xt; E-yt; E-zt
-
- Here you can specify a pulsed alternating electric field. The field
+ Here you can specify an electric field that optionally can be
+ alternating and pulsed. The general expression for the field
has the form of a gaussian laser pulse:
E(t) = E0 exp ( -(t-t0)^2/(2 sigma^2) ) cos(omega (t-t0))
For example, the four parameters for direction x are set in the
- three fields of :mdp:`E-x` and :mdp:`E-xt` like
-
- E-x = 1 E0 0
+ three fields of :mdp:`electric-field-x` (and similar for y and z)
+ like
- E-xt = omega t0 sigma
+ electric-field-x = E0 omega t0 sigma
In the special case that sigma = 0, the exponential term is omitted
- and only the cosine term is used.
+ and only the cosine term is used. If also omega = 0 a static
+ electric field is applied.
More details in Carl Caleman and David van der Spoel: Picosecond
Melting of Ice by an Infrared Laser Pulse - A Simulation Study
biod.pnpi.spb.ru / alexxy / gromacs.git / blobdiff