Merge release-2018 into release-2019
[alexxy/gromacs.git] / docs / user-guide / mdp-options.rst
1 .. README
2    See the "run control" section for a working example of the
3    syntax to use when making .mdp entries, with and without detailed
4    documentation for values those entries might take. Everything can
5    be cross-referenced, see the examples there. TODO Make more
6    cross-references.
7
8 Molecular dynamics parameters (.mdp options)
9 ============================================
10
11 .. _mdp-general:
12
13 General information
14 -------------------
15
16 Default values are given in parentheses, or listed first among
17 choices. The first option in the list is always the default
18 option. Units are given in square brackets. The difference between a
19 dash and an underscore is ignored.
20
21 A :ref:`sample mdp file <mdp>` is available. This should be
22 appropriate to start a normal simulation. Edit it to suit your
23 specific needs and desires.
24
25
26 Preprocessing
27 ^^^^^^^^^^^^^
28
29 .. mdp:: include
30
31    directories to include in your topology. Format:
32    ``-I/home/john/mylib -I../otherlib``
33
34 .. mdp:: define
35
36    defines to pass to the preprocessor, default is no defines. You can
37    use any defines to control options in your customized topology
38    files. Options that act on existing :ref:`top` file mechanisms
39    include
40
41       ``-DFLEXIBLE`` will use flexible water instead of rigid water
42       into your topology, this can be useful for normal mode analysis.
43
44       ``-DPOSRES`` will trigger the inclusion of ``posre.itp`` into
45       your topology, used for implementing position restraints.
46
47
48 Run control
49 ^^^^^^^^^^^
50
51 .. mdp:: integrator
52
53    (Despite the name, this list includes algorithms that are not
54    actually integrators over time. :mdp-value:`integrator=steep` and
55    all entries following it are in this category)
56
57    .. mdp-value:: md
58
59       A leap-frog algorithm for integrating Newton's equations of motion.
60
61    .. mdp-value:: md-vv
62
63       A velocity Verlet algorithm for integrating Newton's equations
64       of motion.  For constant NVE simulations started from
65       corresponding points in the same trajectory, the trajectories
66       are analytically, but not binary, identical to the
67       :mdp-value:`integrator=md` leap-frog integrator. The the kinetic
68       energy, which is determined from the whole step velocities and
69       is therefore slightly too high. The advantage of this integrator
70       is more accurate, reversible Nose-Hoover and Parrinello-Rahman
71       coupling integration based on Trotter expansion, as well as
72       (slightly too small) full step velocity output. This all comes
73       at the cost off extra computation, especially with constraints
74       and extra communication in parallel. Note that for nearly all
75       production simulations the :mdp-value:`integrator=md` integrator
76       is accurate enough.
77
78    .. mdp-value:: md-vv-avek
79
80       A velocity Verlet algorithm identical to
81       :mdp-value:`integrator=md-vv`, except that the kinetic energy is
82       determined as the average of the two half step kinetic energies
83       as in the :mdp-value:`integrator=md` integrator, and this thus
84       more accurate.  With Nose-Hoover and/or Parrinello-Rahman
85       coupling this comes with a slight increase in computational
86       cost.
87
88    .. mdp-value:: sd
89
90       An accurate and efficient leap-frog stochastic dynamics
91       integrator. With constraints, coordinates needs to be
92       constrained twice per integration step. Depending on the
93       computational cost of the force calculation, this can take a
94       significant part of the simulation time. The temperature for one
95       or more groups of atoms (:mdp:`tc-grps`) is set with
96       :mdp:`ref-t`, the inverse friction constant for each group is
97       set with :mdp:`tau-t`.  The parameter :mdp:`tcoupl` is
98       ignored. The random generator is initialized with
99       :mdp:`ld-seed`. When used as a thermostat, an appropriate value
100       for :mdp:`tau-t` is 2 ps, since this results in a friction that
101       is lower than the internal friction of water, while it is high
102       enough to remove excess heat NOTE: temperature deviations decay
103       twice as fast as with a Berendsen thermostat with the same
104       :mdp:`tau-t`.
105
106    .. mdp-value:: bd
107
108       An Euler integrator for Brownian or position Langevin dynamics,
109       the velocity is the force divided by a friction coefficient
110       (:mdp:`bd-fric`) plus random thermal noise (:mdp:`ref-t`). When
111       :mdp:`bd-fric` is 0, the friction coefficient for each particle
112       is calculated as mass/ :mdp:`tau-t`, as for the integrator
113       :mdp-value:`integrator=sd`. The random generator is initialized
114       with :mdp:`ld-seed`.
115
116    .. mdp-value:: steep
117
118       A steepest descent algorithm for energy minimization. The
119       maximum step size is :mdp:`emstep`, the tolerance is
120       :mdp:`emtol`.
121
122    .. mdp-value:: cg
123
124       A conjugate gradient algorithm for energy minimization, the
125       tolerance is :mdp:`emtol`. CG is more efficient when a steepest
126       descent step is done every once in a while, this is determined
127       by :mdp:`nstcgsteep`. For a minimization prior to a normal mode
128       analysis, which requires a very high accuracy, |Gromacs| should be
129       compiled in double precision.
130
131    .. mdp-value:: l-bfgs
132
133       A quasi-Newtonian algorithm for energy minimization according to
134       the low-memory Broyden-Fletcher-Goldfarb-Shanno approach. In
135       practice this seems to converge faster than Conjugate Gradients,
136       but due to the correction steps necessary it is not (yet)
137       parallelized.
138
139    .. mdp-value:: nm
140
141       Normal mode analysis is performed on the structure in the :ref:`tpr`
142       file.  |Gromacs| should be compiled in double precision.
143
144    .. mdp-value:: tpi
145
146       Test particle insertion. The last molecule in the topology is
147       the test particle. A trajectory must be provided to ``mdrun
148       -rerun``. This trajectory should not contain the molecule to be
149       inserted. Insertions are performed :mdp:`nsteps` times in each
150       frame at random locations and with random orientiations of the
151       molecule. When :mdp:`nstlist` is larger than one,
152       :mdp:`nstlist` insertions are performed in a sphere with radius
153       :mdp:`rtpi` around a the same random location using the same
154       pair list. Since pair list construction is expensive,
155       one can perform several extra insertions with the same list
156       almost for free. The random seed is set with
157       :mdp:`ld-seed`. The temperature for the Boltzmann weighting is
158       set with :mdp:`ref-t`, this should match the temperature of the
159       simulation of the original trajectory. Dispersion correction is
160       implemented correctly for TPI. All relevant quantities are
161       written to the file specified with ``mdrun -tpi``. The
162       distribution of insertion energies is written to the file
163       specified with ``mdrun -tpid``. No trajectory or energy file is
164       written. Parallel TPI gives identical results to single-node
165       TPI. For charged molecules, using PME with a fine grid is most
166       accurate and also efficient, since the potential in the system
167       only needs to be calculated once per frame.
168
169    .. mdp-value:: tpic
170
171       Test particle insertion into a predefined cavity location. The
172       procedure is the same as for :mdp-value:`integrator=tpi`, except
173       that one coordinate extra is read from the trajectory, which is
174       used as the insertion location. The molecule to be inserted
175       should be centered at 0,0,0. |Gromacs| does not do this for you,
176       since for different situations a different way of centering
177       might be optimal. Also :mdp:`rtpi` sets the radius for the
178       sphere around this location. Neighbor searching is done only
179       once per frame, :mdp:`nstlist` is not used. Parallel
180       :mdp-value:`integrator=tpic` gives identical results to
181       single-rank :mdp-value:`integrator=tpic`.
182
183    .. mdp-value:: mimic
184
185       Enable MiMiC QM/MM coupling to run hybrid molecular dynamics.
186       Keey in mind that its required to launch CPMD compiled with MiMiC as well.
187       In this mode all options regarding integration (T-coupling, P-coupling,
188       timestep and number of steps) are ignored as CPMD will do the integration
189       instead. Options related to forces computation (cutoffs, PME parameters,
190       etc.) are working as usual. Atom selection to define QM atoms is read
191       from :mdp:`QMMM-grps`
192
193 .. mdp:: tinit
194
195         (0) [ps]
196         starting time for your run (only makes sense for time-based
197         integrators)
198
199 .. mdp:: dt
200
201         (0.001) [ps]
202         time step for integration (only makes sense for time-based
203         integrators)
204
205 .. mdp:: nsteps
206
207         (0)
208         maximum number of steps to integrate or minimize, -1 is no
209         maximum
210
211 .. mdp:: init-step
212
213         (0)
214         The starting step. The time at step i in a run is
215         calculated as: t = :mdp:`tinit` + :mdp:`dt` *
216         (:mdp:`init-step` + i). The free-energy lambda is calculated
217         as: lambda = :mdp:`init-lambda` + :mdp:`delta-lambda` *
218         (:mdp:`init-step` + i). Also non-equilibrium MD parameters can
219         depend on the step number. Thus for exact restarts or redoing
220         part of a run it might be necessary to set :mdp:`init-step` to
221         the step number of the restart frame. :ref:`gmx convert-tpr`
222         does this automatically.
223
224 .. mdp:: simulation-part
225
226          (0)
227          A simulation can consist of multiple parts, each of which has
228          a part number. This option specifies what that number will
229          be, which helps keep track of parts that are logically the
230          same simulation. This option is generally useful to set only
231          when coping with a crashed simulation where files were lost.
232
233 .. mdp:: comm-mode
234
235    .. mdp-value:: Linear
236
237       Remove center of mass translational velocity
238
239    .. mdp-value:: Angular
240
241       Remove center of mass translational and rotational velocity
242
243    .. mdp-value:: Linear-acceleration-correction
244
245       Remove center of mass translational velocity. Correct the center of
246       mass position assuming linear acceleration over :mdp:`nstcomm` steps.
247       This is useful for cases where an acceleration is expected on the
248       center of mass which is nearly constant over :mdp:`nstcomm` steps.
249       This can occur for example when pulling on a group using an absolute
250       reference.
251
252    .. mdp-value:: None
253
254       No restriction on the center of mass motion
255
256 .. mdp:: nstcomm
257
258    (100) [steps]
259    frequency for center of mass motion removal
260
261 .. mdp:: comm-grps
262
263    group(s) for center of mass motion removal, default is the whole
264    system
265
266
267 Langevin dynamics
268 ^^^^^^^^^^^^^^^^^
269
270 .. mdp:: bd-fric
271
272    (0) [amu ps\ :sup:`-1`]
273    Brownian dynamics friction coefficient. When :mdp:`bd-fric` is 0,
274    the friction coefficient for each particle is calculated as mass/
275    :mdp:`tau-t`.
276
277 .. mdp:: ld-seed
278
279    (-1) [integer]
280    used to initialize random generator for thermal noise for
281    stochastic and Brownian dynamics. When :mdp:`ld-seed` is set to -1,
282    a pseudo random seed is used. When running BD or SD on multiple
283    processors, each processor uses a seed equal to :mdp:`ld-seed` plus
284    the processor number.
285
286
287 Energy minimization
288 ^^^^^^^^^^^^^^^^^^^
289
290 .. mdp:: emtol
291
292    (10.0) [kJ mol\ :sup:`-1` nm\ :sup:`-1`]
293    the minimization is converged when the maximum force is smaller
294    than this value
295
296 .. mdp:: emstep
297
298    (0.01) [nm]
299    initial step-size
300
301 .. mdp:: nstcgsteep
302
303    (1000) [steps]
304    frequency of performing 1 steepest descent step while doing
305    conjugate gradient energy minimization.
306
307 .. mdp:: nbfgscorr
308
309    (10)
310    Number of correction steps to use for L-BFGS minimization. A higher
311    number is (at least theoretically) more accurate, but slower.
312
313
314 Shell Molecular Dynamics
315 ^^^^^^^^^^^^^^^^^^^^^^^^
316
317 When shells or flexible constraints are present in the system the
318 positions of the shells and the lengths of the flexible constraints
319 are optimized at every time step until either the RMS force on the
320 shells and constraints is less than :mdp:`emtol`, or a maximum number
321 of iterations :mdp:`niter` has been reached. Minimization is converged
322 when the maximum force is smaller than :mdp:`emtol`. For shell MD this
323 value should be 1.0 at most.
324
325 .. mdp:: niter
326
327    (20)
328    maximum number of iterations for optimizing the shell positions and
329    the flexible constraints.
330
331 .. mdp:: fcstep
332
333    (0) [ps\ :sup:`2`]
334    the step size for optimizing the flexible constraints. Should be
335    chosen as mu/(d2V/dq2) where mu is the reduced mass of two
336    particles in a flexible constraint and d2V/dq2 is the second
337    derivative of the potential in the constraint direction. Hopefully
338    this number does not differ too much between the flexible
339    constraints, as the number of iterations and thus the runtime is
340    very sensitive to fcstep. Try several values!
341
342
343 Test particle insertion
344 ^^^^^^^^^^^^^^^^^^^^^^^
345
346 .. mdp:: rtpi
347
348    (0.05) [nm]
349    the test particle insertion radius, see integrators
350    :mdp-value:`integrator=tpi` and :mdp-value:`integrator=tpic`
351
352
353 Output control
354 ^^^^^^^^^^^^^^
355
356 .. mdp:: nstxout
357
358    (0) [steps]
359    number of steps that elapse between writing coordinates to the output
360    trajectory file (:ref:`trr`), the last coordinates are always written
361
362 .. mdp:: nstvout
363
364    (0) [steps]
365    number of steps that elapse between writing velocities to the output
366    trajectory file (:ref:`trr`), the last velocities are always written
367
368 .. mdp:: nstfout
369
370    (0) [steps]
371    number of steps that elapse between writing forces to the output
372    trajectory file (:ref:`trr`), the last forces are always written.
373
374 .. mdp:: nstlog
375
376    (1000) [steps]
377    number of steps that elapse between writing energies to the log
378    file, the last energies are always written
379
380 .. mdp:: nstcalcenergy
381
382    (100)
383    number of steps that elapse between calculating the energies, 0 is
384    never. This option is only relevant with dynamics. This option affects the
385    performance in parallel simulations, because calculating energies
386    requires global communication between all processes which can
387    become a bottleneck at high parallelization.
388
389 .. mdp:: nstenergy
390
391    (1000) [steps]
392    number of steps that elapse between writing energies to energy file,
393    the last energies are always written, should be a multiple of
394    :mdp:`nstcalcenergy`. Note that the exact sums and fluctuations
395    over all MD steps modulo :mdp:`nstcalcenergy` are stored in the
396    energy file, so :ref:`gmx energy` can report exact energy averages
397    and fluctuations also when :mdp:`nstenergy` > 1
398
399 .. mdp:: nstxout-compressed
400
401    (0) [steps]
402    number of steps that elapse between writing position coordinates
403    using lossy compression (:ref:`xtc` file)
404
405 .. mdp:: compressed-x-precision
406
407    (1000) [real]
408    precision with which to write to the compressed trajectory file
409
410 .. mdp:: compressed-x-grps
411
412    group(s) to write to the compressed trajectory file, by default the
413    whole system is written (if :mdp:`nstxout-compressed` > 0)
414
415 .. mdp:: energygrps
416
417    group(s) for which to write to write short-ranged non-bonded
418    potential energies to the energy file (not supported on GPUs)
419
420
421 Neighbor searching
422 ^^^^^^^^^^^^^^^^^^
423
424 .. mdp:: cutoff-scheme
425
426    .. mdp-value:: Verlet
427
428       Generate a pair list with buffering. The buffer size is
429       automatically set based on :mdp:`verlet-buffer-tolerance`,
430       unless this is set to -1, in which case :mdp:`rlist` will be
431       used. This option has an explicit, exact cut-off at :mdp:`rvdw`
432       equal to :mdp:`rcoulomb`, unless PME or Ewald is used, in which
433       case :mdp:`rcoulomb` > :mdp:`rvdw` is allowed. Currently only
434       cut-off, reaction-field, PME or Ewald electrostatics and plain
435       LJ are supported. Some :ref:`gmx mdrun` functionality is not yet
436       supported with the :mdp-value:`cutoff-scheme=Verlet` scheme, but :ref:`gmx grompp`
437       checks for this. Native GPU acceleration is only supported with
438       :mdp-value:`cutoff-scheme=Verlet`. With GPU-accelerated PME or with separate PME
439       ranks, :ref:`gmx mdrun` will automatically tune the CPU/GPU load
440       balance by scaling :mdp:`rcoulomb` and the grid spacing. This
441       can be turned off with ``mdrun -notunepme``. :mdp-value:`cutoff-scheme=Verlet` is
442       faster than :mdp-value:`cutoff-scheme=group` when there is no water, or if
443       :mdp-value:`cutoff-scheme=group` would use a pair-list buffer to conserve energy.
444
445    .. mdp-value:: group
446
447       Generate a pair list for groups of atoms. These groups
448       correspond to the charge groups in the topology. This was the
449       only cut-off treatment scheme before version 4.6, and is
450       **deprecated since 5.1**. There is no explicit buffering of
451       the pair list. This enables efficient force calculations for
452       water, but energy is only conserved when a buffer is explicitly
453       added.
454
455 .. mdp:: nstlist
456
457    (10) [steps]
458
459    .. mdp-value:: >0
460
461       Frequency to update the neighbor list. When this is 0, the
462       neighbor list is made only once. With energy minimization the
463       pair list will be updated for every energy evaluation when
464       :mdp:`nstlist` is greater than 0. With :mdp-value:`cutoff-scheme=Verlet` and
465       :mdp:`verlet-buffer-tolerance` set, :mdp:`nstlist` is actually
466       a minimum value and :ref:`gmx mdrun` might increase it, unless
467       it is set to 1. With parallel simulations and/or non-bonded
468       force calculation on the GPU, a value of 20 or 40 often gives
469       the best performance. With :mdp-value:`cutoff-scheme=group` and non-exact
470       cut-off's, :mdp:`nstlist` will affect the accuracy of your
471       simulation and it can not be chosen freely.
472
473    .. mdp-value:: 0
474
475       The neighbor list is only constructed once and never
476       updated. This is mainly useful for vacuum simulations in which
477       all particles see each other.
478
479    .. mdp-value:: <0
480
481       Unused.
482
483 .. mdp:: ns-type
484
485    .. mdp-value:: grid
486
487       Make a grid in the box and only check atoms in neighboring grid
488       cells when constructing a new neighbor list every
489       :mdp:`nstlist` steps. In large systems grid search is much
490       faster than simple search.
491
492    .. mdp-value:: simple
493
494       Check every atom in the box when constructing a new neighbor
495       list every :mdp:`nstlist` steps (only with :mdp-value:`cutoff-scheme=group`
496       cut-off scheme).
497
498 .. mdp:: pbc
499
500    .. mdp-value:: xyz
501
502       Use periodic boundary conditions in all directions.
503
504    .. mdp-value:: no
505
506       Use no periodic boundary conditions, ignore the box. To simulate
507       without cut-offs, set all cut-offs and :mdp:`nstlist` to 0. For
508       best performance without cut-offs on a single MPI rank, set
509       :mdp:`nstlist` to zero and :mdp-value:`ns-type=simple`.
510
511    .. mdp-value:: xy
512
513       Use periodic boundary conditions in x and y directions
514       only. This works only with :mdp-value:`ns-type=grid` and can be used
515       in combination with walls_. Without walls or with only one wall
516       the system size is infinite in the z direction. Therefore
517       pressure coupling or Ewald summation methods can not be
518       used. These disadvantages do not apply when two walls are used.
519
520 .. mdp:: periodic-molecules
521
522    .. mdp-value:: no
523
524       molecules are finite, fast molecular PBC can be used
525
526    .. mdp-value:: yes
527
528       for systems with molecules that couple to themselves through the
529       periodic boundary conditions, this requires a slower PBC
530       algorithm and molecules are not made whole in the output
531
532 .. mdp:: verlet-buffer-tolerance
533
534    (0.005) [kJ mol\ :sup:`-1` ps\ :sup:`-1`]
535
536    Useful only with the :mdp-value:`cutoff-scheme=Verlet` :mdp:`cutoff-scheme`. This sets
537    the maximum allowed error for pair interactions per particle caused
538    by the Verlet buffer, which indirectly sets :mdp:`rlist`. As both
539    :mdp:`nstlist` and the Verlet buffer size are fixed (for
540    performance reasons), particle pairs not in the pair list can
541    occasionally get within the cut-off distance during
542    :mdp:`nstlist` -1 steps. This causes very small jumps in the
543    energy. In a constant-temperature ensemble, these very small energy
544    jumps can be estimated for a given cut-off and :mdp:`rlist`. The
545    estimate assumes a homogeneous particle distribution, hence the
546    errors might be slightly underestimated for multi-phase
547    systems. (See the `reference manual`_ for details). For longer
548    pair-list life-time (:mdp:`nstlist` -1) * :mdp:`dt` the buffer is
549    overestimated, because the interactions between particles are
550    ignored. Combined with cancellation of errors, the actual drift of
551    the total energy is usually one to two orders of magnitude
552    smaller. Note that the generated buffer size takes into account
553    that the |Gromacs| pair-list setup leads to a reduction in the
554    drift by a factor 10, compared to a simple particle-pair based
555    list. Without dynamics (energy minimization etc.), the buffer is 5%
556    of the cut-off. For NVE simulations the initial temperature is
557    used, unless this is zero, in which case a buffer of 10% is
558    used. For NVE simulations the tolerance usually needs to be lowered
559    to achieve proper energy conservation on the nanosecond time
560    scale. To override the automated buffer setting, use
561    :mdp:`verlet-buffer-tolerance` =-1 and set :mdp:`rlist` manually.
562
563 .. mdp:: rlist
564
565    (1) [nm]
566    Cut-off distance for the short-range neighbor list. With the
567    :mdp-value:`cutoff-scheme=Verlet` :mdp:`cutoff-scheme`, this is by default set by the
568    :mdp:`verlet-buffer-tolerance` option and the value of
569    :mdp:`rlist` is ignored.
570
571
572 Electrostatics
573 ^^^^^^^^^^^^^^
574
575 .. mdp:: coulombtype
576
577    .. mdp-value:: Cut-off
578
579       Plain cut-off with pair list radius :mdp:`rlist` and
580       Coulomb cut-off :mdp:`rcoulomb`, where :mdp:`rlist` >=
581       :mdp:`rcoulomb`.
582
583    .. mdp-value:: Ewald
584
585       Classical Ewald sum electrostatics. The real-space cut-off
586       :mdp:`rcoulomb` should be equal to :mdp:`rlist`. Use *e.g.*
587       :mdp:`rlist` =0.9, :mdp:`rcoulomb` =0.9. The highest magnitude
588       of wave vectors used in reciprocal space is controlled by
589       :mdp:`fourierspacing`. The relative accuracy of
590       direct/reciprocal space is controlled by :mdp:`ewald-rtol`.
591
592       NOTE: Ewald scales as O(N\ :sup:`3/2`) and is thus extremely slow for
593       large systems. It is included mainly for reference - in most
594       cases PME will perform much better.
595
596    .. mdp-value:: PME
597
598       Fast smooth Particle-Mesh Ewald (SPME) electrostatics. Direct
599       space is similar to the Ewald sum, while the reciprocal part is
600       performed with FFTs. Grid dimensions are controlled with
601       :mdp:`fourierspacing` and the interpolation order with
602       :mdp:`pme-order`. With a grid spacing of 0.1 nm and cubic
603       interpolation the electrostatic forces have an accuracy of
604       2-3*10\ :sup:`-4`. Since the error from the vdw-cutoff is larger than
605       this you might try 0.15 nm. When running in parallel the
606       interpolation parallelizes better than the FFT, so try
607       decreasing grid dimensions while increasing interpolation.
608
609    .. mdp-value:: P3M-AD
610
611       Particle-Particle Particle-Mesh algorithm with analytical
612       derivative for for long range electrostatic interactions. The
613       method and code is identical to SPME, except that the influence
614       function is optimized for the grid. This gives a slight increase
615       in accuracy.
616
617    .. mdp-value:: Reaction-Field
618
619       Reaction field electrostatics with Coulomb cut-off
620       :mdp:`rcoulomb`, where :mdp:`rlist` >= :mdp:`rvdw`. The
621       dielectric constant beyond the cut-off is
622       :mdp:`epsilon-rf`. The dielectric constant can be set to
623       infinity by setting :mdp:`epsilon-rf` =0.
624
625    .. mdp-value:: Generalized-Reaction-Field
626
627       Generalized reaction field with Coulomb cut-off
628       :mdp:`rcoulomb`, where :mdp:`rlist` >= :mdp:`rcoulomb`. The
629       dielectric constant beyond the cut-off is
630       :mdp:`epsilon-rf`. The ionic strength is computed from the
631       number of charged (*i.e.* with non zero charge) charge
632       groups. The temperature for the GRF potential is set with
633       :mdp:`ref-t`.
634
635    .. mdp-value:: Reaction-Field-zero
636
637       In |Gromacs|, normal reaction-field electrostatics with
638       :mdp-value:`cutoff-scheme=group` leads to bad energy
639       conservation. :mdp-value:`coulombtype=Reaction-Field-zero` solves this by making
640       the potential zero beyond the cut-off. It can only be used with
641       an infinite dielectric constant (:mdp:`epsilon-rf` =0), because
642       only for that value the force vanishes at the
643       cut-off. :mdp:`rlist` should be 0.1 to 0.3 nm larger than
644       :mdp:`rcoulomb` to accommodate the size of charge groups
645       and diffusion between neighbor list updates. This, and the fact
646       that table lookups are used instead of analytical functions make
647       reaction-field-zero computationally more expensive than
648       normal reaction-field.
649
650    .. mdp-value:: Shift
651
652       Analogous to :mdp-value:`vdwtype=Shift` for :mdp:`vdwtype`. You
653       might want to use :mdp-value:`coulombtype=Reaction-Field-zero` instead, which has
654       a similar potential shape, but has a physical interpretation and
655       has better energies due to the exclusion correction terms.
656
657    .. mdp-value:: Encad-Shift
658
659       The Coulomb potential is decreased over the whole range, using
660       the definition from the Encad simulation package.
661
662    .. mdp-value:: Switch
663
664       Analogous to :mdp-value:`vdwtype=Switch` for
665       :mdp:`vdwtype`. Switching the Coulomb potential can lead to
666       serious artifacts, advice: use :mdp-value:`coulombtype=Reaction-Field-zero`
667       instead.
668
669    .. mdp-value:: User
670
671       :ref:`gmx mdrun` will now expect to find a file ``table.xvg``
672       with user-defined potential functions for repulsion, dispersion
673       and Coulomb. When pair interactions are present, :ref:`gmx
674       mdrun` also expects to find a file ``tablep.xvg`` for the pair
675       interactions. When the same interactions should be used for
676       non-bonded and pair interactions the user can specify the same
677       file name for both table files. These files should contain 7
678       columns: the ``x`` value, ``f(x)``, ``-f'(x)``, ``g(x)``,
679       ``-g'(x)``, ``h(x)``, ``-h'(x)``, where ``f(x)`` is the Coulomb
680       function, ``g(x)`` the dispersion function and ``h(x)`` the
681       repulsion function. When :mdp:`vdwtype` is not set to User the
682       values for ``g``, ``-g'``, ``h`` and ``-h'`` are ignored. For
683       the non-bonded interactions ``x`` values should run from 0 to
684       the largest cut-off distance + :mdp:`table-extension` and
685       should be uniformly spaced. For the pair interactions the table
686       length in the file will be used. The optimal spacing, which is
687       used for non-user tables, is ``0.002 nm`` when you run in mixed
688       precision or ``0.0005 nm`` when you run in double precision. The
689       function value at ``x=0`` is not important. More information is
690       in the printed manual.
691
692    .. mdp-value:: PME-Switch
693
694       A combination of PME and a switch function for the direct-space
695       part (see above). :mdp:`rcoulomb` is allowed to be smaller than
696       :mdp:`rlist`. This is mainly useful constant energy simulations
697       (note that using PME with :mdp-value:`cutoff-scheme=Verlet`
698       will be more efficient).
699
700    .. mdp-value:: PME-User
701
702       A combination of PME and user tables (see
703       above). :mdp:`rcoulomb` is allowed to be smaller than
704       :mdp:`rlist`. The PME mesh contribution is subtracted from the
705       user table by :ref:`gmx mdrun`. Because of this subtraction the
706       user tables should contain about 10 decimal places.
707
708    .. mdp-value:: PME-User-Switch
709
710       A combination of PME-User and a switching function (see
711       above). The switching function is applied to final
712       particle-particle interaction, *i.e.* both to the user supplied
713       function and the PME Mesh correction part.
714
715 .. mdp:: coulomb-modifier
716
717    .. mdp-value:: Potential-shift-Verlet
718
719       Selects Potential-shift with the Verlet cutoff-scheme, as it is
720       (nearly) free; selects None with the group cutoff-scheme.
721
722    .. mdp-value:: Potential-shift
723
724       Shift the Coulomb potential by a constant such that it is zero
725       at the cut-off. This makes the potential the integral of the
726       force. Note that this does not affect the forces or the
727       sampling.
728
729    .. mdp-value:: None
730
731       Use an unmodified Coulomb potential. With the group scheme this
732       means no exact cut-off is used, energies and forces are
733       calculated for all pairs in the pair list.
734
735 .. mdp:: rcoulomb-switch
736
737    (0) [nm]
738    where to start switching the Coulomb potential, only relevant
739    when force or potential switching is used
740
741 .. mdp:: rcoulomb
742
743    (1) [nm]
744    The distance for the Coulomb cut-off. Note that with PME this value
745    can be increased by the PME tuning in :ref:`gmx mdrun` along with
746    the PME grid spacing.
747
748 .. mdp:: epsilon-r
749
750    (1)
751    The relative dielectric constant. A value of 0 means infinity.
752
753 .. mdp:: epsilon-rf
754
755    (0)
756    The relative dielectric constant of the reaction field. This
757    is only used with reaction-field electrostatics. A value of 0
758    means infinity.
759
760
761 Van der Waals
762 ^^^^^^^^^^^^^
763
764 .. mdp:: vdwtype
765
766    .. mdp-value:: Cut-off
767
768       Plain cut-off with pair list radius :mdp:`rlist` and VdW
769       cut-off :mdp:`rvdw`, where :mdp:`rlist` >= :mdp:`rvdw`.
770
771    .. mdp-value:: PME
772
773       Fast smooth Particle-mesh Ewald (SPME) for VdW interactions. The
774       grid dimensions are controlled with :mdp:`fourierspacing` in
775       the same way as for electrostatics, and the interpolation order
776       is controlled with :mdp:`pme-order`. The relative accuracy of
777       direct/reciprocal space is controlled by :mdp:`ewald-rtol-lj`,
778       and the specific combination rules that are to be used by the
779       reciprocal routine are set using :mdp:`lj-pme-comb-rule`.
780
781    .. mdp-value:: Shift
782
783       This functionality is deprecated and replaced by using
784       :mdp-value:`vdwtype=Cut-off` with :mdp-value:`vdw-modifier=Force-switch`.
785       The LJ (not Buckingham) potential is decreased over the whole range and
786       the forces decay smoothly to zero between :mdp:`rvdw-switch` and
787       :mdp:`rvdw`. The neighbor search cut-off :mdp:`rlist` should
788       be 0.1 to 0.3 nm larger than :mdp:`rvdw` to accommodate the
789       size of charge groups and diffusion between neighbor list
790       updates.
791
792    .. mdp-value:: Switch
793
794       This functionality is deprecated and replaced by using
795       :mdp-value:`vdwtype=Cut-off` with :mdp-value:`vdw-modifier=Potential-switch`.
796       The LJ (not Buckingham) potential is normal out to :mdp:`rvdw-switch`, after
797       which it is switched off to reach zero at :mdp:`rvdw`. Both the
798       potential and force functions are continuously smooth, but be
799       aware that all switch functions will give rise to a bulge
800       (increase) in the force (since we are switching the
801       potential). The neighbor search cut-off :mdp:`rlist` should be
802       0.1 to 0.3 nm larger than :mdp:`rvdw` to accommodate the
803       size of charge groups and diffusion between neighbor list
804       updates.
805
806    .. mdp-value:: Encad-Shift
807
808       The LJ (not Buckingham) potential is decreased over the whole
809       range, using the definition from the Encad simulation package.
810
811    .. mdp-value:: User
812
813       See user for :mdp:`coulombtype`. The function value at zero is
814       not important. When you want to use LJ correction, make sure
815       that :mdp:`rvdw` corresponds to the cut-off in the user-defined
816       function. When :mdp:`coulombtype` is not set to User the values
817       for the ``f`` and ``-f'`` columns are ignored.
818
819 .. mdp:: vdw-modifier
820
821    .. mdp-value:: Potential-shift-Verlet
822
823       Selects Potential-shift with the Verlet cutoff-scheme, as it is
824       (nearly) free; selects None with the group cutoff-scheme.
825
826    .. mdp-value:: Potential-shift
827
828       Shift the Van der Waals potential by a constant such that it is
829       zero at the cut-off. This makes the potential the integral of
830       the force. Note that this does not affect the forces or the
831       sampling.
832
833    .. mdp-value:: None
834
835       Use an unmodified Van der Waals potential. With the group scheme
836       this means no exact cut-off is used, energies and forces are
837       calculated for all pairs in the pair list.
838
839    .. mdp-value:: Force-switch
840
841       Smoothly switches the forces to zero between :mdp:`rvdw-switch`
842       and :mdp:`rvdw`. This shifts the potential shift over the whole
843       range and switches it to zero at the cut-off. Note that this is
844       more expensive to calculate than a plain cut-off and it is not
845       required for energy conservation, since Potential-shift
846       conserves energy just as well.
847
848    .. mdp-value:: Potential-switch
849
850       Smoothly switches the potential to zero between
851       :mdp:`rvdw-switch` and :mdp:`rvdw`. Note that this introduces
852       articifically large forces in the switching region and is much
853       more expensive to calculate. This option should only be used if
854       the force field you are using requires this.
855
856 .. mdp:: rvdw-switch
857
858    (0) [nm]
859    where to start switching the LJ force and possibly the potential,
860    only relevant when force or potential switching is used
861
862 .. mdp:: rvdw
863
864    (1) [nm]
865    distance for the LJ or Buckingham cut-off
866
867 .. mdp:: DispCorr
868
869    .. mdp-value:: no
870
871       don't apply any correction
872
873    .. mdp-value:: EnerPres
874
875       apply long range dispersion corrections for Energy and Pressure
876
877    .. mdp-value:: Ener
878
879       apply long range dispersion corrections for Energy only
880
881
882 Tables
883 ^^^^^^
884
885 .. mdp:: table-extension
886
887    (1) [nm]
888    Extension of the non-bonded potential lookup tables beyond the
889    largest cut-off distance. The value should be large enough to
890    account for charge group sizes and the diffusion between
891    neighbor-list updates. Without user defined potential the same
892    table length is used for the lookup tables for the 1-4
893    interactions, which are always tabulated irrespective of the use of
894    tables for the non-bonded interactions. The value of
895    :mdp:`table-extension` in no way affects the values of
896    :mdp:`rlist`, :mdp:`rcoulomb`, or :mdp:`rvdw`.
897
898 .. mdp:: energygrp-table
899
900    When user tables are used for electrostatics and/or VdW, here one
901    can give pairs of energy groups for which seperate user tables
902    should be used. The two energy groups will be appended to the table
903    file name, in order of their definition in :mdp:`energygrps`,
904    seperated by underscores. For example, if ``energygrps = Na Cl
905    Sol`` and ``energygrp-table = Na Na Na Cl``, :ref:`gmx mdrun` will
906    read ``table_Na_Na.xvg`` and ``table_Na_Cl.xvg`` in addition to the
907    normal ``table.xvg`` which will be used for all other energy group
908    pairs.
909
910
911 Ewald
912 ^^^^^
913
914 .. mdp:: fourierspacing
915
916    (0.12) [nm]
917    For ordinary Ewald, the ratio of the box dimensions and the spacing
918    determines a lower bound for the number of wave vectors to use in
919    each (signed) direction. For PME and P3M, that ratio determines a
920    lower bound for the number of Fourier-space grid points that will
921    be used along that axis. In all cases, the number for each
922    direction can be overridden by entering a non-zero value for that
923    :mdp:`fourier-nx` direction. For optimizing the relative load of
924    the particle-particle interactions and the mesh part of PME, it is
925    useful to know that the accuracy of the electrostatics remains
926    nearly constant when the Coulomb cut-off and the PME grid spacing
927    are scaled by the same factor. Note that this spacing can be scaled
928    up along with :mdp:`rcoulomb` by the PME tuning in :ref:`gmx mdrun`.
929
930 .. mdp:: fourier-nx
931 .. mdp:: fourier-ny
932 .. mdp:: fourier-nz
933
934    (0)
935    Highest magnitude of wave vectors in reciprocal space when using Ewald.
936    Grid size when using PME or P3M. These values override
937    :mdp:`fourierspacing` per direction. The best choice is powers of
938    2, 3, 5 and 7. Avoid large primes. Note that these grid sizes can
939    be reduced along with scaling up :mdp:`rcoulomb` by the PME tuning
940    in :ref:`gmx mdrun`.
941
942 .. mdp:: pme-order
943
944    (4)
945    Interpolation order for PME. 4 equals cubic interpolation. You
946    might try 6/8/10 when running in parallel and simultaneously
947    decrease grid dimension.
948
949 .. mdp:: ewald-rtol
950
951    (10\ :sup:`-5`)
952    The relative strength of the Ewald-shifted direct potential at
953    :mdp:`rcoulomb` is given by :mdp:`ewald-rtol`. Decreasing this
954    will give a more accurate direct sum, but then you need more wave
955    vectors for the reciprocal sum.
956
957 .. mdp:: ewald-rtol-lj
958
959    (10\ :sup:`-3`)
960    When doing PME for VdW-interactions, :mdp:`ewald-rtol-lj` is used
961    to control the relative strength of the dispersion potential at
962    :mdp:`rvdw` in the same way as :mdp:`ewald-rtol` controls the
963    electrostatic potential.
964
965 .. mdp:: lj-pme-comb-rule
966
967    (Geometric)
968    The combination rules used to combine VdW-parameters in the
969    reciprocal part of LJ-PME. Geometric rules are much faster than
970    Lorentz-Berthelot and usually the recommended choice, even when the
971    rest of the force field uses the Lorentz-Berthelot rules.
972
973    .. mdp-value:: Geometric
974
975       Apply geometric combination rules
976
977    .. mdp-value:: Lorentz-Berthelot
978
979       Apply Lorentz-Berthelot combination rules
980
981 .. mdp:: ewald-geometry
982
983    .. mdp-value:: 3d
984
985       The Ewald sum is performed in all three dimensions.
986
987    .. mdp-value:: 3dc
988
989       The reciprocal sum is still performed in 3D, but a force and
990       potential correction applied in the `z` dimension to produce a
991       pseudo-2D summation. If your system has a slab geometry in the
992       `x-y` plane you can try to increase the `z`-dimension of the box
993       (a box height of 3 times the slab height is usually ok) and use
994       this option.
995
996 .. mdp:: epsilon-surface
997
998    (0)
999    This controls the dipole correction to the Ewald summation in
1000    3D. The default value of zero means it is turned off. Turn it on by
1001    setting it to the value of the relative permittivity of the
1002    imaginary surface around your infinite system. Be careful - you
1003    shouldn't use this if you have free mobile charges in your
1004    system. This value does not affect the slab 3DC variant of the long
1005    range corrections.
1006
1007
1008 Temperature coupling
1009 ^^^^^^^^^^^^^^^^^^^^
1010
1011 .. mdp:: tcoupl
1012
1013    .. mdp-value:: no
1014
1015       No temperature coupling.
1016
1017    .. mdp-value:: berendsen
1018
1019       Temperature coupling with a Berendsen thermostat to a bath with
1020       temperature :mdp:`ref-t`, with time constant
1021       :mdp:`tau-t`. Several groups can be coupled separately, these
1022       are specified in the :mdp:`tc-grps` field separated by spaces.
1023
1024    .. mdp-value:: nose-hoover
1025
1026       Temperature coupling using a Nose-Hoover extended ensemble. The
1027       reference temperature and coupling groups are selected as above,
1028       but in this case :mdp:`tau-t` controls the period of the
1029       temperature fluctuations at equilibrium, which is slightly
1030       different from a relaxation time. For NVT simulations the
1031       conserved energy quantity is written to the energy and log files.
1032
1033    .. mdp-value:: andersen
1034
1035       Temperature coupling by randomizing a fraction of the particle velocities
1036       at each timestep. Reference temperature and coupling groups are
1037       selected as above. :mdp:`tau-t` is the average time between
1038       randomization of each molecule. Inhibits particle dynamics
1039       somewhat, but little or no ergodicity issues. Currently only
1040       implemented with velocity Verlet, and not implemented with
1041       constraints.
1042
1043    .. mdp-value:: andersen-massive
1044
1045       Temperature coupling by randomizing velocities of all particles at
1046       infrequent timesteps. Reference temperature and coupling groups are
1047       selected as above. :mdp:`tau-t` is the time between
1048       randomization of all molecules. Inhibits particle dynamics
1049       somewhat, but little or no ergodicity issues. Currently only
1050       implemented with velocity Verlet.
1051
1052    .. mdp-value:: v-rescale
1053
1054       Temperature coupling using velocity rescaling with a stochastic
1055       term (JCP 126, 014101). This thermostat is similar to Berendsen
1056       coupling, with the same scaling using :mdp:`tau-t`, but the
1057       stochastic term ensures that a proper canonical ensemble is
1058       generated. The random seed is set with :mdp:`ld-seed`. This
1059       thermostat works correctly even for :mdp:`tau-t` =0. For NVT
1060       simulations the conserved energy quantity is written to the
1061       energy and log file.
1062
1063 .. mdp:: nsttcouple
1064
1065    (-1)
1066    The frequency for coupling the temperature. The default value of -1
1067    sets :mdp:`nsttcouple` equal to :mdp:`nstlist`, unless
1068    :mdp:`nstlist` <=0, then a value of 10 is used. For velocity
1069    Verlet integrators :mdp:`nsttcouple` is set to 1.
1070
1071 .. mdp:: nh-chain-length
1072
1073    (10)
1074    The number of chained Nose-Hoover thermostats for velocity Verlet
1075    integrators, the leap-frog :mdp-value:`integrator=md` integrator
1076    only supports 1. Data for the NH chain variables is not printed
1077    to the :ref:`edr` file by default, but can be turned on with the
1078    :mdp:`print-nose-hoover-chains` option.
1079
1080 .. mdp:: print-nose-hoover-chain-variables
1081
1082    .. mdp-value:: no
1083
1084       Do not store Nose-Hoover chain variables in the energy file.
1085
1086    .. mdp-value:: yes
1087
1088       Store all positions and velocities of the Nose-Hoover chain
1089       in the energy file.
1090
1091 .. mdp:: tc-grps
1092
1093    groups to couple to separate temperature baths
1094
1095 .. mdp:: tau-t
1096
1097    [ps]
1098    time constant for coupling (one for each group in
1099    :mdp:`tc-grps`), -1 means no temperature coupling
1100
1101 .. mdp:: ref-t
1102
1103    [K]
1104    reference temperature for coupling (one for each group in
1105    :mdp:`tc-grps`)
1106
1107
1108 Pressure coupling
1109 ^^^^^^^^^^^^^^^^^
1110
1111 .. mdp:: pcoupl
1112
1113    .. mdp-value:: no
1114
1115       No pressure coupling. This means a fixed box size.
1116
1117    .. mdp-value:: Berendsen
1118
1119       Exponential relaxation pressure coupling with time constant
1120       :mdp:`tau-p`. The box is scaled every :mdp:`nstpcouple` steps. It has been
1121       argued that this does not yield a correct thermodynamic
1122       ensemble, but it is the most efficient way to scale a box at the
1123       beginning of a run.
1124
1125    .. mdp-value:: Parrinello-Rahman
1126
1127       Extended-ensemble pressure coupling where the box vectors are
1128       subject to an equation of motion. The equation of motion for the
1129       atoms is coupled to this. No instantaneous scaling takes
1130       place. As for Nose-Hoover temperature coupling the time constant
1131       :mdp:`tau-p` is the period of pressure fluctuations at
1132       equilibrium. This is probably a better method when you want to
1133       apply pressure scaling during data collection, but beware that
1134       you can get very large oscillations if you are starting from a
1135       different pressure. For simulations where the exact fluctations
1136       of the NPT ensemble are important, or if the pressure coupling
1137       time is very short it may not be appropriate, as the previous
1138       time step pressure is used in some steps of the |Gromacs|
1139       implementation for the current time step pressure.
1140
1141    .. mdp-value:: MTTK
1142
1143       Martyna-Tuckerman-Tobias-Klein implementation, only useable with
1144       :mdp-value:`integrator=md-vv` or :mdp-value:`integrator=md-vv-avek`, very similar to
1145       Parrinello-Rahman. As for Nose-Hoover temperature coupling the
1146       time constant :mdp:`tau-p` is the period of pressure
1147       fluctuations at equilibrium. This is probably a better method
1148       when you want to apply pressure scaling during data collection,
1149       but beware that you can get very large oscillations if you are
1150       starting from a different pressure. Currently (as of version
1151       5.1), it only supports isotropic scaling, and only works without
1152       constraints.
1153
1154 .. mdp:: pcoupltype
1155
1156    Specifies the kind of isotropy of the pressure coupling used. Each
1157    kind takes one or more values for :mdp:`compressibility` and
1158    :mdp:`ref-p`. Only a single value is permitted for :mdp:`tau-p`.
1159
1160    .. mdp-value:: isotropic
1161
1162       Isotropic pressure coupling with time constant
1163       :mdp:`tau-p`. One value each for :mdp:`compressibility` and
1164       :mdp:`ref-p` is required.
1165
1166    .. mdp-value:: semiisotropic
1167
1168       Pressure coupling which is isotropic in the ``x`` and ``y``
1169       direction, but different in the ``z`` direction. This can be
1170       useful for membrane simulations. Two values each for
1171       :mdp:`compressibility` and :mdp:`ref-p` are required, for
1172       ``x/y`` and ``z`` directions respectively.
1173
1174    .. mdp-value:: anisotropic
1175
1176       Same as before, but 6 values are needed for ``xx``, ``yy``, ``zz``,
1177       ``xy/yx``, ``xz/zx`` and ``yz/zy`` components,
1178       respectively. When the off-diagonal compressibilities are set to
1179       zero, a rectangular box will stay rectangular. Beware that
1180       anisotropic scaling can lead to extreme deformation of the
1181       simulation box.
1182
1183    .. mdp-value:: surface-tension
1184
1185       Surface tension coupling for surfaces parallel to the
1186       xy-plane. Uses normal pressure coupling for the `z`-direction,
1187       while the surface tension is coupled to the `x/y` dimensions of
1188       the box. The first :mdp:`ref-p` value is the reference surface
1189       tension times the number of surfaces ``bar nm``, the second
1190       value is the reference `z`-pressure ``bar``. The two
1191       :mdp:`compressibility` values are the compressibility in the
1192       `x/y` and `z` direction respectively. The value for the
1193       `z`-compressibility should be reasonably accurate since it
1194       influences the convergence of the surface-tension, it can also
1195       be set to zero to have a box with constant height.
1196
1197 .. mdp:: nstpcouple
1198
1199    (-1)
1200    The frequency for coupling the pressure. The default value of -1
1201    sets :mdp:`nstpcouple` equal to :mdp:`nstlist`, unless
1202    :mdp:`nstlist` <=0, then a value of 10 is used. For velocity
1203    Verlet integrators :mdp:`nstpcouple` is set to 1.
1204
1205 .. mdp:: tau-p
1206
1207    (1) [ps]
1208    The time constant for pressure coupling (one value for all
1209    directions).
1210
1211 .. mdp:: compressibility
1212
1213    [bar\ :sup:`-1`]
1214    The compressibility (NOTE: this is now really in bar\ :sup:`-1`) For water at 1
1215    atm and 300 K the compressibility is 4.5e-5 bar\ :sup:`-1`. The number of
1216    required values is implied by :mdp:`pcoupltype`.
1217
1218 .. mdp:: ref-p
1219
1220    [bar]
1221    The reference pressure for coupling. The number of required values
1222    is implied by :mdp:`pcoupltype`.
1223
1224 .. mdp:: refcoord-scaling
1225
1226    .. mdp-value:: no
1227
1228       The reference coordinates for position restraints are not
1229       modified. Note that with this option the virial and pressure
1230       will depend on the absolute positions of the reference
1231       coordinates.
1232
1233    .. mdp-value:: all
1234
1235       The reference coordinates are scaled with the scaling matrix of
1236       the pressure coupling.
1237
1238    .. mdp-value:: com
1239
1240       Scale the center of mass of the reference coordinates with the
1241       scaling matrix of the pressure coupling. The vectors of each
1242       reference coordinate to the center of mass are not scaled. Only
1243       one COM is used, even when there are multiple molecules with
1244       position restraints. For calculating the COM of the reference
1245       coordinates in the starting configuration, periodic boundary
1246       conditions are not taken into account.
1247
1248
1249 Simulated annealing
1250 ^^^^^^^^^^^^^^^^^^^
1251
1252 Simulated annealing is controlled separately for each temperature
1253 group in |Gromacs|. The reference temperature is a piecewise linear
1254 function, but you can use an arbitrary number of points for each
1255 group, and choose either a single sequence or a periodic behaviour for
1256 each group. The actual annealing is performed by dynamically changing
1257 the reference temperature used in the thermostat algorithm selected,
1258 so remember that the system will usually not instantaneously reach the
1259 reference temperature!
1260
1261 .. mdp:: annealing
1262
1263    Type of annealing for each temperature group
1264
1265    .. mdp-value:: no
1266
1267        No simulated annealing - just couple to reference temperature value.
1268
1269    .. mdp-value:: single
1270
1271        A single sequence of annealing points. If your simulation is
1272        longer than the time of the last point, the temperature will be
1273        coupled to this constant value after the annealing sequence has
1274        reached the last time point.
1275
1276    .. mdp-value:: periodic
1277
1278        The annealing will start over at the first reference point once
1279        the last reference time is reached. This is repeated until the
1280        simulation ends.
1281
1282 .. mdp:: annealing-npoints
1283
1284    A list with the number of annealing reference/control points used
1285    for each temperature group. Use 0 for groups that are not
1286    annealed. The number of entries should equal the number of
1287    temperature groups.
1288
1289 .. mdp:: annealing-time
1290
1291    List of times at the annealing reference/control points for each
1292    group. If you are using periodic annealing, the times will be used
1293    modulo the last value, *i.e.* if the values are 0, 5, 10, and 15,
1294    the coupling will restart at the 0ps value after 15ps, 30ps, 45ps,
1295    etc. The number of entries should equal the sum of the numbers
1296    given in :mdp:`annealing-npoints`.
1297
1298 .. mdp:: annealing-temp
1299
1300    List of temperatures at the annealing reference/control points for
1301    each group. The number of entries should equal the sum of the
1302    numbers given in :mdp:`annealing-npoints`.
1303
1304 Confused? OK, let's use an example. Assume you have two temperature
1305 groups, set the group selections to ``annealing = single periodic``,
1306 the number of points of each group to ``annealing-npoints = 3 4``, the
1307 times to ``annealing-time = 0 3 6 0 2 4 6`` and finally temperatures
1308 to ``annealing-temp = 298 280 270 298 320 320 298``. The first group
1309 will be coupled to 298K at 0ps, but the reference temperature will
1310 drop linearly to reach 280K at 3ps, and then linearly between 280K and
1311 270K from 3ps to 6ps. After this is stays constant, at 270K. The
1312 second group is coupled to 298K at 0ps, it increases linearly to 320K
1313 at 2ps, where it stays constant until 4ps. Between 4ps and 6ps it
1314 decreases to 298K, and then it starts over with the same pattern
1315 again, *i.e.* rising linearly from 298K to 320K between 6ps and
1316 8ps. Check the summary printed by :ref:`gmx grompp` if you are unsure!
1317
1318
1319 Velocity generation
1320 ^^^^^^^^^^^^^^^^^^^
1321
1322 .. mdp:: gen-vel
1323
1324    .. mdp-value:: no
1325
1326         Do not generate velocities. The velocities are set to zero
1327         when there are no velocities in the input structure file.
1328
1329    .. mdp-value:: yes
1330
1331         Generate velocities in :ref:`gmx grompp` according to a
1332         Maxwell distribution at temperature :mdp:`gen-temp`, with
1333         random seed :mdp:`gen-seed`. This is only meaningful with
1334         :mdp-value:`integrator=md`.
1335
1336 .. mdp:: gen-temp
1337
1338    (300) [K]
1339    temperature for Maxwell distribution
1340
1341 .. mdp:: gen-seed
1342
1343    (-1) [integer]
1344    used to initialize random generator for random velocities,
1345    when :mdp:`gen-seed` is set to -1, a pseudo random seed is
1346    used.
1347
1348
1349 Bonds
1350 ^^^^^
1351
1352 .. mdp:: constraints
1353
1354    Controls which bonds in the topology will be converted to rigid
1355    holonomic constraints. Note that typical rigid water models do not
1356    have bonds, but rather a specialized ``[settles]`` directive, so
1357    are not affected by this keyword.
1358
1359    .. mdp-value:: none
1360
1361       No bonds converted to constraints.
1362
1363    .. mdp-value:: h-bonds
1364
1365       Convert the bonds with H-atoms to constraints.
1366
1367    .. mdp-value:: all-bonds
1368
1369       Convert all bonds to constraints.
1370
1371    .. mdp-value:: h-angles
1372
1373       Convert all bonds to constraints and convert the angles that
1374       involve H-atoms to bond-constraints.
1375
1376    .. mdp-value:: all-angles
1377
1378       Convert all bonds to constraints and all angles to bond-constraints.
1379
1380 .. mdp:: constraint-algorithm
1381
1382    Chooses which solver satisfies any non-SETTLE holonomic
1383    constraints.
1384
1385    .. mdp-value:: LINCS
1386
1387       LINear Constraint Solver. With domain decomposition the parallel
1388       version P-LINCS is used. The accuracy in set with
1389       :mdp:`lincs-order`, which sets the number of matrices in the
1390       expansion for the matrix inversion. After the matrix inversion
1391       correction the algorithm does an iterative correction to
1392       compensate for lengthening due to rotation. The number of such
1393       iterations can be controlled with :mdp:`lincs-iter`. The root
1394       mean square relative constraint deviation is printed to the log
1395       file every :mdp:`nstlog` steps. If a bond rotates more than
1396       :mdp:`lincs-warnangle` in one step, a warning will be printed
1397       both to the log file and to ``stderr``. LINCS should not be used
1398       with coupled angle constraints.
1399
1400    .. mdp-value:: SHAKE
1401
1402       SHAKE is slightly slower and less stable than LINCS, but does
1403       work with angle constraints. The relative tolerance is set with
1404       :mdp:`shake-tol`, 0.0001 is a good value for "normal" MD. SHAKE
1405       does not support constraints between atoms on different nodes,
1406       thus it can not be used with domain decompositon when inter
1407       charge-group constraints are present. SHAKE can not be used with
1408       energy minimization.
1409
1410 .. mdp:: continuation
1411
1412    This option was formerly known as ``unconstrained-start``.
1413
1414    .. mdp-value:: no
1415
1416       apply constraints to the start configuration and reset shells
1417
1418    .. mdp-value:: yes
1419
1420       do not apply constraints to the start configuration and do not
1421       reset shells, useful for exact coninuation and reruns
1422
1423 .. mdp:: shake-tol
1424
1425    (0.0001)
1426    relative tolerance for SHAKE
1427
1428 .. mdp:: lincs-order
1429
1430    (4)
1431    Highest order in the expansion of the constraint coupling
1432    matrix. When constraints form triangles, an additional expansion of
1433    the same order is applied on top of the normal expansion only for
1434    the couplings within such triangles. For "normal" MD simulations an
1435    order of 4 usually suffices, 6 is needed for large time-steps with
1436    virtual sites or BD. For accurate energy minimization an order of 8
1437    or more might be required. With domain decomposition, the cell size
1438    is limited by the distance spanned by :mdp:`lincs-order` +1
1439    constraints. When one wants to scale further than this limit, one
1440    can decrease :mdp:`lincs-order` and increase :mdp:`lincs-iter`,
1441    since the accuracy does not deteriorate when (1+ :mdp:`lincs-iter`
1442    )* :mdp:`lincs-order` remains constant.
1443
1444 .. mdp:: lincs-iter
1445
1446    (1)
1447    Number of iterations to correct for rotational lengthening in
1448    LINCS. For normal runs a single step is sufficient, but for NVE
1449    runs where you want to conserve energy accurately or for accurate
1450    energy minimization you might want to increase it to 2.
1451
1452 .. mdp:: lincs-warnangle
1453
1454    (30) [deg]
1455    maximum angle that a bond can rotate before LINCS will complain
1456
1457 .. mdp:: morse
1458
1459    .. mdp-value:: no
1460
1461       bonds are represented by a harmonic potential
1462
1463    .. mdp-value:: yes
1464
1465       bonds are represented by a Morse potential
1466
1467
1468 Energy group exclusions
1469 ^^^^^^^^^^^^^^^^^^^^^^^
1470
1471 .. mdp:: energygrp-excl
1472
1473    Pairs of energy groups for which all non-bonded interactions are
1474    excluded. An example: if you have two energy groups ``Protein`` and
1475    ``SOL``, specifying ``energygrp-excl = Protein Protein SOL SOL``
1476    would give only the non-bonded interactions between the protein and
1477    the solvent. This is especially useful for speeding up energy
1478    calculations with ``mdrun -rerun`` and for excluding interactions
1479    within frozen groups.
1480
1481
1482 Walls
1483 ^^^^^
1484
1485 .. mdp:: nwall
1486
1487    (0)
1488    When set to 1 there is a wall at ``z=0``, when set to 2 there is
1489    also a wall at ``z=z-box``. Walls can only be used with :mdp:`pbc`
1490    ``=xy``. When set to 2, pressure coupling and Ewald summation can be
1491    used (it is usually best to use semiisotropic pressure coupling
1492    with the ``x/y`` compressibility set to 0, as otherwise the surface
1493    area will change). Walls interact wit the rest of the system
1494    through an optional :mdp:`wall-atomtype`. Energy groups ``wall0``
1495    and ``wall1`` (for :mdp:`nwall` =2) are added automatically to
1496    monitor the interaction of energy groups with each wall. The center
1497    of mass motion removal will be turned off in the ``z``-direction.
1498
1499 .. mdp:: wall-atomtype
1500
1501    the atom type name in the force field for each wall. By (for
1502    example) defining a special wall atom type in the topology with its
1503    own combination rules, this allows for independent tuning of the
1504    interaction of each atomtype with the walls.
1505
1506 .. mdp:: wall-type
1507
1508    .. mdp-value:: 9-3
1509
1510       LJ integrated over the volume behind the wall: 9-3 potential
1511
1512    .. mdp-value:: 10-4
1513
1514       LJ integrated over the wall surface: 10-4 potential
1515
1516    .. mdp-value:: 12-6
1517
1518       direct LJ potential with the ``z`` distance from the wall
1519
1520 .. mdp:: table
1521
1522    user defined potentials indexed with the ``z`` distance from the
1523    wall, the tables are read analogously to the
1524    :mdp:`energygrp-table` option, where the first name is for a
1525    "normal" energy group and the second name is ``wall0`` or
1526    ``wall1``, only the dispersion and repulsion columns are used
1527
1528 .. mdp:: wall-r-linpot
1529
1530    (-1) [nm]
1531    Below this distance from the wall the potential is continued
1532    linearly and thus the force is constant. Setting this option to a
1533    postive value is especially useful for equilibration when some
1534    atoms are beyond a wall. When the value is <=0 (<0 for
1535    :mdp:`wall-type` =table), a fatal error is generated when atoms
1536    are beyond a wall.
1537
1538 .. mdp:: wall-density
1539
1540    [nm\ :sup:`-3`] / [nm\ :sup:`-2`]
1541    the number density of the atoms for each wall for wall types 9-3
1542    and 10-4
1543
1544 .. mdp:: wall-ewald-zfac
1545
1546    (3)
1547    The scaling factor for the third box vector for Ewald summation
1548    only, the minimum is 2. Ewald summation can only be used with
1549    :mdp:`nwall` =2, where one should use :mdp:`ewald-geometry`
1550    ``=3dc``. The empty layer in the box serves to decrease the
1551    unphysical Coulomb interaction between periodic images.
1552
1553
1554 COM pulling
1555 ^^^^^^^^^^^
1556
1557 Note that where pulling coordinates are applicable, there can be more
1558 than one (set with :mdp:`pull-ncoords`) and multiple related :ref:`mdp`
1559 variables will exist accordingly. Documentation references to things
1560 like :mdp:`pull-coord1-vec` should be understood to apply to to the
1561 applicable pulling coordinate, eg. the second pull coordinate is described by
1562 pull-coord2-vec, pull-coord2-k, and so on.
1563
1564 .. mdp:: pull
1565
1566    .. mdp-value:: no
1567
1568       No center of mass pulling. All the following pull options will
1569       be ignored (and if present in the :ref:`mdp` file, they unfortunately
1570       generate warnings)
1571
1572    .. mdp-value:: yes
1573
1574        Center of mass pulling will be applied on 1 or more groups using
1575        1 or more pull coordinates.
1576
1577 .. mdp:: pull-cylinder-r
1578
1579    (1.5) [nm]
1580    the radius of the cylinder for :mdp-value:`pull-coord1-geometry=cylinder`
1581
1582 .. mdp:: pull-constr-tol
1583
1584    (10\ :sup:`-6`)
1585    the relative constraint tolerance for constraint pulling
1586
1587 .. mdp:: pull-print-com
1588
1589    .. mdp-value:: no
1590
1591       do not print the COM for any group
1592
1593    .. mdp-value:: yes
1594
1595       print the COM of all groups for all pull coordinates
1596
1597 .. mdp:: pull-print-ref-value
1598
1599    .. mdp-value:: no
1600
1601       do not print the reference value for each pull coordinate
1602
1603    .. mdp-value:: yes
1604
1605       print the reference value for each pull coordinate
1606
1607 .. mdp:: pull-print-components
1608
1609    .. mdp-value:: no
1610
1611       only print the distance for each pull coordinate
1612
1613    .. mdp-value:: yes
1614
1615       print the distance and Cartesian components selected in
1616       :mdp:`pull-coord1-dim`
1617
1618 .. mdp:: pull-nstxout
1619
1620    (50)
1621    frequency for writing out the COMs of all the pull group (0 is
1622    never)
1623
1624 .. mdp:: pull-nstfout
1625
1626    (50)
1627    frequency for writing out the force of all the pulled group
1628    (0 is never)
1629
1630 .. mdp:: pull-pbc-ref-prev-step-com
1631
1632    .. mdp-value:: no
1633
1634       Use the reference atom (:mdp:`pull-group1-pbcatom`) for the
1635       treatment of periodic boundary conditions.
1636
1637    .. mdp-value:: yes
1638
1639       Use the COM of the previous step as reference for the treatment
1640       of periodic boundary conditions. The reference is initialized
1641       using the reference atom (:mdp:`pull-group1-pbcatom`), which should
1642       be located centrally in the group. Using the COM from the
1643       previous step can be useful if one or more pull groups are large.
1644
1645 .. mdp:: pull-xout-average
1646
1647    .. mdp-value:: no
1648
1649       Write the instantaneous coordinates for all the pulled groups.
1650
1651    .. mdp-value:: yes
1652
1653       Write the average coordinates (since last output) for all the
1654       pulled groups. N.b., some analysis tools might expect instantaneous
1655       pull output.
1656
1657 .. mdp:: pull-fout-average
1658
1659    .. mdp-value:: no
1660
1661       Write the instantaneous force for all the pulled groups.
1662
1663    .. mdp-value:: yes
1664
1665       Write the average force (since last output) for all the
1666       pulled groups. N.b., some analysis tools might expect instantaneous
1667       pull output.
1668
1669 .. mdp:: pull-ngroups
1670
1671    (1)
1672    The number of pull groups, not including the absolute reference
1673    group, when used. Pull groups can be reused in multiple pull
1674    coordinates. Below only the pull options for group 1 are given,
1675    further groups simply increase the group index number.
1676
1677 .. mdp:: pull-ncoords
1678
1679    (1)
1680    The number of pull coordinates. Below only the pull options for
1681    coordinate 1 are given, further coordinates simply increase the
1682    coordinate index number.
1683
1684 .. mdp:: pull-group1-name
1685
1686    The name of the pull group, is looked up in the index file or in
1687    the default groups to obtain the atoms involved.
1688
1689 .. mdp:: pull-group1-weights
1690
1691    Optional relative weights which are multiplied with the masses of
1692    the atoms to give the total weight for the COM. The number should
1693    be 0, meaning all 1, or the number of atoms in the pull group.
1694
1695 .. mdp:: pull-group1-pbcatom
1696
1697    (0)
1698    The reference atom for the treatment of periodic boundary
1699    conditions inside the group (this has no effect on the treatment of
1700    the pbc between groups). This option is only important when the
1701    diameter of the pull group is larger than half the shortest box
1702    vector. For determining the COM, all atoms in the group are put at
1703    their periodic image which is closest to
1704    :mdp:`pull-group1-pbcatom`. A value of 0 means that the middle
1705    atom (number wise) is used, which is only safe for small groups.
1706    :ref:`gmx grompp` checks that the maximum distance from the reference
1707    atom (specifically chosen, or not) to the other atoms in the group
1708    is not too large. This parameter is not used with
1709    :mdp:`pull-coord1-geometry` cylinder. A value of -1 turns on cosine
1710    weighting, which is useful for a group of molecules in a periodic
1711    system, *e.g.* a water slab (see Engin et al. J. Chem. Phys. B
1712    2010).
1713
1714 .. mdp:: pull-coord1-type
1715
1716    .. mdp-value:: umbrella
1717
1718       Center of mass pulling using an umbrella potential between the
1719       reference group and one or more groups.
1720
1721    .. mdp-value:: constraint
1722
1723       Center of mass pulling using a constraint between the reference
1724       group and one or more groups. The setup is identical to the
1725       option umbrella, except for the fact that a rigid constraint is
1726       applied instead of a harmonic potential.
1727
1728    .. mdp-value:: constant-force
1729
1730       Center of mass pulling using a linear potential and therefore a
1731       constant force. For this option there is no reference position
1732       and therefore the parameters :mdp:`pull-coord1-init` and
1733       :mdp:`pull-coord1-rate` are not used.
1734
1735    .. mdp-value:: flat-bottom
1736
1737       At distances above :mdp:`pull-coord1-init` a harmonic potential
1738       is applied, otherwise no potential is applied.
1739
1740    .. mdp-value:: flat-bottom-high
1741
1742       At distances below :mdp:`pull-coord1-init` a harmonic potential
1743       is applied, otherwise no potential is applied.
1744
1745    .. mdp-value:: external-potential
1746
1747       An external potential that needs to be provided by another
1748       module.
1749
1750 .. mdp:: pull-coord1-potential-provider
1751
1752       The name of the external module that provides the potential for
1753       the case where :mdp:`pull-coord1-type` is external-potential.
1754
1755 .. mdp:: pull-coord1-geometry
1756
1757    .. mdp-value:: distance
1758
1759       Pull along the vector connecting the two groups. Components can
1760       be selected with :mdp:`pull-coord1-dim`.
1761
1762    .. mdp-value:: direction
1763
1764       Pull in the direction of :mdp:`pull-coord1-vec`.
1765
1766    .. mdp-value:: direction-periodic
1767
1768       As :mdp-value:`pull-coord1-geometry=direction`, but allows the distance to be larger
1769       than half the box size. With this geometry the box should not be
1770       dynamic (*e.g.* no pressure scaling) in the pull dimensions and
1771       the pull force is not added to virial.
1772
1773    .. mdp-value:: direction-relative
1774
1775       As :mdp-value:`pull-coord1-geometry=direction`, but the pull vector is the vector
1776       that points from the COM of a third to the COM of a fourth pull
1777       group. This means that 4 groups need to be supplied in
1778       :mdp:`pull-coord1-groups`. Note that the pull force will give
1779       rise to a torque on the pull vector, which is turn leads to
1780       forces perpendicular to the pull vector on the two groups
1781       defining the vector. If you want a pull group to move between
1782       the two groups defining the vector, simply use the union of
1783       these two groups as the reference group.
1784
1785    .. mdp-value:: cylinder
1786
1787       Designed for pulling with respect to a layer where the reference
1788       COM is given by a local cylindrical part of the reference group.
1789       The pulling is in the direction of :mdp:`pull-coord1-vec`. From
1790       the first of the two groups in :mdp:`pull-coord1-groups` a
1791       cylinder is selected around the axis going through the COM of
1792       the second group with direction :mdp:`pull-coord1-vec` with
1793       radius :mdp:`pull-cylinder-r`. Weights of the atoms decrease
1794       continously to zero as the radial distance goes from 0 to
1795       :mdp:`pull-cylinder-r` (mass weighting is also used). The radial
1796       dependence gives rise to radial forces on both pull groups.
1797       Note that the radius should be smaller than half the box size.
1798       For tilted cylinders they should be even smaller than half the
1799       box size since the distance of an atom in the reference group
1800       from the COM of the pull group has both a radial and an axial
1801       component. This geometry is not supported with constraint
1802       pulling.
1803
1804    .. mdp-value:: angle
1805
1806       Pull along an angle defined by four groups. The angle is
1807       defined as the angle between two vectors: the vector connecting
1808       the COM of the first group to the COM of the second group and
1809       the vector connecting the COM of the third group to the COM of
1810       the fourth group.
1811
1812    .. mdp-value:: angle-axis
1813
1814       As :mdp-value:`pull-coord1-geometry=angle` but the second vector is given by :mdp:`pull-coord1-vec`.
1815       Thus, only the two groups that define the first vector need to be given.
1816
1817    .. mdp-value:: dihedral
1818
1819       Pull along a dihedral angle defined by six groups. These pairwise
1820       define three vectors: the vector connecting the COM of group 1
1821       to the COM of group 2, the COM of group 3 to the COM of group 4,
1822       and the COM of group 5 to the COM group 6. The dihedral angle is
1823       then defined as the angle between two planes: the plane spanned by the
1824       the two first vectors and the plane spanned the two last vectors.
1825
1826
1827 .. mdp:: pull-coord1-groups
1828
1829    The group indices on which this pull coordinate will operate.
1830    The number of group indices required is geometry dependent.
1831    The first index can be 0, in which case an
1832    absolute reference of :mdp:`pull-coord1-origin` is used. With an
1833    absolute reference the system is no longer translation invariant
1834    and one should think about what to do with the center of mass
1835    motion.
1836
1837 .. mdp:: pull-coord1-dim
1838
1839    (Y Y Y)
1840    Selects the dimensions that this pull coordinate acts on and that
1841    are printed to the output files when
1842    :mdp:`pull-print-components` = :mdp-value:`pull-coord1-start=yes`. With
1843    :mdp:`pull-coord1-geometry` = :mdp-value:`pull-coord1-geometry=distance`, only Cartesian
1844    components set to Y contribute to the distance. Thus setting this
1845    to Y Y N results in a distance in the x/y plane. With other
1846    geometries all dimensions with non-zero entries in
1847    :mdp:`pull-coord1-vec` should be set to Y, the values for other
1848    dimensions only affect the output.
1849
1850 .. mdp:: pull-coord1-origin
1851
1852    (0.0 0.0 0.0)
1853    The pull reference position for use with an absolute reference.
1854
1855 .. mdp:: pull-coord1-vec
1856
1857    (0.0 0.0 0.0)
1858    The pull direction. :ref:`gmx grompp` normalizes the vector.
1859
1860 .. mdp:: pull-coord1-start
1861
1862    .. mdp-value:: no
1863
1864       do not modify :mdp:`pull-coord1-init`
1865
1866    .. mdp-value:: yes
1867
1868       add the COM distance of the starting conformation to
1869       :mdp:`pull-coord1-init`
1870
1871 .. mdp:: pull-coord1-init
1872
1873    (0.0) [nm] or [deg]
1874    The reference distance or reference angle at t=0.
1875
1876 .. mdp:: pull-coord1-rate
1877
1878    (0) [nm/ps] or [deg/ps]
1879    The rate of change of the reference position or reference angle.
1880
1881 .. mdp:: pull-coord1-k
1882
1883    (0) [kJ mol\ :sup:`-1` nm\ :sup:`-2`] or [kJ mol\ :sup:`-1` nm\ :sup:`-1`] or
1884    [kJ mol\ :sup:`-1` rad\ :sup:`-2`] or [kJ mol\ :sup:`-1` rad\ :sup:`-1`]
1885    The force constant. For umbrella pulling this is the harmonic force
1886    constant in kJ mol\ :sup:`-1` nm\ :sup:`-2` (or kJ mol\ :sup:`-1` rad\ :sup:`-2`
1887    for angles). For constant force pulling this is the
1888    force constant of the linear potential, and thus the negative (!)
1889    of the constant force in kJ mol\ :sup:`-1` nm\ :sup:`-1`
1890    (or kJ mol\ :sup:`-1` rad\ :sup:`-1` for angles).
1891    Note that for angles the force constant is expressed in terms of radians
1892    (while :mdp:`pull-coord1-init` and :mdp:`pull-coord1-rate` are expressed in degrees).
1893
1894 .. mdp:: pull-coord1-kB
1895
1896    (pull-k1) [kJ mol\ :sup:`-1` nm\ :sup:`-2`] or [kJ mol\ :sup:`-1` nm\ :sup:`-1`]
1897    or [kJ mol\ :sup:`-1` rad\ :sup:`-2`] or [kJ mol\ :sup:`-1` rad\ :sup:`-1`]
1898    As :mdp:`pull-coord1-k`, but for state B. This is only used when
1899    :mdp:`free-energy` is turned on. The force constant is then (1 -
1900    lambda) * :mdp:`pull-coord1-k` + lambda * :mdp:`pull-coord1-kB`.
1901
1902 AWH adaptive biasing
1903 ^^^^^^^^^^^^^^^^^^^^
1904
1905 .. mdp:: awh
1906
1907    .. mdp-value:: no
1908
1909       No biasing.
1910
1911    .. mdp-value:: yes
1912
1913       Adaptively bias a reaction coordinate using the AWH method and estimate
1914       the corresponding PMF. The PMF and other AWH data are written to energy
1915       file at an interval set by :mdp:`awh-nstout` and can be extracted with
1916       the ``gmx awh`` tool. The AWH coordinate can be
1917       multidimensional and is defined by mapping each dimension to a pull coordinate index.
1918       This is only allowed if :mdp-value:`pull-coord1-type=external-potential` and
1919       :mdp:`pull-coord1-potential-provider` = ``awh`` for the concerned pull coordinate
1920       indices.
1921
1922 .. mdp:: awh-potential
1923
1924    .. mdp-value:: convolved
1925
1926       The applied biasing potential is the convolution of the bias function and a
1927       set of harmonic umbrella potentials (see :mdp-value:`awh-potential=umbrella` below). This results
1928       in a smooth potential function and force. The resolution of the potential is set
1929       by the force constant of each umbrella, see :mdp:`awh1-dim1-force-constant`.
1930
1931    .. mdp-value:: umbrella
1932
1933       The potential bias is applied by controlling the position of an harmonic potential
1934       using Monte-Carlo sampling.  The force constant is set with
1935       :mdp:`awh1-dim1-force-constant`. The umbrella location
1936       is sampled using Monte-Carlo every :mdp:`awh-nstsample` steps.
1937       There are no advantages to using an umbrella.
1938       This option is mainly for comparison and testing purposes.
1939
1940 .. mdp:: awh-share-multisim
1941
1942    .. mdp-value:: no
1943
1944       AWH will not share biases across simulations started with
1945       :ref:`gmx mdrun` option ``-multidir``. The biases will be independent.
1946
1947    .. mdp-value:: yes
1948
1949       With :ref:`gmx mdrun` and option ``-multidir`` the bias and PMF estimates
1950       for biases with :mdp:`awh1-share-group` >0 will be shared across simulations
1951       with the biases with the same :mdp:`awh1-share-group` value.
1952       The simulations should have the same AWH settings for sharing to make sense.
1953       :ref:`gmx mdrun` will check whether the simulations are technically
1954       compatible for sharing, but the user should check that bias sharing
1955       physically makes sense.
1956
1957 .. mdp:: awh-seed
1958
1959    (-1) Random seed for Monte-Carlo sampling the umbrella position,
1960    where -1 indicates to generate a seed. Only used with
1961    :mdp-value:`awh-potential=umbrella`.
1962
1963 .. mdp:: awh-nstout
1964
1965    (100000)
1966    Number of steps between printing AWH data to the energy file, should be
1967    a multiple of :mdp:`nstenergy`.
1968
1969 .. mdp:: awh-nstsample
1970
1971    (10)
1972    Number of steps between sampling of the coordinate value. This sampling
1973    is the basis for updating the bias and estimating the PMF and other AWH observables.
1974
1975 .. mdp:: awh-nsamples-update
1976
1977    (10)
1978    The number of coordinate samples used for each AWH update.
1979    The update interval in steps is :mdp:`awh-nstsample` times this value.
1980
1981 .. mdp:: awh-nbias
1982
1983    (1)
1984    The number of biases, each acting on its own coordinate.
1985    The following options should be specified
1986    for each bias although below only the options for bias number 1 is shown. Options for
1987    other bias indices are  obtained by replacing '1' by the bias index.
1988
1989 .. mdp:: awh1-error-init
1990
1991    (10.0) [kJ mol\ :sup:`-1`]
1992    Estimated initial average error of the PMF for this bias. This value together with the
1993    given diffusion constant(s) :mdp:`awh1-dim1-diffusion` determine the initial biasing rate.
1994    The error is obviously not known *a priori*. Only a rough estimate of :mdp:`awh1-error-init`
1995    is needed however.
1996    As a  general guideline, leave :mdp:`awh1-error-init` to its default value when starting a new
1997    simulation. On the other hand, when there is *a priori* knowledge of the PMF (e.g. when
1998    an initial PMF estimate is provided, see the :mdp:`awh1-user-data` option)
1999    then :mdp:`awh1-error-init` should reflect that knowledge.
2000
2001 .. mdp:: awh1-growth
2002
2003    .. mdp-value:: exp-linear
2004
2005    Each bias keeps a reference weight histogram for the coordinate samples.
2006    Its size sets the magnitude of the bias function and free energy estimate updates
2007    (few samples corresponds to large updates and vice versa).
2008    Thus, its growth rate sets the maximum convergence rate.
2009    By default, there is an initial stage in which the histogram grows close to exponentially (but slower than the sampling rate).
2010    In the final stage that follows, the growth rate is linear and equal to the sampling rate (set by :mdp:`awh-nstsample`).
2011    The initial stage is typically necessary for efficient convergence when starting a new simulation where
2012    high free energy barriers have not yet been flattened by the bias.
2013
2014    .. mdp-value:: linear
2015
2016    As :mdp-value:`awh1-growth=exp-linear` but skip the initial stage. This may be useful if there is *a priori*
2017    knowledge (see :mdp:`awh1-error-init`) which eliminates the need for an initial stage. This is also
2018    the setting compatible with :mdp-value:`awh1-target=local-boltzmann`.
2019
2020 .. mdp:: awh1-equilibrate-histogram
2021
2022    .. mdp-value:: no
2023
2024       Do not equilibrate histogram.
2025
2026    .. mdp-value:: yes
2027
2028       Before entering the initial stage (see :mdp-value:`awh1-growth=exp-linear`), make sure the
2029       histogram of sampled weights is following the target distribution closely enough (specifically,
2030       at least 80% of the target region needs to have a local relative error of less than 20%). This
2031       option would typically only be used when :mdp:`awh1-share-group` > 0
2032       and the initial configurations poorly represent the target
2033       distribution.
2034
2035 .. mdp:: awh1-target
2036
2037    .. mdp-value:: constant
2038
2039       The bias is tuned towards a constant (uniform) coordinate distribution
2040       in the defined sampling interval (defined by  [:mdp:`awh1-dim1-start`, :mdp:`awh1-dim1-end`]).
2041
2042    .. mdp-value:: cutoff
2043
2044       Similar to :mdp-value:`awh1-target=constant`, but the target
2045       distribution is proportional to 1/(1 + exp(F - :mdp-value:`awh1-target=cutoff`)),
2046       where F is the free energy relative to the estimated global minimum.
2047       This provides a smooth switch of a flat target distribution in
2048       regions with free energy lower than the cut-off to a Boltzmann
2049       distribution in regions with free energy higher than the cut-off.
2050
2051    .. mdp-value:: boltzmann
2052
2053       The target distribution is a Boltzmann distribtution with a scaled beta (inverse temperature)
2054       factor given by :mdp:`awh1-target-beta-scaling`. *E.g.*, a value of 0.1
2055       would give the same coordinate distribution as sampling with a simulation temperature
2056       scaled by 10.
2057
2058    .. mdp-value:: local-boltzmann
2059
2060       Same target distribution and use of :mdp:`awh1-target-beta-scaling`
2061       but the convergence towards the target distribution is inherently local *i.e.*, the rate of
2062       change of the bias only depends on the local sampling. This local convergence property is
2063       only compatible with :mdp-value:`awh1-growth=linear`, since for
2064       :mdp-value:`awh1-growth=exp-linear` histograms are globally rescaled in the initial stage.
2065
2066 .. mdp:: awh1-target-beta-scaling
2067
2068    (0)
2069    For :mdp-value:`awh1-target=boltzmann` and :mdp-value:`awh1-target=local-boltzmann`
2070    it is the unitless beta scaling factor taking values in (0,1).
2071
2072 .. mdp:: awh1-target-cutoff
2073
2074    (0) [kJ mol\ :sup:`-1`]
2075    For :mdp-value:`awh1-target=cutoff` this is the cutoff, should be > 0.
2076
2077 .. mdp:: awh1-user-data
2078
2079    .. mdp-value:: no
2080
2081       Initialize the PMF and target distribution with default values.
2082
2083    .. mdp-value:: yes
2084
2085       Initialize the PMF and target distribution with user provided data. For :mdp:`awh-nbias` = 1,
2086       :ref:`gmx mdrun` will expect a file ``awhinit.xvg`` to be present in the run directory.
2087       For multiple biases, :ref:`gmx mdrun` expects files ``awhinit1.xvg``, ``awhinit2.xvg``, etc.
2088       The file name can be changed with the ``-awh`` option.
2089       The first :mdp:`awh1-ndim` columns of
2090       each input file should contain the coordinate values, such that each row defines a point in
2091       coordinate space. Column :mdp:`awh1-ndim` + 1 should contain the PMF value for each point.
2092       The target distribution column can either follow the PMF (column  :mdp:`awh1-ndim` + 2) or
2093       be in the same column as written by :ref:`gmx awh`.
2094
2095 .. mdp:: awh1-share-group
2096
2097    .. mdp-value:: 0
2098
2099       Do not share the bias.
2100
2101    .. mdp-value:: positive
2102
2103       Share the bias and PMF estimates within and/or between simulations.
2104       Within a simulation, the bias will be shared between biases that have the
2105       same :mdp:`awh1-share-group` index (note that the current code does not support this).
2106       With :mdp-value:`awh-share-multisim=yes` and
2107       :ref:`gmx mdrun` option ``-multidir`` the bias will also be shared across simulations.
2108       Sharing may increase convergence initially, although the starting configurations
2109       can be critical, especially when sharing between many biases.
2110       Currently, positive group values should start at 1 and increase
2111       by 1 for each subsequent bias that is shared.
2112
2113 .. mdp:: awh1-ndim
2114
2115    (1) [integer]
2116    Number of dimensions of the coordinate, each dimension maps to 1 pull coordinate.
2117    The following options should be specified for each such dimension. Below only
2118    the options for dimension number 1 is shown. Options for other dimension indices are
2119    obtained by replacing '1' by the dimension index.
2120
2121 .. mdp:: awh1-dim1-coord-provider
2122
2123    .. mdp-value:: pull
2124
2125       The module providing the reaction coordinate for this dimension.
2126       Currently AWH can only act on pull coordinates.
2127
2128 .. mdp:: awh1-dim1-coord-index
2129
2130    (1)
2131    Index of the pull coordinate defining this coordinate dimension.
2132
2133 .. mdp:: awh1-dim1-force-constant
2134
2135    (0) [kJ mol\ :sup:`-1` nm\ :sup:`-2`] or [kJ mol\ :sup:`-1` rad\ :sup:`-2`]
2136    Force constant for the (convolved) umbrella potential(s) along this
2137    coordinate dimension.
2138
2139 .. mdp:: awh1-dim1-start
2140
2141    (0.0) [nm] or [rad]
2142    Start value of the sampling interval along this dimension. The range of allowed
2143    values depends on the relevant pull geometry (see :mdp:`pull-coord1-geometry`).
2144    For periodic geometries :mdp:`awh1-dim1-start` greater than :mdp:`awh1-dim1-end`
2145    is allowed. The interval will then wrap around from +period/2 to -period/2.
2146
2147 .. mdp:: awh1-dim1-end
2148
2149    (0.0) [nm] or [rad]
2150    End value defining the sampling interval together with :mdp:`awh1-dim1-start`.
2151
2152 .. mdp:: awh1-dim1-period
2153
2154    (0.0) [nm] or [rad]
2155    The period of this reaction coordinate, use 0 when the coordinate is not periodic.
2156
2157 .. mdp:: awh1-dim1-diffusion
2158
2159    (10\ :sup:`-5`) [nm\ :sup:`2`/ps] or [rad\ :sup:`2`/ps]
2160    Estimated diffusion constant for this coordinate dimension determining the initial
2161    biasing rate. This needs only be a rough estimate and should not critically
2162    affect the results unless it is set to something very low, leading to slow convergence,
2163    or very high, forcing the system far from equilibrium. Not setting this value
2164    explicitly generates a warning.
2165
2166 .. mdp:: awh1-dim1-cover-diameter
2167
2168    (0.0) [nm] or [rad]
2169    Diameter that needs to be sampled by a single simulation around a coordinate value
2170    before the point is considered covered in the initial stage (see :mdp-value:`awh1-growth=exp-linear`).
2171    A value > 0  ensures that for each covering there is a continuous transition of this diameter
2172    across each coordinate value.
2173    This is trivially true for independent simulations but not for for multiple bias-sharing simulations
2174    (:mdp:`awh1-share-group`>0).
2175    For a diameter = 0, covering occurs as soon as the simulations have sampled the whole interval, which
2176    for many sharing simulations does not guarantee transitions across free energy barriers.
2177    On the other hand, when the diameter >= the sampling interval length, covering occurs when a single simulation
2178    has independently sampled the whole interval.
2179
2180 Enforced rotation
2181 ^^^^^^^^^^^^^^^^^
2182
2183 These :ref:`mdp` parameters can be used enforce the rotation of a group of atoms,
2184 e.g. a protein subunit. The `reference manual`_ describes in detail 13 different potentials
2185 that can be used to achieve such a rotation.
2186
2187 .. mdp:: rotation
2188
2189    .. mdp-value:: no
2190
2191       No enforced rotation will be applied. All enforced rotation options will
2192       be ignored (and if present in the :ref:`mdp` file, they unfortunately
2193       generate warnings).
2194
2195    .. mdp-value:: yes
2196
2197       Apply the rotation potential specified by :mdp:`rot-type0` to the group of atoms given
2198       under the :mdp:`rot-group0` option.
2199
2200 .. mdp:: rot-ngroups
2201
2202    (1)
2203    Number of rotation groups.
2204
2205 .. mdp:: rot-group0
2206
2207    Name of rotation group 0 in the index file.
2208
2209 .. mdp:: rot-type0
2210
2211    (iso)
2212    Type of rotation potential that is applied to rotation group 0. Can be of of the following:
2213    ``iso``, ``iso-pf``, ``pm``, ``pm-pf``, ``rm``, ``rm-pf``, ``rm2``, ``rm2-pf``,
2214    ``flex``, ``flex-t``, ``flex2``, or ``flex2-t``.
2215
2216 .. mdp:: rot-massw0
2217
2218    (no)
2219    Use mass weighted rotation group positions.
2220
2221 .. mdp:: rot-vec0
2222
2223    (1.0 0.0 0.0)
2224    Rotation vector, will get normalized.
2225
2226 .. mdp:: rot-pivot0
2227
2228    (0.0 0.0 0.0) [nm]
2229    Pivot point for the potentials ``iso``, ``pm``, ``rm``, and ``rm2``.
2230
2231 .. mdp:: rot-rate0
2232
2233    (0) [degree ps\ :sup:`-1`]
2234    Reference rotation rate of group 0.
2235
2236 .. mdp:: rot-k0
2237
2238    (0) [kJ mol\ :sup:`-1` nm\ :sup:`-2`]
2239    Force constant for group 0.
2240
2241 .. mdp:: rot-slab-dist0
2242
2243    (1.5) [nm]
2244    Slab distance, if a flexible axis rotation type was chosen.
2245
2246 .. mdp:: rot-min-gauss0
2247
2248    (0.001)
2249    Minimum value (cutoff) of Gaussian function for the force to be evaluated
2250    (for the flexible axis potentials).
2251
2252 .. mdp:: rot-eps0
2253
2254    (0.0001) [nm\ :sup:`2`]
2255    Value of additive constant epsilon for ``rm2*`` and ``flex2*`` potentials.
2256
2257 .. mdp:: rot-fit-method0
2258
2259    (rmsd)
2260    Fitting method when determining the actual angle of a rotation group
2261    (can be one of ``rmsd``, ``norm``, or ``potential``).
2262
2263 .. mdp:: rot-potfit-nsteps0
2264
2265    (21)
2266    For fit type ``potential``, the number of angular positions around the reference angle for which the
2267    rotation potential is evaluated.
2268
2269 .. mdp:: rot-potfit-step0
2270
2271    (0.25)
2272    For fit type ``potential``, the distance in degrees between two angular positions.
2273
2274 .. mdp:: rot-nstrout
2275
2276    (100)
2277    Output frequency (in steps) for the angle of the rotation group, as well as for the torque
2278    and the rotation potential energy.
2279
2280 .. mdp:: rot-nstsout
2281
2282    (1000)
2283    Output frequency for per-slab data of the flexible axis potentials, i.e. angles, torques and slab centers.
2284
2285
2286 NMR refinement
2287 ^^^^^^^^^^^^^^
2288
2289 .. mdp:: disre
2290
2291    .. mdp-value:: no
2292
2293       ignore distance restraint information in topology file
2294
2295    .. mdp-value:: simple
2296
2297       simple (per-molecule) distance restraints.
2298
2299    .. mdp-value:: ensemble
2300
2301       distance restraints over an ensemble of molecules in one
2302       simulation box. Normally, one would perform ensemble averaging
2303       over multiple simulations, using ``mdrun
2304       -multidir``. The environment
2305       variable ``GMX_DISRE_ENSEMBLE_SIZE`` sets the number of systems
2306       within each ensemble (usually equal to the number of directories
2307       supplied to ``mdrun -multidir``).
2308
2309 .. mdp:: disre-weighting
2310
2311    .. mdp-value:: equal
2312
2313       divide the restraint force equally over all atom pairs in the
2314       restraint
2315
2316    .. mdp-value:: conservative
2317
2318       the forces are the derivative of the restraint potential, this
2319       results in an weighting of the atom pairs to the reciprocal
2320       seventh power of the displacement. The forces are conservative
2321       when :mdp:`disre-tau` is zero.
2322
2323 .. mdp:: disre-mixed
2324
2325    .. mdp-value:: no
2326
2327       the violation used in the calculation of the restraint force is
2328       the time-averaged violation
2329
2330    .. mdp-value:: yes
2331
2332       the violation used in the calculation of the restraint force is
2333       the square root of the product of the time-averaged violation
2334       and the instantaneous violation
2335
2336 .. mdp:: disre-fc
2337
2338    (1000) [kJ mol\ :sup:`-1` nm\ :sup:`-2`]
2339    force constant for distance restraints, which is multiplied by a
2340    (possibly) different factor for each restraint given in the `fac`
2341    column of the interaction in the topology file.
2342
2343 .. mdp:: disre-tau
2344
2345    (0) [ps]
2346    time constant for distance restraints running average. A value of
2347    zero turns off time averaging.
2348
2349 .. mdp:: nstdisreout
2350
2351    (100) [steps]
2352    period between steps when the running time-averaged and
2353    instantaneous distances of all atom pairs involved in restraints
2354    are written to the energy file (can make the energy file very
2355    large)
2356
2357 .. mdp:: orire
2358
2359    .. mdp-value:: no
2360
2361       ignore orientation restraint information in topology file
2362
2363    .. mdp-value:: yes
2364
2365       use orientation restraints, ensemble averaging can be performed
2366       with ``mdrun -multidir``
2367
2368 .. mdp:: orire-fc
2369
2370    (0) [kJ mol\ :sup:`-1`]
2371    force constant for orientation restraints, which is multiplied by a
2372    (possibly) different weight factor for each restraint, can be set
2373    to zero to obtain the orientations from a free simulation
2374
2375 .. mdp:: orire-tau
2376
2377    (0) [ps]
2378    time constant for orientation restraints running average. A value
2379    of zero turns off time averaging.
2380
2381 .. mdp:: orire-fitgrp
2382
2383    fit group for orientation restraining. This group of atoms is used
2384    to determine the rotation **R** of the system with respect to the
2385    reference orientation. The reference orientation is the starting
2386    conformation of the first subsystem. For a protein, backbone is a
2387    reasonable choice
2388
2389 .. mdp:: nstorireout
2390
2391    (100) [steps]
2392    period between steps when the running time-averaged and
2393    instantaneous orientations for all restraints, and the molecular
2394    order tensor are written to the energy file (can make the energy
2395    file very large)
2396
2397
2398 Free energy calculations
2399 ^^^^^^^^^^^^^^^^^^^^^^^^
2400
2401 .. mdp:: free-energy
2402
2403    .. mdp-value:: no
2404
2405       Only use topology A.
2406
2407    .. mdp-value:: yes
2408
2409       Interpolate between topology A (lambda=0) to topology B
2410       (lambda=1) and write the derivative of the Hamiltonian with
2411       respect to lambda (as specified with :mdp:`dhdl-derivatives`),
2412       or the Hamiltonian differences with respect to other lambda
2413       values (as specified with foreign lambda) to the energy file
2414       and/or to ``dhdl.xvg``, where they can be processed by, for
2415       example :ref:`gmx bar`. The potentials, bond-lengths and angles
2416       are interpolated linearly as described in the manual. When
2417       :mdp:`sc-alpha` is larger than zero, soft-core potentials are
2418       used for the LJ and Coulomb interactions.
2419
2420 .. mdp:: expanded
2421
2422    Turns on expanded ensemble simulation, where the alchemical state
2423    becomes a dynamic variable, allowing jumping between different
2424    Hamiltonians. See the expanded ensemble options for controlling how
2425    expanded ensemble simulations are performed. The different
2426    Hamiltonians used in expanded ensemble simulations are defined by
2427    the other free energy options.
2428
2429 .. mdp:: init-lambda
2430
2431    (-1)
2432    starting value for lambda (float). Generally, this should only be
2433    used with slow growth (*i.e.* nonzero :mdp:`delta-lambda`). In
2434    other cases, :mdp:`init-lambda-state` should be specified
2435    instead. Must be greater than or equal to 0.
2436
2437 .. mdp:: delta-lambda
2438
2439    (0)
2440    increment per time step for lambda
2441
2442 .. mdp:: init-lambda-state
2443
2444    (-1)
2445    starting value for the lambda state (integer). Specifies which
2446    columm of the lambda vector (:mdp:`coul-lambdas`,
2447    :mdp:`vdw-lambdas`, :mdp:`bonded-lambdas`,
2448    :mdp:`restraint-lambdas`, :mdp:`mass-lambdas`,
2449    :mdp:`temperature-lambdas`, :mdp:`fep-lambdas`) should be
2450    used. This is a zero-based index: :mdp:`init-lambda-state` 0 means
2451    the first column, and so on.
2452
2453 .. mdp:: fep-lambdas
2454
2455    [array]
2456    Zero, one or more lambda values for which Delta H values will be
2457    determined and written to dhdl.xvg every :mdp:`nstdhdl`
2458    steps. Values must be between 0 and 1. Free energy differences
2459    between different lambda values can then be determined with
2460    :ref:`gmx bar`. :mdp:`fep-lambdas` is different from the
2461    other -lambdas keywords because all components of the lambda vector
2462    that are not specified will use :mdp:`fep-lambdas` (including
2463    :mdp:`restraint-lambdas` and therefore the pull code restraints).
2464
2465 .. mdp:: coul-lambdas
2466
2467    [array]
2468    Zero, one or more lambda values for which Delta H values will be
2469    determined and written to dhdl.xvg every :mdp:`nstdhdl`
2470    steps. Values must be between 0 and 1. Only the electrostatic
2471    interactions are controlled with this component of the lambda
2472    vector (and only if the lambda=0 and lambda=1 states have differing
2473    electrostatic interactions).
2474
2475 .. mdp:: vdw-lambdas
2476
2477    [array]
2478    Zero, one or more lambda values for which Delta H values will be
2479    determined and written to dhdl.xvg every :mdp:`nstdhdl`
2480    steps. Values must be between 0 and 1. Only the van der Waals
2481    interactions are controlled with this component of the lambda
2482    vector.
2483
2484 .. mdp:: bonded-lambdas
2485
2486    [array]
2487    Zero, one or more lambda values for which Delta H values will be
2488    determined and written to dhdl.xvg every :mdp:`nstdhdl`
2489    steps. Values must be between 0 and 1. Only the bonded interactions
2490    are controlled with this component of the lambda vector.
2491
2492 .. mdp:: restraint-lambdas
2493
2494    [array]
2495    Zero, one or more lambda values for which Delta H values will be
2496    determined and written to dhdl.xvg every :mdp:`nstdhdl`
2497    steps. Values must be between 0 and 1. Only the restraint
2498    interactions: dihedral restraints, and the pull code restraints are
2499    controlled with this component of the lambda vector.
2500
2501 .. mdp:: mass-lambdas
2502
2503    [array]
2504    Zero, one or more lambda values for which Delta H values will be
2505    determined and written to dhdl.xvg every :mdp:`nstdhdl`
2506    steps. Values must be between 0 and 1. Only the particle masses are
2507    controlled with this component of the lambda vector.
2508
2509 .. mdp:: temperature-lambdas
2510
2511    [array]
2512    Zero, one or more lambda values for which Delta H values will be
2513    determined and written to dhdl.xvg every :mdp:`nstdhdl`
2514    steps. Values must be between 0 and 1. Only the temperatures
2515    controlled with this component of the lambda vector. Note that
2516    these lambdas should not be used for replica exchange, only for
2517    simulated tempering.
2518
2519 .. mdp:: calc-lambda-neighbors
2520
2521    (1)
2522    Controls the number of lambda values for which Delta H values will
2523    be calculated and written out, if :mdp:`init-lambda-state` has
2524    been set. A positive value will limit the number of lambda points
2525    calculated to only the nth neighbors of :mdp:`init-lambda-state`:
2526    for example, if :mdp:`init-lambda-state` is 5 and this parameter
2527    has a value of 2, energies for lambda points 3-7 will be calculated
2528    and writen out. A value of -1 means all lambda points will be
2529    written out. For normal BAR such as with :ref:`gmx bar`, a value of
2530    1 is sufficient, while for MBAR -1 should be used.
2531
2532 .. mdp:: sc-alpha
2533
2534    (0)
2535    the soft-core alpha parameter, a value of 0 results in linear
2536    interpolation of the LJ and Coulomb interactions
2537
2538 .. mdp:: sc-r-power
2539
2540    (6)
2541    the power of the radial term in the soft-core equation. Possible
2542    values are 6 and 48. 6 is more standard, and is the default. When
2543    48 is used, then sc-alpha should generally be much lower (between
2544    0.001 and 0.003).
2545
2546 .. mdp:: sc-coul
2547
2548    (no)
2549    Whether to apply the soft-core free energy interaction
2550    transformation to the Columbic interaction of a molecule. Default
2551    is no, as it is generally more efficient to turn off the Coulomic
2552    interactions linearly before turning off the van der Waals
2553    interactions. Note that it is only taken into account when lambda
2554    states are used, not with :mdp:`couple-lambda0` /
2555    :mdp:`couple-lambda1`, and you can still turn off soft-core
2556    interactions by setting :mdp:`sc-alpha` to 0.
2557
2558 .. mdp:: sc-power
2559
2560    (0)
2561    the power for lambda in the soft-core function, only the values 1
2562    and 2 are supported
2563
2564 .. mdp:: sc-sigma
2565
2566    (0.3) [nm]
2567    the soft-core sigma for particles which have a C6 or C12 parameter
2568    equal to zero or a sigma smaller than :mdp:`sc-sigma`
2569
2570 .. mdp:: couple-moltype
2571
2572    Here one can supply a molecule type (as defined in the topology)
2573    for calculating solvation or coupling free energies. There is a
2574    special option ``system`` that couples all molecule types in the
2575    system. This can be useful for equilibrating a system starting from
2576    (nearly) random coordinates. :mdp:`free-energy` has to be turned
2577    on. The Van der Waals interactions and/or charges in this molecule
2578    type can be turned on or off between lambda=0 and lambda=1,
2579    depending on the settings of :mdp:`couple-lambda0` and
2580    :mdp:`couple-lambda1`. If you want to decouple one of several
2581    copies of a molecule, you need to copy and rename the molecule
2582    definition in the topology.
2583
2584 .. mdp:: couple-lambda0
2585
2586    .. mdp-value:: vdw-q
2587
2588       all interactions are on at lambda=0
2589
2590    .. mdp-value:: vdw
2591
2592       the charges are zero (no Coulomb interactions) at lambda=0
2593
2594    .. mdp-value:: q
2595
2596       the Van der Waals interactions are turned at lambda=0; soft-core
2597       interactions will be required to avoid singularities
2598
2599    .. mdp-value:: none
2600
2601       the Van der Waals interactions are turned off and the charges
2602       are zero at lambda=0; soft-core interactions will be required to
2603       avoid singularities.
2604
2605 .. mdp:: couple-lambda1
2606
2607    analogous to :mdp:`couple-lambda1`, but for lambda=1
2608
2609 .. mdp:: couple-intramol
2610
2611    .. mdp-value:: no
2612
2613       All intra-molecular non-bonded interactions for moleculetype
2614       :mdp:`couple-moltype` are replaced by exclusions and explicit
2615       pair interactions. In this manner the decoupled state of the
2616       molecule corresponds to the proper vacuum state without
2617       periodicity effects.
2618
2619    .. mdp-value:: yes
2620
2621       The intra-molecular Van der Waals and Coulomb interactions are
2622       also turned on/off. This can be useful for partitioning
2623       free-energies of relatively large molecules, where the
2624       intra-molecular non-bonded interactions might lead to
2625       kinetically trapped vacuum conformations. The 1-4 pair
2626       interactions are not turned off.
2627
2628 .. mdp:: nstdhdl
2629
2630    (100)
2631    the frequency for writing dH/dlambda and possibly Delta H to
2632    dhdl.xvg, 0 means no ouput, should be a multiple of
2633    :mdp:`nstcalcenergy`.
2634
2635 .. mdp:: dhdl-derivatives
2636
2637    (yes)
2638
2639    If yes (the default), the derivatives of the Hamiltonian with
2640    respect to lambda at each :mdp:`nstdhdl` step are written
2641    out. These values are needed for interpolation of linear energy
2642    differences with :ref:`gmx bar` (although the same can also be
2643    achieved with the right foreign lambda setting, that may not be as
2644    flexible), or with thermodynamic integration
2645
2646 .. mdp:: dhdl-print-energy
2647
2648    (no)
2649
2650    Include either the total or the potential energy in the dhdl
2651    file. Options are 'no', 'potential', or 'total'. This information
2652    is needed for later free energy analysis if the states of interest
2653    are at different temperatures. If all states are at the same
2654    temperature, this information is not needed. 'potential' is useful
2655    in case one is using ``mdrun -rerun`` to generate the ``dhdl.xvg``
2656    file. When rerunning from an existing trajectory, the kinetic
2657    energy will often not be correct, and thus one must compute the
2658    residual free energy from the potential alone, with the kinetic
2659    energy component computed analytically.
2660
2661 .. mdp:: separate-dhdl-file
2662
2663    .. mdp-value:: yes
2664
2665       The free energy values that are calculated (as specified with
2666       the foreign lambda and :mdp:`dhdl-derivatives` settings) are
2667       written out to a separate file, with the default name
2668       ``dhdl.xvg``. This file can be used directly with :ref:`gmx
2669       bar`.
2670
2671    .. mdp-value:: no
2672
2673       The free energy values are written out to the energy output file
2674       (``ener.edr``, in accumulated blocks at every :mdp:`nstenergy`
2675       steps), where they can be extracted with :ref:`gmx energy` or
2676       used directly with :ref:`gmx bar`.
2677
2678 .. mdp:: dh-hist-size
2679
2680    (0)
2681    If nonzero, specifies the size of the histogram into which the
2682    Delta H values (specified with foreign lambda) and the derivative
2683    dH/dl values are binned, and written to ener.edr. This can be used
2684    to save disk space while calculating free energy differences. One
2685    histogram gets written for each foreign lambda and two for the
2686    dH/dl, at every :mdp:`nstenergy` step. Be aware that incorrect
2687    histogram settings (too small size or too wide bins) can introduce
2688    errors. Do not use histograms unless you're certain you need it.
2689
2690 .. mdp:: dh-hist-spacing
2691
2692    (0.1)
2693    Specifies the bin width of the histograms, in energy units. Used in
2694    conjunction with :mdp:`dh-hist-size`. This size limits the
2695    accuracy with which free energies can be calculated. Do not use
2696    histograms unless you're certain you need it.
2697
2698
2699 Expanded Ensemble calculations
2700 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2701
2702 .. mdp:: nstexpanded
2703
2704    The number of integration steps beween attempted moves changing the
2705    system Hamiltonian in expanded ensemble simulations. Must be a
2706    multiple of :mdp:`nstcalcenergy`, but can be greater or less than
2707    :mdp:`nstdhdl`.
2708
2709 .. mdp:: lmc-stats
2710
2711    .. mdp-value:: no
2712
2713       No Monte Carlo in state space is performed.
2714
2715    .. mdp-value:: metropolis-transition
2716
2717       Uses the Metropolis weights to update the expanded ensemble
2718       weight of each state. Min{1,exp(-(beta_new u_new - beta_old
2719       u_old)}
2720
2721    .. mdp-value:: barker-transition
2722
2723       Uses the Barker transition critera to update the expanded
2724       ensemble weight of each state i, defined by exp(-beta_new
2725       u_new)/(exp(-beta_new u_new)+exp(-beta_old u_old))
2726
2727    .. mdp-value:: wang-landau
2728
2729       Uses the Wang-Landau algorithm (in state space, not energy
2730       space) to update the expanded ensemble weights.
2731
2732    .. mdp-value:: min-variance
2733
2734       Uses the minimum variance updating method of Escobedo et al. to
2735       update the expanded ensemble weights. Weights will not be the
2736       free energies, but will rather emphasize states that need more
2737       sampling to give even uncertainty.
2738
2739 .. mdp:: lmc-mc-move
2740
2741    .. mdp-value:: no
2742
2743       No Monte Carlo in state space is performed.
2744
2745    .. mdp-value:: metropolis-transition
2746
2747       Randomly chooses a new state up or down, then uses the
2748       Metropolis critera to decide whether to accept or reject:
2749       Min{1,exp(-(beta_new u_new - beta_old u_old)}
2750
2751    .. mdp-value:: barker-transition
2752
2753       Randomly chooses a new state up or down, then uses the Barker
2754       transition critera to decide whether to accept or reject:
2755       exp(-beta_new u_new)/(exp(-beta_new u_new)+exp(-beta_old u_old))
2756
2757    .. mdp-value:: gibbs
2758
2759        Uses the conditional weights of the state given the coordinate
2760        (exp(-beta_i u_i) / sum_k exp(beta_i u_i) to decide which state
2761        to move to.
2762
2763    .. mdp-value:: metropolized-gibbs
2764
2765        Uses the conditional weights of the state given the coordinate
2766        (exp(-beta_i u_i) / sum_k exp(beta_i u_i) to decide which state
2767        to move to, EXCLUDING the current state, then uses a rejection
2768        step to ensure detailed balance. Always more efficient that
2769        Gibbs, though only marginally so in many situations, such as
2770        when only the nearest neighbors have decent phase space
2771        overlap.
2772
2773 .. mdp:: lmc-seed
2774
2775    (-1)
2776    random seed to use for Monte Carlo moves in state space. When
2777    :mdp:`lmc-seed` is set to -1, a pseudo random seed is us
2778
2779 .. mdp:: mc-temperature
2780
2781    Temperature used for acceptance/rejection for Monte Carlo moves. If
2782    not specified, the temperature of the simulation specified in the
2783    first group of :mdp:`ref-t` is used.
2784
2785 .. mdp:: wl-ratio
2786
2787    (0.8)
2788    The cutoff for the histogram of state occupancies to be reset, and
2789    the free energy incrementor to be changed from delta to delta *
2790    :mdp:`wl-scale`. If we define the Nratio = (number of samples at
2791    each histogram) / (average number of samples at each
2792    histogram). :mdp:`wl-ratio` of 0.8 means that means that the
2793    histogram is only considered flat if all Nratio > 0.8 AND
2794    simultaneously all 1/Nratio > 0.8.
2795
2796 .. mdp:: wl-scale
2797
2798    (0.8)
2799    Each time the histogram is considered flat, then the current value
2800    of the Wang-Landau incrementor for the free energies is multiplied
2801    by :mdp:`wl-scale`. Value must be between 0 and 1.
2802
2803 .. mdp:: init-wl-delta
2804
2805    (1.0)
2806    The initial value of the Wang-Landau incrementor in kT. Some value
2807    near 1 kT is usually most efficient, though sometimes a value of
2808    2-3 in units of kT works better if the free energy differences are
2809    large.
2810
2811 .. mdp:: wl-oneovert
2812
2813    (no)
2814    Set Wang-Landau incrementor to scale with 1/(simulation time) in
2815    the large sample limit. There is significant evidence that the
2816    standard Wang-Landau algorithms in state space presented here
2817    result in free energies getting 'burned in' to incorrect values
2818    that depend on the initial state. when :mdp:`wl-oneovert` is true,
2819    then when the incrementor becomes less than 1/N, where N is the
2820    mumber of samples collected (and thus proportional to the data
2821    collection time, hence '1 over t'), then the Wang-Lambda
2822    incrementor is set to 1/N, decreasing every step. Once this occurs,
2823    :mdp:`wl-ratio` is ignored, but the weights will still stop
2824    updating when the equilibration criteria set in
2825    :mdp:`lmc-weights-equil` is achieved.
2826
2827 .. mdp:: lmc-repeats
2828
2829    (1)
2830    Controls the number of times that each Monte Carlo swap type is
2831    performed each iteration. In the limit of large numbers of Monte
2832    Carlo repeats, then all methods converge to Gibbs sampling. The
2833    value will generally not need to be different from 1.
2834
2835 .. mdp:: lmc-gibbsdelta
2836
2837    (-1)
2838    Limit Gibbs sampling to selected numbers of neighboring states. For
2839    Gibbs sampling, it is sometimes inefficient to perform Gibbs
2840    sampling over all of the states that are defined. A positive value
2841    of :mdp:`lmc-gibbsdelta` means that only states plus or minus
2842    :mdp:`lmc-gibbsdelta` are considered in exchanges up and down. A
2843    value of -1 means that all states are considered. For less than 100
2844    states, it is probably not that expensive to include all states.
2845
2846 .. mdp:: lmc-forced-nstart
2847
2848    (0)
2849    Force initial state space sampling to generate weights. In order to
2850    come up with reasonable initial weights, this setting allows the
2851    simulation to drive from the initial to the final lambda state,
2852    with :mdp:`lmc-forced-nstart` steps at each state before moving on
2853    to the next lambda state. If :mdp:`lmc-forced-nstart` is
2854    sufficiently long (thousands of steps, perhaps), then the weights
2855    will be close to correct. However, in most cases, it is probably
2856    better to simply run the standard weight equilibration algorithms.
2857
2858 .. mdp:: nst-transition-matrix
2859
2860    (-1)
2861    Frequency of outputting the expanded ensemble transition matrix. A
2862    negative number means it will only be printed at the end of the
2863    simulation.
2864
2865 .. mdp:: symmetrized-transition-matrix
2866
2867    (no)
2868    Whether to symmetrize the empirical transition matrix. In the
2869    infinite limit the matrix will be symmetric, but will diverge with
2870    statistical noise for short timescales. Forced symmetrization, by
2871    using the matrix T_sym = 1/2 (T + transpose(T)), removes problems
2872    like the existence of (small magnitude) negative eigenvalues.
2873
2874 .. mdp:: mininum-var-min
2875
2876    (100)
2877    The min-variance strategy (option of :mdp:`lmc-stats` is only
2878    valid for larger number of samples, and can get stuck if too few
2879    samples are used at each state. :mdp:`mininum-var-min` is the
2880    minimum number of samples that each state that are allowed before
2881    the min-variance strategy is activated if selected.
2882
2883 .. mdp:: init-lambda-weights
2884
2885    The initial weights (free energies) used for the expanded ensemble
2886    states. Default is a vector of zero weights. format is similar to
2887    the lambda vector settings in :mdp:`fep-lambdas`, except the
2888    weights can be any floating point number. Units are kT. Its length
2889    must match the lambda vector lengths.
2890
2891 .. mdp:: lmc-weights-equil
2892
2893    .. mdp-value:: no
2894
2895       Expanded ensemble weights continue to be updated throughout the
2896       simulation.
2897
2898    .. mdp-value:: yes
2899
2900       The input expanded ensemble weights are treated as equilibrated,
2901       and are not updated throughout the simulation.
2902
2903    .. mdp-value:: wl-delta
2904
2905       Expanded ensemble weight updating is stopped when the
2906       Wang-Landau incrementor falls below this value.
2907
2908    .. mdp-value:: number-all-lambda
2909
2910       Expanded ensemble weight updating is stopped when the number of
2911       samples at all of the lambda states is greater than this value.
2912
2913    .. mdp-value:: number-steps
2914
2915       Expanded ensemble weight updating is stopped when the number of
2916       steps is greater than the level specified by this value.
2917
2918    .. mdp-value:: number-samples
2919
2920       Expanded ensemble weight updating is stopped when the number of
2921       total samples across all lambda states is greater than the level
2922       specified by this value.
2923
2924    .. mdp-value:: count-ratio
2925
2926       Expanded ensemble weight updating is stopped when the ratio of
2927       samples at the least sampled lambda state and most sampled
2928       lambda state greater than this value.
2929
2930 .. mdp:: simulated-tempering
2931
2932    (no)
2933    Turn simulated tempering on or off. Simulated tempering is
2934    implemented as expanded ensemble sampling with different
2935    temperatures instead of different Hamiltonians.
2936
2937 .. mdp:: sim-temp-low
2938
2939    (300) [K]
2940    Low temperature for simulated tempering.
2941
2942 .. mdp:: sim-temp-high
2943
2944    (300) [K]
2945    High temperature for simulated tempering.
2946
2947 .. mdp:: simulated-tempering-scaling
2948
2949    Controls the way that the temperatures at intermediate lambdas are
2950    calculated from the :mdp:`temperature-lambdas` part of the lambda
2951    vector.
2952
2953    .. mdp-value:: linear
2954
2955       Linearly interpolates the temperatures using the values of
2956       :mdp:`temperature-lambdas`, *i.e.* if :mdp:`sim-temp-low`
2957       =300, :mdp:`sim-temp-high` =400, then lambda=0.5 correspond to
2958       a temperature of 350. A nonlinear set of temperatures can always
2959       be implemented with uneven spacing in lambda.
2960
2961    .. mdp-value:: geometric
2962
2963       Interpolates temperatures geometrically between
2964       :mdp:`sim-temp-low` and :mdp:`sim-temp-high`. The i:th state
2965       has temperature :mdp:`sim-temp-low` * (:mdp:`sim-temp-high` /
2966       :mdp:`sim-temp-low`) raised to the power of
2967       (i/(ntemps-1)). This should give roughly equal exchange for
2968       constant heat capacity, though of course things simulations that
2969       involve protein folding have very high heat capacity peaks.
2970
2971    .. mdp-value:: exponential
2972
2973       Interpolates temperatures exponentially between
2974       :mdp:`sim-temp-low` and :mdp:`sim-temp-high`. The i:th state
2975       has temperature :mdp:`sim-temp-low` + (:mdp:`sim-temp-high` -
2976       :mdp:`sim-temp-low`)*((exp(:mdp:`temperature-lambdas`
2977       (i))-1)/(exp(1.0)-i)).
2978
2979
2980 Non-equilibrium MD
2981 ^^^^^^^^^^^^^^^^^^
2982
2983 .. mdp:: acc-grps
2984
2985    groups for constant acceleration (*e.g.* ``Protein Sol``) all atoms
2986    in groups Protein and Sol will experience constant acceleration as
2987    specified in the :mdp:`accelerate` line
2988
2989 .. mdp:: accelerate
2990
2991    (0) [nm ps\ :sup:`-2`]
2992    acceleration for :mdp:`acc-grps`; x, y and z for each group
2993    (*e.g.* ``0.1 0.0 0.0 -0.1 0.0 0.0`` means that first group has
2994    constant acceleration of 0.1 nm ps\ :sup:`-2` in X direction, second group
2995    the opposite).
2996
2997 .. mdp:: freezegrps
2998
2999    Groups that are to be frozen (*i.e.* their X, Y, and/or Z position
3000    will not be updated; *e.g.* ``Lipid SOL``). :mdp:`freezedim`
3001    specifies for which dimension(s) the freezing applies. To avoid
3002    spurious contributions to the virial and pressure due to large
3003    forces between completely frozen atoms you need to use energy group
3004    exclusions, this also saves computing time. Note that coordinates
3005    of frozen atoms are not scaled by pressure-coupling algorithms.
3006
3007 .. mdp:: freezedim
3008
3009    dimensions for which groups in :mdp:`freezegrps` should be frozen,
3010    specify `Y` or `N` for X, Y and Z and for each group (*e.g.* ``Y Y
3011    N N N N`` means that particles in the first group can move only in
3012    Z direction. The particles in the second group can move in any
3013    direction).
3014
3015 .. mdp:: cos-acceleration
3016
3017    (0) [nm ps\ :sup:`-2`]
3018    the amplitude of the acceleration profile for calculating the
3019    viscosity. The acceleration is in the X-direction and the magnitude
3020    is :mdp:`cos-acceleration` cos(2 pi z/boxheight). Two terms are
3021    added to the energy file: the amplitude of the velocity profile and
3022    1/viscosity.
3023
3024 .. mdp:: deform
3025
3026    (0 0 0 0 0 0) [nm ps\ :sup:`-1`]
3027    The velocities of deformation for the box elements: a(x) b(y) c(z)
3028    b(x) c(x) c(y). Each step the box elements for which :mdp:`deform`
3029    is non-zero are calculated as: box(ts)+(t-ts)*deform, off-diagonal
3030    elements are corrected for periodicity. The coordinates are
3031    transformed accordingly. Frozen degrees of freedom are (purposely)
3032    also transformed. The time ts is set to t at the first step and at
3033    steps at which x and v are written to trajectory to ensure exact
3034    restarts. Deformation can be used together with semiisotropic or
3035    anisotropic pressure coupling when the appropriate
3036    compressibilities are set to zero. The diagonal elements can be
3037    used to strain a solid. The off-diagonal elements can be used to
3038    shear a solid or a liquid.
3039
3040
3041 Electric fields
3042 ^^^^^^^^^^^^^^^
3043
3044 .. mdp:: electric-field-x ; electric-field-y ; electric-field-z
3045
3046    Here you can specify an electric field that optionally can be
3047    alternating and pulsed. The general expression for the field
3048    has the form of a gaussian laser pulse:
3049
3050    E(t) = E0 exp ( -(t-t0)\ :sup:`2`/(2 sigma\ :sup:`2`) ) cos(omega (t-t0))
3051
3052    For example, the four parameters for direction x are set in the
3053    three fields of :mdp:`electric-field-x` (and similar for y and z)
3054    like
3055
3056    electric-field-x  = E0 omega t0 sigma
3057
3058    In the special case that sigma = 0, the exponential term is omitted
3059    and only the cosine term is used. If also omega = 0 a static
3060    electric field is applied.
3061
3062    More details in Carl Caleman and David van der Spoel: Picosecond
3063    Melting of Ice by an Infrared Laser Pulse - A Simulation Study.
3064    Angew. Chem. Intl. Ed. 47 pp. 14 17-1420 (2008)
3065
3066
3067
3068 Mixed quantum/classical molecular dynamics
3069 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3070
3071 .. MDP:: QMMM
3072
3073    .. mdp-value:: no
3074
3075       No QM/MM.
3076
3077    .. mdp-value:: yes
3078
3079       Do a QM/MM simulation. Several groups can be described at
3080       different QM levels separately. These are specified in the
3081       :mdp:`QMMM-grps` field separated by spaces. The level of *ab
3082       initio* theory at which the groups are described is specified by
3083       :mdp:`QMmethod` and :mdp:`QMbasis` Fields. Describing the
3084       groups at different levels of theory is only possible with the
3085       ONIOM QM/MM scheme, specified by :mdp:`QMMMscheme`.
3086
3087 .. mdp:: QMMM-grps
3088
3089    groups to be descibed at the QM level (works also in case of MiMiC QM/MM)
3090
3091 .. mdp:: QMMMscheme
3092
3093    .. mdp-value:: normal
3094
3095       normal QM/MM. There can only be one :mdp:`QMMM-grps` that is
3096       modelled at the :mdp:`QMmethod` and :mdp:`QMbasis` level of
3097       *ab initio* theory. The rest of the system is described at the
3098       MM level. The QM and MM subsystems interact as follows: MM point
3099       charges are included in the QM one-electron hamiltonian and all
3100       Lennard-Jones interactions are described at the MM level.
3101
3102    .. mdp-value:: ONIOM
3103
3104       The interaction between the subsystem is described using the
3105       ONIOM method by Morokuma and co-workers. There can be more than
3106       one :mdp:`QMMM-grps` each modeled at a different level of QM
3107       theory (:mdp:`QMmethod` and :mdp:`QMbasis`).
3108
3109 .. mdp:: QMmethod
3110
3111    (RHF)
3112    Method used to compute the energy and gradients on the QM
3113    atoms. Available methods are AM1, PM3, RHF, UHF, DFT, B3LYP, MP2,
3114    CASSCF, and MMVB. For CASSCF, the number of electrons and orbitals
3115    included in the active space is specified by :mdp:`CASelectrons`
3116    and :mdp:`CASorbitals`.
3117
3118 .. mdp:: QMbasis
3119
3120    (STO-3G)
3121    Basis set used to expand the electronic wavefuntion. Only Gaussian
3122    basis sets are currently available, *i.e.* ``STO-3G, 3-21G, 3-21G*,
3123    3-21+G*, 6-21G, 6-31G, 6-31G*, 6-31+G*,`` and ``6-311G``.
3124
3125 .. mdp:: QMcharge
3126
3127    (0) [integer]
3128    The total charge in `e` of the :mdp:`QMMM-grps`. In case there are
3129    more than one :mdp:`QMMM-grps`, the total charge of each ONIOM
3130    layer needs to be specified separately.
3131
3132 .. mdp:: QMmult
3133
3134    (1) [integer]
3135    The multiplicity of the :mdp:`QMMM-grps`. In case there are more
3136    than one :mdp:`QMMM-grps`, the multiplicity of each ONIOM layer
3137    needs to be specified separately.
3138
3139 .. mdp:: CASorbitals
3140
3141    (0) [integer]
3142    The number of orbitals to be included in the active space when
3143    doing a CASSCF computation.
3144
3145 .. mdp:: CASelectrons
3146
3147    (0) [integer]
3148    The number of electrons to be included in the active space when
3149    doing a CASSCF computation.
3150
3151 .. MDP:: SH
3152
3153    .. mdp-value:: no
3154
3155       No surface hopping. The system is always in the electronic
3156       ground-state.
3157
3158    .. mdp-value:: yes
3159
3160       Do a QM/MM MD simulation on the excited state-potential energy
3161       surface and enforce a *diabatic* hop to the ground-state when
3162       the system hits the conical intersection hyperline in the course
3163       the simulation. This option only works in combination with the
3164       CASSCF method.
3165
3166
3167 Computational Electrophysiology
3168 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3169 Use these options to switch on and control ion/water position exchanges in "Computational
3170 Electrophysiology" simulation setups. (See the `reference manual`_ for details).
3171
3172 .. mdp:: swapcoords
3173
3174    .. mdp-value:: no
3175
3176       Do not enable ion/water position exchanges.
3177
3178    .. mdp-value:: X ; Y ; Z
3179
3180       Allow for ion/water position exchanges along the chosen direction.
3181       In a typical setup with the membranes parallel to the x-y plane,
3182       ion/water pairs need to be exchanged in Z direction to sustain the
3183       requested ion concentrations in the compartments.
3184
3185 .. mdp:: swap-frequency
3186
3187    (1) The swap attempt frequency, i.e. every how many time steps the ion counts
3188    per compartment are determined and exchanges made if necessary.
3189    Normally it is not necessary to check at every time step.
3190    For typical Computational Electrophysiology setups, a value of about 100 is
3191    sufficient and yields a negligible performance impact.
3192
3193 .. mdp:: split-group0
3194
3195    Name of the index group of the membrane-embedded part of channel #0.
3196    The center of mass of these atoms defines one of the compartment boundaries
3197    and should be chosen such that it is near the center of the membrane.
3198
3199 .. mdp:: split-group1
3200
3201    Channel #1 defines the position of the other compartment boundary.
3202
3203 .. mdp:: massw-split0
3204
3205    (no) Defines whether or not mass-weighting is used to calculate the split group center.
3206
3207    .. mdp-value:: no
3208
3209       Use the geometrical center.
3210
3211    .. mdp-value:: yes
3212
3213       Use the center of mass.
3214
3215 .. mdp:: massw-split1
3216
3217    (no) As above, but for split-group #1.
3218
3219 .. mdp:: solvent-group
3220
3221    Name of the index group of solvent molecules.
3222
3223 .. mdp:: coupl-steps
3224
3225    (10) Average the number of ions per compartment over these many swap attempt steps.
3226    This can be used to prevent that ions near a compartment boundary
3227    (diffusing through a channel, e.g.) lead to unwanted back and forth swaps.
3228
3229 .. mdp:: iontypes
3230
3231    (1) The number of different ion types to be controlled. These are during the
3232    simulation exchanged with solvent molecules to reach the desired reference numbers.
3233
3234 .. mdp:: iontype0-name
3235
3236    Name of the first ion type.
3237
3238 .. mdp:: iontype0-in-A
3239
3240    (-1) Requested (=reference) number of ions of type 0 in compartment A.
3241    The default value of -1 means: use the number of ions as found in time step 0
3242    as reference value.
3243
3244 .. mdp:: iontype0-in-B
3245
3246    (-1) Reference number of ions of type 0 for compartment B.
3247
3248 .. mdp:: bulk-offsetA
3249
3250    (0.0) Offset of the first swap layer from the compartment A midplane.
3251    By default (i.e. bulk offset = 0.0), ion/water exchanges happen between layers
3252    at maximum distance (= bulk concentration) to the split group layers. However,
3253    an offset b (-1.0 < b < +1.0) can be specified to offset the bulk layer from the middle at 0.0
3254    towards one of the compartment-partitioning layers (at +/- 1.0).
3255
3256 .. mdp:: bulk-offsetB
3257
3258    (0.0) Offset of the other swap layer from the compartment B midplane.
3259
3260
3261 .. mdp:: threshold
3262
3263    (\1) Only swap ions if threshold difference to requested count is reached.
3264
3265 .. mdp:: cyl0-r
3266
3267    (2.0) [nm] Radius of the split cylinder #0.
3268    Two split cylinders (mimicking the channel pores) can optionally be defined
3269    relative to the center of the split group. With the help of these cylinders
3270    it can be counted which ions have passed which channel. The split cylinder
3271    definition has no impact on whether or not ion/water swaps are done.
3272
3273 .. mdp:: cyl0-up
3274
3275    (1.0) [nm] Upper extension of the split cylinder #0.
3276
3277 .. mdp:: cyl0-down
3278
3279    (1.0) [nm] Lower extension of the split cylinder #0.
3280
3281 .. mdp:: cyl1-r
3282
3283    (2.0) [nm] Radius of the split cylinder #1.
3284
3285 .. mdp:: cyl1-up
3286
3287    (1.0) [nm] Upper extension of the split cylinder #1.
3288
3289 .. mdp:: cyl1-down
3290
3291    (1.0) [nm] Lower extension of the split cylinder #1.
3292
3293
3294 User defined thingies
3295 ^^^^^^^^^^^^^^^^^^^^^
3296
3297 .. mdp:: user1-grps
3298 .. mdp:: user2-grps
3299 .. mdp:: userint1 (0)
3300 .. mdp:: userint2 (0)
3301 .. mdp:: userint3 (0)
3302 .. mdp:: userint4 (0)
3303 .. mdp:: userreal1 (0)
3304 .. mdp:: userreal2 (0)
3305 .. mdp:: userreal3 (0)
3306 .. mdp:: userreal4 (0)
3307
3308    These you can use if you modify code. You can pass integers and
3309    reals and groups to your subroutine. Check the inputrec definition
3310    in ``src/gromacs/mdtypes/inputrec.h``
3311
3312 Removed features
3313 ^^^^^^^^^^^^^^^^
3314
3315 These features have been removed from |Gromacs|, but so that old
3316 :ref:`mdp` and :ref:`tpr` files cannot be mistakenly misused, we still
3317 parse this option. :ref:`gmx grompp` and :ref:`gmx mdrun` will issue a
3318 fatal error if this is set.
3319
3320 .. mdp:: adress
3321
3322    (no)
3323
3324 .. mdp:: implicit-solvent
3325
3326    (no)
3327
3328 .. _reference manual: gmx-manual-parent-dir_