src/programs/mdrun/tests/refdata/MdrunTest_WritesHelp.xml

   1 <?xml version="1.0"?>
   2 <?xml-stylesheet type="text/xsl" href="referencedata.xsl"?>
   3 <ReferenceData>
   4   <String Name="Help string">SYNOPSIS
   5
   6 gmx [-s [&lt;.tpr&gt;]] [-cpi [&lt;.cpt&gt;]] [-table [&lt;.xvg&gt;]] [-tablep [&lt;.xvg&gt;]]
   7     [-tableb [&lt;.xvg&gt; [...]]] [-rerun [&lt;.xtc/.trr/...&gt;]] [-ei [&lt;.edi&gt;]]
   8     [-multidir [&lt;dir&gt; [...]]] [-awh [&lt;.xvg&gt;]] [-membed [&lt;.dat&gt;]]
   9     [-mp [&lt;.top&gt;]] [-mn [&lt;.ndx&gt;]] [-o [&lt;.trr/.cpt/...&gt;]] [-x [&lt;.xtc/.tng&gt;]]
  10     [-cpo [&lt;.cpt&gt;]] [-c [&lt;.gro/.g96/...&gt;]] [-e [&lt;.edr&gt;]] [-g [&lt;.log&gt;]]
  11     [-dhdl [&lt;.xvg&gt;]] [-field [&lt;.xvg&gt;]] [-tpi [&lt;.xvg&gt;]] [-tpid [&lt;.xvg&gt;]]
  12     [-eo [&lt;.xvg&gt;]] [-px [&lt;.xvg&gt;]] [-pf [&lt;.xvg&gt;]] [-ro [&lt;.xvg&gt;]]
  13     [-ra [&lt;.log&gt;]] [-rs [&lt;.log&gt;]] [-rt [&lt;.log&gt;]] [-mtx [&lt;.mtx&gt;]]
  14     [-if [&lt;.xvg&gt;]] [-swap [&lt;.xvg&gt;]] [-deffnm &lt;string&gt;] [-xvg &lt;enum&gt;]
  15     [-dd &lt;vector&gt;] [-ddorder &lt;enum&gt;] [-npme &lt;int&gt;] [-nt &lt;int&gt;] [-ntmpi &lt;int&gt;]
  16     [-ntomp &lt;int&gt;] [-ntomp_pme &lt;int&gt;] [-pin &lt;enum&gt;] [-pinoffset &lt;int&gt;]
  17     [-pinstride &lt;int&gt;] [-gpu_id &lt;string&gt;] [-gputasks &lt;string&gt;] [-[no]ddcheck]
  18     [-rdd &lt;real&gt;] [-rcon &lt;real&gt;] [-dlb &lt;enum&gt;] [-dds &lt;real&gt;] [-nb &lt;enum&gt;]
  19     [-nstlist &lt;int&gt;] [-[no]tunepme] [-pme &lt;enum&gt;] [-pmefft &lt;enum&gt;]
  20     [-bonded &lt;enum&gt;] [-[no]v] [-pforce &lt;real&gt;] [-[no]reprod] [-cpt &lt;real&gt;]
  21     [-[no]cpnum] [-[no]append] [-nsteps &lt;int&gt;] [-maxh &lt;real&gt;] [-replex &lt;int&gt;]
  22     [-nex &lt;int&gt;] [-reseed &lt;int&gt;]
  23
  24 DESCRIPTION
  25
  26 [THISMODULE] is the main computational chemistry engine within GROMACS.
  27 Obviously, it performs Molecular Dynamics simulations, but it can also perform
  28 Stochastic Dynamics, Energy Minimization, test particle insertion or
  29 (re)calculation of energies. Normal mode analysis is another option. In this
  30 case mdrun builds a Hessian matrix from single conformation. For usual Normal
  31 Modes-like calculations, make sure that the structure provided is properly
  32 energy-minimized. The generated matrix can be diagonalized by [gmx-nmeig].
  33
  34 The mdrun program reads the run input file (-s) and distributes the topology
  35 over ranks if needed. mdrun produces at least four output files. A single log
  36 file (-g) is written. The trajectory file (-o), contains coordinates,
  37 velocities and optionally forces. The structure file (-c) contains the
  38 coordinates and velocities of the last step. The energy file (-e) contains
  39 energies, the temperature, pressure, etc, a lot of these things are also
  40 printed in the log file. Optionally coordinates can be written to a compressed
  41 trajectory file (-x).
  42
  43 The option -dhdl is only used when free energy calculation is turned on.
  44
  45 Running mdrun efficiently in parallel is a complex topic, many aspects of
  46 which are covered in the online User Guide. You should look there for
  47 practical advice on using many of the options available in mdrun.
  48
  49 ED (essential dynamics) sampling and/or additional flooding potentials are
  50 switched on by using the -ei flag followed by an .edi file. The .edi file can
  51 be produced with the make_edi tool or by using options in the essdyn menu of
  52 the WHAT IF program. mdrun produces a .xvg output file that contains
  53 projections of positions, velocities and forces onto selected eigenvectors.
  54
  55 When user-defined potential functions have been selected in the .mdp file the
  56 -table option is used to pass mdrun a formatted table with potential
  57 functions. The file is read from either the current directory or from the
  58 GMXLIB directory. A number of pre-formatted tables are presented in the GMXLIB
  59 dir, for 6-8, 6-9, 6-10, 6-11, 6-12 Lennard-Jones potentials with normal
  60 Coulomb. When pair interactions are present, a separate table for pair
  61 interaction functions is read using the -tablep option.
  62
  63 When tabulated bonded functions are present in the topology, interaction
  64 functions are read using the -tableb option. For each different tabulated
  65 interaction type used, a table file name must be given. For the topology to
  66 work, a file name given here must match a character sequence before the file
  67 extension. That sequence is: an underscore, then a 'b' for bonds, an 'a' for
  68 angles or a 'd' for dihedrals, and finally the matching table number index
  69 used in the topology. Note that, these options are deprecated, and in future
  70 will be available via grompp.
  71
  72 The options -px and -pf are used for writing pull COM coordinates and forces
  73 when pulling is selected in the .mdp file.
  74
  75 The option -membed does what used to be g_membed, i.e. embed a protein into a
  76 membrane. This module requires a number of settings that are provided in a
  77 data file that is the argument of this option. For more details in membrane
  78 embedding, see the documentation in the user guide. The options -mn and -mp
  79 are used to provide the index and topology files used for the embedding.
  80
  81 The option -pforce is useful when you suspect a simulation crashes due to too
  82 large forces. With this option coordinates and forces of atoms with a force
  83 larger than a certain value will be printed to stderr. It will also terminate
  84 the run when non-finite forces are present.
  85
  86 Checkpoints containing the complete state of the system are written at regular
  87 intervals (option -cpt) to the file -cpo, unless option -cpt is set to -1. The
  88 previous checkpoint is backed up to state_prev.cpt to make sure that a recent
  89 state of the system is always available, even when the simulation is
  90 terminated while writing a checkpoint. With -cpnum all checkpoint files are
  91 kept and appended with the step number. A simulation can be continued by
  92 reading the full state from file with option -cpi. This option is intelligent
  93 in the way that if no checkpoint file is found, GROMACS just assumes a normal
  94 run and starts from the first step of the .tpr file. By default the output
  95 will be appending to the existing output files. The checkpoint file contains
  96 checksums of all output files, such that you will never loose data when some
  97 output files are modified, corrupt or removed. There are three scenarios with
  98 -cpi:
  99
 100 * no files with matching names are present: new output files are written
 101
 102 * all files are present with names and checksums matching those stored in the
 103 checkpoint file: files are appended
 104
 105 * otherwise no files are modified and a fatal error is generated
 106
 107 With -noappend new output files are opened and the simulation part number is
 108 added to all output file names. Note that in all cases the checkpoint file
 109 itself is not renamed and will be overwritten, unless its name does not match
 110 the -cpo option.
 111
 112 With checkpointing the output is appended to previously written output files,
 113 unless -noappend is used or none of the previous output files are present
 114 (except for the checkpoint file). The integrity of the files to be appended is
 115 verified using checksums which are stored in the checkpoint file. This ensures
 116 that output can not be mixed up or corrupted due to file appending. When only
 117 some of the previous output files are present, a fatal error is generated and
 118 no old output files are modified and no new output files are opened. The
 119 result with appending will be the same as from a single run. The contents will
 120 be binary identical, unless you use a different number of ranks or dynamic
 121 load balancing or the FFT library uses optimizations through timing.
 122
 123 With option -maxh a simulation is terminated and a checkpoint file is written
 124 at the first neighbor search step where the run time exceeds -maxh*0.99 hours.
 125 This option is particularly useful in combination with setting nsteps to -1
 126 either in the mdp or using the similarly named command line option (although
 127 the latter is deprecated). This results in an infinite run, terminated only
 128 when the time limit set by -maxh is reached (if any) or upon receiving a
 129 signal.
 130
 131 Interactive molecular dynamics (IMD) can be activated by using at least one of
 132 the three IMD switches: The -imdterm switch allows one to terminate the
 133 simulation from the molecular viewer (e.g. VMD). With -imdwait, mdrun pauses
 134 whenever no IMD client is connected. Pulling from the IMD remote can be turned
 135 on by -imdpull. The port mdrun listens to can be altered by -imdport.The file
 136 pointed to by -if contains atom indices and forces if IMD pulling is used.
 137
 138 OPTIONS
 139
 140 Options to specify input files:
 141
 142  -s      [&lt;.tpr&gt;]           (topol.tpr)
 143            Portable xdr run input file
 144  -cpi    [&lt;.cpt&gt;]           (state.cpt)      (Opt.)
 145            Checkpoint file
 146  -table  [&lt;.xvg&gt;]           (table.xvg)      (Opt.)
 147            xvgr/xmgr file
 148  -tablep [&lt;.xvg&gt;]           (tablep.xvg)     (Opt.)
 149            xvgr/xmgr file
 150  -tableb [&lt;.xvg&gt; [...]]     (table.xvg)      (Opt.)
 151            xvgr/xmgr file
 152  -rerun  [&lt;.xtc/.trr/...&gt;]  (rerun.xtc)      (Opt.)
 153            Trajectory: xtc trr cpt gro g96 pdb tng
 154  -ei     [&lt;.edi&gt;]           (sam.edi)        (Opt.)
 155            ED sampling input
 156  -multidir [&lt;dir&gt; [...]]    (rundir)         (Opt.)
 157            Run directory
 158  -awh    [&lt;.xvg&gt;]           (awhinit.xvg)    (Opt.)
 159            xvgr/xmgr file
 160  -membed [&lt;.dat&gt;]           (membed.dat)     (Opt.)
 161            Generic data file
 162  -mp     [&lt;.top&gt;]           (membed.top)     (Opt.)
 163            Topology file
 164  -mn     [&lt;.ndx&gt;]           (membed.ndx)     (Opt.)
 165            Index file
 166
 167 Options to specify output files:
 168
 169  -o      [&lt;.trr/.cpt/...&gt;]  (traj.trr)
 170            Full precision trajectory: trr cpt tng
 171  -x      [&lt;.xtc/.tng&gt;]      (traj_comp.xtc)  (Opt.)
 172            Compressed trajectory (tng format or portable xdr format)
 173  -cpo    [&lt;.cpt&gt;]           (state.cpt)      (Opt.)
 174            Checkpoint file
 175  -c      [&lt;.gro/.g96/...&gt;]  (confout.gro)
 176            Structure file: gro g96 pdb brk ent esp
 177  -e      [&lt;.edr&gt;]           (ener.edr)
 178            Energy file
 179  -g      [&lt;.log&gt;]           (md.log)
 180            Log file
 181  -dhdl   [&lt;.xvg&gt;]           (dhdl.xvg)       (Opt.)
 182            xvgr/xmgr file
 183  -field  [&lt;.xvg&gt;]           (field.xvg)      (Opt.)
 184            xvgr/xmgr file
 185  -tpi    [&lt;.xvg&gt;]           (tpi.xvg)        (Opt.)
 186            xvgr/xmgr file
 187  -tpid   [&lt;.xvg&gt;]           (tpidist.xvg)    (Opt.)
 188            xvgr/xmgr file
 189  -eo     [&lt;.xvg&gt;]           (edsam.xvg)      (Opt.)
 190            xvgr/xmgr file
 191  -px     [&lt;.xvg&gt;]           (pullx.xvg)      (Opt.)
 192            xvgr/xmgr file
 193  -pf     [&lt;.xvg&gt;]           (pullf.xvg)      (Opt.)
 194            xvgr/xmgr file
 195  -ro     [&lt;.xvg&gt;]           (rotation.xvg)   (Opt.)
 196            xvgr/xmgr file
 197  -ra     [&lt;.log&gt;]           (rotangles.log)  (Opt.)
 198            Log file
 199  -rs     [&lt;.log&gt;]           (rotslabs.log)   (Opt.)
 200            Log file
 201  -rt     [&lt;.log&gt;]           (rottorque.log)  (Opt.)
 202            Log file
 203  -mtx    [&lt;.mtx&gt;]           (nm.mtx)         (Opt.)
 204            Hessian matrix
 205  -if     [&lt;.xvg&gt;]           (imdforces.xvg)  (Opt.)
 206            xvgr/xmgr file
 207  -swap   [&lt;.xvg&gt;]           (swapions.xvg)   (Opt.)
 208            xvgr/xmgr file
 209
 210 Other options:
 211
 212  -deffnm &lt;string&gt;
 213            Set the default filename for all file options
 214  -xvg    &lt;enum&gt;             (xmgrace)
 215            xvg plot formatting: xmgrace, xmgr, none
 216  -dd     &lt;vector&gt;           (0 0 0)
 217            Domain decomposition grid, 0 is optimize
 218  -ddorder &lt;enum&gt;            (interleave)
 219            DD rank order: interleave, pp_pme, cartesian
 220  -npme   &lt;int&gt;              (-1)
 221            Number of separate ranks to be used for PME, -1 is guess
 222  -nt     &lt;int&gt;              (0)
 223            Total number of threads to start (0 is guess)
 224  -ntmpi  &lt;int&gt;              (0)
 225            Number of thread-MPI ranks to start (0 is guess)
 226  -ntomp  &lt;int&gt;              (0)
 227            Number of OpenMP threads per MPI rank to start (0 is guess)
 228  -ntomp_pme &lt;int&gt;           (0)
 229            Number of OpenMP threads per MPI rank to start (0 is -ntomp)
 230  -pin    &lt;enum&gt;             (auto)
 231            Whether mdrun should try to set thread affinities: auto, on, off
 232  -pinoffset &lt;int&gt;           (0)
 233            The lowest logical core number to which mdrun should pin the first
 234            thread
 235  -pinstride &lt;int&gt;           (0)
 236            Pinning distance in logical cores for threads, use 0 to minimize
 237            the number of threads per physical core
 238  -gpu_id &lt;string&gt;
 239            List of unique GPU device IDs available to use
 240  -gputasks &lt;string&gt;
 241            List of GPU device IDs, mapping each PP task on each node to a
 242            device
 243  -[no]ddcheck               (yes)
 244            Check for all bonded interactions with DD
 245  -rdd    &lt;real&gt;             (0)
 246            The maximum distance for bonded interactions with DD (nm), 0 is
 247            determine from initial coordinates
 248  -rcon   &lt;real&gt;             (0)
 249            Maximum distance for P-LINCS (nm), 0 is estimate
 250  -dlb    &lt;enum&gt;             (auto)
 251            Dynamic load balancing (with DD): auto, no, yes
 252  -dds    &lt;real&gt;             (0.8)
 253            Fraction in (0,1) by whose reciprocal the initial DD cell size will
 254            be increased in order to provide a margin in which dynamic load
 255            balancing can act while preserving the minimum cell size.
 256  -nb     &lt;enum&gt;             (auto)
 257            Calculate non-bonded interactions on: auto, cpu, gpu
 258  -nstlist &lt;int&gt;             (0)
 259            Set nstlist when using a Verlet buffer tolerance (0 is guess)
 260  -[no]tunepme               (yes)
 261            Optimize PME load between PP/PME ranks or GPU/CPU (only with the
 262            Verlet cut-off scheme)
 263  -pme    &lt;enum&gt;             (auto)
 264            Perform PME calculations on: auto, cpu, gpu
 265  -pmefft &lt;enum&gt;             (auto)
 266            Perform PME FFT calculations on: auto, cpu, gpu
 267  -bonded &lt;enum&gt;             (auto)
 268            Perform bonded calculations on: auto, cpu, gpu
 269  -[no]v                     (no)
 270            Be loud and noisy
 271  -pforce &lt;real&gt;             (-1)
 272            Print all forces larger than this (kJ/mol nm)
 273  -[no]reprod                (no)
 274            Try to avoid optimizations that affect binary reproducibility
 275  -cpt    &lt;real&gt;             (15)
 276            Checkpoint interval (minutes)
 277  -[no]cpnum                 (no)
 278            Keep and number checkpoint files
 279  -[no]append                (yes)
 280            Append to previous output files when continuing from checkpoint
 281            instead of adding the simulation part number to all file names
 282  -nsteps &lt;int&gt;              (-2)
 283            Run this number of steps (-1 means infinite, -2 means use mdp
 284            option, smaller is invalid)
 285  -maxh   &lt;real&gt;             (-1)
 286            Terminate after 0.99 times this time (hours)
 287  -replex &lt;int&gt;              (0)
 288            Attempt replica exchange periodically with this period (steps)
 289  -nex    &lt;int&gt;              (0)
 290            Number of random exchanges to carry out each exchange interval (N^3
 291            is one suggestion).  -nex zero or not specified gives neighbor
 292            replica exchange.
 293  -reseed &lt;int&gt;              (-1)
 294            Seed for replica exchange, -1 is generate a seed
 295 </String>
 296 </ReferenceData>