CHFL_SELECTION

typedef struct CHFL_SELECTION CHFL_SELECTION

An opaque type handling a selection.

CHFL_SELECTION allow to select atoms in a CHFL_FRAME, from a selection language. The selection language is built by combining basic operations. Each basic operation follows the <selector>[(<variable>)] <operator> <value> structure, where <operator> is a comparison operator in == != < <= > >=.

Here is the full list of functions acting on CHFL_SELECTION:

CHFL_SELECTION *chfl_selection(const char *selection)

Create a new selection from the given selection string.

The caller of this function should free the associated memory using chfl_free.

CHFL_SELECTION* selection = chfl_selection("pairs: name(#1) O and name(#2) H");

if (selection == NULL) {
    /* handle error */
}

chfl_free(selection);
Return
A pointer to the selection, or NULL in case of error. You can use chfl_last_error to learn about the error.

CHFL_SELECTION *chfl_selection_copy(const CHFL_SELECTION *selection)

Get a copy of a selection.

The copy does not contains any state, and chfl_selection_evaluate must be called again before using chfl_selection_matches.

The caller of this function should free the associated memory using chfl_free.

CHFL_SELECTION* selection = chfl_selection("name O");
CHFL_SELECTION* copy = chfl_selection_copy(selection);

if (copy == NULL) {
    /* handle error */
}

chfl_free(copy);
chfl_free(selection);
Return
A pointer to the new selection, or NULL in case of error. You can use chfl_last_error to learn about the error.

chfl_status chfl_selection_size(const CHFL_SELECTION *selection, uint64_t *size)

Get the size of a selection in size.

The size of a selection is the number of atoms we are selecting together. This value is 1 for the ‘atom’ context, 2 for the ‘pair’ and ‘bond’ context, 3 for the ‘three’ and ‘angles’ contextes and 4 for the ‘four’ and ‘dihedral’ contextes.

CHFL_SELECTION* selection = chfl_selection("pairs: name(#1) O and name(#2) H");

uint64_t size = 0;
chfl_selection_size(selection, &size);
assert(size == 2);

chfl_free(selection);
Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_selection_string(const CHFL_SELECTION *selection, char *string, uint64_t buffsize)

Get the selection string used to create a given selection in the string buffer.

The buffer size must be passed in buffsize. This function will truncate the selection string to fit in the buffer.

CHFL_SELECTION* selection = chfl_selection("pairs: name(#1) O and name(#2) H");

char string[64]= {0};
chfl_selection_string(selection, string, sizeof(string));
assert(strcmp(string, "pairs: name(#1) O and name(#2) H") == 0);

chfl_free(selection);
Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_selection_evaluate(CHFL_SELECTION *selection, const CHFL_FRAME *frame, uint64_t *n_matches)

Evaluate a selection for a given frame, and store the number of matches in n_matches.

Use the chfl_selection_matches function to get the matches for this selection.

CHFL_FRAME* frame = chfl_frame();

CHFL_ATOM* O = chfl_atom("O");
CHFL_ATOM* H = chfl_atom("H");
chfl_frame_add_atom(frame, O, (chfl_vector3d){0, 0, 0}, NULL);
chfl_frame_add_atom(frame, H, (chfl_vector3d){1, 0, 0}, NULL);
chfl_frame_add_atom(frame, H, (chfl_vector3d){0, 1, 0}, NULL);
chfl_free(O);
chfl_free(H);

CHFL_SELECTION* selection = chfl_selection("name H");

uint64_t size = 0;
chfl_selection_evaluate(selection, frame, &size);
assert(size == 2);

chfl_free(selection);
chfl_free(frame);
Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_selection_matches(const CHFL_SELECTION *selection, chfl_match matches[], uint64_t n_matches)

Get the matches for a selection after a call to chfl_selection_evaluate, in matches.

The size of the matches array must be passed in n_matches.

CHFL_FRAME* frame = chfl_frame();

CHFL_ATOM* O = chfl_atom("O");
CHFL_ATOM* H = chfl_atom("H");
chfl_frame_add_atom(frame, O, (chfl_vector3d){0, 0, 0}, NULL);
chfl_frame_add_atom(frame, H, (chfl_vector3d){1, 0, 0}, NULL);
chfl_frame_add_atom(frame, H, (chfl_vector3d){0, 1, 0}, NULL);
chfl_free(O);
chfl_free(H);

CHFL_SELECTION* selection = chfl_selection("name H");

uint64_t size = 0;
chfl_selection_evaluate(selection, frame, &size);
assert(size == 2);

chfl_match matches[2];
chfl_selection_matches(selection, matches, 2);
assert(matches[0].atoms[0] == 1);
assert(matches[1].atoms[0] == 2);

chfl_free(selection);
chfl_free(frame);
Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

struct chfl_match

A chfl_match is a set of atomic indexes matching a given selection. The size of a match depends on the associated selection, and can vary from 1 to CHFL_MAX_SELECTION_SIZE.

Public Members

uint64_t size

The actual size of the match. Elements in atoms are significant up to this value, and filled with (uint64_t)-1 for all the other values.

uint64_t atoms[CHFL_MAX_SELECTION_SIZE]

Atomic indexes matching the associated selection.

CHFL_MAX_SELECTION_SIZE

Maximal size for a selection match.