2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2009,2010,2011,2012,2013, by the GROMACS development team, led by
5 * David van der Spoel, Berk Hess, Erik Lindahl, and including many
6 * others, as listed in the AUTHORS file in the top-level source
7 * directory and at http://www.gromacs.org.
9 * GROMACS is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Lesser General Public License
11 * as published by the Free Software Foundation; either version 2.1
12 * of the License, or (at your option) any later version.
14 * GROMACS is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Lesser General Public License for more details.
19 * You should have received a copy of the GNU Lesser General Public
20 * License along with GROMACS; if not, see
21 * http://www.gnu.org/licenses, or write to the Free Software Foundation,
22 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
24 * If you want to redistribute modifications to GROMACS, please
25 * consider that scientific software is very special. Version
26 * control is crucial - bugs must be traceable. We will be happy to
27 * consider code for inclusion in the official distribution, but
28 * derived work must not be called official GROMACS. Details are found
29 * in the README & COPYING files - if they are missing, get the
30 * official version at http://www.gromacs.org.
32 * To help us fund GROMACS development, we humbly ask that you cite
33 * the research papers on the package. Check out http://www.gromacs.org.
37 * Declares gmx::SelectionTreeElement and related things.
39 * The selection element trees constructed by the parser and the compiler
40 * are described on the respective pages:
41 * \ref page_module_selection_parser and \ref page_module_selection_compiler.
43 * This is an implementation header: there should be no need to use it outside
46 * \author Teemu Murtola <teemu.murtola@gmail.com>
47 * \ingroup module_selection
49 #ifndef GMX_SELECTION_SELELEM_H
50 #define GMX_SELECTION_SELELEM_H
54 #include <boost/shared_ptr.hpp>
56 #include "gromacs/legacyheaders/types/simple.h"
57 #include "gromacs/utility/common.h"
59 #include "indexutil.h"
62 struct gmx_ana_poscalc_t;
63 struct gmx_ana_selparam_t;
64 struct gmx_ana_selmethod_t;
66 struct gmx_sel_evaluate_t;
67 struct gmx_sel_mempool_t;
69 struct t_compiler_data;
73 class SelectionTreeElement;
75 //! Smart pointer type for selection tree element pointers.
76 typedef boost::shared_ptr<SelectionTreeElement> SelectionTreeElementPointer;
79 /********************************************************************/
80 /*! \name Enumerations for expression types
81 ********************************************************************/
84 /** Defines the type of a gmx::SelectionTreeElement object. */
87 /** Constant-valued expression. */
89 /** Method expression that requires evaluation. */
91 /** Boolean expression. */
93 /** Arithmetic expression. */
95 /** Root node of the evaluation tree. */
97 /** Subexpression that may be referenced several times. */
99 /** Reference to a subexpression. */
101 /** Unresolved reference to an external group. */
103 /** Post-processing of selection value. */
107 /** Defines the boolean operation of gmx::SelectionTreeElement objects with type \ref SEL_BOOLEAN. */
110 BOOL_NOT, /**< Not */
111 BOOL_AND, /**< And */
113 BOOL_XOR /**< Xor (not implemented). */
116 /** Defines the arithmetic operation of gmx::SelectionTreeElement objects with type \ref SEL_ARITHMETIC. */
119 ARITH_PLUS, /**< + */
120 ARITH_MINUS, /**< - */
121 ARITH_NEG, /**< Unary - */
122 ARITH_MULT, /**< * */
124 ARITH_EXP /**< ^ (to power) */
127 /** Returns a string representation of the type of a gmx::SelectionTreeElement. */
129 _gmx_selelem_type_str(const gmx::SelectionTreeElement &sel);
130 /** Returns a string representation of the boolean type of a \ref SEL_BOOLEAN gmx::SelectionTreeElement. */
132 _gmx_selelem_boolean_type_str(const gmx::SelectionTreeElement &sel);
133 /** Returns a string representation of the type of a \c gmx_ana_selvalue_t. */
135 _gmx_sel_value_type_str(const gmx_ana_selvalue_t *val);
140 /********************************************************************/
141 /*! \name Selection expression flags
142 * \anchor selelem_flags
143 ********************************************************************/
146 * Selection value flags are set.
148 * If this flag is set, the flags covered by \ref SEL_VALFLAGMASK
149 * have been set properly for the element.
151 #define SEL_FLAGSSET 1
153 * The element evaluates to a single value.
155 * This flag is always set for \ref GROUP_VALUE elements.
157 #define SEL_SINGLEVAL 2
159 * The element evaluates to one value for each input atom.
161 #define SEL_ATOMVAL 4
163 * The element evaluates to an arbitrary number of values.
165 #define SEL_VARNUMVAL 8
167 * The element (or one of its children) is dynamic.
169 #define SEL_DYNAMIC 16
171 * Mask that covers the flags that describe the number of values.
173 #define SEL_VALTYPEMASK (SEL_SINGLEVAL | SEL_ATOMVAL | SEL_VARNUMVAL)
175 * Mask that covers the flags that describe the value type.
177 #define SEL_VALFLAGMASK (SEL_FLAGSSET | SEL_VALTYPEMASK | SEL_DYNAMIC)
179 * Data has been allocated for the \p v.u union.
181 * If not set, the \p v.u.ptr points to data allocated externally.
182 * This is the case if the value of the element is used as a parameter
183 * for a selection method or if the element evaluates the final value of
186 * Even if the flag is set, \p v.u.ptr can be NULL during initialization.
189 * This flag overlaps with the function of \p v.nalloc field, and could
190 * probably be removed, making memory management simpler. Currently, the
191 * \p v.nalloc field is not kept up-to-date in all cases when this flag
192 * is changed and is used in places where this flag is not, so this would
193 * require a careful investigation of the selection code.
195 #define SEL_ALLOCVAL (1<<8)
197 * Data has been allocated for the group/position structure.
199 * If not set, the memory allocated for fields in \p v.u.g or \p v.u.p is
200 * managed externally.
202 * This field has no effect if the value type is not \ref GROUP_VALUE or
203 * \ref POS_VALUE, but should not be set.
205 #define SEL_ALLOCDATA (1<<9)
207 * \p method->init_frame should be called for the frame.
209 #define SEL_INITFRAME (1<<10)
211 * Parameter has been evaluated for the current frame.
213 * This flag is set for children of \ref SEL_EXPRESSION elements (which
214 * describe method parameters) after the element has been evaluated for the
216 * It is not set for \ref SEL_ATOMVAL elements, because they may need to
217 * be evaluated multiple times.
219 #define SEL_EVALFRAME (1<<11)
221 * \p method->init has been called.
223 #define SEL_METHODINIT (1<<12)
225 * \p method->outinit has been called.
227 * This flag is also used for \ref SEL_SUBEXPRREF elements.
229 #define SEL_OUTINIT (1<<13)
237 * Function pointer for evaluating a gmx::SelectionTreeElement.
239 typedef void (*sel_evalfunc)(struct gmx_sel_evaluate_t *data,
240 const SelectionTreeElementPointer &sel,
244 * Represents an element of a selection expression.
246 class SelectionTreeElement
250 * Allocates memory and performs common initialization.
252 * \param[in] type Type of selection element to create.
254 * \a type is set to \p type,
255 * \a v::type is set to \ref GROUP_VALUE for boolean and comparison
256 * expressions and \ref NO_VALUE for others, and
257 * \ref SEL_ALLOCVAL is set for non-root elements (\ref SEL_ALLOCDATA
258 * is also set for \ref SEL_BOOLEAN elements).
259 * All the pointers are set to NULL.
261 explicit SelectionTreeElement(e_selelem_t type);
262 ~SelectionTreeElement();
264 //! Frees the memory allocated for the \a v union.
266 //! Frees the memory allocated for the \a u union.
267 void freeExpressionData();
268 /* In compiler.cpp */
270 * Frees the memory allocated for the selection compiler.
272 * This function only frees the data for the given selection, not its
273 * children. It is safe to call the function when compiler data has
274 * not been allocated or has already been freed; in such a case,
277 void freeCompilerData();
280 * Reserves memory for value from a memory pool.
282 * \param[in] count Number of values to reserve memory for.
284 * Reserves memory for the values of this element from the \a mempool
286 * If no memory pool is set, nothing is done.
288 void mempoolReserve(int count);
290 * Releases memory pool used for value.
292 * Releases the memory allocated for the values of this element from the
293 * \a mempool memory pool.
294 * If no memory pool is set, nothing is done.
296 void mempoolRelease();
298 //! Returns the name of the element.
299 const std::string &name() const { return name_; }
301 * Sets the name of the element.
303 * \param[in] name Name to set (can be NULL).
304 * \throws std::bad_alloc if out of memory.
306 void setName(const char *name) { name_ = (name != NULL ? name : ""); }
307 //! \copydoc setName(const char *)
308 void setName(const std::string &name) { name_ = name; }
310 * Sets the name of a root element if it is missing.
312 * \param[in] selectionText Full selection text to use as a fallback.
313 * \throws std::bad_alloc if out of memory.
315 * If index groups have not yet been set and the selection is a result
316 * of a group reference, the name may still be empty after this call.
318 * Strong exception safety guarantee.
320 void fillNameIfMissing(const char *selectionText);
322 //! Type of the element.
325 * Value storage of the element.
327 * This field contains the evaluated value of the element, as well as
328 * the output value type.
330 gmx_ana_selvalue_t v;
332 * Evaluation function for the element.
334 * Can be either NULL (if the expression is a constant and does not
335 * require evaluation) or point to one of the functions defined in
338 sel_evalfunc evaluate;
340 * Information flags about the element.
342 * Allowed flags are listed here:
343 * \ref selelem_flags "flags for gmx::SelectionTreeElement".
346 //! Data required by the evaluation function.
348 /*! \brief Index group data for several element types.
350 * - \ref SEL_CONST : if the value type is \ref GROUP_VALUE,
351 * this field holds the unprocessed group value.
352 * - \ref SEL_ROOT : holds the group value for which the
353 * selection subtree should be evaluated.
354 * - \ref SEL_SUBEXPR : holds the group for which the subexpression
355 * has been evaluated.
357 gmx_ana_index_t cgrp;
358 //! Data for \ref SEL_EXPRESSION and \ref SEL_MODIFIER elements.
360 //! Pointer the the method used in this expression.
361 struct gmx_ana_selmethod_t *method;
362 //! Pointer to the data allocated by the method's \p init_data (see sel_datafunc()).
364 //! Pointer to the position data passed to the method.
365 struct gmx_ana_pos_t *pos;
366 //! Pointer to the evaluation data for \p pos.
367 struct gmx_ana_poscalc_t *pc;
369 //! Operation type for \ref SEL_BOOLEAN elements.
371 //! Operation type for \ref SEL_ARITHMETIC elements.
375 //! String representation.
378 //! Associated selection parameter for \ref SEL_SUBEXPRREF elements.
379 struct gmx_ana_selparam_t *param;
380 //! The string/number used to reference the group.
382 //! Name of the referenced external group.
384 //! If \a name is NULL, the index number of the referenced group.
388 //! Memory pool to use for values, or NULL if standard memory handling.
389 struct gmx_sel_mempool_t *mempool;
390 //! Internal data for the selection compiler.
391 t_compiler_data *cdata;
393 /*! \brief The first child element.
395 * Other children can be accessed through the \p next field of \p child.
397 SelectionTreeElementPointer child;
398 //! The next sibling element.
399 SelectionTreeElementPointer next;
403 * Name of the element.
405 * This field is only used for informative purposes.
409 GMX_DISALLOW_COPY_AND_ASSIGN(SelectionTreeElement);
414 /********************************************************************/
415 /*! \name Selection expression functions
420 /** Writes out a human-readable name for an evaluation function. */
422 _gmx_sel_print_evalfunc_name(FILE *fp, gmx::sel_evalfunc evalfunc);
424 /** Sets the value type of a gmx::SelectionTreeElement. */
426 _gmx_selelem_set_vtype(const gmx::SelectionTreeElementPointer &sel,
429 /** Frees the memory allocated for a selection method. */
431 _gmx_selelem_free_method(struct gmx_ana_selmethod_t *method, void *mdata);
433 /** Prints a human-readable version of a selection element subtree. */
435 _gmx_selelem_print_tree(FILE *fp, const gmx::SelectionTreeElement &sel,
436 bool bValues, int level);
438 /** Prints a human-readable version of the internal compiler data structure. */
440 _gmx_selelem_print_compiler_info(FILE *fp, const gmx::SelectionTreeElement &sel,
443 /** Returns true if the selection element subtree requires topology information for evaluation. */
445 _gmx_selelem_requires_top(const gmx::SelectionTreeElement &root);
447 /* In sm_insolidangle.c */
448 /** Returns true if the covered fraction of the selection can be calculated. */
450 _gmx_selelem_can_estimate_cover(const gmx::SelectionTreeElement &sel);
451 /** Returns the covered fraction of the selection for the current frame. */
453 _gmx_selelem_estimate_coverfrac(const gmx::SelectionTreeElement &sel);