3 * This source code is part of
7 * GROningen MAchine for Chemical Simulations
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.
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.
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.
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.
29 * For more info, check our website at http://www.gromacs.org
33 * Declares gmx::SelectionTreeElement and related things.
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.
39 * This is an implementation header: there should be no need to use it outside
42 * \author Teemu Murtola <teemu.murtola@cbr.su.se>
43 * \ingroup module_selection
45 #ifndef GMX_SELECTION_SELELEM_H
46 #define GMX_SELECTION_SELELEM_H
48 #include <boost/shared_ptr.hpp>
50 #include "gromacs/legacyheaders/types/simple.h"
51 #include "gromacs/utility/common.h"
53 #include "indexutil.h"
56 struct gmx_ana_poscalc_t;
57 struct gmx_ana_selparam_t;
58 struct gmx_ana_selmethod_t;
60 struct gmx_sel_evaluate_t;
61 struct gmx_sel_mempool_t;
63 struct t_compiler_data;
67 class SelectionTreeElement;
69 //! Smart pointer type for selection tree element pointers.
70 typedef boost::shared_ptr<SelectionTreeElement> SelectionTreeElementPointer;
73 /********************************************************************/
74 /*! \name Enumerations for expression types
75 ********************************************************************/
78 /** Defines the type of a gmx::SelectionTreeElement object. */
81 /** Constant-valued expression. */
83 /** Method expression that requires evaluation. */
85 /** Boolean expression. */
87 /** Arithmetic expression. */
89 /** Root node of the evaluation tree. */
91 /** Subexpression that may be referenced several times. */
93 /** Reference to a subexpression. */
95 /** Unresolved reference to an external group. */
97 /** Post-processing of selection value. */
101 /** Defines the boolean operation of gmx::SelectionTreeElement objects with type \ref SEL_BOOLEAN. */
104 BOOL_NOT, /**< Not */
105 BOOL_AND, /**< And */
107 BOOL_XOR /**< Xor (not implemented). */
110 /** Defines the arithmetic operation of gmx::SelectionTreeElement objects with type \ref SEL_ARITHMETIC. */
113 ARITH_PLUS, /**< + */
114 ARITH_MINUS, /**< - */
115 ARITH_NEG, /**< Unary - */
116 ARITH_MULT, /**< * */
118 ARITH_EXP /**< ^ (to power) */
121 /** Returns a string representation of the type of a gmx::SelectionTreeElement. */
123 _gmx_selelem_type_str(const gmx::SelectionTreeElement &sel);
124 /** Returns a string representation of the boolean type of a \ref SEL_BOOLEAN gmx::SelectionTreeElement. */
126 _gmx_selelem_boolean_type_str(const gmx::SelectionTreeElement &sel);
127 /** Returns a string representation of the type of a \c gmx_ana_selvalue_t. */
129 _gmx_sel_value_type_str(const gmx_ana_selvalue_t *val);
134 /********************************************************************/
135 /*! \name Selection expression flags
136 * \anchor selelem_flags
137 ********************************************************************/
140 * Selection value flags are set.
142 * If this flag is set, the flags covered by \ref SEL_VALFLAGMASK
143 * have been set properly for the element.
145 #define SEL_FLAGSSET 1
147 * The element evaluates to a single value.
149 * This flag is always set for \ref GROUP_VALUE elements.
151 #define SEL_SINGLEVAL 2
153 * The element evaluates to one value for each input atom.
155 #define SEL_ATOMVAL 4
157 * The element evaluates to an arbitrary number of values.
159 #define SEL_VARNUMVAL 8
161 * The element (or one of its children) is dynamic.
163 #define SEL_DYNAMIC 16
165 * Mask that covers the flags that describe the number of values.
167 #define SEL_VALTYPEMASK (SEL_SINGLEVAL | SEL_ATOMVAL | SEL_VARNUMVAL)
169 * Mask that covers the flags that describe the value type.
171 #define SEL_VALFLAGMASK (SEL_FLAGSSET | SEL_VALTYPEMASK | SEL_DYNAMIC)
173 * Data has been allocated for the \p v.u union.
175 * If not set, the \p v.u.ptr points to data allocated externally.
176 * This is the case if the value of the element is used as a parameter
177 * for a selection method or if the element evaluates the final value of
180 * Even if the flag is set, \p v.u.ptr can be NULL during initialization.
183 * This flag overlaps with the function of \p v.nalloc field, and could
184 * probably be removed, making memory management simpler. Currently, the
185 * \p v.nalloc field is not kept up-to-date in all cases when this flag
186 * is changed and is used in places where this flag is not, so this would
187 * require a careful investigation of the selection code.
189 #define SEL_ALLOCVAL (1<<8)
191 * Data has been allocated for the group/position structure.
193 * If not set, the memory allocated for fields in \p v.u.g or \p v.u.p is
194 * managed externally.
196 * This field has no effect if the value type is not \ref GROUP_VALUE or
197 * \ref POS_VALUE, but should not be set.
199 #define SEL_ALLOCDATA (1<<9)
201 * \p method->init_frame should be called for the frame.
203 #define SEL_INITFRAME (1<<10)
205 * Parameter has been evaluated for the current frame.
207 * This flag is set for children of \ref SEL_EXPRESSION elements (which
208 * describe method parameters) after the element has been evaluated for the
210 * It is not set for \ref SEL_ATOMVAL elements, because they may need to
211 * be evaluated multiple times.
213 #define SEL_EVALFRAME (1<<11)
215 * \p method->init has been called.
217 #define SEL_METHODINIT (1<<12)
219 * \p method->outinit has been called.
221 * This flag is also used for \ref SEL_SUBEXPRREF elements.
223 #define SEL_OUTINIT (1<<13)
231 * Function pointer for evaluating a gmx::SelectionTreeElement.
233 typedef void (*sel_evalfunc)(struct gmx_sel_evaluate_t *data,
234 const SelectionTreeElementPointer &sel,
238 * Represents an element of a selection expression.
240 class SelectionTreeElement
244 * Allocates memory and performs common initialization.
246 * \param[in] type Type of selection element to create.
248 * \a type is set to \p type,
249 * \a v::type is set to \ref GROUP_VALUE for boolean and comparison
250 * expressions and \ref NO_VALUE for others, and
251 * \ref SEL_ALLOCVAL is set for non-root elements (\ref SEL_ALLOCDATA
252 * is also set for \ref SEL_BOOLEAN elements).
253 * All the pointers are set to NULL.
255 explicit SelectionTreeElement(e_selelem_t type);
256 ~SelectionTreeElement();
258 //! Frees the memory allocated for the \a v union.
260 //! Frees the memory allocated for the \a u union.
261 void freeExpressionData();
262 /* In compiler.cpp */
264 * Frees the memory allocated for the selection compiler.
266 * This function only frees the data for the given selection, not its
267 * children. It is safe to call the function when compiler data has
268 * not been allocated or has already been freed; in such a case,
271 void freeCompilerData();
274 * Reserves memory for value from a memory pool.
276 * \param[in] count Number of values to reserve memory for.
278 * Reserves memory for the values of this element from the \a mempool
280 * If no memory pool is set, nothing is done.
282 void mempoolReserve(int count);
284 * Releases memory pool used for value.
286 * Releases the memory allocated for the values of this element from the
287 * \a mempool memory pool.
288 * If no memory pool is set, nothing is done.
290 void mempoolRelease();
292 /*! \brief Name of the element.
294 * This field is only used for informative purposes.
295 * It is always either NULL or a pointer to a string.
296 * Memory is never allocated for it directly.
299 //! Type of the element.
302 * Value storage of the element.
304 * This field contains the evaluated value of the element, as well as
305 * the output value type.
307 gmx_ana_selvalue_t v;
309 * Evaluation function for the element.
311 * Can be either NULL (if the expression is a constant and does not
312 * require evaluation) or point to one of the functions defined in
315 sel_evalfunc evaluate;
317 * Information flags about the element.
319 * Allowed flags are listed here:
320 * \ref selelem_flags "flags for gmx::SelectionTreeElement".
323 //! Data required by the evaluation function.
325 /*! \brief Index group data for several element types.
327 * - \ref SEL_CONST : if the value type is \ref GROUP_VALUE,
328 * this field holds the unprocessed group value.
329 * - \ref SEL_ROOT : holds the group value for which the
330 * selection subtree should be evaluated.
331 * - \ref SEL_SUBEXPR : holds the group for which the subexpression
332 * has been evaluated.
334 gmx_ana_index_t cgrp;
335 //! Data for \ref SEL_EXPRESSION and \ref SEL_MODIFIER elements.
337 //! Pointer the the method used in this expression.
338 struct gmx_ana_selmethod_t *method;
339 //! Pointer to the data allocated by the method's \p init_data (see sel_datafunc()).
341 //! Pointer to the position data passed to the method.
342 struct gmx_ana_pos_t *pos;
343 //! Pointer to the evaluation data for \p pos.
344 struct gmx_ana_poscalc_t *pc;
346 //! Operation type for \ref SEL_BOOLEAN elements.
348 //! Operation type for \ref SEL_ARITHMETIC elements.
352 //! String representation.
355 //! Associated selection parameter for \ref SEL_SUBEXPRREF elements.
356 struct gmx_ana_selparam_t *param;
357 //! The string/number used to reference the group.
359 //! Name of the referenced external group.
361 //! If \a name is NULL, the index number of the referenced group.
365 //! Memory pool to use for values, or NULL if standard memory handling.
366 struct gmx_sel_mempool_t *mempool;
367 //! Internal data for the selection compiler.
368 t_compiler_data *cdata;
370 /*! \brief The first child element.
372 * Other children can be accessed through the \p next field of \p child.
374 SelectionTreeElementPointer child;
375 //! The next sibling element.
376 SelectionTreeElementPointer next;
379 GMX_DISALLOW_COPY_AND_ASSIGN(SelectionTreeElement);
384 /********************************************************************/
385 /*! \name Selection expression functions
390 /** Writes out a human-readable name for an evaluation function. */
392 _gmx_sel_print_evalfunc_name(FILE *fp, gmx::sel_evalfunc evalfunc);
394 /** Sets the value type of a gmx::SelectionTreeElement. */
396 _gmx_selelem_set_vtype(const gmx::SelectionTreeElementPointer &sel,
399 /** Frees the memory allocated for a selection method. */
401 _gmx_selelem_free_method(struct gmx_ana_selmethod_t *method, void *mdata);
403 /** Prints a human-readable version of a selection element subtree. */
405 _gmx_selelem_print_tree(FILE *fp, const gmx::SelectionTreeElement &sel,
406 bool bValues, int level);
408 /** Prints a human-readable version of the internal compiler data structure. */
410 _gmx_selelem_print_compiler_info(FILE *fp, const gmx::SelectionTreeElement &sel,
413 /** Returns true if the selection element subtree requires topology information for evaluation. */
415 _gmx_selelem_requires_top(const gmx::SelectionTreeElement &root);
417 /* In sm_insolidangle.c */
418 /** Returns true if the covered fraction of the selection can be calculated. */
420 _gmx_selelem_can_estimate_cover(const gmx::SelectionTreeElement &sel);
421 /** Returns the covered fraction of the selection for the current frame. */
423 _gmx_selelem_estimate_coverfrac(const gmx::SelectionTreeElement &sel);