Additional selection examples

Add some examples with explicit tool references, in particular for how
to use selections with tools that require pairs of atoms (gmx distance
and vector options of gmx gangle).

Add examples to explain the difference between the various
center-of-mass keywords.

Fix old note about default index groups with selection tools
(defselections.dat is not currently used).

Change-Id: Ic9e723e6dd2f46f8f0f5a7e1c4127994577acc3e

diff --git a/src/gromacs/selection/selhelp.cpp b/src/gromacs/selection/selhelp.cpp
index e521f1bc3084639ee831afbbf75c7dbc86d43eea..746b4394eff038867ab5577a367f4a53c7d5432b 100644 (file)
--- a/src/gromacs/selection/selhelp.cpp
+++ b/src/gromacs/selection/selhelp.cpp
@@ -152,10 +152,9 @@ const char *const CmdLineHelpText::text[] = {
     "To use groups from a traditional index file, use argument [TT]-n[tt]",
     "to provide a file. See the \"syntax\" subtopic for how to use them.",
     "If this option is not provided, default groups are generated.",
-    "The default groups are generated by reading selections from a file",
-    "[TT]defselection.dat[tt]. If such a file is found in the current",
-    "directory, it is used instead of the one provided by default.[PAR]",
-
+    "The default groups are generated with the same logic as for",
+    "non-selection tools.",
+    "",
     "Depending on the tool, two additional command-line arguments may be",
     "available to control the behavior:",
     "",
@@ -219,44 +218,90 @@ const char        ExamplesHelpText::name[]  = "examples";
 const char        ExamplesHelpText::title[] =
     "Selection examples";
 const char *const ExamplesHelpText::text[] = {
-    // TODO: Once there are more tools available, use examples that invoke
-    // tools and explain what the selections do in those tools.
-    "Below, examples of increasingly complex selections are given.[PAR]",
-
-    "Selection of all water oxygens::",
+    "Below, examples of different types of selections are given.",
     "",
-    "  resname SOL and name OW",
+    "* Selection of all water oxygens::",
     "",
-
-    "Centers of mass of residues 1 to 5 and 10::",
+    "    resname SOL and name OW",
     "",
-    "  res_com of resnr 1 to 5 10",
+    "* Centers of mass of residues 1 to 5 and 10::",
     "",
-
-    "All atoms farther than 1 nm of a fixed position::",
+    "    res_com of resnr 1 to 5 10",
     "",
-    "  not within 1 of [1.2, 3.1, 2.4]",
+    "* All atoms farther than 1 nm of a fixed position::",
     "",
-
-    "All atoms of a residue LIG within 0.5 nm of a protein (with a custom name)::",
+    "    not within 1 of [1.2, 3.1, 2.4]",
     "",
-    "  \"Close to protein\" resname LIG and within 0.5 of group \"Protein\"",
+    "* All atoms of a residue LIG within 0.5 nm of a protein (with a custom name)::",
     "",
-
-    "All protein residues that have at least one atom within 0.5 nm of a residue LIG::",
+    "    \"Close to protein\" resname LIG and within 0.5 of group \"Protein\"",
     "",
-    "  group \"Protein\" and same residue as within 0.5 of resname LIG",
+    "* All protein residues that have at least one atom within 0.5 nm of a residue LIG::",
     "",
-
-    "All RES residues whose COM is between 2 and 4 nm from the COM of all of them::",
+    "    group \"Protein\" and same residue as within 0.5 of resname LIG",
     "",
-    "  rdist = res_com distance from com of resname RES",
-    "  resname RES and rdist >= 2 and rdist <= 4",
+    "* All RES residues whose COM is between 2 and 4 nm from the COM of all of them::",
     "",
-
-    "Selection like C1 C2 C2 C3 C3 C4 ... C8 C9 (e.g., for g_bond)::",
+    "    rdist = res_com distance from com of resname RES",
+    "    resname RES and rdist >= 2 and rdist <= 4",
+    "",
+    // TODO: Make it possible to use links below.
+    "* Selection like with duplicate atoms like C1 C2 C2 C3 C3 C4 ... C8 C9::",
+    "",
+    "    name \"C[1-8]\" merge name \"C[2-9]\"",
+    "",
+    "  This can be used with [TT]gmx distance[tt] to compute C1-C2, C2-C3 etc.",
+    "  distances.",
+    "",
+    "* Selection with atoms in order C2 C1::",
+    "",
+    "    name C1 C2 permute 2 1",
+    "",
+    "  This can be used with [TT]gmx gangle[tt] to get C2->C1 vectors instead of",
+    "  C1->C2.",
+    "",
+    "* Selection with COMs of two index groups::",
+    "",
+    "    com of group 1 plus com of group 2",
+    "",
+    "  This can be used with [TT]gmx distance[tt] to compute the distance between",
+    "  these two COMs.",
+    "",
+    "* Fixed vector along x (can be used as a reference with [TT]gmx gangle[tt])::",
+    "",
+    "    [0, 0, 0] plus [1, 0, 0]",
+    "",
+    "* The following examples explain the difference between the various",
+    "  position types.  This selection selects a position for each residue",
+    "  where any of the three atoms C[123] has [TT]x < 2[tt].  The positions",
+    "  are computed as the COM of all three atoms.",
+    "  This is the default behavior if you just write [TT]res_com of[tt]. ::",
+    "",
+    "    part_res_com of name C1 C2 C3 and x < 2",
+    "",
+    "  This selection does the same, but the positions are computed as COM",
+    "  positions of whole residues::",
+    "",
+    "    whole_res_com of name C1 C2 C3 and x < 2",
+    "",
+    "  Finally, this selection selects the same residues, but the positions",
+    "  are computed as COM of exactly those atoms atoms that match the",
+    "  [TT]x < 2[tt] criterion::",
+    "",
+    "    dyn_res_com of name C1 C2 C3 and x < 2",
+    "",
+    "* Without the [TT]of[tt] keyword, the default behavior is different from",
+    "  above, but otherwise the rules are the same::",
+    "",
+    "    name C1 C2 C3 and res_com x < 2",
+    "",
+    "  works as if [TT]whole_res_com[tt] was specified, and selects the three",
+    "  atoms from residues whose COM satisfiex [TT]x < 2[tt].",
+    "  Using ::",
+    "",
+    "    name C1 C2 C3 and part_res_com x < 2",
     "",
-    "  name \"C[1-8]\" merge name \"C[2-9]\"",
+    "  instead selects residues based on the COM computed from the C[123] atoms.",
 };
 
 struct KeywordsHelpText