Selection class

class chemfiles::Selection

This class allow to select atoms in a 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 == != < <= > >=.

Refer to the Selection language documentation to know the allowed selectors and how to use them.

Public Functions

SelectionSelection(const std::string &selection)

Create a selection using the given string.

auto selection = Selection("name H or mass < 67");

assert(selection.size() == 1);
assert(selection.string() == "name H or mass < 67");

Exceptions

std::vector<Match> Selectionevaluate(const Frame &frame) const

Evaluates the selection on a given frame. This function returns the list of matches in the frame for this selection.

auto frame = Frame();
frame.add_atom(Atom("H"), {1.2, 0.0, 0.0});
frame.add_atom(Atom("O"), {0.0, 0.0, 0.0});
frame.add_atom(Atom("H"), {0.0, 1.2, 0.0});

frame.add_bond(0, 1);
frame.add_bond(0, 2);

auto selection = Selection("pairs: name(#1) H and name(#2) O");
std::vector<Match> matches = selection.evaluate(frame);
assert(matches.size() == 2);
assert(matches == std::vector<Match>({{0u, 1u}, {2u, 1u}}));

std::vector<size_t> Selectionlist(const Frame &frame) const

Evaluates a selection of size 1 on a given frame. This function returns the list of atomic indexes in the frame matching this selection.

auto frame = Frame();
frame.add_atom(Atom("H"), {1.2, 0.0, 0.0});
frame.add_atom(Atom("0"), {0.0, 0.0, 0.0});
frame.add_atom(Atom("H"), {0.0, 1.2, 0.0});

frame.add_bond(0, 1);
frame.add_bond(0, 2);

auto selection = Selection("name H");
std::vector<size_t> matches = selection.list(frame);
assert(matches.size() == 2);
assert(matches == std::vector<size_t>({0, 2}));

Exceptions

size_t Selectionsize() const

Get the size of the selection, i.e. the number of atoms selected together.

assert(Selection("type H and index > 254").size() == 1);
assert(Selection("pairs: name(#1) H and type(#2) Ow").size() == 2);
assert(Selection("four: (name(#1) H and type(#2) Ow) or (name(#3) Ow and type(#4) H)").size() == 4);

std::string chemfiles::Selectionstring() const

Get the string used to build this selection

auto selection = Selection("angles: name(#2) O and mass(#1) < 3.4");
assert(selection.string() == "angles: name(#2) O and mass(#1) < 3.4");

class chemfiles::Match

A 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 MAX_MATCH_SIZE.

// selection and frame are already created
auto matches = selection.evaluate(frame);

auto match = matches[2];
assert(match.size() == selection.size());
assert(match.size() == 3);

assert(match[0] == 1);
assert(match[1] == 0);
assert(match[2] == 2);

Public Functions

const size_t &chemfiles::Matchoperator[](size_t i) const

Get the ith atomic index in the match.

Exceptions

size_t chemfiles::Matchsize() const

Size of the match, i.e. number of valid indexes in the match. This value is always equals to the size of the Selection this match comes from.

Public Static Attributes

constexpr size_t chemfiles::MatchMAX_MATCH_SIZE = 4

Maximal number of atoms in a match.