From 75a8c1d6f316e49e27433cc4ea011fef274c6d10 Mon Sep 17 00:00:00 2001 From: Teemu Murtola Date: Wed, 28 Oct 2009 18:04:29 +0100 Subject: [PATCH] Updated selection documentation. Removed selection syntax documentation from Doxygen comments, as it is now provided through the online help system. Also made some minor improvements to the help texts. --- src/gmxlib/selection/selection.c | 250 --------------------------------------- src/gmxlib/selection/selhelp.c | 13 +- src/gmxlib/trajana/trajana.c | 47 ++++++++ 3 files changed, 55 insertions(+), 255 deletions(-) diff --git a/src/gmxlib/selection/selection.c b/src/gmxlib/selection/selection.c index 70fc7929ab..ac3293c625 100644 --- a/src/gmxlib/selection/selection.c +++ b/src/gmxlib/selection/selection.c @@ -28,256 +28,6 @@ * * For more info, check our website at http://www.gromacs.org */ -/*! \page selengine Text-based selections - * - * \section selection_basics Basics - * - * Selections are enabled for an analysis program automatically. - * By default, dynamic selections are allowed, and the user can freely - * choose whether to analyze atoms or centers of mass/geometry of - * residues/molecules. - * These defaults, as well as some others, can be changed by specifying - * flags for gmx_ana_traj_create(). - * - * Two command-line options are always added: - * - \p -select can be used to specify the selection on the command line. - * - \p -sf can be used to specify a file name from which the selection is - * read. - * If both options are specified, \p -select takes precedence. - * - If neither of the above is present, the user is prompted to type - * selections. - * This is also done if an empty string is passed to \p -select. - * An index file can be provided with \p -n, and the user can also select - * groups from it instead of writing a full selection. - * If no index file is provided, the default groups are generated. - * - * \todo - * Improve the user interface for interactive selection input. - * - * If \ref ANA_ONLY_ATOMPOS is not specified, an additional command-line - * option is added: - * - \p -seltype can be used to specify the default type of positions to - * calculate for each selection. - * - * An additional command-line option is added if dynamic selections are - * allowed (i.e., if \ref ANA_NO_DYNSEL is not specified). - * This options control how position keywords work within selections: - * - By default, each atom can be selected separately based on its - * coordinates (unless \ref ANA_REQUIRE_WHOLE is specified), but this - * can be changed with \p -selrpos to select all the atoms in a - * residue/molecule based on the center of mass/geometry of the - * residue/molecule. - * - * The two options that specify the position types can take any of the - * following values: - * - \p atom uses individual atom positions. - * - \p res_com and \p res_cog use the centers of mass/geometry of residues. - * - \p mol_com and \p mol_cog use the centers of mass/geometry of molecules. - * - The way the COM/COG are calculated can be altered with a one of the - * following prefixes (e.g., \p part_res_com): - * - \p whole_ prefix calcualtes the centers for the whole - * residue/molecule, even if only part of it is selected. - * - \p part_ prefix calculates the centers for the selected atoms, - * but uses always the same atoms for the same residue/molecule. - * The used atoms are determined from the the largest group allowed by - * the selection. - * - \p dyn_ prefix calculates the centers strictly only for the - * selected atoms. - * . - * - If no prefix is specified, \p -seltype defaults to \p part_ and - * \p -selrpos defaults to \p whole_. - * The latter is often desirable to select the same molecules in different - * tools, while the first is a compromise between speed (\p dyn_ positions - * can be slower to evaluate than \p part_) and intuitive behavior. - * - * The analysis program can then access the selected positions for each frame - * through a \p gmx_ana_selection_t array that is passed to the frame - * analysis function (see gmx_analysisfunc()). - * As long as the analysis program is written such that it does not assume - * that the number of positions or the atoms in the groups groups remain - * constant, any kind of selection expression can be used. - * - * Some analysis programs may require a special structure for the index groups - * (e.g., \c g_angle requires the index group to be made of groups of three or - * four atoms). - * For such programs, it is up to the user to provide a proper selection - * expression that always returns such positions. - * The analysis program can define \ref ANA_REQUIRE_WHOLE to make the - * default behavior appropriate for the most common uses where the groups - * should consist of atoms within a single residue/molecule. - * - * \note - * Currently, it is not possible to write selection expressions that would - * evaluate to index groups where the same atom occurs more than once. - * Such index groups may be useful with tools like \c g_angle to calculate - * the averages over several angles. - * It is possible to implement such a feature, but currently the best solution is to - * write/modify the tool such that it can deal with multiple index groups, - * each of which then defines angles that don't have overlapping atoms. - * - * - * \section selection_syntax Selection syntax - * - * A set of selections consists of one or more selections, separated by - * semicolons. Each selection defines a set of positions for the analysis. - * Each selection can also be preceded by a string that gives a name for - * the selection for use in, e.g., graph legends. - * If no name is provided, a the string used for the selection is used - * automatically. - * It is also possible to use variables to store selection expressions. - * A variable is defined with the following syntax: -\verbatim -VARNAME = EXPR ; -\endverbatim - * After this, you can use VARNAME anywhere where EXPR would be valid. - * - * No semicolons should be used when providing the selections interactively; - * in the interactive prompt, each selection should appear on a line of its - * own. Lines can be continued with \\ if necessary. - * Notice that the above only applies to real interactive input, - * not if you provide the selections, e.g., from a pipe. - * - * Positions can be defined in several different ways (ATOM_EXPR stands for any - * expression that evaluates to a set of atoms): - * - (X, Y, Z): a fixed position (X, Y, Z should be real numbers). - * - cog of ATOM_EXPR [pbc]: center of geometry of ATOM_EXPR. - * - com of EXPR [pbc]: center of mass of ATOM_EXPR. - * - res_com of ATOM_EXPR: a set of positions consisting of centers - * of mass of the residues in ATOM_EXPR. - * res_com can be replaced with any of the position types - * acceptable for the \p -seltype and \p -selrpos options. - * - ATOM_EXPR: the default positions provided with \p -seltype are - * evaluated for ATOM_EXPR. - * - * If you specify \p pbc with the \p cog or \p com expressions, - * the center is calculated iteratively to try to deal with cases where - * ATOM_EXPR wraps around periodic boundary conditions. - * - * To select atoms (ATOM_EXPR expressions above), the following keywords are - * currently available: - * - atomnr [INT|INT to INT] ... : selects atoms by number - * (first atom = 1) - * - resnr [INT|INT to INT] ... : selects residues by number - * (first residue = 1) - * - name STR ... : selects atoms by name - * - type STR ... : selects atoms by type - * - resname STR ... : selects residues by name - * - insertcode STR ... : selects residues by insertion code - * - chain STR ... : selects residues by chain ID - * - mass: returns the mass of the atom, use, e.g., like - * mass < 15 - * - charge: returns the charge of the atom - * - altloc STR ... : selects atoms by the alternate location - * identifier specified in the PDB file - * - occupancy: returns the occupancy of the atom from the PDB file - * - betafactor: returns the B-factor of the atom from the PDB file - * - within RADIUS of POS_EXPR: Selects atoms that are within - * RADIUS of any positions defined by POS_EXPR. POS_EXPR can be defined - * as in selections above (\p -selrpos is used instead of \p -seltype to - * convert atom expressions to positions). - * - insolidangle span POS_EXPR center POS [cutoff ANGLE]: - * Selects atoms that are within ANGLE degrees (default=5) of any position - * in POS_EXPR as seen from POS (a position expression that evaluates to - * a single position), i.e., atoms in the solid angle spanned by the - * positions in POS_EXPR and centered at POS - * (see \subpage sm_insolidangle "detailed explanation"). - * - same residue as ATOM_EXPR: - * Selects any atoms that are in a same residue with any atom in ATOM_EXPR. - * - * For string-based selection keywords, it is possible to use wildcards - * (e.g., name "C*") or regular expressions - * (e.g., resname "R[AB]"). - * Strings that contain non-alphanumeric characters should be enclosed in - * double quotes as in the examples. - * The match type is automatically guessed from the string: if it contains any - * other characters than letters, numbers, '*', or '?', it is interpreted - * as a regular expression. - * - * In addition, the following keywords yield numeric values that can - * be compared with each other or constant values to select a subset of - * the particles (\p resnr and similar keywords can also be used in this way): - * - distance from POS [cutoff REAL]: calculates the distance from - * POS - * - mindistance from POS_EXPR [cutoff REAL]: calculates the minimum - * distance from the positions in POS_EXPR - * - x, y, z: returns the respective coordinate - * of the particle - * - * For the distance selection keywords, it is possible to specify a cutoff - * to possibly speed up the evaluation: all distances above the specified - * cutoff are returned as equal to the cutoff. - * - * For all selection keywords that select by position, the position specified - * by \p -selrpos is used. This can be overridden by prepending a reference - * position specifier to the keyword. For example, - * res_com dist from POS - * evaluates the residue center of mass distances irrespective of the value of - * \p -selrpos. - * - * Arithmetic expressions are not implemented. - * - * It is also possible to combine expressions through boolean operations: - * - not ATOM_EXPR - * - ATOM_EXPR and ATOM_EXPR - * - ATOM_EXPR or ATOM_EXPR - * - * are all valid expressions. - * Parenthesis can also be used to alter the evaluation order. - * - * All selections are by default evaluated such that the atom indices are - * returned in ascending order. This can be changed by appending - * permute P1 P2 ... Pn to an expression. - * The \c Pi should form a permutation of the numbers 1 to n. - * This keyword permutes each n-position block in the selection such that the - * i'th position in the block becomes Pi'th. - * Note that it is the positions that are permuted, not individual atoms. - * A fatal error occurs if the size of the selection is not a multiple of n. - * It is only possible to permute the whole selection expression, not any - * subexpressions, i.e., the \c permute keyword should appear last in a - * selection. - * - * - * \section selection_eval Selection evaluation and optimization - * - * Boolean evaluation proceeds from left to right and is short-circuiting, - * i.e., as soon as it is known whether an atom will be selected, the - * remaining expressions are not evaluated at all. - * This can be used to optimize the selections: you should write the - * most restrictive and/or the most inexpensive expressions first in - * boolean expressions. - * The relative ordering between dynamic and static expressions does not - * matter: all static expressions are evaluated only once, before the first - * frame, and the result becomes the leftmost expression. - * - * Another point for optimization is in common subexpressions: they are not - * automatically recognized, but can be manually optimized by the use of - * variables. This can have a big impact on the performance of complex - * selections, in particular if you define several index groups like this: -\verbatim -rdist = distance from com of resnr 1 to 5; -resname RES and rdist < 2; -resname RES and rdist < 4; -resname RES and rdist < 6; -\endverbatim - * Without the variable assignment, the distances would be evaluated three - * times, although they are exactly the same within each selection. - * Anything assigned into a variable becomes a common subexpression that - * is evaluated only once during a frame. - * Currently, in some cases the use of variables can actually lead to a small - * performance loss because of the checks necessary to determine for which - * atoms the expression has already been evaluated, but this should not be - * a major problem. - * - * - * \section selection_methods Implementing new keywords - * - * New selection keywords can be easily implemented, either directly into the - * library or as part of analysis programs (the latter may be useful for - * testing or methods very specific to some analysis). - * For both cases, you should first create a \c gmx_ana_selmethod_t structure - * and fill it with the necessary information. - * Details can be found on a separate page: \ref selmethods. - */ /*! \internal \file * \brief * Implementation of functions in selection.h. diff --git a/src/gmxlib/selection/selhelp.c b/src/gmxlib/selection/selhelp.c index c07280803d..8de5cf9685 100644 --- a/src/gmxlib/selection/selhelp.c +++ b/src/gmxlib/selection/selhelp.c @@ -65,16 +65,19 @@ static const char *help_cmdline[] = { "If both options are specified, [TT]-select[tt] takes precedence.", "If neither of the above is present, the user is prompted to type the", "selection on the standard input (a pipe can also be used to provide", - "the selections in this case.", + "the selections in this case).", "This is also done if an empty string is passed to [TT]-select[tt].[PAR]", "Option [TT]-n[tt] can be used to provide an index file.", - "If no index file is provided, the default groups are generated.", + "If no index file is provided, default groups are generated.", "In both cases, the user can also select an index group instead of", - "writing a full selection.[PAR]", + "writing a full selection.", + "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]", "Depending on the tool, two additional command-line arguments may be", - "provided:[BR]", + "available to control the behavior:[BR]", "1. [TT]-seltype[tt] can be used to specify the default type of", "positions to calculate for each selection.[BR]", "2. [TT]-selrpos[tt] can be used to specify the default type of", @@ -155,7 +158,7 @@ static const char *help_positions[] = { "[TT]POSTYPE[tt] can be [TT]atom[tt], [TT]res_com[tt], [TT]res_cog[tt],", "[TT]mol_com[tt] or [TT]mol_cog[tt], with an optional prefix [TT]whole_[tt]", "[TT]part_[tt] or [TT]dyn_[tt].", - "[TT]whole_[tt] calcualtes the centers for the whole residue/molecule,", + "[TT]whole_[tt] calculates the centers for the whole residue/molecule,", "even if only part of it is selected.", "[TT]part_[tt] prefix calculates the centers for the selected atoms, but", "uses always the same atoms for the same residue/molecule. The used atoms", diff --git a/src/gmxlib/trajana/trajana.c b/src/gmxlib/trajana/trajana.c index fc105b1925..923b83219a 100644 --- a/src/gmxlib/trajana/trajana.c +++ b/src/gmxlib/trajana/trajana.c @@ -70,6 +70,53 @@ * - \subpage selparser * - \subpage selcompiler */ +/*! \page selengine Text-based selections + * + * \section selection_basics Basics + * + * Selections are enabled automatically for an analysis program that uses + * the library. The selection syntax is described in an online help that is + * accessible from all tools that use the library. + * By default, dynamic selections are allowed, and the user can freely + * choose whether to analyze atoms or centers of mass/geometry of + * residues/molecules. + * These defaults, as well as some others, can be changed by specifying + * flags for gmx_ana_traj_create(). + * + * The analysis program can then access the selected positions for each frame + * through a \p gmx_ana_selection_t array that is passed to the frame + * analysis function (see gmx_analysisfunc()). + * As long as the analysis program is written such that it does not assume + * that the number of positions or the atoms in the groups groups remain + * constant, any kind of selection expression can be used. + * + * Some analysis programs may require a special structure for the index groups + * (e.g., \c g_angle requires the index group to be made of groups of three or + * four atoms). + * For such programs, it is up to the user to provide a proper selection + * expression that always returns such positions. + * Such analysis program can define \ref ANA_REQUIRE_WHOLE to make the + * default behavior appropriate for the most common uses where the groups + * should consist of atoms within a single residue/molecule. + * + * \note + * Currently, it is not possible to write selection expressions that would + * evaluate to index groups where the same atom occurs more than once. + * Such index groups may be useful with tools like \c g_angle to calculate + * the averages over several angles. + * It is possible to implement such a feature, but currently the best solution is to + * write/modify the tool such that it can deal with multiple index groups, + * each of which then defines angles that don't have overlapping atoms. + * + * \section selection_methods Implementing new keywords + * + * New selection keywords can be easily implemented, either directly into the + * library or as part of analysis programs (the latter may be useful for + * testing or methods very specific to some analysis). + * For both cases, you should first create a \c gmx_ana_selmethod_t structure + * and fill it with the necessary information. + * Details can be found on a separate page: \ref selmethods. + */ /*! \internal \file * \brief Implementation of functions in trajana.h. */ -- 2.11.4.GIT