docs/user-guide/cmdline.rst

   1 Command-line reference
   2 ======================
   3
   4 .. toctree::
   5    :hidden:
   6    :glob:
   7
   8    /onlinehelp/gmx
   9    /onlinehelp/gmx-*
  10
  11 |Gromacs| includes many tools for preparing, running and analysing
  12 molecular dynamics simulations. These are all structured as part of a single
  13 :command:`gmx` wrapper binary, and invoked with commands like :command:`gmx grompp`.
  14 :ref:`mdrun <gmx mdrun>` is the only other binary that
  15 :ref:`can be built <building just the mdrun binary>`; in the normal
  16 build it can be run with :command:`gmx mdrun`. Documentation for these can
  17 be found at the respective sections below, as well as on man pages (e.g.,
  18 :manpage:`gmx-grompp(1)`) and with :samp:`gmx help {command}` or
  19 :samp:`gmx {command} -h`.
  20
  21 If you've installed an MPI version of |Gromacs|, by default the
  22 :command:`gmx` binary is called :command:`gmx_mpi` and you should adapt
  23 accordingly.
  24
  25 Command-line interface and conventions
  26 --------------------------------------
  27
  28 All |Gromacs| commands require an option before any arguments (i.e., all
  29 command-line arguments need to be preceded by an argument starting with a
  30 dash, and values not starting with a dash are arguments to the preceding
  31 option).  Most options, except for boolean flags, expect an argument (or
  32 multiple in some cases) after the option name.
  33 The argument must be a separate command-line argument, i.e., separated by
  34 space, as in ``-f traj.xtc``.  If more than one argument needs to be given to
  35 an option, they should be similarly separated from each other.
  36 Some options also have default arguments, i.e., just specifying the option
  37 without any argument uses the default argument.
  38 If an option is not specified at all, a default value is used; in the case of
  39 optional files, the default might be not to use that file (see below).
  40
  41 All |Gromacs| command options start with a single dash, whether they are
  42 single- or multiple-letter options.  However, two dashes are also recognized
  43 (starting from 5.1).
  44
  45 In addition to command-specific options, some options are handled by the
  46 :command:`gmx` wrapper, and can be specified for any command.  See
  47 :doc:`wrapper binary help </onlinehelp/gmx>` for the list of such options.
  48 These options are recognized both before the command name (e.g.,
  49 :command:`gmx -quiet grompp`) as well as after the command name (e.g.,
  50 :command:`gmx grompp -quiet`).
  51 There is also a ``-hidden`` option that can be specified in combination with
  52 ``-h`` to show help for advanced/developer-targeted options.
  53
  54 Most analysis commands can process a trajectory with fewer atoms than the
  55 run input or structure file, but only if the trajectory consists of the
  56 first *n* atoms of the run input or structure file.
  57
  58 Handling specific types of command-line options
  59 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  60
  61 boolean options
  62   Boolean flags can be specified like ``-pbc`` and negated like ``-nopbc``.
  63   It is also possible to use an explicit value like ``-pbc no`` and
  64   ``-pbc yes``.
  65 file name options
  66   Options that accept files names have features that support using default file
  67   names (where the default file name is specific to that option):
  68
  69   * If a required option is not set, the default is used.
  70   * If an option is marked optional, the file is not used unless the option
  71     is set (or other conditions make the file required).
  72   * If an option is set, and no file name is provided, the default is used.
  73
  74   All such options will accept file names without a file extension.
  75   The extension is automatically appended in such a case.
  76   When multiple input formats are accepted, such as a generic structure format,
  77   the directory will be searched for files of each type with the supplied or
  78   default name. When no file with a recognized extension is found, an error is given.
  79   For output files with multiple formats, a default file type will be used.
  80
  81   Some file formats can also be read from compressed (:file:`.Z` or
  82   :file:`.gz`) formats.
  83 enum options
  84   Enumerated options (enum) should be used with one of the arguments listed in
  85   the option description. The argument may be abbreviated, and the first match
  86   to the shortest argument in the list will be selected.
  87 vector options
  88   Some options accept a vector of values.  Either 1 or 3 parameters can be
  89   supplied; when only one parameter is supplied the two other values are also
  90   set to this value.
  91 selection options
  92   See :doc:`/onlinehelp/selections`.
  93
  94 Commands by name
  95 ----------------
  96
  97 .. include:: /fragments/byname.rst
  98
  99 Commands by topic
 100 -----------------
 101
 102 .. include:: /fragments/bytopic.rst
 103
 104 Special topics
 105 --------------
 106
 107 The information in these topics is also accessible through
 108 :samp:`gmx help {topic}` on the command line.
 109
 110 .. toctree::
 111
 112    /onlinehelp/selections
 113
 114 .. _command-changes:
 115
 116 Command changes between versions
 117 --------------------------------
 118
 119 Starting from |Gromacs| 5.0, some of the analysis commands (and a few other
 120 commands as well) have changed significantly.
 121 In the process, some old analysis tools have been removed in favor of more
 122 powerful functionality that is available through an alternative tool.
 123 This page documents how to perform different tasks that were possible with the
 124 old tools with the new set of tools.
 125
 126 Many of the new tools mentioned below now accept selections through one or more
 127 command-line options instead of prompting for an index group.  Please see
 128 :doc:`/onlinehelp/selections` additional information on how to use the
 129 selections.
 130
 131 5.0
 132 ^^^
 133
 134 General
 135 .......
 136
 137 Version 5.0 introduced the :command:`gmx` wrapper binary.
 138 For backwards compatibility, this version still creates symbolic links by default for
 139 old tools: e.g., ``g_order <options>`` is equivalent to ``gmx order <options>``, and
 140 ``g_order`` is simply a symbolic link on the file system.
 141
 142 g_bond
 143 ......
 144
 145 This tool has been removed in 5.0. A replacement is :ref:`gmx distance`.
 146
 147 You can provide your existing index file to :ref:`gmx distance`, and it will
 148 calculate the same distances.  The only difference is that ``-blen`` and
 149 ``-tol`` options have different default values, and that you can control the
 150 output histogram with ``-binw``.  ``-aver`` and ``-averdist`` options are not
 151 present.  Instead, you can choose between the different things to calculate
 152 using ``-oav`` (corresponds to ``-d`` with ``-averdist``), ``-oall``
 153 (corresponds to ``-d`` without ``-averdist``), ``-oh`` (corresponds to ``-o``
 154 with ``-aver``), and ``-oallstat`` (corresponds to ``-l`` without ``-aver``).
 155 You can produce any combination of output files.  Compared to ``g_bond``,
 156 ``gmx distance -oall`` is currently missing labels for the output columns.
 157
 158 g_dist
 159 ......
 160
 161 This tool has been removed in 5.0.  A replacement is :ref:`gmx distance` (for
 162 most options) or :ref:`gmx select` (for ``-dist`` or ``-lt``).
 163
 164 If you had index groups A and B in :file:`index.ndx` for ``g_dist``, you can use the
 165 following command to compute the same distance with gmx distance::
 166
 167   gmx distance -n index.ndx -select 'com of group "A" plus com of group "B"' -oxyz -oall
 168
 169 The ``-intra`` switch is replaced with ``-nopbc``.
 170
 171 If you used ``-dist D``, you can do the same calculation with ``gmx select``::
 172
 173   gmx select -n index.ndx -select 'group "B" and within D of com of group "A"' -on/-oi/-os/-olt
 174
 175 You can select the output option that best suits your post-processing needs
 176 (``-olt`` is a replacement for ``g_dist -dist -lt``)
 177
 178 g_sas
 179 .....
 180
 181 This tool has been rewritten in 5.0, and renamed to :ref:`gmx sasa` (the
 182 underlying surface area calculation algorithm is still the same).
 183
 184 The main difference in the new tool is support for selections.  Instead of
 185 prompting for an index group, a (potentially dynamic) selection for the
 186 calculation can be given with ``-surface``.  Any number of output groups can be
 187 given with ``-output``. The total area of the ``-surface`` group is now always
 188 calculated. Please see ``gmx sasa -h``.
 189
 190 The tool no longer automatically divides the surface into hydrophobic and
 191 hydrophilic areas, and there is no ``-f_index`` option.  The same effects can
 192 be obtained by defining suitable selections for ``-output``.  If you want
 193 output that contains the same numbers as with the old tool for a calculation
 194 group A and output group B, you can use ::
 195
 196   gmx sasa -surface 'group "A"' -output '"Hydrophobic" group "A" and charge {-0.2 to 0.2}; "Hydrophilic" group "B" and not charge {-0.2 to 0.2}; "Total" group "B"'
 197
 198 Solvation free energy estimates are now calculated only if separately requested
 199 with ``-odg``, and are written into a separate file.
 200
 201 Output option ``-i`` for a position restraint file is not currently implemented
 202 in the new tool, but would not be very difficult to add if requested.
 203
 204 g_sgangle
 205 .........
 206
 207 This tool has been removed in 5.0. A replacement is :ref:`gmx gangle` (for angle
 208 calculation) and :ref:`gmx distance` (for ``-od``, ``-od1``, ``-od2``).
 209
 210 If you had index groups A and B in index.ndx for ``g_sgangle``, you can use the
 211 following command to compute the same angle with ``gmx gangle``::
 212
 213   gmx gangle -n index.ndx -g1 vector/plane -group1 'group "A"' -g2 vector/plane -group2 'group "B"' -oav
 214
 215 You need to select either ``vector`` or ``plane`` for the ``-g1`` and ``-g2``
 216 options depending on which one your index groups specify.
 217
 218 If you only had a single index group A in index.ndx and you used ``g_sgangle``
 219 ``-z`` or ``-one``, you can use::
 220
 221   gmx gangle -n index.ndx -g1 vector/plane -group1 'group "A"' -g2 z/t0 -oav
 222
 223 For the distances, you can use :ref:`gmx distance` to compute one or more
 224 distances as you want. Both distances between centers of groups or individual
 225 atoms are supported using the new selection syntax.
 226
 227 genbox
 228 ......
 229
 230 This tool has been split to :ref:`gmx solvate` and :ref:`gmx insert-molecules`.
 231
 232 tpbconv
 233 .......
 234
 235 This tool has been renamed :ref:`gmx convert-tpr`.