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 ::t_selelem 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 SELECTION_ELEMENT_H
46 #define SELECTION_ELEMENT_H
48 #include <types/simple.h>
50 #include "gromacs/selection/indexutil.h"
51 #include "gromacs/selection/selvalue.h"
53 struct gmx_ana_poscalc_t;
54 struct gmx_ana_selparam_t;
55 struct gmx_ana_selmethod_t;
57 struct gmx_sel_evaluate_t;
58 struct gmx_sel_mempool_t;
61 /********************************************************************/
62 /*! \name Enumerations for expression types
63 ********************************************************************/
66 /** Defines the type of a \c t_selelem object. */
69 /** Constant-valued expression. */
71 /** Method expression that requires evaluation. */
73 /** Boolean expression. */
75 /** Arithmetic expression. */
77 /** Root node of the evaluation tree. */
79 /** Subexpression that may be referenced several times. */
81 /** Reference to a subexpression. */
83 /** Unresolved reference to an external group. */
85 /** Post-processing of selection value. */
89 /** Defines the boolean operation of \c t_selelem objects with type \ref SEL_BOOLEAN. */
95 BOOL_XOR /**< Xor (not implemented). */
98 /** Defines the arithmetic operation of \c t_selelem objects with type \ref SEL_ARITHMETIC. */
101 ARITH_PLUS, /**< + */
102 ARITH_MINUS, /**< - */
103 ARITH_NEG, /**< Unary - */
104 ARITH_MULT, /**< * */
106 ARITH_EXP /**< ^ (to power) */
109 /** Returns a string representation of the type of a \c t_selelem. */
111 _gmx_selelem_type_str(struct t_selelem *sel);
112 /** Returns a string representation of the boolean type of a \ref SEL_BOOLEAN \c t_selelem. */
114 _gmx_selelem_boolean_type_str(struct t_selelem *sel);
115 /** Returns a string representation of the type of a \c gmx_ana_selvalue_t. */
117 _gmx_sel_value_type_str(gmx_ana_selvalue_t *val);
122 /********************************************************************/
123 /*! \name Selection expression flags
124 * \anchor selelem_flags
125 ********************************************************************/
128 * Selection value flags are set.
130 * If this flag is set, the flags covered by \ref SEL_VALFLAGMASK
131 * have been set properly for the element.
133 #define SEL_FLAGSSET 1
135 * The element evaluates to a single value.
137 * This flag is always set for \ref GROUP_VALUE elements.
139 #define SEL_SINGLEVAL 2
141 * The element evaluates to one value for each input atom.
143 #define SEL_ATOMVAL 4
145 * The element evaluates to an arbitrary number of values.
147 #define SEL_VARNUMVAL 8
149 * The element (or one of its children) is dynamic.
151 #define SEL_DYNAMIC 16
153 * Mask that covers the flags that describe the number of values.
155 #define SEL_VALTYPEMASK (SEL_SINGLEVAL | SEL_ATOMVAL | SEL_VARNUMVAL)
157 * Mask that covers the flags that describe the value type.
159 #define SEL_VALFLAGMASK (SEL_FLAGSSET | SEL_VALTYPEMASK | SEL_DYNAMIC)
161 * Data has been allocated for the \p v.u union.
163 * If not set, the \p v.u.ptr points to data allocated externally.
164 * This is the case if the value of the element is used as a parameter
165 * for a selection method or if the element evaluates the final value of
168 * Even if the flag is set, \p v.u.ptr can be NULL during initialization.
171 * This flag overlaps with the function of \p v.nalloc field, and could
172 * probably be removed, making memory management simpler. Currently, the
173 * \p v.nalloc field is not kept up-to-date in all cases when this flag
174 * is changed and is used in places where this flag is not, so this would
175 * require a careful investigation of the selection code.
177 #define SEL_ALLOCVAL (1<<8)
179 * Data has been allocated for the group/position structure.
181 * If not set, the memory allocated for fields in \p v.u.g or \p v.u.p is
182 * managed externally.
184 * This field has no effect if the value type is not \ref GROUP_VALUE or
185 * \ref POS_VALUE, but should not be set.
187 #define SEL_ALLOCDATA (1<<9)
189 * \p method->init_frame should be called for the frame.
191 #define SEL_INITFRAME (1<<10)
193 * Parameter has been evaluated for the current frame.
195 * This flag is set for children of \ref SEL_EXPRESSION elements (which
196 * describe method parameters) after the element has been evaluated for the
198 * It is not set for \ref SEL_ATOMVAL elements, because they may need to
199 * be evaluated multiple times.
201 #define SEL_EVALFRAME (1<<11)
203 * \p method->init has been called.
205 #define SEL_METHODINIT (1<<12)
207 * \p method->outinit has been called.
209 * This flag is also used for \ref SEL_SUBEXPRREF elements.
211 #define SEL_OUTINIT (1<<13)
215 /********************************************************************/
216 /*! \name Selection expression data structures and functions
217 ********************************************************************/
223 * Function pointer for evaluating a \c t_selelem.
225 typedef void (*sel_evalfunc)(struct gmx_sel_evaluate_t *data,
226 struct t_selelem *sel, gmx_ana_index_t *g);
229 * Represents an element of a selection expression.
231 typedef struct t_selelem
233 /*! \brief Name of the element.
235 * This field is only used for informative purposes.
236 * It is always either NULL or a pointer to a string.
237 * Memory is never allocated for it directly.
240 /** Type of the element. */
243 * Value storage of the element.
245 * This field contains the evaluated value of the element, as well as
246 * the output value type.
248 gmx_ana_selvalue_t v;
250 * Evaluation function for the element.
252 * Can be either NULL (if the expression is a constant and does not require
253 * evaluation) or point to one of the functions defined in evaluate.h.
255 sel_evalfunc evaluate;
257 * Information flags about the element.
259 * Allowed flags are listed here:
260 * \ref selelem_flags "flags for \c t_selelem".
263 /** Data required by the evaluation function. */
265 /*! \brief Index group data for several element types.
267 * - \ref SEL_CONST : if the value type is \ref GROUP_VALUE,
268 * this field holds the unprocessed group value.
269 * - \ref SEL_ROOT : holds the group value for which the
270 * selection subtree should be evaluated.
271 * - \ref SEL_SUBEXPR : holds the group for which the subexpression
272 * has been evaluated.
274 gmx_ana_index_t cgrp;
275 /** Data for \ref SEL_EXPRESSION and \ref SEL_MODIFIER elements. */
277 /** Pointer the the method used in this expression. */
278 struct gmx_ana_selmethod_t *method;
279 /** Pointer to the data allocated by the method's \p init_data (see sel_datafunc()). */
281 /** Pointer to the position data passed to the method. */
282 struct gmx_ana_pos_t *pos;
283 /** Pointer to the evaluation data for \p pos. */
284 struct gmx_ana_poscalc_t *pc;
286 /** Operation type for \ref SEL_BOOLEAN elements. */
288 /** Operation type for \ref SEL_ARITHMETIC elements. */
290 /** Operation type. */
292 /** String representation. */
295 /** Associated selection parameter for \ref SEL_SUBEXPRREF elements. */
296 struct gmx_ana_selparam_t *param;
297 /** The string/number used to reference the group. */
299 /** Name of the referenced external group. */
301 /** If \a name is NULL, the index number of the referenced group. */
305 /** Memory pool to use for values, or NULL if standard memory handling. */
306 struct gmx_sel_mempool_t *mempool;
307 /** Internal data for the selection compiler. */
308 struct t_compiler_data *cdata;
310 /*! \brief The first child element.
312 * Other children can be accessed through the \p next field of \p child.
314 struct t_selelem *child;
315 /** The next sibling element. */
316 struct t_selelem *next;
317 /*! \brief Number of references to this element.
319 * Should be larger than one only for \ref SEL_SUBEXPR elements.
325 /** Writes out a human-readable name for an evaluation function. */
327 _gmx_sel_print_evalfunc_name(FILE *fp, sel_evalfunc evalfunc);
329 /** Allocates memory and performs some common initialization for a \c t_selelem. */
331 _gmx_selelem_create(e_selelem_t type);
332 /** Sets the value type of a \c t_selelem. */
334 _gmx_selelem_set_vtype(t_selelem *sel, e_selvalue_t vtype);
335 /** Reserves memory for value of a \c t_selelem from a memory pool. */
337 _gmx_selelem_mempool_reserve(t_selelem *sel, int count);
338 /** Releases memory pool used for value of a \c t_selelem. */
340 _gmx_selelem_mempool_release(t_selelem *sel);
341 /** Frees the memory allocated for a \c t_selelem structure and all its children. */
343 _gmx_selelem_free(t_selelem *sel);
344 /** Frees the memory allocated for a \c t_selelem structure, all its children, and also all structures referenced through t_selelem::next fields. */
346 _gmx_selelem_free_chain(t_selelem *first);
348 /** Frees the memory allocated for the \c t_selelem::d union. */
350 _gmx_selelem_free_values(t_selelem *sel);
351 /** Frees the memory allocated for a selection method. */
353 _gmx_selelem_free_method(struct gmx_ana_selmethod_t *method, void *mdata);
354 /** Frees the memory allocated for the \c t_selelem::u field. */
356 _gmx_selelem_free_exprdata(t_selelem *sel);
358 /** Frees the memory allocated for the selection compiler. */
360 _gmx_selelem_free_compiler_data(t_selelem *sel);
362 /** Prints a human-readable version of a selection element subtree. */
364 _gmx_selelem_print_tree(FILE *fp, t_selelem *root, bool bValues, int level);
366 /** Prints a human-readable version of the internal compiler data structure. */
368 _gmx_selelem_print_compiler_info(FILE *fp, t_selelem *sel, int level);
370 /** Returns true if the selection element subtree requires topology information for evaluation. */
372 _gmx_selelem_requires_top(t_selelem *root);
374 /* In sm_insolidangle.c */
375 /** Returns true if the covered fraction of the selection can be calculated. */
377 _gmx_selelem_can_estimate_cover(t_selelem *sel);
378 /** Returns the covered fraction of the selection for the current frame. */
380 _gmx_selelem_estimate_coverfrac(t_selelem *sel);