src/gromacs/selection/selelem.h

   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
  33  * Declares ::t_selelem and related things.
  34  *
  35  * The selection element trees constructed by the parser and the compiler
  36  * are described on the respective pages:
  37  * \ref page_module_selection_parser and \ref page_module_selection_compiler.
  38  *
  39  * This is an implementation header: there should be no need to use it outside
  40  * this directory.
  41  *
  42  * \author Teemu Murtola <teemu.murtola@cbr.su.se>
  43  * \ingroup module_selection
  44  */
  45 #ifndef SELECTION_ELEMENT_H
  46 #define SELECTION_ELEMENT_H
  47
  48 #include <types/simple.h>
  49
  50 #include "gromacs/selection/indexutil.h"
  51 #include "gromacs/selection/selvalue.h"
  52
  53 struct gmx_ana_poscalc_t;
  54 struct gmx_ana_selparam_t;
  55 struct gmx_ana_selmethod_t;
  56
  57 struct gmx_sel_evaluate_t;
  58 struct gmx_sel_mempool_t;
  59 struct t_selelem;
  60
  61 /********************************************************************/
  62 /*! \name Enumerations for expression types
  63  ********************************************************************/
  64 /*@{*/
  65
  66 /** Defines the type of a \c t_selelem object. */
  67 typedef enum
  68 {
  69     /** Constant-valued expression. */
  70     SEL_CONST,
  71     /** Method expression that requires evaluation. */
  72     SEL_EXPRESSION,
  73     /** Boolean expression. */
  74     SEL_BOOLEAN,
  75     /** Arithmetic expression. */
  76     SEL_ARITHMETIC,
  77     /** Root node of the evaluation tree. */
  78     SEL_ROOT,
  79     /** Subexpression that may be referenced several times. */
  80     SEL_SUBEXPR,
  81     /** Reference to a subexpression. */
  82     SEL_SUBEXPRREF,
  83     /** Unresolved reference to an external group. */
  84     SEL_GROUPREF,
  85     /** Post-processing of selection value. */
  86     SEL_MODIFIER
  87 } e_selelem_t;
  88
  89 /** Defines the boolean operation of \c t_selelem objects with type \ref SEL_BOOLEAN. */
  90 typedef enum
  91 {
  92     BOOL_NOT,           /**< Not */
  93     BOOL_AND,           /**< And */
  94     BOOL_OR,            /**< Or */
  95     BOOL_XOR            /**< Xor (not implemented). */
  96 } e_boolean_t;
  97
  98 /** Defines the arithmetic operation of \c t_selelem objects with type \ref SEL_ARITHMETIC. */
  99 typedef enum
 100 {
 101     ARITH_PLUS,         /**< + */
 102     ARITH_MINUS,        /**< - */
 103     ARITH_NEG,          /**< Unary - */
 104     ARITH_MULT,         /**< * */
 105     ARITH_DIV,          /**< / */
 106     ARITH_EXP           /**< ^ (to power) */
 107 } e_arithmetic_t;
 108
 109 /** Returns a string representation of the type of a \c t_selelem. */
 110 extern const char *
 111 _gmx_selelem_type_str(struct t_selelem *sel);
 112 /** Returns a string representation of the boolean type of a \ref SEL_BOOLEAN \c t_selelem. */
 113 extern const char *
 114 _gmx_selelem_boolean_type_str(struct t_selelem *sel);
 115 /** Returns a string representation of the type of a \c gmx_ana_selvalue_t. */
 116 extern const char *
 117 _gmx_sel_value_type_str(gmx_ana_selvalue_t *val);
 118
 119 /*@}*/
 120
 121
 122 /********************************************************************/
 123 /*! \name Selection expression flags
 124  * \anchor selelem_flags
 125  ********************************************************************/
 126 /*@{*/
 127 /*! \brief
 128  * Selection value flags are set.
 129  *
 130  * If this flag is set, the flags covered by \ref SEL_VALFLAGMASK
 131  * have been set properly for the element.
 132  */
 133 #define SEL_FLAGSSET    1
 134 /*! \brief
 135  * The element evaluates to a single value.
 136  *
 137  * This flag is always set for \ref GROUP_VALUE elements.
 138  */
 139 #define SEL_SINGLEVAL   2
 140 /*! \brief
 141  * The element evaluates to one value for each input atom.
 142  */
 143 #define SEL_ATOMVAL     4
 144 /*! \brief
 145  * The element evaluates to an arbitrary number of values.
 146  */
 147 #define SEL_VARNUMVAL   8
 148 /*! \brief
 149  * The element (or one of its children) is dynamic.
 150  */
 151 #define SEL_DYNAMIC     16
 152 /*! \brief
 153  * Mask that covers the flags that describe the number of values.
 154  */
 155 #define SEL_VALTYPEMASK (SEL_SINGLEVAL | SEL_ATOMVAL | SEL_VARNUMVAL)
 156 /*! \brief
 157  * Mask that covers the flags that describe the value type.
 158  */
 159 #define SEL_VALFLAGMASK (SEL_FLAGSSET | SEL_VALTYPEMASK | SEL_DYNAMIC)
 160 /*! \brief
 161  * Data has been allocated for the \p v.u union.
 162  *
 163  * If not set, the \p v.u.ptr points to data allocated externally.
 164  * This is the case if the value of the element is used as a parameter
 165  * for a selection method or if the element evaluates the final value of
 166  * a selection.
 167  *
 168  * Even if the flag is set, \p v.u.ptr can be NULL during initialization.
 169  *
 170  * \todo
 171  * This flag overlaps with the function of \p v.nalloc field, and could
 172  * probably be removed, making memory management simpler. Currently, the
 173  * \p v.nalloc field is not kept up-to-date in all cases when this flag
 174  * is changed and is used in places where this flag is not, so this would
 175  * require a careful investigation of the selection code.
 176  */
 177 #define SEL_ALLOCVAL    (1<<8)
 178 /*! \brief
 179  * Data has been allocated for the group/position structure.
 180  *
 181  * If not set, the memory allocated for fields in \p v.u.g or \p v.u.p is
 182  * managed externally.
 183  *
 184  * This field has no effect if the value type is not \ref GROUP_VALUE or
 185  * \ref POS_VALUE, but should not be set.
 186  */
 187 #define SEL_ALLOCDATA   (1<<9)
 188 /*! \brief
 189  * \p method->init_frame should be called for the frame.
 190  */
 191 #define SEL_INITFRAME   (1<<10)
 192 /*! \brief
 193  * Parameter has been evaluated for the current frame.
 194  *
 195  * This flag is set for children of \ref SEL_EXPRESSION elements (which
 196  * describe method parameters) after the element has been evaluated for the
 197  * current frame.
 198  * It is not set for \ref SEL_ATOMVAL elements, because they may need to
 199  * be evaluated multiple times.
 200  */
 201 #define SEL_EVALFRAME   (1<<11)
 202 /*! \brief
 203  * \p method->init has been called.
 204  */
 205 #define SEL_METHODINIT  (1<<12)
 206 /*! \brief
 207  * \p method->outinit has been called.
 208  *
 209  * This flag is also used for \ref SEL_SUBEXPRREF elements.
 210  */
 211 #define SEL_OUTINIT     (1<<13)
 212 /*@}*/
 213
 214
 215 /********************************************************************/
 216 /*! \name Selection expression data structures and functions
 217  ********************************************************************/
 218 /*@{*/
 219
 220 struct t_selelem;
 221
 222 /*! \brief
 223  * Function pointer for evaluating a \c t_selelem.
 224  */
 225 typedef void (*sel_evalfunc)(struct gmx_sel_evaluate_t *data,
 226                              struct t_selelem *sel, gmx_ana_index_t *g);
 227
 228 /*! \internal \brief
 229  * Represents an element of a selection expression.
 230  */
 231 typedef struct t_selelem
 232 {
 233     /*! \brief Name of the element.
 234      *
 235      * This field is only used for informative purposes.
 236      * It is always either NULL or a pointer to a string.
 237      * Memory is never allocated for it directly.
 238      */
 239     const char                         *name;
 240     /** Type of the element. */
 241     e_selelem_t                         type;
 242     /*! \brief
 243      * Value storage of the element.
 244      *
 245      * This field contains the evaluated value of the element, as well as
 246      * the output value type.
 247      */
 248     gmx_ana_selvalue_t                  v;
 249     /*! \brief
 250      * Evaluation function for the element.
 251      *
 252      * Can be either NULL (if the expression is a constant and does not require
 253      * evaluation) or point to one of the functions defined in evaluate.h.
 254      */
 255     sel_evalfunc                        evaluate;
 256     /*! \brief
 257      * Information flags about the element.
 258      *
 259      * Allowed flags are listed here:
 260      * \ref selelem_flags "flags for \c t_selelem".
 261      */
 262     int                                 flags;
 263     /** Data required by the evaluation function. */
 264     union {
 265         /*! \brief Index group data for several element types.
 266          *
 267          *  - \ref SEL_CONST : if the value type is \ref GROUP_VALUE,
 268          *    this field holds the unprocessed group value.
 269          *  - \ref SEL_ROOT : holds the group value for which the
 270          *    selection subtree should be evaluated.
 271          *  - \ref SEL_SUBEXPR : holds the group for which the subexpression
 272          *    has been evaluated.
 273          */
 274         gmx_ana_index_t                 cgrp;
 275         /** Data for \ref SEL_EXPRESSION and \ref SEL_MODIFIER elements. */
 276         struct {
 277             /** Pointer the the method used in this expression. */
 278             struct gmx_ana_selmethod_t *method;
 279             /** Pointer to the data allocated by the method's \p init_data (see sel_datafunc()). */
 280             void                       *mdata;
 281             /** Pointer to the position data passed to the method. */
 282             struct gmx_ana_pos_t       *pos;
 283             /** Pointer to the evaluation data for \p pos. */
 284             struct gmx_ana_poscalc_t   *pc;
 285         }                               expr;
 286         /** Operation type for \ref SEL_BOOLEAN elements. */
 287         e_boolean_t                     boolt;
 288         /** Operation type for \ref SEL_ARITHMETIC elements. */
 289         struct {
 290             /** Operation type. */
 291             e_arithmetic_t              type;
 292             /** String representation. */
 293             char                       *opstr;
 294         }                               arith;
 295         /** Associated selection parameter for \ref SEL_SUBEXPRREF elements. */
 296         struct gmx_ana_selparam_t      *param;
 297         /** The string/number used to reference the group. */
 298         struct {
 299             /** Name of the referenced external group. */
 300             char                       *name;
 301             /** If \a name is NULL, the index number of the referenced group. */
 302             int                         id;
 303         }                               gref;
 304     }                                   u;
 305     /** Memory pool to use for values, or NULL if standard memory handling. */
 306     struct gmx_sel_mempool_t           *mempool;
 307     /** Internal data for the selection compiler. */
 308     struct t_compiler_data             *cdata;
 309
 310     /*! \brief The first child element.
 311      *
 312      * Other children can be accessed through the \p next field of \p child.
 313      */
 314     struct t_selelem                    *child;
 315     /** The next sibling element. */
 316     struct t_selelem                    *next;
 317     /*! \brief Number of references to this element.
 318      *
 319      * Should be larger than one only for \ref SEL_SUBEXPR elements.
 320      */
 321     int                                  refcount;
 322 } t_selelem;
 323
 324 /* In evaluate.c */
 325 /** Writes out a human-readable name for an evaluation function. */
 326 extern void
 327 _gmx_sel_print_evalfunc_name(FILE *fp, sel_evalfunc evalfunc);
 328
 329 /** Allocates memory and performs some common initialization for a \c t_selelem. */
 330 extern t_selelem *
 331 _gmx_selelem_create(e_selelem_t type);
 332 /** Sets the value type of a \c t_selelem. */
 333 extern int
 334 _gmx_selelem_set_vtype(t_selelem *sel, e_selvalue_t vtype);
 335 /** Reserves memory for value of a \c t_selelem from a memory pool. */
 336 extern void
 337 _gmx_selelem_mempool_reserve(t_selelem *sel, int count);
 338 /** Releases memory pool used for value of a \c t_selelem. */
 339 extern void
 340 _gmx_selelem_mempool_release(t_selelem *sel);
 341 /** Frees the memory allocated for a \c t_selelem structure and all its children. */
 342 extern void
 343 _gmx_selelem_free(t_selelem *sel);
 344 /** Frees the memory allocated for a \c t_selelem structure, all its children, and also all structures referenced through t_selelem::next fields. */
 345 extern void
 346 _gmx_selelem_free_chain(t_selelem *first);
 347
 348 /** Frees the memory allocated for the \c t_selelem::d union. */
 349 extern void
 350 _gmx_selelem_free_values(t_selelem *sel);
 351 /** Frees the memory allocated for a selection method. */
 352 extern void
 353 _gmx_selelem_free_method(struct gmx_ana_selmethod_t *method, void *mdata);
 354 /** Frees the memory allocated for the \c t_selelem::u field. */
 355 extern void
 356 _gmx_selelem_free_exprdata(t_selelem *sel);
 357 /* In compiler.c */
 358 /** Frees the memory allocated for the selection compiler. */
 359 extern void
 360 _gmx_selelem_free_compiler_data(t_selelem *sel);
 361
 362 /** Prints a human-readable version of a selection element subtree. */
 363 extern void
 364 _gmx_selelem_print_tree(FILE *fp, t_selelem *root, bool bValues, int level);
 365 /* In compile.c */
 366 /** Prints a human-readable version of the internal compiler data structure. */
 367 extern void
 368 _gmx_selelem_print_compiler_info(FILE *fp, t_selelem *sel, int level);
 369
 370 /** Returns true if the selection element subtree requires topology information for evaluation. */
 371 extern bool
 372 _gmx_selelem_requires_top(t_selelem *root);
 373
 374 /* In sm_insolidangle.c */
 375 /** Returns true if the covered fraction of the selection can be calculated. */
 376 extern bool
 377 _gmx_selelem_can_estimate_cover(t_selelem *sel);
 378 /** Returns the covered fraction of the selection for the current frame. */
 379 extern real
 380 _gmx_selelem_estimate_coverfrac(t_selelem *sel);
 381
 382 /*@}*/
 383
 384 #endif