Merge branch 'release-4-5-patches' of git@git.gromacs.org:gromacs into release-4...

[gromacs/rigid-bodies.git] / man / man1 / mdrun.1

.TH mdrun 1 "Thu 26 Aug 2010" "" "GROMACS suite, VERSION 4.5"
.SH NAME
mdrun - performs a simulation, do a normal mode analysis or an energy minimization

.B VERSION 4.5
.SH SYNOPSIS
\f3mdrun\fP
.BI "\-s" " topol.tpr "
.BI "\-o" " traj.trr "
.BI "\-x" " traj.xtc "
.BI "\-cpi" " state.cpt "
.BI "\-cpo" " state.cpt "
.BI "\-c" " confout.gro "
.BI "\-e" " ener.edr "
.BI "\-g" " md.log "
.BI "\-dhdl" " dhdl.xvg "
.BI "\-field" " field.xvg "
.BI "\-table" " table.xvg "
.BI "\-tablep" " tablep.xvg "
.BI "\-tableb" " table.xvg "
.BI "\-rerun" " rerun.xtc "
.BI "\-tpi" " tpi.xvg "
.BI "\-tpid" " tpidist.xvg "
.BI "\-ei" " sam.edi "
.BI "\-eo" " sam.edo "
.BI "\-j" " wham.gct "
.BI "\-jo" " bam.gct "
.BI "\-ffout" " gct.xvg "
.BI "\-devout" " deviatie.xvg "
.BI "\-runav" " runaver.xvg "
.BI "\-px" " pullx.xvg "
.BI "\-pf" " pullf.xvg "
.BI "\-mtx" " nm.mtx "
.BI "\-dn" " dipole.ndx "
.BI "\-[no]h" ""
.BI "\-[no]version" ""
.BI "\-nice" " int "
.BI "\-deffnm" " string "
.BI "\-xvg" " enum "
.BI "\-[no]pd" ""
.BI "\-dd" " vector "
.BI "\-nt" " int "
.BI "\-npme" " int "
.BI "\-ddorder" " enum "
.BI "\-[no]ddcheck" ""
.BI "\-rdd" " real "
.BI "\-rcon" " real "
.BI "\-dlb" " enum "
.BI "\-dds" " real "
.BI "\-gcom" " int "
.BI "\-[no]v" ""
.BI "\-[no]compact" ""
.BI "\-[no]seppot" ""
.BI "\-pforce" " real "
.BI "\-[no]reprod" ""
.BI "\-cpt" " real "
.BI "\-[no]cpnum" ""
.BI "\-[no]append" ""
.BI "\-maxh" " real "
.BI "\-multi" " int "
.BI "\-replex" " int "
.BI "\-reseed" " int "
.BI "\-[no]ionize" ""
.SH DESCRIPTION
\&The mdrun program is the main computational chemistry engine
\&within GROMACS. Obviously, it performs Molecular Dynamics simulations,
\&but it can also perform Stochastic Dynamics, Energy Minimization,
\&test particle insertion or (re)calculation of energies.
\&Normal mode analysis is another option. In this case mdrun
\&builds a Hessian matrix from single conformation.
\&For usual Normal Modes\-like calculations, make sure that
\&the structure provided is properly energy\-minimized.
\&The generated matrix can be diagonalized by g_nmeig.


\&The mdrun program reads the run input file (\fB \-s\fR)
\&and distributes the topology over nodes if needed.
\&mdrun produces at least four output files.
\&A single log file (\fB \-g\fR) is written, unless the option
\&\fB \-seppot\fR is used, in which case each node writes a log file.
\&The trajectory file (\fB \-o\fR), contains coordinates, velocities and
\&optionally forces.
\&The structure file (\fB \-c\fR) contains the coordinates and
\&velocities of the last step.
\&The energy file (\fB \-e\fR) contains energies, the temperature,
\&pressure, etc, a lot of these things are also printed in the log file.
\&Optionally coordinates can be written to a compressed trajectory file
\&(\fB \-x\fR).


\&The option \fB \-dhdl\fR is only used when free energy calculation is
\&turned on.


\&When mdrun is started using MPI with more than 1 node, parallelization
\&is used. By default domain decomposition is used, unless the \fB \-pd\fR
\&option is set, which selects particle decomposition.


\&With domain decomposition, the spatial decomposition can be set
\&with option \fB \-dd\fR. By default mdrun selects a good decomposition.
\&The user only needs to change this when the system is very inhomogeneous.
\&Dynamic load balancing is set with the option \fB \-dlb\fR,
\&which can give a significant performance improvement,
\&especially for inhomogeneous systems. The only disadvantage of
\&dynamic load balancing is that runs are no longer binary reproducible,
\&but in most cases this is not important.
\&By default the dynamic load balancing is automatically turned on
\&when the measured performance loss due to load imbalance is 5% or more.
\&At low parallelization these are the only important options
\&for domain decomposition.
\&At high parallelization the options in the next two sections
\&could be important for increasing the performace.
\&


\&When PME is used with domain decomposition, separate nodes can
\&be assigned to do only the PME mesh calculation;
\&this is computationally more efficient starting at about 12 nodes.
\&The number of PME nodes is set with option \fB \-npme\fR,
\&this can not be more than half of the nodes.
\&By default mdrun makes a guess for the number of PME
\&nodes when the number of nodes is larger than 11 or performance wise
\&not compatible with the PME grid x dimension.
\&But the user should optimize npme. Performance statistics on this issue
\&are written at the end of the log file.
\&For good load balancing at high parallelization, the PME grid x and y
\&dimensions should be divisible by the number of PME nodes
\&(the simulation will run correctly also when this is not the case).
\&


\&This section lists all options that affect the domain decomposition.
\&

\&Option \fB \-rdd\fR can be used to set the required maximum distance
\&for inter charge\-group bonded interactions.
\&Communication for two\-body bonded interactions below the non\-bonded
\&cut\-off distance always comes for free with the non\-bonded communication.
\&Atoms beyond the non\-bonded cut\-off are only communicated when they have
\&missing bonded interactions; this means that the extra cost is minor
\&and nearly indepedent of the value of \fB \-rdd\fR.
\&With dynamic load balancing option \fB \-rdd\fR also sets
\&the lower limit for the domain decomposition cell sizes.
\&By default \fB \-rdd\fR is determined by mdrun based on
\&the initial coordinates. The chosen value will be a balance
\&between interaction range and communication cost.
\&

\&When inter charge\-group bonded interactions are beyond
\&the bonded cut\-off distance, mdrun terminates with an error message.
\&For pair interactions and tabulated bonds
\&that do not generate exclusions, this check can be turned off
\&with the option \fB \-noddcheck\fR.
\&

\&When constraints are present, option \fB \-rcon\fR influences
\&the cell size limit as well.
\&Atoms connected by NC constraints, where NC is the LINCS order plus 1,
\&should not be beyond the smallest cell size. A error message is
\&generated when this happens and the user should change the decomposition
\&or decrease the LINCS order and increase the number of LINCS iterations.
\&By default mdrun estimates the minimum cell size required for P\-LINCS
\&in a conservative fashion. For high parallelization it can be useful
\&to set the distance required for P\-LINCS with the option \fB \-rcon\fR.
\&

\&The \fB \-dds\fR option sets the minimum allowed x, y and/or z scaling
\&of the cells with dynamic load balancing. mdrun will ensure that
\&the cells can scale down by at least this factor. This option is used
\&for the automated spatial decomposition (when not using \fB \-dd\fR)
\&as well as for determining the number of grid pulses, which in turn
\&sets the minimum allowed cell size. Under certain circumstances
\&the value of \fB \-dds\fR might need to be adjusted to account for
\&high or low spatial inhomogeneity of the system.
\&


\&The option \fB \-gcom\fR can be used to only do global communication
\&every n steps.
\&This can improve performance for highly parallel simulations
\&where this global communication step becomes the bottleneck.
\&For a global thermostat and/or barostat the temperature
\&and/or pressure will also only be updated every \-gcom steps.
\&By default it is set to the minimum of nstcalcenergy and nstlist.


\&With \fB \-rerun\fR an input trajectory can be given for which 
\&forces and energies will be (re)calculated. Neighbor searching will be
\&performed for every frame, unless \fB nstlist\fR is zero
\&(see the \fB .mdp\fR file).


\&ED (essential dynamics) sampling is switched on by using the \fB \-ei\fR
\&flag followed by an \fB .edi\fR file.
\&The \fB .edi\fR file can be produced using options in the essdyn
\&menu of the WHAT IF program. mdrun produces a \fB .edo\fR file that
\&contains projections of positions, velocities and forces onto selected
\&eigenvectors.


\&When user\-defined potential functions have been selected in the
\&\fB .mdp\fR file the \fB \-table\fR option is used to pass mdrun
\&a formatted table with potential functions. The file is read from
\&either the current directory or from the GMXLIB directory.
\&A number of pre\-formatted tables are presented in the GMXLIB dir,
\&for 6\-8, 6\-9, 6\-10, 6\-11, 6\-12 Lennard Jones potentials with
\&normal Coulomb.
\&When pair interactions are present a separate table for pair interaction
\&functions is read using the \fB \-tablep\fR option.


\&When tabulated bonded functions are present in the topology,
\&interaction functions are read using the \fB \-tableb\fR option.
\&For each different tabulated interaction type the table file name is
\&modified in a different way: before the file extension an underscore is
\&appended, then a b for bonds, an a for angles or a d for dihedrals
\&and finally the table number of the interaction type.


\&The options \fB \-px\fR and \fB \-pf\fR are used for writing pull COM
\&coordinates and forces when pulling is selected
\&in the \fB .mdp\fR file.


\&With \fB \-multi\fR multiple systems are simulated in parallel.
\&As many input files are required as the number of systems.
\&The system number is appended to the run input and each output filename,
\&for instance topol.tpr becomes topol0.tpr, topol1.tpr etc.
\&The number of nodes per system is the total number of nodes
\&divided by the number of systems.
\&One use of this option is for NMR refinement: when distance
\&or orientation restraints are present these can be ensemble averaged
\&over all the systems.


\&With \fB \-replex\fR replica exchange is attempted every given number
\&of steps. The number of replicas is set with the \fB \-multi\fR option,
\&see above.
\&All run input files should use a different coupling temperature,
\&the order of the files is not important. The random seed is set with
\&\fB \-reseed\fR. The velocities are scaled and neighbor searching
\&is performed after every exchange.


\&Finally some experimental algorithms can be tested when the
\&appropriate options have been given. Currently under
\&investigation are: polarizability, and X\-Ray bombardments.
\&


\&The option \fB \-pforce\fR is useful when you suspect a simulation
\&crashes due to too large forces. With this option coordinates and
\&forces of atoms with a force larger than a certain value will
\&be printed to stderr.
\&


\&Checkpoints containing the complete state of the system are written
\&at regular intervals (option \fB \-cpt\fR) to the file \fB \-cpo\fR,
\&unless option \fB \-cpt\fR is set to \-1.
\&The previous checkpoint is backed up to \fB state_prev.cpt\fR to
\&make sure that a recent state of the system is always available,
\&even when the simulation is terminated while writing a checkpoint.
\&With \fB \-cpnum\fR all checkpoint files are kept and appended
\&with the step number.
\&A simulation can be continued by reading the full state from file
\&with option \fB \-cpi\fR. This option is intelligent in the way that
\&if no checkpoint file is found, Gromacs just assumes a normal run and
\&starts from the first step of the tpr file. By default the output
\&will be appending to the existing output files. The checkpoint file
\&contains checksums of all output files, such that you will never
\&loose data when some output files are modified, corrupt or removed.
\&There are three scenarios with \fB \-cpi\fR:

\&* no files with matching names are present: new output files are written

\&* all files are present with names and checksums matching those stored
\&in the checkpoint file: files are appended

\&* otherwise no files are modified and a fatal error is generated

\&With \fB \-noappend\fR new output files are opened and the simulation
\&part number is added to all output file names.
\&Note that in all cases the checkpoint file itself is not renamed
\&and will be overwritten, unless its name does not match
\&the \fB \-cpo\fR option.
\&


\&With checkpointing the output is appended to previously written
\&output files, unless \fB \-noappend\fR is used or none of the previous
\&output files are present (except for the checkpoint file).
\&The integrity of the files to be appended is verified using checksums
\&which are stored in the checkpoint file. This ensures that output can
\&not be mixed up or corrupted due to file appending. When only some
\&of the previous output files are present, a fatal error is generated
\&and no old output files are modified and no new output files are opened.
\&The result with appending will be the same as from a single run.
\&The contents will be binary identical, unless you use a different number
\&of nodes or dynamic load balancing or the FFT library uses optimizations
\&through timing.
\&


\&With option \fB \-maxh\fR a simulation is terminated and a checkpoint
\&file is written at the first neighbor search step where the run time
\&exceeds \fB \-maxh\fR*0.99 hours.
\&


\&When mdrun receives a TERM signal, it will set nsteps to the current
\&step plus one. When mdrun receives an INT signal (e.g. when ctrl+C is
\&pressed), it will stop after the next neighbor search step 
\&(with nstlist=0 at the next step).
\&In both cases all the usual output will be written to file.
\&When running with MPI, a signal to one of the mdrun processes
\&is sufficient, this signal should not be sent to mpirun or
\&the mdrun process that is the parent of the others.
\&


\&When mdrun is started with MPI, it does not run niced by default.
.SH FILES
.BI "\-s" " topol.tpr" 
.B Input
 Run input file: tpr tpb tpa 

.BI "\-o" " traj.trr" 
.B Output
 Full precision trajectory: trr trj cpt 

.BI "\-x" " traj.xtc" 
.B Output, Opt.
 Compressed trajectory (portable xdr format) 

.BI "\-cpi" " state.cpt" 
.B Input, Opt.
 Checkpoint file 

.BI "\-cpo" " state.cpt" 
.B Output, Opt.
 Checkpoint file 

.BI "\-c" " confout.gro" 
.B Output
 Structure file: gro g96 pdb etc. 

.BI "\-e" " ener.edr" 
.B Output
 Energy file 

.BI "\-g" " md.log" 
.B Output
 Log file 

.BI "\-dhdl" " dhdl.xvg" 
.B Output, Opt.
 xvgr/xmgr file 

.BI "\-field" " field.xvg" 
.B Output, Opt.
 xvgr/xmgr file 

.BI "\-table" " table.xvg" 
.B Input, Opt.
 xvgr/xmgr file 

.BI "\-tablep" " tablep.xvg" 
.B Input, Opt.
 xvgr/xmgr file 

.BI "\-tableb" " table.xvg" 
.B Input, Opt.
 xvgr/xmgr file 

.BI "\-rerun" " rerun.xtc" 
.B Input, Opt.
 Trajectory: xtc trr trj gro g96 pdb cpt 

.BI "\-tpi" " tpi.xvg" 
.B Output, Opt.
 xvgr/xmgr file 

.BI "\-tpid" " tpidist.xvg" 
.B Output, Opt.
 xvgr/xmgr file 

.BI "\-ei" " sam.edi" 
.B Input, Opt.
 ED sampling input 

.BI "\-eo" " sam.edo" 
.B Output, Opt.
 ED sampling output 

.BI "\-j" " wham.gct" 
.B Input, Opt.
 General coupling stuff 

.BI "\-jo" " bam.gct" 
.B Output, Opt.
 General coupling stuff 

.BI "\-ffout" " gct.xvg" 
.B Output, Opt.
 xvgr/xmgr file 

.BI "\-devout" " deviatie.xvg" 
.B Output, Opt.
 xvgr/xmgr file 

.BI "\-runav" " runaver.xvg" 
.B Output, Opt.
 xvgr/xmgr file 

.BI "\-px" " pullx.xvg" 
.B Output, Opt.
 xvgr/xmgr file 

.BI "\-pf" " pullf.xvg" 
.B Output, Opt.
 xvgr/xmgr file 

.BI "\-mtx" " nm.mtx" 
.B Output, Opt.
 Hessian matrix 

.BI "\-dn" " dipole.ndx" 
.B Output, Opt.
 Index file 

.SH OTHER OPTIONS
.BI "\-[no]h"  "no    "
 Print help info and quit

.BI "\-[no]version"  "no    "
 Print version info and quit

.BI "\-nice"  " int" " 0" 
 Set the nicelevel

.BI "\-deffnm"  " string" " " 
 Set the default filename for all file options

.BI "\-xvg"  " enum" " xmgrace" 
 xvg plot formatting: \fB xmgrace\fR, \fB xmgr\fR or \fB none\fR

.BI "\-[no]pd"  "no    "
 Use particle decompostion

.BI "\-dd"  " vector" " 0 0 0" 
 Domain decomposition grid, 0 is optimize

.BI "\-nt"  " int" " 0" 
 Number of threads to start (0 is guess)

.BI "\-npme"  " int" " \-1" 
 Number of separate nodes to be used for PME, \-1 is guess

.BI "\-ddorder"  " enum" " interleave" 
 DD node order: \fB interleave\fR, \fB pp_pme\fR or \fB cartesian\fR

.BI "\-[no]ddcheck"  "yes   "
 Check for all bonded interactions with DD

.BI "\-rdd"  " real" " 0     " 
 The maximum distance for bonded interactions with DD (nm), 0 is determine from initial coordinates

.BI "\-rcon"  " real" " 0     " 
 Maximum distance for P\-LINCS (nm), 0 is estimate

.BI "\-dlb"  " enum" " auto" 
 Dynamic load balancing (with DD): \fB auto\fR, \fB no\fR or \fB yes\fR

.BI "\-dds"  " real" " 0.8   " 
 Minimum allowed dlb scaling of the DD cell size

.BI "\-gcom"  " int" " \-1" 
 Global communication frequency

.BI "\-[no]v"  "no    "
 Be loud and noisy

.BI "\-[no]compact"  "yes   "
 Write a compact log file

.BI "\-[no]seppot"  "no    "
 Write separate V and dVdl terms for each interaction type and node to the log file(s)

.BI "\-pforce"  " real" " \-1    " 
 Print all forces larger than this (kJ/mol nm)

.BI "\-[no]reprod"  "no    "
 Try to avoid optimizations that affect binary reproducibility

.BI "\-cpt"  " real" " 15    " 
 Checkpoint interval (minutes)

.BI "\-[no]cpnum"  "no    "
 Keep and number checkpoint files

.BI "\-[no]append"  "yes   "
 Append to previous output files when continuing from checkpoint instead of adding the simulation part number to all file names

.BI "\-maxh"  " real" " \-1    " 
 Terminate after 0.99 times this time (hours)

.BI "\-multi"  " int" " 0" 
 Do multiple simulations in parallel

.BI "\-replex"  " int" " 0" 
 Attempt replica exchange every  steps

.BI "\-reseed"  " int" " \-1" 
 Seed for replica exchange, \-1 is generate a seed

.BI "\-[no]ionize"  "no    "
 Do a simulation including the effect of an X\-Ray bombardment on your system

.SH SEE ALSO
.BR gromacs(7)

More information about \fBGROMACS\fR is available at <\fIhttp://www.gromacs.org/\fR>.