src/gmxlib/selection/selhelp.c

   1 /*
   2  *
   3  *                This source code is part of
   4  *
   5  *                 G   R   O   M   A   C   S
   6  *
   7  *          GROningen MAchine for Chemical Simulations
   8  *
   9  * Written by David van der Spoel, Erik Lindahl, Berk Hess, and others.
  10  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
  11  * Copyright (c) 2001-2009, The GROMACS development team,
  12  * check out http://www.gromacs.org for more information.
  13
  14  * This program is free software; you can redistribute it and/or
  15  * modify it under the terms of the GNU General Public License
  16  * as published by the Free Software Foundation; either version 2
  17  * of the License, or (at your option) any later version.
  18  *
  19  * If you want to redistribute modifications, please consider that
  20  * scientific software is very special. Version control is crucial -
  21  * bugs must be traceable. We will be happy to consider code for
  22  * inclusion in the official distribution, but derived work must not
  23  * be called official GROMACS. Details are found in the README & COPYING
  24  * files - if they are missing, get the official version at www.gromacs.org.
  25  *
  26  * To help us fund GROMACS development, we humbly ask that you cite
  27  * the papers on the package - you can find them in the top README file.
  28  *
  29  * For more info, check our website at http://www.gromacs.org
  30  */
  31 /*! \internal \file
  32  * \brief Implementation of functions in selhelp.c.
  33  */
  34 #include <macros.h>
  35 #include <string2.h>
  36 #include <wman.h>
  37
  38 #include "selcollection.h"
  39 #include "selmethod.h"
  40 #include "selhelp.h"
  41 #include "symrec.h"
  42
  43 typedef struct {
  44     const char  *topic;
  45     int          nl;
  46     const char **text;
  47 } t_selection_help_item;
  48
  49 static const char *help_common[] = {
  50     "SELECTION HELP[PAR]",
  51
  52     "Please read the subtopic pages (available through \"help topic\") for",
  53     "more information.",
  54 };
  55
  56 static const char *help_cmdline[] = {
  57     "SELECTION COMMAND-LINE ARGUMENTS[PAR]",
  58
  59     "There are two alternative command-line arguments for specifying",
  60     "selections:[BR]",
  61     "1. [TT]-select[tt] can be used to specify the complete selection as a",
  62     "string on the command line.[BR]",
  63     "2. [TT]-sf[tt] can be used to specify a file name from which the",
  64     "selection is read.[BR]",
  65     "If both options are specified, [TT]-select[tt] takes precedence.",
  66     "If neither of the above is present, the user is prompted to type the",
  67     "selection on the standard input (a pipe can also be used to provide",
  68     "the selections in this case).",
  69     "This is also done if an empty string is passed to [TT]-select[tt].[PAR]",
  70
  71     "Option [TT]-n[tt] can be used to provide an index file.",
  72     "If no index file is provided, default groups are generated.",
  73     "In both cases, the user can also select an index group instead of",
  74     "writing a full selection.",
  75     "The default groups are generated by reading selections from a file",
  76     "[TT]defselection.dat[tt]. If such a file is found in the current",
  77     "directory, it is used instead of the one provided by default.[PAR]",
  78
  79     "Depending on the tool, two additional command-line arguments may be",
  80     "available to control the behavior:[BR]",
  81     "1. [TT]-seltype[tt] can be used to specify the default type of",
  82     "positions to calculate for each selection.[BR]",
  83     "2. [TT]-selrpos[tt] can be used to specify the default type of",
  84     "positions used in selecting atoms by coordinates.[BR]",
  85     "See \"help positions\" for more information on these options.",
  86 };
  87
  88 static const char *help_eval[] = {
  89     "SELECTION EVALUATION AND OPTIMIZATION[PAR]",
  90
  91     "Boolean evaluation proceeds from left to right and is short-circuiting",
  92     "i.e., as soon as it is known whether an atom will be selected, the",
  93     "remaining expressions are not evaluated at all.",
  94     "This can be used to optimize the selections: you should write the",
  95     "most restrictive and/or the most inexpensive expressions first in",
  96     "boolean expressions.",
  97     "The relative ordering between dynamic and static expressions does not",
  98     "matter: all static expressions are evaluated only once, before the first",
  99     "frame, and the result becomes the leftmost expression.[PAR]",
 100
 101     "Another point for optimization is in common subexpressions: they are not",
 102     "automatically recognized, but can be manually optimized by the use of",
 103     "variables. This can have a big impact on the performance of complex",
 104     "selections, in particular if you define several index groups like this:",
 105     "  [TT]rdist = distance from com of resnr 1 to 5;[tt][BR]",
 106     "  [TT]resname RES and rdist < 2;[tt][BR]",
 107     "  [TT]resname RES and rdist < 4;[tt][BR]",
 108     "  [TT]resname RES and rdist < 6;[tt][BR]",
 109     "Without the variable assignment, the distances would be evaluated three",
 110     "times, although they are exactly the same within each selection.",
 111     "Anything assigned into a variable becomes a common subexpression that",
 112     "is evaluated only once during a frame.",
 113     "Currently, in some cases the use of variables can actually lead to a small",
 114     "performance loss because of the checks necessary to determine for which",
 115     "atoms the expression has already been evaluated, but this should not be",
 116     "a major problem.",
 117 };
 118
 119 static const char *help_keywords[] = {
 120     "SELECTION KEYWORDS[PAR]",
 121
 122     "The following selection keywords are currently available.",
 123     "For keywords marked with a star, additional help is available through",
 124     "\"help KEYWORD\", where KEYWORD is the name of the keyword.",
 125 };
 126
 127 static const char *help_limits[] = {
 128     "SELECTION LIMITATIONS[PAR]",
 129
 130     "Arithmetic expressions are not implemented.[PAR]",
 131
 132     "Some analysis programs may require a special structure for the input",
 133     "selections (e.g., [TT]g_angle[tt] requires the index group to be made",
 134     "of groups of three or four atoms).",
 135     "For such programs, it is up to the user to provide a proper selection",
 136     "expression that always returns such positions.[PAR]",
 137 };
 138
 139 static const char *help_positions[] = {
 140     "SPECIFYING POSITIONS[PAR]",
 141
 142     "Possible ways of specifying positions in selections are:[PAR]",
 143
 144     "1. A constant position can be defined as [TT](XX, YY, ZZ)[tt], where",
 145     "[TT]XX[tt], [TT]YY[tt] and [TT]ZZ[tt] are real numbers.[PAR]",
 146
 147     "2. [TT]com of ATOM_EXPR [pbc][tt] or [TT]cog of ATOM_EXPR [pbc][tt]",
 148     "calculate the center of mass/geometry of [TT]ATOM_EXPR[tt]. If",
 149     "[TT]pbc[tt] is specified, the center is calculated iteratively to try",
 150     "to deal with cases where [TT]ATOM_EXPR[tt] wraps around periodic",
 151     "boundary conditions.[PAR]",
 152
 153     "3. [TT]POSTYPE of ATOM_EXPR[tt] calculates the specified positions for",
 154     "the atoms in [TT]ATOM_EXPR[tt].",
 155     "[TT]POSTYPE[tt] can be [TT]atom[tt], [TT]res_com[tt], [TT]res_cog[tt],",
 156     "[TT]mol_com[tt] or [TT]mol_cog[tt], with an optional prefix [TT]whole_[tt]",
 157     "[TT]part_[tt] or [TT]dyn_[tt].",
 158     "[TT]whole_[tt] calculates the centers for the whole residue/molecule,",
 159     "even if only part of it is selected.",
 160     "[TT]part_[tt] prefix calculates the centers for the selected atoms, but",
 161     "uses always the same atoms for the same residue/molecule. The used atoms",
 162     "are determined from the the largest group allowed by the selection.",
 163     "[TT]dyn_[tt] calculates the centers strictly only for the selected atoms.",
 164     "If no prefix is specified, whole selections default to [TT]part_[tt] and",
 165     "other places default to [TT]whole_[tt].",
 166     "The latter is often desirable to select the same molecules in different",
 167     "tools, while the first is a compromise between speed ([TT]dyn_[tt]",
 168     "positions can be slower to evaluate than [TT]part_[tt]) and intuitive",
 169     "behavior.[PAR]",
 170
 171     "4. [TT]ATOM_EXPR[tt], when given for whole selections, is handled as 3.",
 172     "above, using the position type from the command-line argument",
 173     "[TT]-seltype[tt].[PAR]",
 174
 175     "Selection keywords that select atoms based on their positions, such as",
 176     "[TT]dist from[tt], use by default the positions defined by the",
 177     "[TT]-selrpos[tt] command-line option.",
 178     "This can be overridden by prepending a [TT]POSTYPE[tt] specifier to the",
 179     "keyword. For example, [TT]res_com dist from POS[tt] evaluates the",
 180     "residue center of mass distances. In the example, all atoms of a residue",
 181     "are either selected or not, based on the single distance calculated.",
 182 };
 183
 184 static const char *help_syntax[] = {
 185     "SELECTION SYNTAX[PAR]",
 186
 187     "A set of selections consists of one or more selections, separated by",
 188     "semicolons. Each selection defines a set of positions for the analysis.",
 189     "Each selection can also be preceded by a string that gives a name for",
 190     "the selection for use in, e.g., graph legends.",
 191     "If no name is provided, the string used for the selection is used",
 192     "automatically as the name.[PAR]",
 193
 194     "For interactive input, the syntax is slightly altered: line breaks can",
 195     "also be used to separate selections. \\ followed by a line break can",
 196     "be used to continue a line if necessary.",
 197     "Notice that the above only applies to real interactive input,",
 198     "not if you provide the selections, e.g., from a pipe.[PAR]",
 199
 200     "It is possible to use variables to store selection expressions.",
 201     "A variable is defined with the following syntax:[BR]",
 202     "[TT]VARNAME = EXPR ;[tt][BR]",
 203     "where [TT]EXPR[tt] is any valid selection expression.",
 204     "After this, [TT]VARNAME[tt] can be used anywhere where [TT]EXPR[tt]",
 205     "would be valid.[PAR]",
 206
 207     "Selections are composed of three main types of expressions, those that",
 208     "define atoms ([TT]ATOM_EXPR[tt]s), those that define positions",
 209     "([TT]POS_EXPR[tt]s), and those that evaluate to numeric values",
 210     "([TT]NUM_EXPR[tt]s). Each selection should be a [TT]POS_EXPR[tt]",
 211     "or a [TT]ATOM_EXPR[tt] (the latter is automatically converted to",
 212     "positions). The basic rules are as follows:[BR]",
 213     "1. An expression like [TT]NUM_EXPR1 < NUM_EXPR2[tt] evaluates to an",
 214     "[TT]ATOM_EXPR[tt] that selects all the atoms for which the comparison",
 215     "is true.[BR]",
 216     "2. Atom expressions can be combined with boolean operations such as",
 217     "[TT]not ATOM_EXPR[tt], [TT]ATOM_EXPR and ATOM_EXPR[tt], or",
 218     "[TT]ATOM_EXPR or ATOM_EXPR[tt]. Parentheses can be used to alter the",
 219     "evaluation order.[BR]",
 220     "3. [TT]ATOM_EXPR[tt] expressions can be converted into [TT]POS_EXPR[tt]",
 221     "expressions in various ways, see \"help positions\" for more details.[PAR]",
 222
 223     "Some keywords select atoms based on string values such as the atom name.",
 224     "For these keywords, it is possible to use wildcards ([TT]name \"C*\"[tt])",
 225     "or regular expressions (e.g., [TT]resname \"R[AB]\"[tt]).",
 226     "The match type is automatically guessed from the string: if it contains",
 227     "other characters than letters, numbers, '*', or '?', it is interpreted",
 228     "as a regular expression.",
 229     "Strings that contain non-alphanumeric characters should be enclosed in",
 230     "double quotes as in the examples. For other strings, the quotes are",
 231     "optional, but if the value conflicts with a reserved keyword, a syntax",
 232     "error will occur. If your strings contain uppercase letters, this should",
 233     "not happen.[PAR]",
 234
 235     "Index groups provided with the [TT]-n[tt] command-line option or",
 236     "generated by default can be accessed with [TT]group NR[tt] or",
 237     "[TT]group NAME[tt], where [TT]NR[tt] is a zero-based index of the group",
 238     "and [TT]NAME[tt] is part of the name of the desired group.",
 239     "The keyword [TT]group[tt] is optional if the whole selection is",
 240     "provided from an index group.",
 241     "To see a list of available groups in the interactive mode, press enter",
 242     "in the beginning of a line.",
 243 };
 244
 245 static const t_selection_help_item helpitems[] = {
 246     {NULL,          asize(help_common),    help_common},
 247     {"cmdline",     asize(help_cmdline),   help_cmdline},
 248     {"evaluation",  asize(help_eval),      help_eval},
 249     {"keywords",    asize(help_keywords),  help_keywords},
 250     {"limitations", asize(help_limits),    help_limits},
 251     {"positions",   asize(help_positions), help_positions},
 252     {"syntax",      asize(help_syntax),    help_syntax},
 253 };
 254
 255 /*! \brief
 256  * Prints a brief list of keywords (selection methods) available.
 257  *
 258  * \param[in] sc    Selection collection for which the list should be printed.
 259  * \param[in] type  Only methods that return this type are printed.
 260  * \param[in] bMod  If FALSE, \ref SMETH_MODIFIER methods are excluded, otherwise
 261  *     only them are printed.
 262  */
 263 static void
 264 print_keyword_list(struct gmx_ana_selcollection_t *sc, e_selvalue_t type,
 265                    bool bMod)
 266 {
 267     gmx_sel_symrec_t *symbol;
 268
 269     symbol = _gmx_sel_first_symbol(sc->symtab, SYMBOL_METHOD);
 270     while (symbol)
 271     {
 272         gmx_ana_selmethod_t *method = _gmx_sel_sym_value_method(symbol);
 273         bool                 bShow;
 274         bShow = (method->type == type)
 275             && ((bMod && (method->flags & SMETH_MODIFIER))
 276                 || (!bMod && !(method->flags & SMETH_MODIFIER)));
 277         if (bShow)
 278         {
 279             fprintf(stderr, " %c ",
 280                     (method->help.nlhelp > 0 && method->help.help) ? '*' : ' ');
 281             if (method->help.syntax)
 282             {
 283                 fprintf(stderr, "%s\n", method->help.syntax);
 284             }
 285             else
 286             {
 287                 fprintf(stderr, "%s\n", method->name);
 288             }
 289         }
 290         symbol = _gmx_sel_next_symbol(symbol, SYMBOL_METHOD);
 291     }
 292 }
 293
 294 /*!
 295  * \param[in]  sc    Selection collection for which help should be printed.
 296  * \param[in]  topic Topic to print help on, or NULL for general help.
 297  *
 298  * \p sc is used to get information on which keywords are available in the
 299  * present context.
 300  */
 301 void
 302 _gmx_sel_print_help(struct gmx_ana_selcollection_t *sc, const char *topic)
 303 {
 304     const t_selection_help_item *item = 0;
 305     int  i;
 306
 307     /* Find the item for the topic */
 308     if (!topic)
 309     {
 310         item = &helpitems[0];
 311     }
 312     else
 313     {
 314         for (i = 1; i < asize(helpitems); ++i)
 315         {
 316             if (strncmp(helpitems[i].topic, topic, strlen(topic)) == 0)
 317             {
 318                 item = &helpitems[i];
 319             }
 320         }
 321     }
 322     /* If the topic is not found, check the available methods.
 323      * If they don't provide any help either, tell the user and exit. */
 324     if (!item)
 325     {
 326         gmx_sel_symrec_t *symbol;
 327
 328         symbol = _gmx_sel_first_symbol(sc->symtab, SYMBOL_METHOD);
 329         while (symbol)
 330         {
 331             gmx_ana_selmethod_t *method = _gmx_sel_sym_value_method(symbol);
 332             if (method->help.nlhelp > 0 && method->help.help
 333                 && strncmp(method->name, topic, strlen(topic)) == 0)
 334             {
 335                 print_tty_formatted(stderr, method->help.nlhelp,
 336                         method->help.help, 0, NULL, NULL, FALSE);
 337                 return;
 338             }
 339             symbol = _gmx_sel_next_symbol(symbol, SYMBOL_METHOD);
 340         }
 341
 342         fprintf(stderr, "No help available for '%s'.\n", topic);
 343         return;
 344     }
 345     /* Print the help */
 346     print_tty_formatted(stderr, item->nl, item->text, 0, NULL, NULL, FALSE);
 347     /* Special handling of certain pages */
 348     if (!topic)
 349     {
 350         /* Print the subtopics on the main page */
 351         fprintf(stderr, "\nAvailable subtopics:\n");
 352         for (i = 1; i < asize(helpitems); ++i)
 353         {
 354             fprintf(stderr, "  %s", helpitems[i].topic);
 355         }
 356         fprintf(stderr, "\n");
 357     }
 358     else if (strcmp(item->topic, "keywords") == 0)
 359     {
 360         /* Print the list of keywords */
 361         fprintf(stderr, "\nKeywords that select atoms by an integer property:\n");
 362         fprintf(stderr, "(use in expressions or like \"atomnr 1 to 5 7 9\")\n");
 363         print_keyword_list(sc, INT_VALUE, FALSE);
 364
 365         fprintf(stderr, "\nKeywords that select atoms by a numeric property:\n");
 366         fprintf(stderr, "(use in expressions or like \"occupancy 0.5 to 1\")\n");
 367         print_keyword_list(sc, REAL_VALUE, FALSE);
 368
 369         fprintf(stderr, "\nKeywords that select atoms by a string property:\n");
 370         fprintf(stderr, "(use like \"name PATTERN [PATTERN] ...\")\n");
 371         print_keyword_list(sc, STR_VALUE, FALSE);
 372
 373         fprintf(stderr, "\nAdditional keywords that directly select atoms:\n");
 374         print_keyword_list(sc, GROUP_VALUE, FALSE);
 375
 376         fprintf(stderr, "\nKeywords that directly evaluate to positions:\n");
 377         fprintf(stderr, "(see also \"help positions\")\n");
 378         print_keyword_list(sc, POS_VALUE, FALSE);
 379
 380         fprintf(stderr, "\nAdditional keywords:\n");
 381         print_keyword_list(sc, POS_VALUE, TRUE);
 382         print_keyword_list(sc, NO_VALUE, TRUE);
 383     }
 384 }