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 == != < <= > >=
.
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_selection_free
.
CHFL_SELECTION* selection = chfl_selection("pairs: name(#1) O and name(#2) H");
if (selection == NULL) {
/* handle error */
}
chfl_selection_free(selection);
chfl_last_error
to learn about the error.
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_selection_free
.
CHFL_SELECTION* selection = chfl_selection("name O");
CHFL_SELECTION* copy = chfl_selection_copy(selection);
if (copy == NULL) {
/* handle error */
}
chfl_selection_free(copy);
chfl_selection_free(selection);
chfl_last_error
to learn about the error.
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_selection_free(selection);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
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_selection_free(selection);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
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_atom_free(O);
chfl_atom_free(H);
CHFL_SELECTION* selection = chfl_selection("name H");
uint64_t size = 0;
chfl_selection_evaluate(selection, frame, &size);
assert(size == 2);
chfl_selection_free(selection);
chfl_frame_free(frame);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
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_atom_free(O);
chfl_atom_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_selection_free(selection);
chfl_frame_free(frame);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
chfl_selection_free
(CHFL_SELECTION *selection)¶Free the memory associated with a selection
.
CHFL_SELECTION* selection = chfl_selection("pairs: name(#1) O and name(#2) H");
if (selection == NULL) {
/* handle error */
}
chfl_selection_free(selection);
CHFL_SUCCESS
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
.
CHFL_MAX_SELECTION_SIZE
¶Maximal size for a selection match.