From: Teemu Murtola Date: Tue, 23 Jun 2015 06:49:40 +0000 (+0300) Subject: Move documentation on tool changes from wiki X-Git-Url: http://biod.pnpi.spb.ru/gitweb/?a=commitdiff_plain;h=30ee04e42d354c9a5d78be28c5847e71397fba56;p=alexxy%2Fgromacs.git Move documentation on tool changes from wiki Move the text on tool changes from the wiki page to the user guide, where it is much easier to maintain together with the code changes. For now, this only contains the 5.0-era changes more or less directly from the wiki, but I will improve this (as a separate change) once I have more time. Change-Id: I4ccea605783de2949221d604e232b36c726dcaa7 --- diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 9c39281249..042f367716 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -122,7 +122,7 @@ if (SPHINX_FOUND) user-guide/mdrun-performance.rst user-guide/mdp-options.rst user-guide/file-formats.rst - user-guide/tools.rst + user-guide/cmdline.rst user-guide/environment-variables.rst user-guide/plotje.gif user-guide/xvgr.gif diff --git a/docs/user-guide/cmdline.rst b/docs/user-guide/cmdline.rst new file mode 100644 index 0000000000..fe6231a9c6 --- /dev/null +++ b/docs/user-guide/cmdline.rst @@ -0,0 +1,235 @@ +Command-line reference +====================== + +.. toctree:: + :hidden: + :glob: + + /onlinehelp/gmx + /onlinehelp/gmx-* + +|Gromacs| includes many tools for preparing, running and analysing +molecular dynamics simulations. These are all structured as part of a single +:command:`gmx` wrapper binary, and invoked with commands like :command:`gmx grompp`. +:ref:`mdrun ` is the only other binary that +:ref:`can be built `; in the normal +build it can be run with :command:`gmx mdrun`. Documentation for these can +be found at the respective sections below, as well as on man pages (e.g., +:manpage:`gmx-grompp(1)`) and with :samp:`gmx help {command}` or +:samp:`gmx {command} -h`. + +If you've installed an MPI version of |Gromacs|, by default the +:command:`gmx` binary is called :command:`gmx_mpi` and you should adapt +accordingly. + +Command-line interface and conventions +-------------------------------------- + +All |Gromacs| commands require an option before any arguments (i.e., all +command-line arguments need to be preceded by an argument starting with a +dash, and values not starting with a dash are arguments to the preceding +option). Most options, except for boolean flags, expect an argument (or +multiple in some cases) after the option name. +The argument must be a separate command-line argument, i.e., separated by +space, as in ``-f traj.xtc``. If more than one argument needs to be given to +an option, they should be similarly separated from each other. +Some options also have default arguments, i.e., just specifying the option +without any argument uses the default argument. +If an option is not specified at all, a default value is used; in the case of +optional files, the default might be not to use that file (see below). + +All |Gromacs| command options start with a single dash, whether they are +single- or multiple-letter options. However, two dashes are also recognized +(starting from 5.1). + +In addition to command-specific options, some options are handled by the +:command:`gmx` wrapper, and can be specified for any command. See +:doc:`wrapper binary help ` for the list of such options. +These options are recognized both before the command name (e.g., +:command:`gmx -quiet grompp`) as well as after the command name (e.g., +:command:`gmx grompp -quiet`). +There is also a ``-hidden`` option that can be specified in combination with +``-h`` to show help for advanced/developer-targeted options. + +Most analysis commands can process a trajectory with fewer atoms than the +run input or structure file, but only if the trajectory consists of the +first *n* atoms of the run input or structure file. + +Handling specific types of command-line options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +boolean options + Boolean flags can be specified like ``-pbc`` and negated like ``-nopbc``. + It is also possible to use an explicit value like ``-pbc no`` and + ``-pbc yes``. +file name options + Options that accept files names have features that support using default file + names (where the default file name is specific to that option): + + * If a required option is not set, the default is used. + * If an option is marked optional, the file is not used unless the option + is set (or other conditions make the file required). + * If an option is set, and no file name is provided, the default is used. + + All such options will accept file names without a file extension. + The extension is automatically appended in such a case. + When multiple input formats are accepted, such as a generic structure format, + the directory will be searched for files of each type with the supplied or + default name. When no file with a recognized extension is found, an error is given. + For output files with multiple formats, a default file type will be used. + + Some file formats can also be read from compressed (:file:`.Z` or + :file:`.gz`) formats. +enum options + Enumerated options (enum) should be used with one of the arguments listed in + the option description. The argument may be abbreviated, and the first match + to the shortest argument in the list will be selected. +vector options + Some options accept a vector of values. Either 1 or 3 parameters can be + supplied; when only one parameter is supplied the two other values are also + set to this value. +selection options + See :doc:`/onlinehelp/selections`. + +Commands by name +---------------- + +.. include:: /fragments/byname.rst + +Commands by topic +----------------- + +.. include:: /fragments/bytopic.rst + +Special topics +-------------- + +The information in these topics is also accessible through +:samp:`gmx help {topic}` on the command line. + +.. toctree:: + + /onlinehelp/selections + +.. _command-changes: + +Command changes between versions +-------------------------------- + +Starting from |Gromacs| 5.0, some of the analysis commands (and a few other +commands as well) have changed significantly. +In the process, some old analysis tools have been removed in favor of more +powerful functionality that is available through an alternative tool. +This page documents how to perform different tasks that were possible with the +old tools with the new set of tools. + +Many of the new tools mentioned below now accept selections through one or more +command-line options instead of prompting for an index group. Please see +:doc:`/onlinehelp/selections` additional information on how to use the +selections. + +5.0 +^^^ + +General +....... + +Version 5.0 introduced the :command:`gmx` wrapper binary. +For backwards compatibility, this version still creates symbolic links by default for +old tools: e.g., ``g_order `` is equivalent to ``gmx order ``, and +``g_order`` is simply a symbolic link on the file system. + +g_bond +...... + +This tool has been removed in 5.0. A replacement is :ref:`gmx distance`. + +You can provide your existing index file to :ref:`gmx distance`, and it will +calculate the same distances. The only difference is that ``-blen`` and +``-tol`` options have different default values, and that you can control the +output histogram with ``-binw``. ``-aver`` and ``-averdist`` options are not +present. Instead, you can choose between the different things to calculate +using ``-oav`` (corresponds to ``-d`` with ``-averdist``), ``-oall`` +(corresponds to ``-d`` without ``-averdist``), ``-oh`` (corresponds to ``-o`` +with ``-aver``), and ``-oallstat`` (corresponds to ``-l`` without ``-aver``). +You can produce any combination of output files. Compared to ``g_bond``, +``gmx distance -oall`` is currently missing labels for the output columns. + +g_dist +...... + +This tool has been removed in 5.0. A replacement is :ref:`gmx distance` (for +most options) or :ref:`gmx select` (for ``-dist`` or ``-lt``). + +If you had index groups A and B in :file:`index.ndx` for ``g_dist``, you can use the +following command to compute the same distance with gmx distance:: + + gmx distance -n index.ndx -select 'com of group "A" plus com of group "B"' -oxyz -oall + +The ``-intra`` switch is replaced with ``-nopbc``. + +If you used ``-dist D``, you can do the same calculation with ``gmx select``:: + + gmx select -n index.ndx -select 'group "B" and within D of com of group "A"' -on/-oi/-os/-olt + +You can select the output option that best suits your post-processing needs +(``-olt`` is a replacement for ``g_dist -dist -lt``) + +g_sas +..... + +This tool has been rewritten in 5.0, and renamed to :ref:`gmx sasa` (the +underlying surface area calculation algorithm is still the same). + +The main difference in the new tool is support for selections. Instead of +prompting for an index group, a (potentially dynamic) selection for the +calculation can be given with ``-surface``. Any number of output groups can be +given with ``-output``. The total area of the ``-surface`` group is now always +calculated. Please see ``gmx sasa -h``. + +The tool no longer automatically divides the surface into hydrophobic and +hydrophilic areas, and there is no ``-f_index`` option. The same effects can +be obtained by defining suitable selections for ``-output``. If you want +output that contains the same numbers as with the old tool for a calculation +group A and output group B, you can use :: + + 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"' + +Solvation free energy estimates are now calculated only if separately requested +with ``-odg``, and are written into a separate file. + +Output option ``-i`` for a position restraint file is not currently implemented +in the new tool, but would not be very difficult to add if requested. + +g_sgangle +......... + +This tool has been removed in 5.0. A replacement is :ref:`gmx gangle` (for angle +calculation) and :ref:`gmx distance` (for ``-od``, ``-od1``, ``-od2``). + +If you had index groups A and B in index.ndx for ``g_sgangle``, you can use the +following command to compute the same angle with ``gmx gangle``:: + + gmx gangle -n index.ndx -g1 vector/plane -group1 'group "A"' -g2 vector/plane -group2 'group "B"' -oav + +You need to select either ``vector`` or ``plane`` for the ``-g1`` and ``-g2`` +options depending on which one your index groups specify. + +If you only had a single index group A in index.ndx and you used ``g_sgangle`` +``-z`` or ``-one``, you can use:: + + gmx gangle -n index.ndx -g1 vector/plane -group1 'group "A"' -g2 z/t0 -oav + +For the distances, you can use :ref:`gmx distance` to compute one or more +distances as you want. Both distances between centers of groups or individual +atoms are supported using the new selection syntax. + +genbox +...... + +This tool has been split to :ref:`gmx solvate` and :ref:`gmx insert-molecules`. + +tpbconv +....... + +This tool has been renamed :ref:`gmx convert-tpr`. diff --git a/docs/user-guide/index.rst b/docs/user-guide/index.rst index d1d7f5aef2..df631e5398 100644 --- a/docs/user-guide/index.rst +++ b/docs/user-guide/index.rst @@ -25,5 +25,5 @@ For background on algorithms and implementations, see the mdrun-performance mdp-options file-formats - tools + cmdline environment-variables diff --git a/docs/user-guide/tools.rst b/docs/user-guide/tools.rst deleted file mode 100644 index 4f193f3abb..0000000000 --- a/docs/user-guide/tools.rst +++ /dev/null @@ -1,108 +0,0 @@ -Command-line reference -====================== - -.. toctree:: - :hidden: - :glob: - - /onlinehelp/gmx - /onlinehelp/gmx-* - -|Gromacs| includes many tools for preparing, running and analysing -molecular dynamics simulations. These are all structured as part of a single -:command:`gmx` wrapper binary, and invoked with commands like :command:`gmx grompp`. -:ref:`mdrun ` is the only other binary that -:ref:`can be built `; in the normal -build it can be run with :command:`gmx mdrun`. Documentation for these can -be found at the respective sections below, as well as on man pages (e.g., -:manpage:`gmx-grompp(1)`) and with :samp:`gmx help {command}` or -:samp:`gmx {command} -h`. - -Command-line interface and conventions --------------------------------------- - -All |Gromacs| commands require an option before any arguments (i.e., all -command-line arguments need to be preceded by an argument starting with a -dash, and values not starting with a dash are arguments to the preceding -option). Most options, except for boolean flags, expect an argument (or -multiple in some cases) after the option name. -The argument must be a separate command-line argument, i.e., separated by -space, as in ``-f traj.xtc``. If more than one argument needs to be given to -an option, they should be similarly separated from each other. -Some options also have default arguments, i.e., just specifying the option -without any argument uses the default argument. -If an option is not specified at all, a default value is used; in the case of -optional files, the default might be not to use that file (see below). - -All |Gromacs| command options start with a single dash, whether they are -single- or multiple-letter options. However, two dashes are also recognized -(starting from 5.1). - -In addition to command-specific options, some options are handled by the -:command:`gmx` wrapper, and can be specified for any command. See -:doc:`wrapper binary help ` for the list of such options. -These options are recognized both before the command name (e.g., -:command:`gmx -quiet grompp`) as well as after the command name (e.g., -:command:`gmx grompp -quiet`). -There is also a ``-hidden`` option that can be specified in combination with -``-h`` to show help for advanced/developer-targeted options. - -Most analysis commands can process a trajectory with fewer atoms than the -run input or structure file, but only if the trajectory consists of the -first *n* atoms of the run input or structure file. - -Handling specific types of command-line options -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -boolean options - Boolean flags can be specified like ``-pbc`` and negated like ``-nopbc``. - It is also possible to use an explicit value like ``-pbc no`` and - ``-pbc yes``. -file name options - Options that accept files names have features that support using default file - names (where the default file name is specific to that option): - - * If a required option is not set, the default is used. - * If an option is marked optional, the file is not used unless the option - is set (or other conditions make the file required). - * If an option is set, and no file name is provided, the default is used. - - All such options will accept file names without a file extension. - The extension is automatically appended in such a case. - When multiple input formats are accepted, such as a generic structure format, - the directory will be searched for files of each type with the supplied or - default name. When no file with a recognized extension is found, an error is given. - For output files with multiple formats, a default file type will be used. - - Some file formats can also be read from compressed (:file:`.Z` or - :file:`.gz`) formats. -enum options - Enumerated options (enum) should be used with one of the arguments listed in - the option description. The argument may be abbreviated, and the first match - to the shortest argument in the list will be selected. -vector options - Some options accept a vector of values. Either 1 or 3 parameters can be - supplied; when only one parameter is supplied the two other values are also - set to this value. -selection options - See :doc:`/onlinehelp/selections`. - -Commands by name ----------------- - -.. include:: /fragments/byname.rst - -Commands by topic ------------------ - -.. include:: /fragments/bytopic.rst - -Special topics --------------- - -The information in these topics is also accessible through -:samp:`gmx help {topic}` on the command line. - -.. toctree:: - - /onlinehelp/selections diff --git a/src/programs/legacymodules.cpp b/src/programs/legacymodules.cpp index 20bd108c44..d2d0a12600 100644 --- a/src/programs/legacymodules.cpp +++ b/src/programs/legacymodules.cpp @@ -106,7 +106,7 @@ class ObsoleteToolModule : public gmx::CommandLineModuleInterface { std::fprintf(stderr, "This tool is no longer present in GROMACS. Please see\n" - " http://www.gromacs.org/Documentation/How-tos/Tool_Changes_for_5.0\n" + " http://jenkins.gromacs.org/job/Documentation_Nightly_master/javadoc/user-guide/cmdline.html#command-changes\n" "for ideas how to perform the same tasks with the " "new tools.\n"); }