Gromacs  2024.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Classes
#include "selelem.h"
+ Include dependency graph for evaluate.h:
+ This graph shows which files directly or indirectly include this file:

Description

Evaluation functions for sel_evalfunc().

This is an implementation header: there should be no need to use it outside this directory. Users should only use SelectionCollection::evaluate() to evaluate selections.

The functions defined in this header file are all the possible values for the gmx::SelectionTreeElement::evaluate field (in addition to NULL).

Author
Teemu Murtola teemu.nosp@m..mur.nosp@m.tola@.nosp@m.gmai.nosp@m.l.com

Classes

struct  gmx_sel_evaluate_t
 Data structure for passing information required during evaluation. More...
 

Functions

Utility functions
void _gmx_sel_evaluate_init (gmx_sel_evaluate_t *data, gmx_sel_mempool_t *mp, gmx_ana_index_t *gall, const gmx_mtop_t *top, t_trxframe *fr, t_pbc *pbc)
 Initializes an evaluation data structure. More...
 
void _gmx_sel_evaluate_children (gmx_sel_evaluate_t *data, const gmx::SelectionTreeElementPointer &sel, gmx_ana_index_t *g)
 Evaluates the children of a general selection element. More...
 
void _gmx_sel_evaluate_method_params (gmx_sel_evaluate_t *data, const gmx::SelectionTreeElementPointer &sel, gmx_ana_index_t *g)
 Evaluates the children of a SEL_EXPRESSION element. More...
 
Misc. evaluation functions
void _gmx_sel_evaluate_root (gmx_sel_evaluate_t *data, const gmx::SelectionTreeElementPointer &sel, gmx_ana_index_t *g)
 Evaluates a root selection element. More...
 
void _gmx_sel_evaluate_static (gmx_sel_evaluate_t *data, const gmx::SelectionTreeElementPointer &sel, gmx_ana_index_t *g)
 Evaluates a static group selection element. More...
 
void _gmx_sel_evaluate_arithmetic (gmx_sel_evaluate_t *data, const gmx::SelectionTreeElementPointer &sel, gmx_ana_index_t *g)
 Evaluates an arithmetic expression element. More...
 
Subexpression evaluation functions
void _gmx_sel_evaluate_subexpr_simple (gmx_sel_evaluate_t *data, const gmx::SelectionTreeElementPointer &sel, gmx_ana_index_t *g)
 Evaluates a subexpression when there is only one reference. More...
 
void _gmx_sel_evaluate_subexpr_staticeval (gmx_sel_evaluate_t *data, const gmx::SelectionTreeElementPointer &sel, gmx_ana_index_t *g)
 Evaluates a subexpression when the evaluation group is static. More...
 
void _gmx_sel_evaluate_subexpr (gmx_sel_evaluate_t *data, const gmx::SelectionTreeElementPointer &sel, gmx_ana_index_t *g)
 Evaluates a subexpression. More...
 
void _gmx_sel_evaluate_subexprref_simple (gmx_sel_evaluate_t *data, const gmx::SelectionTreeElementPointer &sel, gmx_ana_index_t *g)
 Evaluates a subexpression reference when there are no other references. More...
 
void _gmx_sel_evaluate_subexprref (gmx_sel_evaluate_t *data, const gmx::SelectionTreeElementPointer &sel, gmx_ana_index_t *g)
 Evaluates a subexpression reference. More...
 
Method evaluation functions
void _gmx_sel_evaluate_method (gmx_sel_evaluate_t *data, const gmx::SelectionTreeElementPointer &sel, gmx_ana_index_t *g)
 Evaluates a method expression. More...
 
void _gmx_sel_evaluate_modifier (gmx_sel_evaluate_t *data, const gmx::SelectionTreeElementPointer &sel, gmx_ana_index_t *g)
 Evaluates a modifier expression. More...
 
Boolean evaluation functions
void _gmx_sel_evaluate_not (gmx_sel_evaluate_t *data, const gmx::SelectionTreeElementPointer &sel, gmx_ana_index_t *g)
 Evaluates a boolean NOT element. More...
 
void _gmx_sel_evaluate_and (gmx_sel_evaluate_t *data, const gmx::SelectionTreeElementPointer &sel, gmx_ana_index_t *g)
 Evaluates a boolean AND element with short-circuiting. More...
 
void _gmx_sel_evaluate_or (gmx_sel_evaluate_t *data, const gmx::SelectionTreeElementPointer &sel, gmx_ana_index_t *g)
 Evaluates a boolean OR element with short-circuiting. More...
 

Function Documentation

void _gmx_sel_evaluate_and ( gmx_sel_evaluate_t data,
const gmx::SelectionTreeElementPointer sel,
gmx_ana_index_t g 
)

Evaluates a boolean AND element with short-circuiting.

Parameters
[in]dataData for the current frame.
[in]selSelection element being evaluated.
[in]gGroup for which sel should be evaluated.
Returns
0 on success, a non-zero error code on error.

Short-circuiting evaluation of logical AND expressions.

Starts by evaluating the first child element in the group g. The each following child element is evaluated in the intersection of all the previous values until all children have been evaluated or the intersection becomes empty. The value of sel is set to the intersection of all the (evaluated) child values.

If the first child does not have an evaluation function, it is skipped and the evaluation is started at the second child. This happens if the first child is a constant expression and during compilation it was detected that the evaluation group is always a subset of the constant group (currently, the compiler never detects this).

This function is used as gmx::SelectionTreeElement::evaluate for SEL_BOOLEAN elements with BOOL_AND.

void _gmx_sel_evaluate_arithmetic ( gmx_sel_evaluate_t data,
const gmx::SelectionTreeElementPointer sel,
gmx_ana_index_t g 
)

Evaluates an arithmetic expression element.

Parameters
[in]dataData for the current frame.
[in]selSelection element being evaluated.
[in]gGroup for which sel should be evaluated.
Returns
0 on success, a non-zero error code on error.
void _gmx_sel_evaluate_children ( gmx_sel_evaluate_t data,
const gmx::SelectionTreeElementPointer sel,
gmx_ana_index_t g 
)

Evaluates the children of a general selection element.

Parameters
[in]dataData for the current frame.
[in]selSelection element being evaluated.
[in]gGroup for which sel should be evaluated.
Returns
0 on success, a non-zero error code on error.

Evaluates each child of sel in g.

void _gmx_sel_evaluate_init ( gmx_sel_evaluate_t data,
gmx_sel_mempool_t mp,
gmx_ana_index_t gall,
const gmx_mtop_t *  top,
t_trxframe *  fr,
t_pbc pbc 
)

Initializes an evaluation data structure.

Parameters
[out]dataEvaluation data structure to initialize.
[in]mpMemory pool for intermediate evaluation values.
[in]gallIndex group with all the atoms.
[in]topTopology structure for evaluation.
[in]frNew frame for evaluation.
[in]pbcNew PBC information for evaluation.
void _gmx_sel_evaluate_method ( gmx_sel_evaluate_t data,
const gmx::SelectionTreeElementPointer sel,
gmx_ana_index_t g 
)

Evaluates a method expression.

Parameters
[in]dataData for the current frame.
[in]selSelection element being evaluated.
[in]gGroup for which sel should be evaluated.
Returns
0 on success, a non-zero error code on error.

Evaluates all child selections (using _gmx_sel_evaluate_method_params()) to evaluate any parameter values. If this is the first time this expression is evaluated for the frame, sel_framefunc() callback is called if one is provided. If a reference position calculation has been initialized for this element, the positions are also updated, and sel_updatefunc_pos() is used to evaluate the value. Otherwise, sel_updatefunc() is used.

This function is used as gmx::SelectionTreeElement::evaluate for SEL_EXPRESSION elements.

void _gmx_sel_evaluate_method_params ( gmx_sel_evaluate_t data,
const gmx::SelectionTreeElementPointer sel,
gmx_ana_index_t g 
)

Evaluates the children of a SEL_EXPRESSION element.

Parameters
[in]dataData for the current frame.
[in]selSelection element being evaluated.
[in]gGroup for which sel should be evaluated.
Returns
0 on success, a non-zero error code on error.

Evaluates each child of a SEL_EXPRESSION element. The value of sel is not touched.

This function is not used as gmx::SelectionTreeElement::evaluate, but is used internally.

void _gmx_sel_evaluate_modifier ( gmx_sel_evaluate_t data,
const gmx::SelectionTreeElementPointer sel,
gmx_ana_index_t g 
)

Evaluates a modifier expression.

Parameters
[in]dataData for the current frame.
[in]selSelection element being evaluated.
[in]gGroup for which sel should be evaluated.
Returns
0 on success, a non-zero error code on error.

Evaluates all child selections (using _gmx_sel_evaluate_method_params()) to evaluate any parameter values. If this is the first time this expression is evaluated for the frame, sel_framefunc() callback is called if one is provided. The modifier is then evaluated using sel_updatefunc_pos().

This function is used as gmx::SelectionTreeElement::evaluate for SEL_MODIFIER elements.

void _gmx_sel_evaluate_not ( gmx_sel_evaluate_t data,
const gmx::SelectionTreeElementPointer sel,
gmx_ana_index_t g 
)

Evaluates a boolean NOT element.

Parameters
[in]dataData for the current frame.
[in]selSelection element being evaluated.
[in]gGroup for which sel should be evaluated.
Returns
0 on success, a non-zero error code on error.

Evaluates the child element (there should be only one) in the group g, and then sets the value of sel to the complement of the child value.

This function is used as gmx::SelectionTreeElement::evaluate for SEL_BOOLEAN elements with BOOL_NOT.

void _gmx_sel_evaluate_or ( gmx_sel_evaluate_t data,
const gmx::SelectionTreeElementPointer sel,
gmx_ana_index_t g 
)

Evaluates a boolean OR element with short-circuiting.

Parameters
[in]dataData for the current frame.
[in]selSelection element being evaluated.
[in]gGroup for which sel should be evaluated.
Returns
0 on success, a non-zero error code on error.

Short-circuiting evaluation of logical OR expressions.

Starts by evaluating the first child element in the group g. For each subsequent child, finds the part of g that is not included the value of any previous child, and evaluates the child in that group until the last child is evaluated or all of g is included in some child value. The value of sel is set to the union of all the (evaluated) child values.

If the first child does not have an evaluation function, its value is used without evaluation. This happens if the first child is a constant expression, the selection has been compiled, and the evaluation group is the same for each frame. In this case, the compiler has taken care of that the child value is a subset of g, making it unnecessary to evaluate it.

This function is used as gmx::SelectionTreeElement::evaluate for SEL_BOOLEAN elements with BOOL_OR.

void _gmx_sel_evaluate_root ( gmx_sel_evaluate_t data,
const gmx::SelectionTreeElementPointer sel,
gmx_ana_index_t g 
)

Evaluates a root selection element.

Parameters
[in]dataData for the current frame.
[in]selSelection element being evaluated.
[in]gGroup for which sel should be evaluated (not used, can be NULL).
Returns
0 on success, a non-zero error code on error.

Evaluates the first child element in the group defined by sel->u.cgrp. If sel->u.cgrp is empty, nothing is done. The value of sel is not touched (root elements do not evaluate to values).

This function can be used as gmx::SelectionTreeElement::evaluate for SEL_ROOT elements.

void _gmx_sel_evaluate_static ( gmx_sel_evaluate_t data,
const gmx::SelectionTreeElementPointer sel,
gmx_ana_index_t g 
)

Evaluates a static group selection element.

Parameters
[in]dataData for the current frame.
[in]selSelection element being evaluated.
[in]gGroup for which sel should be evaluated.
Returns
0 for success.

Sets the value of sel to the intersection of g and sel->u.cgrp.

This function can be used as gmx::SelectionTreeElement::evaluate for SEL_CONST elements with value type GROUP_VALUE.

void _gmx_sel_evaluate_subexpr ( gmx_sel_evaluate_t data,
const gmx::SelectionTreeElementPointer sel,
gmx_ana_index_t g 
)

Evaluates a subexpression.

Parameters
[in]dataData for the current frame.
[in]selSelection element being evaluated.
[in]gGroup for which sel should be evaluated.
Returns
0 on success, a non-zero error code on error.

Finds the part of g for which the subexpression has not yet been evaluated by comparing g to sel->u.cgrp. If the part is not empty, the child expression is evaluated for this part, and the results merged to the old values of the child. The value of sel itself is undefined after the call.

Todo:
The call to gmx_ana_index_difference() can take quite a lot of unnecessary time if the subexpression is evaluated either several times for the same group or for completely distinct groups. However, in the majority of cases, these situations occur when _gmx_sel_evaluate_subexpr_staticeval() can be used, so this should not be a major problem.
void _gmx_sel_evaluate_subexpr_simple ( gmx_sel_evaluate_t data,
const gmx::SelectionTreeElementPointer sel,
gmx_ana_index_t g 
)

Evaluates a subexpression when there is only one reference.

Parameters
[in]dataData for the current frame.
[in]selSelection element being evaluated.
[in]gGroup for which sel should be evaluated.
Returns
0 on success, a non-zero error code on error.

Evaluates the child element (there should be exactly one) in g. The compiler has taken care that the child actually stores the evaluated value in the value pointer of this element.

This function is used as gmx::SelectionTreeElement::evaluate for SEL_SUBEXPR elements that are used only once, and hence do not need full subexpression handling.

void _gmx_sel_evaluate_subexpr_staticeval ( gmx_sel_evaluate_t data,
const gmx::SelectionTreeElementPointer sel,
gmx_ana_index_t g 
)

Evaluates a subexpression when the evaluation group is static.

Parameters
[in]dataData for the current frame.
[in]selSelection element being evaluated.
[in]gGroup for which sel should be evaluated.
Returns
0 on success, a non-zero error code on error.

If this is the first call for this frame, evaluates the child element there should be exactly one in g. The compiler has taken care that the child actually stores the evaluated value in the value pointer of this element. Assumes that g is persistent for the duration of the whole evaluation.

This function is used as gmx::SelectionTreeElement::evaluate for SEL_SUBEXPR elements that have a static evaluation group, and hence do not need full subexpression handling.

void _gmx_sel_evaluate_subexprref ( gmx_sel_evaluate_t data,
const gmx::SelectionTreeElementPointer sel,
gmx_ana_index_t g 
)

Evaluates a subexpression reference.

Parameters
[in]dataData for the current frame.
[in]selSelection element being evaluated.
[in]gGroup for which sel should be evaluated.
Returns
0 on success, a non-zero error code on error.

If the value type is POS_VALUE, the value of the child is simply copied to set the value of sel (the child subexpression should already have been evaluated by its root). If the value type is something else, the child is evaluated for the group g, and the value of the child is then copied. There should be only one child element.

This function is used as gmx::SelectionTreeElement::evaluate for SEL_SUBEXPRREF elements.

void _gmx_sel_evaluate_subexprref_simple ( gmx_sel_evaluate_t data,
const gmx::SelectionTreeElementPointer sel,
gmx_ana_index_t g 
)

Evaluates a subexpression reference when there are no other references.

Parameters
[in]dataData for the current frame.
[in]selSelection element being evaluated.
[in]gGroup for which sel should be evaluated.
Returns
0 for success.

Sets the value pointers of the child and its child to point to the same memory as the value pointer of this element to avoid copying, and then evaluates evaluates the child.

This function is used as gmx::SelectionTreeElement:evaluate for SEL_SUBEXPRREF elements for which the SEL_SUBEXPR does not have other references.