3 * This source code is part of
7 * GROningen MAchine for Chemical Simulations
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.
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.
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.
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.
29 * For more info, check our website at http://www.gromacs.org
33 * Implements functions in selhelp.h.
35 * \author Teemu Murtola <teemu.murtola@cbr.su.se>
36 * \ingroup module_selection
42 #include <boost/scoped_ptr.hpp>
44 #include "gromacs/onlinehelp/helptopic.h"
45 #include "gromacs/onlinehelp/helpwritercontext.h"
46 #include "gromacs/utility/exceptions.h"
47 #include "gromacs/utility/file.h"
48 #include "gromacs/utility/stringutil.h"
51 #include "selmethod.h"
59 static const char name[];
60 static const char title[];
61 static const char *const text[];
64 const char CommonHelpText::name[] = "selections";
65 const char CommonHelpText::title[] =
66 "Selection syntax and usage";
67 const char *const CommonHelpText::text[] = {
68 "Selections are used to select atoms/molecules/residues for analysis.",
69 "In contrast to traditional index files, selections can be dynamic, i.e.,",
70 "select different atoms for different trajectory frames.[PAR]",
72 "Each analysis tool requires a different number of selections and the",
73 "selections are interpreted differently. The general idea is still the",
74 "same: each selection evaluates to a set of positions, where a position",
75 "can be an atom position or center-of-mass or center-of-geometry of",
76 "a set of atoms. The tool then uses these positions for its analysis to",
77 "allow very flexible processing. Some analysis tools may have limitations",
78 "on the types of selections allowed.[PAR]",
80 "To get started with selections, run, e.g., [TT][PROGRAM] select[tt]",
81 "without specifying selections on the command-line and use the interactive",
82 "prompt to try out different selections.",
83 "This tool provides output options that allow one to see what is actually",
84 "selected by the given selections, and the interactive prompt reports",
85 "syntax errors immediately, allowing one to try again.",
86 "The subtopics listed below give more details on different aspects of",
90 struct ArithmeticHelpText
92 static const char name[];
93 static const char title[];
94 static const char *const text[];
97 const char ArithmeticHelpText::name[] = "arithmetic";
98 const char ArithmeticHelpText::title[] =
99 "Arithmetic expressions in selections";
100 const char *const ArithmeticHelpText::text[] = {
101 "Basic arithmetic evaluation is supported for numeric expressions.",
102 "Supported operations are addition, subtraction, negation, multiplication,",
103 "division, and exponentiation (using ^).",
104 "Result of a division by zero or other illegal operations is undefined.",
107 struct CmdLineHelpText
109 static const char name[];
110 static const char title[];
111 static const char *const text[];
114 const char CmdLineHelpText::name[] = "cmdline";
115 const char CmdLineHelpText::title[] =
116 "Specifying selections from command line";
117 const char *const CmdLineHelpText::text[] = {
118 "If no selections are provided on the command line, you are prompted to",
119 "type the selections interactively (a pipe can also be used to provide",
120 "the selections in this case for most tools). While this works well for",
121 "testing, it is easier to provide the selections from the command line",
122 "if they are complex or for scripting.[PAR]",
124 "Each tool has different command-line arguments for specifying selections",
125 "(listed by [TT][PROGRAM] help <tool>[tt]).",
126 "You can either pass a single string containing all selections (separated",
127 "by semicolons), or multiple strings, each containing one selection.",
128 "Note that you need to quote the selections to protect them from the",
131 "If you set a selection command-line argument, but do not provide any",
132 "selections, you are prompted to type the selections for that argument",
133 "interactively. This is useful if that selection argument is optional,",
134 "in which case it is not normally prompted for.[PAR]",
136 "To provide selections from a file, use [TT]-sf file.dat[tt] in the place",
137 "of the selection for a selection argument (e.g.,",
138 "[TT]-select -sf file.dat[tt]). In general, the [TT]-sf[tt] argument reads",
139 "selections from the provided file and assigns them to selection arguments",
140 "that have been specified up to that point, but for which no selections",
141 "have been provided.",
142 "As a special case, [TT]-sf[tt] provided on its own, without preceding",
143 "selection arguments, assigns the selections to all (yet unset) required",
144 "selections (i.e., those that would be promted interactively if no",
145 "selections are provided on the command line).[PAR]",
147 "To use groups from a traditional index file, use argument [TT]-n[tt]",
148 "to provide a file. See the \"syntax\" subtopic for how to use them.",
149 "If this option is not provided, default groups are generated.",
150 "The default groups are generated by reading selections from a file",
151 "[TT]defselection.dat[tt]. If such a file is found in the current",
152 "directory, it is used instead of the one provided by default.[PAR]",
154 "Depending on the tool, two additional command-line arguments may be",
155 "available to control the behavior:[BR]",
156 "1. [TT]-seltype[tt] can be used to specify the default type of",
157 "positions to calculate for each selection.[BR]",
158 "2. [TT]-selrpos[tt] can be used to specify the default type of",
159 "positions used in selecting atoms by coordinates.[BR]",
160 "See the \"positions\" subtopic for more information on these options.",
163 struct EvaluationHelpText
165 static const char name[];
166 static const char title[];
167 static const char *const text[];
170 const char EvaluationHelpText::name[] = "evaluation";
171 const char EvaluationHelpText::title[] =
172 "Selection evaluation and optimization";
173 const char *const EvaluationHelpText::text[] = {
174 "Boolean evaluation proceeds from left to right and is short-circuiting",
175 "i.e., as soon as it is known whether an atom will be selected, the",
176 "remaining expressions are not evaluated at all.",
177 "This can be used to optimize the selections: you should write the",
178 "most restrictive and/or the most inexpensive expressions first in",
179 "boolean expressions.",
180 "The relative ordering between dynamic and static expressions does not",
181 "matter: all static expressions are evaluated only once, before the first",
182 "frame, and the result becomes the leftmost expression.[PAR]",
184 "Another point for optimization is in common subexpressions: they are not",
185 "automatically recognized, but can be manually optimized by the use of",
186 "variables. This can have a big impact on the performance of complex",
187 "selections, in particular if you define several index groups like this:",
188 " [TT]rdist = distance from com of resnr 1 to 5;[tt][BR]",
189 " [TT]resname RES and rdist < 2;[tt][BR]",
190 " [TT]resname RES and rdist < 4;[tt][BR]",
191 " [TT]resname RES and rdist < 6;[tt][BR]",
192 "Without the variable assignment, the distances would be evaluated three",
193 "times, although they are exactly the same within each selection.",
194 "Anything assigned into a variable becomes a common subexpression that",
195 "is evaluated only once during a frame.",
196 "Currently, in some cases the use of variables can actually lead to a small",
197 "performance loss because of the checks necessary to determine for which",
198 "atoms the expression has already been evaluated, but this should not be",
202 struct ExamplesHelpText
204 static const char name[];
205 static const char title[];
206 static const char *const text[];
209 const char ExamplesHelpText::name[] = "examples";
210 const char ExamplesHelpText::title[] =
211 "Selection examples";
212 const char *const ExamplesHelpText::text[] = {
213 // TODO: Once there are more tools available, use examples that invoke
214 // tools and explain what the selections do in those tools.
215 "Below, examples of increasingly complex selections are given.[PAR]",
217 "Selection of all water oxygens:[BR]",
218 " resname SOL and name OW",
221 "Centers of mass of residues 1 to 5 and 10:[BR]",
222 " res_com of resnr 1 to 5 10",
225 "All atoms farther than 1 nm of a fixed position:[BR]",
226 " not within 1 of (1.2, 3.1, 2.4)",
229 "All atoms of a residue LIG within 0.5 nm of a protein (with a custom name):[BR]",
230 " \"Close to protein\" resname LIG and within 0.5 of group \"Protein\"",
233 "All protein residues that have at least one atom within 0.5 nm of a residue LIG:[BR]",
234 " group \"Protein\" and same residue as within 0.5 of resname LIG",
237 "All RES residues whose COM is between 2 and 4 nm from the COM of all of them:[BR]",
238 " rdist = res_com distance from com of resname RES[BR]",
239 " resname RES and rdist >= 2 and rdist <= 4",
242 "Selection like C1 C2 C2 C3 C3 C4 ... C8 C9 (e.g., for g_bond):[BR]",
243 " name \"C[1-8]\" merge name \"C[2-9]\"",
246 struct KeywordsHelpText
248 static const char name[];
249 static const char title[];
250 static const char *const text[];
253 const char KeywordsHelpText::name[] = "keywords";
254 const char KeywordsHelpText::title[] =
255 "Selection keywords";
256 const char *const KeywordsHelpText::text[] = {
257 "The following selection keywords are currently available.",
258 "For keywords marked with a star, additional help is available through",
259 "a subtopic KEYWORD, where KEYWORD is the name of the keyword.",
262 struct LimitationsHelpText
264 static const char name[];
265 static const char title[];
266 static const char *const text[];
269 const char LimitationsHelpText::name[] = "limitations";
270 const char LimitationsHelpText::title[] =
271 "Selection limitations";
272 const char *const LimitationsHelpText::text[] = {
273 "Some analysis programs may require a special structure for the input",
274 "selections (e.g., [TT]g_angle[tt] requires the index group to be made",
275 "of groups of three or four atoms).",
276 "For such programs, it is up to the user to provide a proper selection",
277 "expression that always returns such positions.",
280 "Due to technical reasons, having a negative value as the first value in",
281 "expressions like[BR]",
282 "[TT]charge -1 to -0.7[tt][BR]",
283 "result in a syntax error. A workaround is to write[BR]",
284 "[TT]charge {-1 to -0.7}[tt][BR]",
288 struct PositionsHelpText
290 static const char name[];
291 static const char title[];
292 static const char *const text[];
295 const char PositionsHelpText::name[] = "positions";
296 const char PositionsHelpText::title[] =
297 "Specifying positions in selections";
298 const char *const PositionsHelpText::text[] = {
299 "Possible ways of specifying positions in selections are:[PAR]",
301 "1. A constant position can be defined as [TT][XX, YY, ZZ][tt], where",
302 "[TT]XX[tt], [TT]YY[tt] and [TT]ZZ[tt] are real numbers.[PAR]",
304 "2. [TT]com of ATOM_EXPR [pbc][tt] or [TT]cog of ATOM_EXPR [pbc][tt]",
305 "calculate the center of mass/geometry of [TT]ATOM_EXPR[tt]. If",
306 "[TT]pbc[tt] is specified, the center is calculated iteratively to try",
307 "to deal with cases where [TT]ATOM_EXPR[tt] wraps around periodic",
308 "boundary conditions.[PAR]",
310 "3. [TT]POSTYPE of ATOM_EXPR[tt] calculates the specified positions for",
311 "the atoms in [TT]ATOM_EXPR[tt].",
312 "[TT]POSTYPE[tt] can be [TT]atom[tt], [TT]res_com[tt], [TT]res_cog[tt],",
313 "[TT]mol_com[tt] or [TT]mol_cog[tt], with an optional prefix [TT]whole_[tt]",
314 "[TT]part_[tt] or [TT]dyn_[tt].",
315 "[TT]whole_[tt] calculates the centers for the whole residue/molecule,",
316 "even if only part of it is selected.",
317 "[TT]part_[tt] prefix calculates the centers for the selected atoms, but",
318 "uses always the same atoms for the same residue/molecule. The used atoms",
319 "are determined from the the largest group allowed by the selection.",
320 "[TT]dyn_[tt] calculates the centers strictly only for the selected atoms.",
321 "If no prefix is specified, whole selections default to [TT]part_[tt] and",
322 "other places default to [TT]whole_[tt].",
323 "The latter is often desirable to select the same molecules in different",
324 "tools, while the first is a compromise between speed ([TT]dyn_[tt]",
325 "positions can be slower to evaluate than [TT]part_[tt]) and intuitive",
328 "4. [TT]ATOM_EXPR[tt], when given for whole selections, is handled as 3.",
329 "above, using the position type from the command-line argument",
330 "[TT]-seltype[tt].[PAR]",
332 "Selection keywords that select atoms based on their positions, such as",
333 "[TT]dist from[tt], use by default the positions defined by the",
334 "[TT]-selrpos[tt] command-line option.",
335 "This can be overridden by prepending a [TT]POSTYPE[tt] specifier to the",
336 "keyword. For example, [TT]res_com dist from POS[tt] evaluates the",
337 "residue center of mass distances. In the example, all atoms of a residue",
338 "are either selected or not, based on the single distance calculated.",
341 struct SyntaxHelpText
343 static const char name[];
344 static const char title[];
345 static const char *const text[];
348 const char SyntaxHelpText::name[] = "syntax";
349 const char SyntaxHelpText::title[] =
351 const char *const SyntaxHelpText::text[] = {
352 "A set of selections consists of one or more selections, separated by",
353 "semicolons. Each selection defines a set of positions for the analysis.",
354 "Each selection can also be preceded by a string that gives a name for",
355 "the selection for use in, e.g., graph legends.",
356 "If no name is provided, the string used for the selection is used",
357 "automatically as the name.[PAR]",
359 "For interactive input, the syntax is slightly altered: line breaks can",
360 "also be used to separate selections. \\ followed by a line break can",
361 "be used to continue a line if necessary.",
362 "Notice that the above only applies to real interactive input,",
363 "not if you provide the selections, e.g., from a pipe.[PAR]",
365 "It is possible to use variables to store selection expressions.",
366 "A variable is defined with the following syntax:[BR]",
367 "[TT]VARNAME = EXPR ;[tt][BR]",
368 "where [TT]EXPR[tt] is any valid selection expression.",
369 "After this, [TT]VARNAME[tt] can be used anywhere where [TT]EXPR[tt]",
370 "would be valid.[PAR]",
372 "Selections are composed of three main types of expressions, those that",
373 "define atoms ([TT]ATOM_EXPR[tt]s), those that define positions",
374 "([TT]POS_EXPR[tt]s), and those that evaluate to numeric values",
375 "([TT]NUM_EXPR[tt]s). Each selection should be a [TT]POS_EXPR[tt]",
376 "or a [TT]ATOM_EXPR[tt] (the latter is automatically converted to",
377 "positions). The basic rules are as follows:[BR]",
378 "1. An expression like [TT]NUM_EXPR1 < NUM_EXPR2[tt] evaluates to an",
379 "[TT]ATOM_EXPR[tt] that selects all the atoms for which the comparison",
381 "2. Atom expressions can be combined with boolean operations such as",
382 "[TT]not ATOM_EXPR[tt], [TT]ATOM_EXPR and ATOM_EXPR[tt], or",
383 "[TT]ATOM_EXPR or ATOM_EXPR[tt]. Parentheses can be used to alter the",
384 "evaluation order.[BR]",
385 "3. [TT]ATOM_EXPR[tt] expressions can be converted into [TT]POS_EXPR[tt]",
386 "expressions in various ways, see the \"positions\" subtopic for more",
389 "Some keywords select atoms based on string values such as the atom name.",
390 "For these keywords, it is possible to use wildcards ([TT]name \"C*\"[tt])",
391 "or regular expressions (e.g., [TT]resname \"R[AB]\"[tt]).",
392 "The match type is automatically guessed from the string: if it contains",
393 "other characters than letters, numbers, '*', or '?', it is interpreted",
394 "as a regular expression.",
395 "To force the matching to use literal string matching, use",
396 "[TT]name = \"C*\"[tt] to match a literal C*.",
397 "To force other type of matching, use '?' or '~' in place of '=' to force",
398 "wildcard or regular expression matching, respectively.[PAR]",
400 "Strings that contain non-alphanumeric characters should be enclosed in",
401 "double quotes as in the examples. For other strings, the quotes are",
402 "optional, but if the value conflicts with a reserved keyword, a syntax",
403 "error will occur. If your strings contain uppercase letters, this should",
406 "Index groups provided with the [TT]-n[tt] command-line option or",
407 "generated by default can be accessed with [TT]group NR[tt] or",
408 "[TT]group NAME[tt], where [TT]NR[tt] is a zero-based index of the group",
409 "and [TT]NAME[tt] is part of the name of the desired group.",
410 "The keyword [TT]group[tt] is optional if the whole selection is",
411 "provided from an index group.",
412 "To see a list of available groups in the interactive mode, press enter",
413 "in the beginning of a line.",
425 * Help topic implementation for an individual selection method.
427 * \ingroup module_selection
429 class KeywordDetailsHelpTopic : public AbstractSimpleHelpTopic
432 //! Initialize help topic for the given selection method.
433 explicit KeywordDetailsHelpTopic(const gmx_ana_selmethod_t &method)
438 virtual const char *name() const
442 virtual const char *title() const
448 virtual std::string helpText() const
450 return concatenateStrings(method_.help.help, method_.help.nlhelp);
454 const gmx_ana_selmethod_t &method_;
456 GMX_DISALLOW_COPY_AND_ASSIGN(KeywordDetailsHelpTopic);
460 * Custom help topic for printing a list of selection keywords.
462 * \ingroup module_selection
464 class KeywordsHelpTopic : public CompositeHelpTopic<KeywordsHelpText>
469 virtual void writeHelp(const HelpWriterContext &context) const;
473 * Container for known selection methods.
475 * The first item in the pair is the name of the selection method, and
476 * the second points to the static data structure that describes the
478 * The name in the first item may differ from the name of the static
479 * data structure if an alias is defined for that method.
481 typedef std::vector<std::pair<std::string,
482 const gmx_ana_selmethod_t *> >
486 * Prints a brief list of keywords (selection methods) available.
488 * \param[in] context Context for printing the help.
489 * \param[in] type Only methods that return this type are printed.
490 * \param[in] bModifiers If false, \ref SMETH_MODIFIER methods are
491 * excluded, otherwise only them are printed.
493 void printKeywordList(const HelpWriterContext &context,
494 e_selvalue_t type, bool bModifiers) const;
499 KeywordsHelpTopic::KeywordsHelpTopic()
501 // TODO: This is not a very elegant way of getting the list of selection
502 // methods, but this needs to be rewritten in any case if/when #652 is
504 boost::scoped_ptr<SelectionParserSymbolTable> symtab(
505 new SelectionParserSymbolTable);
506 gmx_ana_selmethod_register_defaults(symtab.get());
508 SelectionParserSymbolIterator symbol
509 = symtab->beginIterator(SelectionParserSymbol::MethodSymbol);
510 while (symbol != symtab->endIterator())
512 const std::string &symname = symbol->name();
513 const gmx_ana_selmethod_t *method = symbol->methodValue();
514 methods_.push_back(std::make_pair(std::string(symname), method));
515 if (method->help.nlhelp > 0 && method->help.help != NULL)
517 addSubTopic(HelpTopicPointer(new KeywordDetailsHelpTopic(*method)));
523 void KeywordsHelpTopic::writeHelp(const HelpWriterContext &context) const
525 if (context.outputFormat() != eHelpOutputFormat_Console)
527 GMX_THROW(NotImplementedError(
528 "Selection help is not implemented for this output format"));
530 // TODO: The markup here is not really appropriate, and printKeywordList()
531 // still prints raw text, but these are waiting for discussion of the
532 // markup format in #969.
533 writeBasicHelpTopic(context, *this, helpText());
534 context.writeTextBlock("[BR]");
536 // Print the list of keywords
537 context.writeTextBlock(
538 "Keywords that select atoms by an integer property:[BR]"
539 "(use in expressions or like \"atomnr 1 to 5 7 9\")[BR]");
540 printKeywordList(context, INT_VALUE, false);
541 context.writeTextBlock("[BR]");
543 context.writeTextBlock(
544 "Keywords that select atoms by a numeric property:[BR]"
545 "(use in expressions or like \"occupancy 0.5 to 1\")[BR]");
546 printKeywordList(context, REAL_VALUE, false);
547 context.writeTextBlock("[BR]");
549 context.writeTextBlock(
550 "Keywords that select atoms by a string property:[BR]"
551 "(use like \"name PATTERN [PATTERN] ...\")[BR]");
552 printKeywordList(context, STR_VALUE, false);
553 context.writeTextBlock("[BR]");
555 context.writeTextBlock(
556 "Additional keywords that directly select atoms:[BR]");
557 printKeywordList(context, GROUP_VALUE, false);
558 context.writeTextBlock("[BR]");
560 context.writeTextBlock(
561 "Keywords that directly evaluate to positions:[BR]"
562 "(see also \"positions\" subtopic)[BR]");
563 printKeywordList(context, POS_VALUE, false);
564 context.writeTextBlock("[BR]");
566 context.writeTextBlock("Additional keywords:[BR]");
567 printKeywordList(context, POS_VALUE, true);
568 printKeywordList(context, NO_VALUE, true);
571 void KeywordsHelpTopic::printKeywordList(const HelpWriterContext &context,
573 bool bModifiers) const
575 File &file = context.outputFile();
576 MethodList::const_iterator iter;
577 for (iter = methods_.begin(); iter != methods_.end(); ++iter)
579 const gmx_ana_selmethod_t &method = *iter->second;
580 bool bIsModifier = (method.flags & SMETH_MODIFIER) != 0;
581 if (method.type == type && bModifiers == bIsModifier)
583 bool bHasHelp = (method.help.nlhelp > 0 && method.help.help != NULL);
584 file.writeString(formatString(" %c ", bHasHelp ? '*' : ' '));
585 if (method.help.syntax != NULL)
587 file.writeLine(method.help.syntax);
591 std::string symname = iter->first;
592 if (symname != method.name)
594 symname.append(formatString(" (synonym for %s)", method.name));
596 file.writeLine(symname);
604 /*! \cond internal */
605 HelpTopicPointer createSelectionHelpTopic()
607 CompositeHelpTopicPointer root(new CompositeHelpTopic<CommonHelpText>);
608 root->registerSubTopic<SimpleHelpTopic<ArithmeticHelpText> >();
609 root->registerSubTopic<SimpleHelpTopic<CmdLineHelpText> >();
610 root->registerSubTopic<SimpleHelpTopic<EvaluationHelpText> >();
611 root->registerSubTopic<SimpleHelpTopic<ExamplesHelpText> >();
612 root->registerSubTopic<KeywordsHelpTopic>();
613 root->registerSubTopic<SimpleHelpTopic<LimitationsHelpText> >();
614 root->registerSubTopic<SimpleHelpTopic<PositionsHelpText> >();
615 root->registerSubTopic<SimpleHelpTopic<SyntaxHelpText> >();