A bit more modular selection position handling.
[gromacs/qmmm-gamess-us.git] / src / gmxlib / selection / selelem.h
bloba6b230d8caad0ded24b61a4c96fd23e9cb6efb23
1 /*
3 * This source code is part of
5 * G R O M A C S
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
31 /*! \internal \file
32 * \brief Definition of \c t_selelem and related things.
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.
38 * This is an implementation header: there should be no need to use it outside
39 * this directory.
41 #ifndef SELECTION_ELEMENT_H
42 #define SELECTION_ELEMENT_H
44 #include <typedefs.h>
46 #include <indexutil.h>
47 #include <selvalue.h>
49 struct gmx_ana_poscalc_t;
50 struct gmx_ana_selparam_t;
51 struct gmx_ana_selmethod_t;
53 struct gmx_sel_evaluate_t;
54 struct t_selelem;
56 /********************************************************************/
57 /*! \name Enumerations for expression types
58 ********************************************************************/
59 /*@{*/
61 /** Defines the type of a \c t_selelem object. */
62 typedef enum
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;
80 /** Defines the boolean operation of \c t_selelem objects with type \ref SEL_BOOLEAN. */
81 typedef enum
83 BOOL_NOT, /**< Not */
84 BOOL_AND, /**< And */
85 BOOL_OR, /**< Or */
86 BOOL_XOR /**< Xor (not implemented). */
87 } e_boolean_t;
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);
99 /*@}*/
102 /********************************************************************/
103 /*! \name Selection expression flags
104 * \anchor selelem_flags
105 ********************************************************************/
106 /*@{*/
107 /*! \brief
108 * Selection value flags are set.
110 * If this flag is set, the flags covered by \ref SEL_VALFLAGMASK
111 * have been set properly for the element.
113 #define SEL_FLAGSSET 1
114 /*! \brief
115 * The element evaluates to a single value.
117 * This flag is always set for \ref GROUP_VALUE elements.
119 #define SEL_SINGLEVAL 2
120 /*! \brief
121 * The element evaluates to one value for each input atom.
123 #define SEL_ATOMVAL 4
124 /*! \brief
125 * The element evaluates to an arbitrary number of values.
127 #define SEL_VARNUMVAL 8
128 /*! \brief
129 * The element (or one of its children) is dynamic.
131 #define SEL_DYNAMIC 16
132 /*! \brief
133 * Mask that covers the flags that describe the number of values.
135 #define SEL_VALTYPEMASK (SEL_SINGLEVAL | SEL_ATOMVAL | SEL_VARNUMVAL)
136 /*! \brief
137 * Mask that covers the flags that describe the value type.
139 #define SEL_VALFLAGMASK (SEL_FLAGSSET | SEL_VALTYPEMASK | SEL_DYNAMIC)
140 /*! \brief
141 * Data has been allocated for the \p v.u union.
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.
148 * Even if the flag is set, \p v.u.ptr can be NULL during initialization.
150 #define SEL_ALLOCVAL (1<<8)
151 /*! \brief
152 * Data has been allocated for the group/position structure.
154 * If not set, the memory allocated for fields in \p v.u.g or \p v.u.p is
155 * managed externally.
157 * This field has no effect if the value type is not \ref GROUP_VALUE or
158 * \ref POS_VALUE, but should not be set.
160 #define SEL_ALLOCDATA (1<<9)
161 /*! \brief
162 * \p method->init_frame should be called for the frame.
164 #define SEL_INITFRAME (1<<10)
165 /*! \brief
166 * Parameter has been evaluated for the current frame.
168 * This flag is set for children of \ref SEL_EXPRESSION elements (which
169 * describe method parameters) after the element has been evaluated for the
170 * current frame.
171 * It is not set for \ref SEL_ATOMVAL elements, because they may need to
172 * be evaluated multiple times.
174 #define SEL_EVALFRAME (1<<11)
175 /*! \brief
176 * \p method->init has been called.
178 #define SEL_METHODINIT (1<<12)
179 /*! \brief
180 * \p method->outinit has been called.
182 * This flag is also used for \ref SEL_SUBEXPRREF elements.
184 #define SEL_OUTINIT (1<<13)
185 /*@}*/
188 /********************************************************************/
189 /*! \name Selection expression data structures and functions
190 ********************************************************************/
191 /*@{*/
193 struct t_selelem;
195 /*! \brief
196 * Function pointer for evaluating a \c t_selelem.
198 typedef int (*sel_evalfunc)(struct gmx_sel_evaluate_t *data,
199 struct t_selelem *sel, gmx_ana_index_t *g);
201 /*! \internal \brief
202 * Represents an element of a selection expression.
204 typedef struct t_selelem
206 /*! \brief Name of the element.
208 * This field is only used for informative purposes.
209 * It is always either NULL or a pointer to a string.
210 * Memory is never allocated for it directly.
212 const char *name;
213 /** Type of the element. */
214 e_selelem_t type;
215 /*! \brief
216 * Value storage of the element.
218 * This field contains the evaluated value of the element, as well as
219 * the output value type.
221 gmx_ana_selvalue_t v;
222 /*! \brief
223 * Evaluation function for the element.
225 * Can be either NULL (if the expression is a constant and does not require
226 * evaluation) or point to one of the functions defined in evaluate.h.
228 sel_evalfunc evaluate;
229 /*! \brief
230 * Information flags about the element.
232 * Allowed flags are listed here:
233 * \ref selelem_flags "flags for \c t_selelem".
235 int flags;
236 /** Data required by the evaluation function. */
237 union {
238 /*! \brief Index group data for several element types.
240 * - \ref SEL_CONST : if the value type is \ref GROUP_VALUE,
241 * this field holds the unprocessed group value.
242 * - \ref SEL_ROOT : holds the group value for which the
243 * selection subtree should be evaluated.
244 * - \ref SEL_SUBEXPR : holds the group for which the subexpression
245 * has been evaluated.
247 gmx_ana_index_t cgrp;
248 /** Data for \ref SEL_EXPRESSION and \ref SEL_MODIFIER elements. */
249 struct {
250 /** Pointer the the method used in this expression. */
251 struct gmx_ana_selmethod_t *method;
252 /** Pointer to the data allocated by the method's \p init_data (see sel_datafunc()). */
253 void *mdata;
254 /** Pointer to the position data passed to the method. */
255 struct gmx_ana_pos_t *pos;
256 /** Pointer to the evaluation data for \p pos. */
257 struct gmx_ana_poscalc_t *pc;
258 } expr;
259 /** Operation type for \ref SEL_BOOLEAN elements. */
260 e_boolean_t boolt;
261 /** Associated selection parameter for \ref SEL_SUBEXPRREF elements. */
262 struct gmx_ana_selparam_t *param;
263 } u;
264 /** Internal data for the selection compiler. */
265 struct t_compiler_data *cdata;
267 /*! \brief The first child element.
269 * Other children can be accessed through the \p next field of \p child.
271 struct t_selelem *child;
272 /** The next sibling element. */
273 struct t_selelem *next;
274 /*! \brief Number of references to this element.
276 * Should be larger than one only for \ref SEL_SUBEXPR elements.
278 int refcount;
279 } t_selelem;
281 /** Allocates memory and performs some common initialization for a \c t_selelem. */
282 extern t_selelem *
283 _gmx_selelem_create(e_selelem_t type);
284 /** Sets the value type of a \c t_selelem. */
285 extern int
286 _gmx_selelem_set_vtype(t_selelem *sel, e_selvalue_t vtype);
287 /** Frees the memory allocated for a \c t_selelem structure and all its children. */
288 extern void
289 _gmx_selelem_free(t_selelem *sel);
290 /** Frees the memory allocated for a \c t_selelem structure, all its children, and also all structures referenced through t_selelem::next fields. */
291 extern void
292 _gmx_selelem_free_chain(t_selelem *first);
294 /** Frees the memory allocated for the \c t_selelem::d union. */
295 extern void
296 _gmx_selelem_free_values(t_selelem *sel);
297 /** Frees the memory allocated for the \c t_selelem::u.expr field. */
298 extern void
299 _gmx_selelem_free_exprdata(t_selelem *sel);
300 /* In compiler.c */
301 /** Frees the memory allocated for the selection compiler. */
302 extern void
303 _gmx_selelem_free_compiler_data(t_selelem *sel);
305 /** Prints a human-readable version of a selection element subtree. */
306 extern void
307 _gmx_selelem_print_tree(FILE *fp, t_selelem *root, bool bValues, int level);
309 /** Returns TRUE if the selection element subtree requires topology information for evaluation. */
310 extern bool
311 _gmx_selelem_requires_top(t_selelem *root);
313 /* In sm_insolidangle.c */
314 /** Returns TRUE if the covered fraction of the selection can be calculated. */
315 extern bool
316 _gmx_selelem_can_estimate_cover(t_selelem *sel);
317 /** Returns the covered fraction of the selection for the current frame. */
318 extern real
319 _gmx_selelem_estimate_coverfrac(t_selelem *sel);
321 /*@}*/
323 #endif