docs/user-guide/mdrun-features.md

   1 # Useful `mdrun` features #
   2
   3 This section discusses features in `mdrun` that don't fit well
   4 elsewhere.
   5
   6 ## Re-running a simulation
   7
   8 The rerun feature allows you to take a trajectory file in any
   9 supported format and compute quantities based upon the coordinates in
  10 that file using the model physics supplied in the `topol.tpr` file. It
  11 can be used with command lines like `mdrun -s topol -rerun
  12 traj.trr`. That [.tpr] could be different from the one that generated
  13 the trajectory. This can be used to compute the energy or forces for
  14 exactly the coordinates supplied as input, or to extract quantities
  15 based on subsets of the molecular system (see [gmx convert-tpr] and
  16 [gmx trjconv]).
  17
  18 Neighbour searching is normally performed for every frame in the
  19 trajectory, since [mdrun] can no longer assume anything about how the
  20 structures were generated. If `nstlist` is zero, then only one
  21 neighbour list will be constructed. Naturally, no update or constraint
  22 algorithms are ever used.
  23
  24 ## Running a simulation in reproducible mode
  25
  26 It is generally difficult to run an efficient parallel MD simulation
  27 that is based primarily on floating-point arithmetic and is fully
  28 reproducible. By default, [mdrun] will observe how things are going
  29 and vary how the simulation is conducted in order to optimize
  30 throughput. However, there is a "reproducible mode" available with
  31 `mdrun -reprod` that will systematically eliminate all sources of
  32 variation within that run; repeated invocations on the same input and
  33 hardware will be binary identical. However, running in this mode on
  34 different hardware, or with a different compiler, etc. will not be
  35 reproducible. This should normally only be used when investigating
  36 possible problems.
  37
  38 ## Running multi-simulations
  39
  40 There are numerous situations where running a related set of
  41 simulations within the same invocation of mdrun are necessary or
  42 useful. Running a replica-exchange simulation requires it, as do
  43 simulations using ensemble-based distance or orientation restraints.
  44 Running a related series of lambda points for a free-energy
  45 computation is also convenient to do this way.
  46
  47 This feature requires [configuring GROMACS with an external MPI
  48 library](install-guide.html#mpi-support) so that the set of
  49 simulations can communicate. The `n` simulations within the set can
  50 use internal MPI parallelism also, so that `mpirun -np x mdrun_mpi`
  51 for `x` a multiple of `n` will use `x/n` ranks per simulation.
  52
  53 There are two ways of organizing files when running such
  54 simulations. Most of the normal mechanisms work in either case,
  55 including `-deffnm`.
  56
  57 `-multidir`
  58   You must create a set of `n` directories for the `n` simulations,
  59   place all the relevant input files in those directories (e.g. named
  60   `topol.tpr`), and run with `mpirun -np x mdrun_mpi -s topol
  61   -multidir <names-of-directories>`. If the order of the simulations
  62   within the multi-simulation is significant, then you are responsible
  63   for ordering their names when you provide them to `-multidir`. Be
  64   careful with shells that do filename globbing dictionary-style, e.g.
  65   `dir1 dir10 dir11 ... dir2 ...`. This option is generally the
  66   most convenient to use. `mdrun -table` for the group cutoff-scheme
  67   works only in this mode.
  68
  69 `-multi`
  70   You must organize that the filenames for each simulation in a set of
  71   `n` simulations have an integer `0` through `n-1` appended to
  72   the filename (e.g. `topol2.tpr`), and run with `mpirun -np x mdrun
  73   -multi n -s input`. The order of simulations within the set is
  74   determined by the integer appended.
  75
  76 ### Examples running multi-simulations
  77
  78     mpirun -np 32 mdrun_mpi -multi
  79
  80 Starts a multi-simulation on 32 ranks with as many simulations `n` as
  81 there are files named `topol*.tpr` for integers `0` to `n-1`. Other
  82 input and output files are suffixed similarly.
  83
  84     mpirun -np 32 mdrun_mpi -multidir a b c d
  85
  86 Starts a multi-simulation on 32 ranks with 4 simulations. The input
  87 and output files are found in directories `a`, `b`, `c`, and `d`.
  88
  89     mpirun -np 32 mdrun_mpi -multidir a b c d -gpu_id 0000000011111111
  90
  91 Starts the same multi-simulation as before. On a machine with two
  92 physical nodes and two GPUs per node, there will be 16 MPI ranks per
  93 node, and 8 MPI ranks per simulation. The 16 MPI ranks doing PP work
  94 on a node are mapped to the GPUs with IDs 0 and 1, even though they
  95 come from more than one simulation. They are mapped in the order
  96 indicated, so that the PP ranks from each simulation use a single
  97 GPU. However, the order `0101010101010101` could run faster.
  98
  99 ### Running replica-exchange simulations
 100
 101 When running a multi-simulation, using `mdrun -replex n` means that a
 102 replica exchange is attempted every given number of steps. The number
 103 of replicas is set with the `-multi` or `-multidir` option, described
 104 above.  All run input files should use a different value for the
 105 coupling parameter (e.g. temperature), which ascends over the set of
 106 input files. The random seed for replica exchange is set with
 107 `-reseed`. After every exchange, The velocities are scaled and
 108 neighbor searching is performed. See the Reference Manual for more
 109 details on how replica exchange functions in GROMACS.