docs/user-guide/mdrun-features.rst

   1 Useful mdrun features
   2 =======================
   3 This section discusses features in :ref:`gmx mdrun` that don't fit well
   4 elsewhere.
   5
   6 .. _single-point energy:
   7
   8 Re-running a simulation
   9 -----------------------
  10 The rerun feature allows you to take any trajectory file ``traj.trr``
  11 and compute quantities based upon the coordinates in that file using
  12 the model physics supplied in the ``topol.tpr`` file. It can be used
  13 with command lines like ``mdrun -s topol -rerun traj.trr``. That :ref:`tpr`
  14 could be different from the one that generated the trajectory. This
  15 can be used to compute the energy or forces for exactly the
  16 coordinates supplied as input, or to extract quantities based on
  17 subsets of the molecular system (see :ref:`gmx convert-tpr` and
  18 :ref:`gmx trjconv`). It is easier to do a correct "single-point" energy
  19 evaluation with this feature than a 0-step simulation.
  20
  21 Neighbor searching is performed for every frame in the trajectory
  22 independently of the value in :mdp:`nstlist`, since
  23 :ref:`gmx mdrun` can no longer assume anything about how the
  24 structures were generated. Naturally, no update or constraint
  25 algorithms are ever used.
  26
  27 The rerun feature cannot, in general, compute many of the quantities
  28 reported during full simulations. It does only take positions as input
  29 (ignoring potentially present velocities), and does only report potential
  30 energies, volume and density, dH/dl terms, and restraint information.
  31 It does notably not report kinetic, total or conserved energy, temperature,
  32 virial or pressure.
  33
  34 Running a simulation in reproducible mode
  35 -----------------------------------------
  36 It is generally difficult to run an efficient parallel MD simulation
  37 that is based primarily on floating-point arithmetic and is fully
  38 reproducible. By default, :ref:`gmx mdrun` will observe how things are going
  39 and vary how the simulation is conducted in order to optimize
  40 throughput. However, there is a "reproducible mode" available with
  41 ``mdrun -reprod`` that will systematically eliminate all sources of
  42 variation within that run; repeated invocations on the same input and
  43 hardware will be binary identical. However, running in this mode on
  44 different hardware, or with a different compiler, etc. will not be
  45 reproducible. This should normally only be used when investigating
  46 possible problems.
  47
  48 Halting running simulations
  49 ---------------------------
  50
  51 When :ref:`gmx mdrun` receives a TERM or INT signal (e.g. when ctrl+C is
  52 pressed), it will stop at the next neighbor search step or at the
  53 second global communication step, whichever happens later.
  54 When :ref:`gmx mdrun` receives a second TERM or INT signal and
  55 reproducibility is not requested, it will stop at the first global
  56 communication step.
  57 In both cases all the usual output will be written to file and
  58 a checkpoint file is written at the last step.
  59 When :ref:`gmx mdrun` receives an ABRT signal or the third TERM or INT signal,
  60 it will abort directly without writing a new checkpoint file.
  61 When running with MPI, a signal to one of the :ref:`gmx mdrun` ranks
  62 is sufficient, this signal should not be sent to mpirun or
  63 the :ref:`gmx mdrun` process that is the parent of the others.
  64
  65 Running multi-simulations
  66 -------------------------
  67 There are numerous situations where running a related set of
  68 simulations within the same invocation of mdrun are necessary or
  69 useful. Running a replica-exchange simulation requires it, as do
  70 simulations using ensemble-based distance or orientation restraints.
  71 Running a related series of lambda points for a free-energy
  72 computation is also convenient to do this way.
  73
  74 This feature requires
  75 :ref:`configuring |Gromacs| with an external MPI library <mpi-support>`
  76 so that the set of
  77 simulations can communicate. The ``n`` simulations within the set can
  78 use internal MPI parallelism also, so that ``mpirun -np x gmx_mpi mdrun``
  79 for ``x`` a multiple of ``n`` will use ``x/n`` ranks per simulation.
  80
  81 There are two ways of organizing files when running such
  82 simulations. All of the normal mechanisms work in either case,
  83 including ``-deffnm``.
  84
  85 ``-multidir``
  86    You must create a set of ``n`` directories for the ``n`` simulations,
  87    place all the relevant input files in those directories (e.g. named
  88    ``topol.tpr``), and run with
  89    ``mpirun -np x gmx_mpi mdrun -s topol -multidir <names-of-directories>``.
  90    If the order of the simulations
  91    within the multi-simulation is significant, then you are responsible
  92    for ordering their names when you provide them to ``-multidir``. Be
  93    careful with shells that do filename globbing dictionary-style, e.g.
  94    ``dir1 dir10 dir11 ... dir2 ...``. This option is generally the
  95    most convenient to use. ``gmx mdrun -table`` for the group cutoff-scheme
  96    works only in this mode.
  97
  98 Examples running multi-simulations
  99 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 100
 101 ::
 102
 103     mpirun -np 32 gmx_mpi mdrun -multidir a b c d
 104
 105 Starts a multi-simulation on 32 ranks with 4 simulations. The input
 106 and output files are found in directories ``a``, ``b``, ``c``, and ``d``.
 107
 108 ::
 109
 110     mpirun -np 32 gmx_mpi mdrun -multidir a b c d -gputasks 0000000011111111
 111
 112 Starts the same multi-simulation as before. On a machine with two
 113 physical nodes and two GPUs per node, there will be 16 MPI ranks per
 114 node, and 8 MPI ranks per simulation. The 16 MPI ranks doing PP work
 115 on a node are mapped to the GPUs with IDs 0 and 1, even though they
 116 come from more than one simulation. They are mapped in the order
 117 indicated, so that the PP ranks from each simulation use a single
 118 GPU. However, the order ``0101010101010101`` could run faster.
 119
 120 Running replica-exchange simulations
 121 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 122
 123 When running a multi-simulation, using ``gmx mdrun -replex n`` means that a
 124 replica exchange is attempted every given number of steps. The number
 125 of replicas is set with ``-multidir`` option, described
 126 above.  All run input files should use a different value for the
 127 coupling parameter (e.g. temperature), which ascends over the set of
 128 input files. The random seed for replica exchange is set with
 129 ``-reseed``. After every exchange, the velocities are scaled and
 130 neighbor searching is performed. See the Reference Manual for more
 131 details on how replica exchange functions in |Gromacs|.
 132
 133 Controlling the length of the simulation
 134 ----------------------------------------
 135
 136 Normally, the length of an MD simulation is best managed through the
 137 :ref:`mdp` option :mdp:`nsteps`, however there are situations where
 138 more control is useful. :samp:`gmx mdrun -nsteps 100` overrides the :ref:`mdp`
 139 file and executes 100 steps. :samp:`gmx mdrun -maxh 2.5` will terminate the
 140 simulation shortly before 2.5 hours elapse, which can be useful when
 141 running under cluster queues (as long as the queuing system does not
 142 ever suspend the simulation).
 143