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