src/gmxlib/selection/selelem.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
   5  * Copyright (c) 2001-2009, The GROMACS development team,
   6  * check out http://www.gromacs.org for more information.
   7  * Copyright (c) 2012,2013, by the GROMACS development team, led by
   8  * David van der Spoel, Berk Hess, Erik Lindahl, and including many
   9  * others, as listed in the AUTHORS file in the top-level source
  10  * directory and at http://www.gromacs.org.
  11  *
  12  * GROMACS is free software; you can redistribute it and/or
  13  * modify it under the terms of the GNU Lesser General Public License
  14  * as published by the Free Software Foundation; either version 2.1
  15  * of the License, or (at your option) any later version.
  16  *
  17  * GROMACS is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20  * Lesser General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Lesser General Public
  23  * License along with GROMACS; if not, see
  24  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  25  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  26  *
  27  * If you want to redistribute modifications to GROMACS, please
  28  * consider that scientific software is very special. Version
  29  * control is crucial - bugs must be traceable. We will be happy to
  30  * consider code for inclusion in the official distribution, but
  31  * derived work must not be called official GROMACS. Details are found
  32  * in the README & COPYING files - if they are missing, get the
  33  * official version at http://www.gromacs.org.
  34  *
  35  * To help us fund GROMACS development, we humbly ask that you cite
  36  * the research papers on the package. Check out http://www.gromacs.org.
  37  */
  38 /*! \internal \file
  39  * \brief Definition of \c t_selelem and related things.
  40  *
  41  * The selection element trees constructed by the parser and the compiler
  42  * are described on the respective pages:
  43  * \ref selparser and \ref selcompiler.
  44  *
  45  * This is an implementation header: there should be no need to use it outside
  46  * this directory.
  47  */
  48 #ifndef SELECTION_ELEMENT_H
  49 #define SELECTION_ELEMENT_H
  50
  51 #include <types/simple.h>
  52
  53 #include <indexutil.h>
  54 #include <selvalue.h>
  55
  56 struct gmx_ana_poscalc_t;
  57 struct gmx_ana_selparam_t;
  58 struct gmx_ana_selmethod_t;
  59
  60 struct gmx_sel_evaluate_t;
  61 struct gmx_sel_mempool_t;
  62 struct t_selelem;
  63
  64 /********************************************************************/
  65 /*! \name Enumerations for expression types
  66  ********************************************************************/
  67 /*@{*/
  68
  69 /** Defines the type of a \c t_selelem object. */
  70 typedef enum
  71 {
  72     /** Constant-valued expression. */
  73     SEL_CONST,
  74     /** Method expression that requires evaluation. */
  75     SEL_EXPRESSION,
  76     /** Boolean expression. */
  77     SEL_BOOLEAN,
  78     /** Arithmetic expression. */
  79     SEL_ARITHMETIC,
  80     /** Root node of the evaluation tree. */
  81     SEL_ROOT,
  82     /** Subexpression that may be referenced several times. */
  83     SEL_SUBEXPR,
  84     /** Reference to a subexpression. */
  85     SEL_SUBEXPRREF,
  86     /** Post-processing of selection value. */
  87     SEL_MODIFIER
  88 } e_selelem_t;
  89
  90 /** Defines the gmx_boolean operation of \c t_selelem objects with type \ref SEL_BOOLEAN. */
  91 typedef enum
  92 {
  93     BOOL_NOT,           /**< Not */
  94     BOOL_AND,           /**< And */
  95     BOOL_OR,            /**< Or */
  96     BOOL_XOR            /**< Xor (not implemented). */
  97 } e_boolean_t;
  98
  99 /** Defines the arithmetic operation of \c t_selelem objects with type \ref SEL_ARITHMETIC. */
 100 typedef enum
 101 {
 102     ARITH_PLUS,         /**< + */
 103     ARITH_MINUS,        /**< - */
 104     ARITH_NEG,          /**< Unary - */
 105     ARITH_MULT,         /**< * */
 106     ARITH_DIV,          /**< / */
 107     ARITH_EXP           /**< ^ (to power) */
 108 } e_arithmetic_t;
 109
 110 /** Returns a string representation of the type of a \c t_selelem. */
 111 extern const char *
 112 _gmx_selelem_type_str(struct t_selelem *sel);
 113 /** Returns a string representation of the gmx_boolean type of a \ref SEL_BOOLEAN \c t_selelem. */
 114 extern const char *
 115 _gmx_selelem_gmx_boolean_type_str(struct t_selelem *sel);
 116 /** Returns a string representation of the type of a \c gmx_ana_selvalue_t. */
 117 extern const char *
 118 _gmx_sel_value_type_str(gmx_ana_selvalue_t *val);
 119
 120 /*@}*/
 121
 122
 123 /********************************************************************/
 124 /*! \name Selection expression flags
 125  * \anchor selelem_flags
 126  ********************************************************************/
 127 /*@{*/
 128 /*! \brief
 129  * Selection value flags are set.
 130  *
 131  * If this flag is set, the flags covered by \ref SEL_VALFLAGMASK
 132  * have been set properly for the element.
 133  */
 134 #define SEL_FLAGSSET    1
 135 /*! \brief
 136  * The element evaluates to a single value.
 137  *
 138  * This flag is always set for \ref GROUP_VALUE elements.
 139  */
 140 #define SEL_SINGLEVAL   2
 141 /*! \brief
 142  * The element evaluates to one value for each input atom.
 143  */
 144 #define SEL_ATOMVAL     4
 145 /*! \brief
 146  * The element evaluates to an arbitrary number of values.
 147  */
 148 #define SEL_VARNUMVAL   8
 149 /*! \brief
 150  * The element (or one of its children) is dynamic.
 151  */
 152 #define SEL_DYNAMIC     16
 153 /*! \brief
 154  * Mask that covers the flags that describe the number of values.
 155  */
 156 #define SEL_VALTYPEMASK (SEL_SINGLEVAL | SEL_ATOMVAL | SEL_VARNUMVAL)
 157 /*! \brief
 158  * Mask that covers the flags that describe the value type.
 159  */
 160 #define SEL_VALFLAGMASK (SEL_FLAGSSET | SEL_VALTYPEMASK | SEL_DYNAMIC)
 161 /*! \brief
 162  * Data has been allocated for the \p v.u union.
 163  *
 164  * If not set, the \p v.u.ptr points to data allocated externally.
 165  * This is the case if the value of the element is used as a parameter
 166  * for a selection method or if the element evaluates the final value of
 167  * a selection.
 168  *
 169  * Even if the flag is set, \p v.u.ptr can be NULL during initialization.
 170  *
 171  * \todo
 172  * This flag overlaps with the function of \p v.nalloc field, and could
 173  * probably be removed, making memory management simpler. Currently, the
 174  * \p v.nalloc field is not kept up-to-date in all cases when this flag
 175  * is changed and is used in places where this flag is not, so this would
 176  * require a careful investigation of the selection code.
 177  */
 178 #define SEL_ALLOCVAL    (1<<8)
 179 /*! \brief
 180  * Data has been allocated for the group/position structure.
 181  *
 182  * If not set, the memory allocated for fields in \p v.u.g or \p v.u.p is
 183  * managed externally.
 184  *
 185  * This field has no effect if the value type is not \ref GROUP_VALUE or
 186  * \ref POS_VALUE, but should not be set.
 187  */
 188 #define SEL_ALLOCDATA   (1<<9)
 189 /*! \brief
 190  * \p method->init_frame should be called for the frame.
 191  */
 192 #define SEL_INITFRAME   (1<<10)
 193 /*! \brief
 194  * Parameter has been evaluated for the current frame.
 195  *
 196  * This flag is set for children of \ref SEL_EXPRESSION elements (which
 197  * describe method parameters) after the element has been evaluated for the
 198  * current frame.
 199  * It is not set for \ref SEL_ATOMVAL elements, because they may need to
 200  * be evaluated multiple times.
 201  */
 202 #define SEL_EVALFRAME   (1<<11)
 203 /*! \brief
 204  * \p method->init has been called.
 205  */
 206 #define SEL_METHODINIT  (1<<12)
 207 /*! \brief
 208  * \p method->outinit has been called.
 209  *
 210  * This flag is also used for \ref SEL_SUBEXPRREF elements.
 211  */
 212 #define SEL_OUTINIT     (1<<13)
 213 /*@}*/
 214
 215
 216 /********************************************************************/
 217 /*! \name Selection expression data structures and functions
 218  ********************************************************************/
 219 /*@{*/
 220
 221 struct t_selelem;
 222
 223 /*! \brief
 224  * Function pointer for evaluating a \c t_selelem.
 225  */
 226 typedef int (*sel_evalfunc)(struct gmx_sel_evaluate_t *data,
 227                             struct t_selelem *sel, gmx_ana_index_t *g);
 228
 229 /*! \internal \brief
 230  * Represents an element of a selection expression.
 231  */
 232 typedef struct t_selelem
 233 {
 234     /*! \brief Name of the element.
 235      *
 236      * This field is only used for informative purposes.
 237      * It is always either NULL or a pointer to a string.
 238      * Memory is never allocated for it directly.
 239      */
 240     const char                         *name;
 241     /** Type of the element. */
 242     e_selelem_t                         type;
 243     /*! \brief
 244      * Value storage of the element.
 245      *
 246      * This field contains the evaluated value of the element, as well as
 247      * the output value type.
 248      */
 249     gmx_ana_selvalue_t                  v;
 250     /*! \brief
 251      * Evaluation function for the element.
 252      *
 253      * Can be either NULL (if the expression is a constant and does not require
 254      * evaluation) or point to one of the functions defined in evaluate.h.
 255      */
 256     sel_evalfunc                        evaluate;
 257     /*! \brief
 258      * Information flags about the element.
 259      *
 260      * Allowed flags are listed here:
 261      * \ref selelem_flags "flags for \c t_selelem".
 262      */
 263     int                                 flags;
 264     /** Data required by the evaluation function. */
 265     union {
 266         /*! \brief Index group data for several element types.
 267          *
 268          *  - \ref SEL_CONST : if the value type is \ref GROUP_VALUE,
 269          *    this field holds the unprocessed group value.
 270          *  - \ref SEL_ROOT : holds the group value for which the
 271          *    selection subtree should be evaluated.
 272          *  - \ref SEL_SUBEXPR : holds the group for which the subexpression
 273          *    has been evaluated.
 274          */
 275         gmx_ana_index_t                 cgrp;
 276         /** Data for \ref SEL_EXPRESSION and \ref SEL_MODIFIER elements. */
 277         struct {
 278             /** Pointer the the method used in this expression. */
 279             struct gmx_ana_selmethod_t *method;
 280             /** Pointer to the data allocated by the method's \p init_data (see sel_datafunc()). */
 281             void                       *mdata;
 282             /** Pointer to the position data passed to the method. */
 283             struct gmx_ana_pos_t       *pos;
 284             /** Pointer to the evaluation data for \p pos. */
 285             struct gmx_ana_poscalc_t   *pc;
 286         }                               expr;
 287         /** Operation type for \ref SEL_BOOLEAN elements. */
 288         e_boolean_t                     boolt;
 289         /** Operation type for \ref SEL_ARITHMETIC elements. */
 290         struct {
 291             /** Operation type. */
 292             e_arithmetic_t              type;
 293             /** String representation. */
 294             char                       *opstr;
 295         }                               arith;
 296         /** Associated selection parameter for \ref SEL_SUBEXPRREF elements. */
 297         struct gmx_ana_selparam_t      *param;
 298     }                                   u;
 299     /** Memory pool to use for values, or NULL if standard memory handling. */
 300     struct gmx_sel_mempool_t           *mempool;
 301     /** Internal data for the selection compiler. */
 302     struct t_compiler_data             *cdata;
 303
 304     /*! \brief The first child element.
 305      *
 306      * Other children can be accessed through the \p next field of \p child.
 307      */
 308     struct t_selelem                    *child;
 309     /** The next sibling element. */
 310     struct t_selelem                    *next;
 311     /*! \brief Number of references to this element.
 312      *
 313      * Should be larger than one only for \ref SEL_SUBEXPR elements.
 314      */
 315     int                                  refcount;
 316 } t_selelem;
 317
 318 /* In evaluate.c */
 319 /** Writes out a human-readable name for an evaluation function. */
 320 extern void
 321 _gmx_sel_print_evalfunc_name(FILE *fp, sel_evalfunc evalfunc);
 322
 323 /** Allocates memory and performs some common initialization for a \c t_selelem. */
 324 extern t_selelem *
 325 _gmx_selelem_create(e_selelem_t type);
 326 /** Sets the value type of a \c t_selelem. */
 327 extern int
 328 _gmx_selelem_set_vtype(t_selelem *sel, e_selvalue_t vtype);
 329 /** Reserves memory for value of a \c t_selelem from a memory pool. */
 330 extern int
 331 _gmx_selelem_mempool_reserve(t_selelem *sel, int count);
 332 /** Releases memory pool used for value of a \c t_selelem. */
 333 extern void
 334 _gmx_selelem_mempool_release(t_selelem *sel);
 335 /** Frees the memory allocated for a \c t_selelem structure and all its children. */
 336 extern void
 337 _gmx_selelem_free(t_selelem *sel);
 338 /** Frees the memory allocated for a \c t_selelem structure, all its children, and also all structures referenced through t_selelem::next fields. */
 339 extern void
 340 _gmx_selelem_free_chain(t_selelem *first);
 341
 342 /** Frees the memory allocated for the \c t_selelem::d union. */
 343 extern void
 344 _gmx_selelem_free_values(t_selelem *sel);
 345 /** Frees the memory allocated for a selection method. */
 346 extern void
 347 _gmx_selelem_free_method(struct gmx_ana_selmethod_t *method, void *mdata);
 348 /** Frees the memory allocated for the \c t_selelem::u field. */
 349 extern void
 350 _gmx_selelem_free_exprdata(t_selelem *sel);
 351 /* In compiler.c */
 352 /** Frees the memory allocated for the selection compiler. */
 353 extern void
 354 _gmx_selelem_free_compiler_data(t_selelem *sel);
 355
 356 /** Prints a human-readable version of a selection element subtree. */
 357 extern void
 358 _gmx_selelem_print_tree(FILE *fp, t_selelem *root, gmx_bool bValues, int level);
 359 /* In compile.c */
 360 /** Prints a human-readable version of the internal compiler data structure. */
 361 extern void
 362 _gmx_selelem_print_compiler_info(FILE *fp, t_selelem *sel, int level);
 363
 364 /** Returns TRUE if the selection element subtree requires topology information for evaluation. */
 365 extern gmx_bool
 366 _gmx_selelem_requires_top(t_selelem *root);
 367
 368 /* In sm_insolidangle.c */
 369 /** Returns TRUE if the covered fraction of the selection can be calculated. */
 370 extern gmx_bool
 371 _gmx_selelem_can_estimate_cover(t_selelem *sel);
 372 /** Returns the covered fraction of the selection for the current frame. */
 373 extern real
 374 _gmx_selelem_estimate_coverfrac(t_selelem *sel);
 375
 376 /*@}*/
 377
 378 #endif