docs/user-guide/tools.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 Command-line interface and conventions
  22 --------------------------------------
  23
  24 All |Gromacs| commands require an option before any arguments (i.e., all
  25 command-line arguments need to be preceded by an argument starting with a
  26 dash, and values not starting with a dash are arguments to the preceding
  27 option).  Most options, except for boolean flags, expect an argument (or
  28 multiple in some cases) after the option name.
  29 The argument must be a separate command-line argument, i.e., separated by
  30 space, as in ``-f traj.xtc``.  If more than one argument needs to be given to
  31 an option, they should be similarly separated from each other.
  32 Some options also have default arguments, i.e., just specifying the option
  33 without any argument uses the default argument.
  34 If an option is not specified at all, a default value is used; in the case of
  35 optional files, the default might be not to use that file (see below).
  36
  37 All |Gromacs| command options start with a single dash, whether they are
  38 single- or multiple-letter options.  However, two dashes are also recognized
  39 (starting from 5.1).
  40
  41 In addition to command-specific options, some options are handled by the
  42 :command:`gmx` wrapper, and can be specified for any command.  See
  43 :doc:`wrapper binary help </onlinehelp/gmx>` for the list of such options.
  44 These options are recognized both before the command name (e.g.,
  45 :command:`gmx -quiet grompp`) as well as after the command name (e.g.,
  46 :command:`gmx grompp -quiet`).
  47 There is also a ``-hidden`` option that can be specified in combination with
  48 ``-h`` to show help for advanced/developer-targeted options.
  49
  50 Most analysis commands can process a trajectory with fewer atoms than the
  51 run input or structure file, but only if the trajectory consists of the
  52 first *n* atoms of the run input or structure file.
  53
  54 Handling specific types of command-line options
  55 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  56
  57 boolean options
  58   Boolean flags can be specified like ``-pbc`` and negated like ``-nopbc``.
  59   It is also possible to use an explicit value like ``-pbc no`` and
  60   ``-pbc yes``.
  61 file name options
  62   Options that accept files names have features that support using default file
  63   names (where the default file name is specific to that option):
  64
  65   * If a required option is not set, the default is used.
  66   * If an option is marked optional, the file is not used unless the option
  67     is set (or other conditions make the file required).
  68   * If an option is set, and no file name is provided, the default is used.
  69
  70   All such options will accept file names without a file extension.
  71   The extension is automatically appended in such a case.
  72   When multiple input formats are accepted, such as a generic structure format,
  73   the directory will be searched for files of each type with the supplied or
  74   default name. When no file with a recognized extension is found, an error is given.
  75   For output files with multiple formats, a default file type will be used.
  76
  77   Some file formats can also be read from compressed (:file:`.Z` or
  78   :file:`.gz`) formats.
  79 enum options
  80   Enumerated options (enum) should be used with one of the arguments listed in
  81   the option description. The argument may be abbreviated, and the first match
  82   to the shortest argument in the list will be selected.
  83 vector options
  84   Some options accept a vector of values.  Either 1 or 3 parameters can be
  85   supplied; when only one parameter is supplied the two other values are also
  86   set to this value.
  87 selection options
  88   See :doc:`/onlinehelp/selections`.
  89
  90 Commands by name
  91 ----------------
  92
  93 .. include:: /fragments/byname.rst
  94
  95 Commands by topic
  96 -----------------
  97
  98 .. include:: /fragments/bytopic.rst
  99
 100 Special topics
 101 --------------
 102
 103 The information in these topics is also accessible through
 104 :samp:`gmx help {topic}` on the command line.
 105
 106 .. toctree::
 107
 108    /onlinehelp/selections