Gromacs  2025-dev-20240719-add48f3
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Custom selection methods

Custom selection methods are defined by creating a new instance of gmx_ana_selmethod_t and filling it with the necessary data for handling the selection. The structure contains callback pointers that define the actual behavior of the method. The following sections discuss how the structure should be filled and how to implement the callbacks.

\c gmx_ana_selmethod_t data structure

An example gmx_ana_selmethod_t definition could look like this:

gmx_ana_selmethod_t sm_example = {
"example", GROUP_VALUE, 0,
asize(sm_params_example), sm_params_example,
{"example from POS_EXPR [cutoff REAL]", NULL, 0, NULL},

The first value defines the name of the method. It is used mostly for informational purposes; the actual name(s) recognized by the selection parser are defined by the call to gmx_ana_selmethod_register() (see Registering the method).

The second value defines the type of the value the method returns. Possible values are

The third value gives additional information about the method using a combination of flags. Possible flags are:

There are two additional flags that specify the number of values the method returns. Only one of them can be set at a time. If neither is set, the default behavior is to evaluate a value for each input atom (except for GROUP_VALUE methods, which always return a single group). Other behaviors can be specified with these flags:

If either of these flags is specified (and the method type is not GROUP_VALUE), the group passed to the evaluation callback should not be used as it can be NULL. Currently, the above flags only work (have been tested) for POS_VALUE methods.

There is one additional flag that can only be specified for STR_VALUE methods: SMETH_CHARVAL . It is meant for to ease implementation of methods that evaluate to strings consisting of single characters.

The next two values determine the number of parameters and a pointer to the parameter array. The contents of the parameter array are described in Defining parameters. If the method does not take parameters, the first value should be 0 and the second can be NULL. Currently, STR_VALUE methods cannot take parameters, but this limitation should be easy to lift if required.

These are followed by function callbacks that determine the actual behavior of the method. Any of these except the evaluation callback can be NULL (the evaluation callback can also be NULL if NO_VALUE is specified for a selection modifier). However, the presence of parameters can require some of the callbacks to be implemented. The details are described in Implementing callbacks.

Finally, there is a data structure that gives help texts for the method.

The gmx_ana_selmethod_t variable should be declared as a global variable or it should be otherwise ensured that the structure is not freed: only a pointer to the structure is stored by the library.

Defining parameters

Parameters to selection methods are defined in a separate array of gmx_ana_selparam_t structures. The order of the parameters does not matter (except possibly for callback implementation), with one important exception: If the method evaluates to a POS_VALUE, the first parameter should have GROUP_VALUE and be the one that is used to calculate the positions.

An example parameter definition:

static gmx_ana_selparam_t sm_params_example[] = {

The first value gives the name of the parameter. The first parameter can have a NULL name, which means that the value should immediately follow the method name. This can be used to specify methods of the type 'within 5 of ...'.

The second value specifies the type of the value that the parameter accepts. NO_VALUE can be used to specify a boolean parameter, other possibilities are the same as for the selection method type.

The third value gives the number of values that the parameter accepts. For boolean parameters (NO_VALUE), it should be 0. For parameters with SPAR_VARNUM of SPAR_ATOMVAL, it should be set to -1 for consistency (it is not used). If SPAR_RANGES is specified, it should be either 1 (to accept a single continuous range) or -1 (if combined with SPAR_VARNUM). In all other cases, it should be a positive integer; in most cases, it should be 1.

The nest two pointers should always be NULL (they should be initialized in the callbacks), except the first pointer in the case of SPAR_ENUMVAL (see below).

The final value gives additional information about the acceptable values for the parameter using a combination of flags. The possible flags are:

Implementing callbacks

There are eight differen callback functions that can be implemented for selection methods: sel_datafunc(), sel_posfunc(), sel_initfunc(), sel_outinitfunc(), sel_freefunc(), sel_framefunc(), and two update functions. They are in this order in the gmx_ana_selmethod_t data structure. In general, any of the callbacks can be NULL, but the presence of parameters or other callbacks imposes some restrictions:

The documentations for the function pointer types provide more information about how the callbacks should be implemented.

Selection modifiers

Selection modifiers are a special kind of selection methods that can be appended to the end of a selection. They are specified by adding the SMETH_MODIFIER flag to the gmx_ana_selmethod_t. They can have two different types:

In addition to restricting the type of the method, selection modifiers do not allow the flags SMETH_SINGLEVAL and SMETH_VARNUMVAL (they would not make sense).

Parameters and callbacks should be implemented as with normal selection method, but beware that very little of the functionality has been tested.

The modifier handling could be made more flexible and more generic; the current implementation does not allow many things which would be possible with slight changes in the internals of the library.

Registering the method

After defining the method with gmx_ana_selmethod_t, it should be registered with the selection engine. In analysis programs, this can be done by calling gmx_ana_selmethod_register(). If adding the method to the library, you should add a pointer to the new method structure into the smtable_def array (in selmethod.cpp), and it is registered automatically. In both cases, gmx_ana_selmethod_register() does several checks on the structure and reports any errors or inconsistencies it finds.