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
Selection
(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");
SelectionError
: if there is a error in the selection string evaluate
(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}}));
list
(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}));
SelectionError
: if the selection size is not 1. size
() 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);
string
() 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");
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
operator[]
(size_t i) const¶Get the i
th atomic index in the match.
OutOfBounds
: if the index is bigger than the size()
of the match Public Static Attributes
MAX_MATCH_SIZE
= 4¶Maximal number of atoms in a match.