Additional selection help

- Explain resindex and resnr keywords in selection help.
- Explain how selection-enabled tools treat -s and -f input files.

Fixes #2083

Change-Id: I93e38c46a2bdb35f057688cf29fb3392712c2443

diff --git a/src/gromacs/selection/selhelp.cpp b/src/gromacs/selection/selhelp.cpp
index 57887d8865258536b4144855192fa660c0835d45..14220e28c291cb9f7315516628a9656b6ce78397 100644 (file)
--- a/src/gromacs/selection/selhelp.cpp
+++ b/src/gromacs/selection/selhelp.cpp
@@ -1,7 +1,7 @@
 /*
  * This file is part of the GROMACS molecular simulation package.
  *
- * Copyright (c) 2009,2010,2011,2012,2013,2014,2015, by the GROMACS development team, led by
+ * Copyright (c) 2009,2010,2011,2012,2013,2014,2015,2016, by the GROMACS development team, led by
  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
  * and including many others, as listed in the AUTHORS file in the
  * top-level source directory and at http://www.gromacs.org.
@@ -163,6 +163,23 @@ const char *const CmdLineHelpText::text[] = {
     "  positions used in selecting atoms by coordinates.",
     "",
     "See the \"positions\" subtopic for more information on these options.",
+    "",
+    "Tools that take selections apply them to a structure/topology and/or",
+    "a trajectory file. If the tool takes both (typically as [TT]-s[tt]",
+    "for structure/topology and [TT]-f[tt] for trajectory), then the",
+    "trajectory file is only used for coordinate information, and all other",
+    "information, such as atom names and residue information, is read from",
+    "the structure/topology file. If the tool only takes a structure file,",
+    "or if only that input parameter is provided, then also the coordinates",
+    "are taken from that file.",
+    "For example, to select atoms from a [TT].pdb[tt]/[TT].gro[tt] file in",
+    "a tool that provides both options, pass it as [TT]-s[tt] (only).",
+    "There is no warning if the trajectory file specifies, e.g., different",
+    "atom names than the structure file. Only the number of atoms is checked.",
+    "Many selection-enabled tools also provide an [TT]-fgroup[tt] option",
+    "to specify the atom indices that are present in the trajectory for cases",
+    "where the trajectory only has a subset of atoms from the",
+    "topology/structure file."
 };
 
 struct EvaluationHelpText

diff --git a/src/gromacs/selection/sm_simple.cpp b/src/gromacs/selection/sm_simple.cpp
index 8f7af415a9f8b74b7f14f9b45bd5e0acb25648c8..ca384efd8144d882ea083bb9dadc4c7f08bf3733 100644 (file)
--- a/src/gromacs/selection/sm_simple.cpp
+++ b/src/gromacs/selection/sm_simple.cpp
@@ -1,7 +1,7 @@
 /*
  * This file is part of the GROMACS molecular simulation package.
  *
- * Copyright (c) 2009,2010,2011,2012,2013,2014,2015, by the GROMACS development team, led by
+ * Copyright (c) 2009,2010,2011,2012,2013,2014,2015,2016, by the GROMACS development team, led by
  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
  * and including many others, as listed in the AUTHORS file in the
  * top-level source directory and at http://www.gromacs.org.
@@ -196,6 +196,28 @@ static const char *const help_atomname[] = {
     "keywords."
 };
 
+//! Help title for residue index selection keywords.
+static const char        helptitle_resindex[] = "Selecting atoms by residue number";
+//! Help text for residue index selection keywords.
+static const char *const help_resindex[] = {
+    "::",
+    "",
+    "  resnr",
+    "  resid",
+    "  resindex",
+    "  residue",
+    "",
+    "[TT]resnr[tt] selects atoms using the residue numbering in the input",
+    "file. [TT]resid[tt] is synonym for this keyword for VMD compatibility.",
+    "",
+    "[TT]resindex N[tt] selects the [TT]N[tt]th residue starting from the",
+    "beginning of the input file. This is useful for uniquely identifying",
+    "residues if there are duplicate numbers in the input file (e.g., in",
+    "multiple chains).",
+    "[TT]residue[tt] is a synonym for [TT]resindex[tt]. This allows",
+    "[TT]same residue as[tt] to work as expected."
+};
+
 /** Selection method data for \p all selection keyword. */
 gmx_ana_selmethod_t sm_all = {
     "all", GROUP_VALUE, 0,
@@ -250,6 +272,7 @@ gmx_ana_selmethod_t sm_resnr = {
     NULL,
     &evaluate_resnr,
     NULL,
+    {NULL, helptitle_resindex, asize(help_resindex), help_resindex}
 };
 
 /** Selection method data for \p resindex selection keyword. */
@@ -264,6 +287,7 @@ gmx_ana_selmethod_t sm_resindex = {
     NULL,
     &evaluate_resindex,
     NULL,
+    {NULL, helptitle_resindex, asize(help_resindex), help_resindex}
 };
 
 /** Selection method data for \p molindex selection keyword. */