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