Frame¶
-
class Frame¶
A frame contains data from one simulation step The Frame class holds data from one step of a simulation: the current topology, the positions, and the velocities of the particles in the system. If some information is missing the corresponding data is filled with a default value. Specifically:
cell
is an infinite unit cell;topology
is empty, and contains no data;positions
is filled with zeros;velocities
is thenullopt
variant ofchemfiles::optional
.
Iterating over a
Frame
will yield all the atoms in the system.Public Functions
-
inline Frame clone() const¶
Get a clone (exact copy) of this frame.
This replace the implicit copy constructor (which is private) to make an explicit copy of the frame.
-
inline const Topology &topology() const¶
Get a const reference to the topology of this frame
It is not possible to get a modifiable reference to the topology, because it would then be possible to remove/add atoms without changing the actual positions and velocity storage. Instead, all the mutating functionalities of the topology are mirrored on the frame (adding and removing bonds, adding residues, etc.)
-
inline void set_cell(UnitCell cell)¶
Set the unit cell for this frame to
cell
- Parameters:
cell – the new UnitCell to use for this frame
-
size_t size() const¶
Get the number of atoms in this frame
-
inline const std::vector<Vector3D> &positions() const¶
Get the positions (in Angstroms) of the atoms in this frame as a const reference
-
void add_velocities()¶
Add velocities data storage to this frame.
If velocities are already defined, this functions does nothing. The new velocities are initialized to 0.
-
inline optional<span<Vector3D>> velocities()¶
Get an velocities (in Angstroms/ps) of the atoms in this frame, if this frame contains velocity data.
-
inline optional<const std::vector<Vector3D>&> velocities() const¶
Get an velocities (in Angstroms/ps) of the atoms in this frame as a const reference, if this frame contains velocity data.
-
void resize(size_t size)¶
Resize the frame to contain
size
atoms.If the new number of atoms is bigger than the old one, missing data is initialized to 0. Pre-existing values are conserved.
If the new size if smaller than the old one, all atoms and connectivity elements after the new size are removed.
-
void reserve(size_t size)¶
Allocate memory in the frame to have enough size for
size
atoms.This function does not change the actual number of atoms in the frame, and should be used as an optimisation.
-
void add_atom(Atom atom, Vector3D position, Vector3D velocity = Vector3D())¶
Add an
atom
at the givenposition
and optionally with the givenvelocity
. Thevelocity
value will only be used if this frame contains velocity data.
-
void remove(size_t i)¶
Remove the atom at index
i
in the system.- Throws:
chemfiles::OutOfBounds – if
i
is bigger than the number of atoms in this frame
-
inline size_t step() const¶
Get the current simulation step.
The step is set by the
Trajectory
when reading a frame.
-
inline void set_step(size_t step)¶
Set the current simulation step to
step
-
void guess_bonds()¶
Guess the bonds, angles, dihedrals and impropers angles in this frame.
The bonds are guessed using a distance-based algorithm, and then angles, dihedrals and impropers are guessed from the bonds. The distance criterion uses the Van der Waals radii of the atoms. If this information is missing for a specific atoms, one can use configuration files to provide it.
- Throws:
Error – if the Van der Waals radius in unknown for a given atom.
-
inline void clear_bonds()¶
Remove all connectivity information in the frame’s topology
-
inline void add_residue(Residue residue)¶
Add a
residue
to this frame’s topology.- Parameters:
residue – the residue to add to this topology
- Throws:
chemfiles::Error – if any atom in the
residue
is already in another residue in this topology. In that case, the topology is not modified.
-
inline void add_bond(size_t atom_i, size_t atom_j, Bond::BondOrder bond_order = Bond::UNKNOWN)¶
Add a bond in the system, between the atoms at index
atom_i
andatom_j
.- Parameters:
atom_i – the index of the first atom in the bond
atom_j – the index of the second atom in the bond
bond_order – the bond order of the new bond
- Throws:
OutOfBounds – if
atom_i
oratom_j
are greater thansize()
Error – if
atom_i == atom_j
, as this is an invalid bond
-
inline void remove_bond(size_t atom_i, size_t atom_j)¶
Remove a bond in the system, between the atoms at index
atom_i
andatom_j
.If the bond does not exist, this does nothing.
- Parameters:
atom_i – the index of the first atom in the bond
atom_j – the index of the second atom in the bond
- Throws:
OutOfBounds – if
atom_i
oratom_j
are greater thansize()
-
inline Atom &operator[](size_t index)¶
Get a reference to the atom at the position
index
.- Parameters:
index – the atomic index
- Throws:
OutOfBounds – if
index
is greater thansize()
-
inline const Atom &operator[](size_t index) const¶
Get a const reference to the atom at the position
index
.- Parameters:
index – the atomic index
- Throws:
OutOfBounds – if
index
is greater thansize()
-
double distance(size_t i, size_t j) const¶
Get the distance between the atoms at indexes
i
andj
, accounting for periodic boundary conditions. The distance is expressed in angstroms.- Throws:
chemfiles::OutOfBounds – if
i
orj
are bigger than the number of atoms in this frame
-
double angle(size_t i, size_t j, size_t k) const¶
Get the angle formed by the atoms at indexes
i
,j
andk
, accounting for periodic boundary conditions. The angle is expressed in radians.- Throws:
chemfiles::OutOfBounds – if
i
,j
ork
are bigger than the number of atoms in this frame
-
double dihedral(size_t i, size_t j, size_t k, size_t m) const¶
Get the dihedral angle formed by the atoms at indexes
i
,j
,k
andm
, accounting for periodic boundary conditions. The angle is expressed in radians.- Throws:
chemfiles::OutOfBounds – if
i
,j
,k
orm
are bigger than the number of atoms in this frame
-
double out_of_plane(size_t i, size_t j, size_t k, size_t m) const¶
Get the out of plane distance formed by the atoms at indexes
i
,j
,k
andm
, accounting for periodic boundary conditions. The distance is expressed in angstroms.This is the distance between the atom j and the ikm plane. The j atom is the center of the improper dihedral angle formed by i, j, k and m.
- Throws:
chemfiles::OutOfBounds – if
i
,j
,k
orm
are bigger than the number of atoms in this frame
-
inline const property_map &properties() const¶
Get the map of properties associated with this frame. This map might be iterated over to list the properties of the frame, or directly accessed.
-
inline void set(std::string name, Property value)¶
Set an arbitrary property for this frame with the given
name
andvalue
. If a property with this name already exist, it is silently replaced with the new value.
-
inline optional<const Property&> get(const std::string &name) const¶
Get the
Property
with the givenname
for this frame if it exists.If no property with the given
name
is found, this function returnsnullopt
.
-
template<Property::Kind kind>
inline optional<typename property_metadata<kind>::type> get(const std::string &name) const¶ Get the
Property
with the givenname
for this frame if it exists, and check that it has the requiredkind
.If no property with the given
name
is found, this function returnsnullopt
.If a property with the given
name
is found, but has a different kind, this function emits a warning and returnsnullopt
.