docs/doxygen/user/selections.md

   1 Dynamic selections {#page_selections}
   2 ==================
   3
   4 The \ref module_selection module provides a mechanism that allows selections
   5 specified as text, and the engine evaluates them to atoms, or more generally to
   6 a set of positions, for one or more sets of coordinates.  The selected atoms
   7 can depend on the trajectory frame.  This allows writing general-purpose
   8 analysis tools that only operate on positions, and get a lot of flexibility for
   9 free from the selection engine.  For example, such tools can readily operate on
  10 centers of mass of groups in addition to individual atoms as long as they do
  11 not require access to atomic properties.
  12
  13 For people familiar with VMD, the selection syntax is quite familiar, but there
  14 are some differences.  Not all the keywords supported by VMD are there, and
  15 there are some extensions related to the support to evaluate to center-of-mass
  16 positions in addition to individual atoms.
  17 For old-time \Gromacs users, tools that support selections do not generally
  18 need `make_ndx`.
  19
  20 Structural overview
  21 ===================
  22
  23 Central concepts useful for understanding the selection engine are explained
  24 below.  A graph represents the relations between the different parts, and a
  25 textual description of the user-visible components and other concepts follows.
  26 The graph also includes an overview of how the selection engine integrates into
  27 the \ref page_analysisframework.  When using selections from the analysis
  28 framework, the parts in gray are managed by the framework.
  29 When using selections outside the framework, it is either possible to use only
  30 the core components (shown in the graph as a box), or to also use the selection
  31 option mechanisms.  In both cases, the caller is responsible of managing all
  32 the objects owned by the framework in the graph.
  33
  34 \dot
  35     digraph selection_overview {
  36         subgraph cluster_framework {
  37             label = "analysis framework"
  38             analysisframework [label="framework", fillcolor=grey75, style=filled]
  39             options [label="options collection", fillcolor=grey75, style=filled]
  40             analysistool [label="analysis tool"]
  41         }
  42         subgraph cluster_core {
  43             label = "core engine"
  44             labelloc = b
  45             selectioncollection [label="selection collection", fillcolor=grey75, style=filled]
  46             selectiondata [label="internal selection data", fillcolor=grey75, style=filled]
  47             selection [label="selection object"]
  48         }
  49         selectionoption [label="selection option"]
  50         selectionoptionmanager [label="selection option manager", fillcolor=grey75, style=filled]
  51
  52         selectioncollection -> selection [label="creates"]
  53         selectioncollection -> selectiondata [label="owns and updates"]
  54         selectionoption -> selection [label="returns"]
  55         selection -> selectiondata [label="reads data", constraint=false]
  56         selectionoptionmanager -> selectionoption [label="provides values to"]
  57         selectionoptionmanager -> selectioncollection [label="gets selection objects"]
  58         analysistool -> selectionoption [label="declares"]
  59         analysistool -> selection [label="reads data from"]
  60         analysistool -> options [label="declares options"]
  61         analysisframework -> selectionoptionmanager [label="owns"]
  62         analysisframework -> selectioncollection [label="owns"]
  63         analysisframework -> options [label="owns"]
  64         options -> selectionoption [label="contains"]
  65     }
  66 \enddot
  67
  68  - _selection_: Evaluates to a single list of _selection positions_.
  69    Note in particular that the output is positions, not a list of atoms.
  70    A tool can accept one or more selections, and expect different semantics for
  71    different selections.
  72  - _dynamic selection_: The word _dynamic_ refers to selections for which the
  73    set of positions (instead of only the positions themselves) depends on the
  74    input coordinates.
  75  - _selection position_: A single coordinate as returned by a selection.
  76    This can correspond to an individual atom, but also to a collective
  77    coordinate such as a center of mass of a group of atoms.
  78    In addition to the output coordinates, the position provides information
  79    about the atoms that constitute it, and metadata that allows one to
  80    associate positions between different frames if different positions
  81    are returned at the same time.
  82  - _selection collection_: Group of selections that are processed as a unit
  83    against the same topology and sets of coordinates.
  84    In the analysis framework, there is always a single selection collection
  85    managed by the framework.
  86  - _selection variable_: When providing selections through text, it is possible
  87    to create variables and use them as part of selections.  This makes it
  88    easier to write repetitive selections by making complex common
  89    subexpressions into variables.  This also provides optimization
  90    opportunities for the selection engine: the variable value is not repeatedly
  91    evaluated.  Variables always exist in the context of a selection collection.
  92  - _selection object_: When a selection is _parsed_ (see below), the selection
  93    collection gives a handle to the selection as a _selection object_.  This
  94    handle is valid for the lifetime of the selection collection, and can be
  95    used to access information about the selection.  Operations on the selection
  96    collection (_compilation_ and _evaluation_, see below) alter the values
  97    returned by the selection objects.
  98  - _selection option_: A special type of command-line option that directly
  99    returns selection objects.  This higher-level construct is used by the
 100    analysis framework to provide a convenient interface for analysis tools:
 101    they can simply declare one or more selection options, and get a list of
 102    _selection objects_ as a return value for each of these.  Other parts of the
 103    selection engine are managed by the framework.
 104
 105 Core selection engine
 106 =====================
 107
 108 The core of the selection engine is the _selection collection_ object.
 109 The graph below shows how it handles selections.  The operations that the
 110 collection object supports and their sequence is shown in the boxes in the
 111 middle.  Inputs are shown at top, and outputs at the bottom.
 112
 113 \dot
 114     digraph selection_process {
 115         subgraph cluster_collection {
 116             label = "selection collection"
 117             subgraph actions {
 118                 rank = same
 119                 create [shape=box]
 120                 parse [shape=box]
 121                 compile [shape=box]
 122                 evaluate [shape=box]
 123                 evaluatefinal [label="finish evaluation",shape=box]
 124
 125                 create -> parse
 126                 parse:ne -> parse:nw
 127                 parse -> compile
 128                 compile -> evaluate
 129                 evaluate:ne -> evaluate:nw
 130                 evaluate -> evaluatefinal
 131             }
 132             selectiondata [label="internal selection data"]
 133         }
 134
 135         selectiontext [label="selection text"]
 136         topology [label="topology/\natom count"]
 137         frame [label="frame coordinates"]
 138
 139         selection [label="selection object"]
 140
 141         selectiontext -> parse
 142         parse:s -> selection:nw [label="returns"]
 143         parse -> selectiondata [label="creates"]
 144         topology -> compile
 145         compile -> selectiondata [label="initializes\npositions"]
 146         frame -> evaluate
 147         evaluate -> selectiondata [label="sets\npositions"]
 148         evaluatefinal -> selectiondata [label="resets to\npost-compilation\nstate"]
 149         selectiondata -> selection [label="reads data", dir=back]
 150     }
 151 \enddot
 152
 153  - _parsing_: after creating an empty selection collection,
 154    selections need to be parsed from text.  As a result, the selection
 155    collection initializes an internal data object to hold some basic
 156    information about the selections, and returns _selection objects_ as a
 157    handle to this data.  It is possible to parse more than one set of
 158    selections into the same collection by calling the parsing methods more than
 159    once.  The input string to parsing can also contain variable declarations,
 160    which get added into the collection and can be used in later calls to the
 161    parser.
 162
 163  - _compilation_: when all selections are parsed, the whole selection
 164    collection is compiled.  This analyzes the provided selections, and
 165    evaluates all parts that do not depend on atom coordinates (e.g.,
 166    (sub)selections based on atom or residue names).  After compilation,
 167    the coordinates in the output positions are not initialized, but all other
 168    information is initialized as if all atoms satisfied any dynamic conditions.
 169    This means that any subsequent evaluation will return a subset of the
 170    positions returned at this point.  The caller can use this information to
 171    check the selections for validity and allocate memory for its own
 172    processing.
 173    Compilation also allocates all the memory necessary to do the evaluation.
 174
 175    In the figure, topology is shown as input to the compilation, but generally
 176    it can be set at any point before the compilation.  If the selection text
 177    does not require any information from the topology for evaluation, it is
 178    sufficient to set only the atom count.
 179
 180  - _evaluation_: after the selections are compiled, they can be evaluated for
 181    one or more sets of atom coordinates.  This updates the set of positions
 182    accessible through the selection objects.  For dynamic selections, the group
 183    of positions can change; for static selections, only the coordinates of the
 184    positions are updated.
 185
 186  - _final evaluation_: This returns the selections to the state they were after
 187    compilation, i.e., to the maximum possible set of positions.  The
 188    coordinates of the positions are again uninitialized, but other information
 189    is available.  The caller can use this information to do post-processing
 190    and, e.g., produce labels in its output based on the selection positions.
 191
 192 \if internal
 193 Internal implementation
 194 =======================
 195
 196 Implementation details of different parts of the module are discussed on
 197 separate pages.
 198
 199   - \subpage page_module_selection_custom
 200   - \subpage page_module_selection_parser
 201   - \subpage page_module_selection_compiler
 202   - \subpage page_module_selection_insolidangle
 203 \endif