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,
      &init_data_example,
       NULL,
      &init_example,
       NULL,
      &free_data_example,
      &init_frame_example,
      &evaluate_example,
       NULL,
      {"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

• NO_VALUE : This is allowed only for methods that have the flag SMETH_MODIFIER set (see Selection modifiers).
• INT_VALUE : The method returns one or more integer values.
• REAL_VALUE : The method returns one or more floating-point values.
• STR_VALUE : The method returns one or more strings.
• POS_VALUE : The method returns one or more 3D vectors.
• GROUP_VALUE : The method returns a single index group.

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

• SMETH_REQTOP : If set, the topology information is always loaded and the top pointer passed to the callbacks is guaranteed to be non-NULL. Should be set if the method requires topology information for evaluation.
• SMETH_DYNAMIC : If set, the method can only be evaluated dynamically, i.e., it requires data from the trajectory frame.
• SMETH_MODIFIER : If set, the method is a selection modifier and not an actual selection method. For more details, see Selection modifiers.
• SMETH_ALLOW_UNSORTED : If set, the method supports unsorted atoms in its input parameters. SMETH_MODIFIER methods are assumed to always support unsorted atoms, as their purpose is to affect the ordering.

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:

• SMETH_SINGLEVAL : If set, the method evaluates to a single value. This is automatically set if the type is GROUP_VALUE.
• SMETH_VARNUMVAL : If set, the method evaluates to an arbitrary number of values. The number of values is determined based on the values given by the user to the method parameters (see Defining parameters).

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[] = {
    {"cutoff", {REAL_VALUE, 1, {NULL}}, NULL, SPAR_OPTIONAL},
    {"from",   {POS_VALUE, -1, {NULL}}, NULL, SPAR_DYNAMIC | SPAR_VARNUM},
  };
* 

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:

• SPAR_OPTIONAL : If set, the user does not need to provide a value for the parameter. If not set, an error is reported if the parameter is not specified by the user.
• SPAR_DYNAMIC : If set, the method can handle dynamic values for the parameter, i.e., the value(s) can be given by an expression that evaluates to different values for different frames.
• SPAR_RANGES : Can be set only for INT_VALUE and REAL_VALUE parameters, and cannot be combined with SPAR_DYNAMIC. If set, the parameter accepts ranges of values. The ranges are automatically sorted and compacted such that a minimum amount of non-overlapping ranges are given for the method.
• SPAR_VARNUM : If set, the parameter can have a variable number of values. These can be provided by the user as a list of values, or using a single SMETH_VARNUMVAL (or a single SMETH_SINGLEVAL) method.
• SPAR_ATOMVAL : If set, the parameter accepts either a single value or an expression that evaluates to a value for each input atom. The single input value is treated as if the same value was returned for each atom. Cannot be combined with SPAR_RANGES or SPAR_VARNUM.
• SPAR_ENUMVAL : Can only be set for STR_VALUE parameters that take a single value, and cannot be combined with any other flag than SPAR_OPTIONAL. If set, the parameter only accepts one of predefined string values. See SPAR_ENUMVAL documentation for details on how to specify the acceptable values.

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:

• sel_datafunc() should be provided if the method takes parameters.
• sel_initfunc() should be provided if the method takes any parameters with the SPAR_VARNUM or SPAR_ATOMVAL flags, except if those parameters have a POS_VALUE.
• sel_outinitfunc() should be provided for POS_VALUE methods and SMETH_VARNUMVAL methods.
• sel_freefunc() should be provided if sel_datafunc() and/or sel_initfunc() allocate any dynamic memory in addition to the data structure itself (or allocates the data structure using some other means than malloc()).
• sel_updatefunc_pos() only makes sense for methods with SMETH_DYNAMIC set.
• At least one update function should be provided unless the method type is NO_VALUE.

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:

• POS_VALUE : These modifiers are given the final positions as an input, and they can make modifications to the selection that are not possible otherwise (e.g., permute the atoms). The modifier should implement sel_updatefunc_pos() and also have one NULL parameter in the beginning of the parameter list that takes POS_VALUE and is used to give the input positions.
• NO_VALUE : These modifiers do not modify the final selection, but can be used to implement per-selection options for analysis tools or to control the default behavior of the selection engine (currently, such a framework is not implemented, but should be easy to implement if required).

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.

Todo:

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.