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 the nullopt variant of chemfiles::optional.

Iterating over a Frame will yield all the atoms in the system.

Public Functions

explicit Frame(UnitCell cell = UnitCell())

Create an empty frame with no atoms and the given cell.

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.)

void set_topology(Topology topology)

Set the topology of this frame to topology

Parameters:

topology – the new Topology to use for this frame

Throws:

Error – if the topology size does not match the size of this frame

inline const UnitCell &cell() const

Get a const reference to the unit cell of this frame

inline UnitCell &cell()

Get a reference to the unit cell of this frame

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 span<Vector3D> positions()

Get the positions (in Angstroms) of the 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 given position and optionally with the given velocity. The velocity 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.

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 and atom_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 or atom_j are greater than size()

• 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 and atom_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 or atom_j are greater than size()

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 than size()

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 than size()

double distance(size_t i, size_t j) const

Get the distance between the atoms at indexes i and j, accounting for periodic boundary conditions. The distance is expressed in angstroms.

Throws:

chemfiles::OutOfBounds – if i or j 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 and k, accounting for periodic boundary conditions. The angle is expressed in radians.

Throws:

chemfiles::OutOfBounds – if i, j or k 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 and m, accounting for periodic boundary conditions. The angle is expressed in radians.

Throws:

chemfiles::OutOfBounds – if i, j, k or m 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 and m, 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 or m 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 and value. 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 given name for this frame if it exists.

If no property with the given name is found, this function returns nullopt.

template<Property::Kind kind>
inline optional<typename property_metadata<kind>::type> get(const std::string &name) const

Get the Property with the given name for this frame if it exists, and check that it has the required kind.

If no property with the given name is found, this function returns nullopt.

If a property with the given name is found, but has a different kind, this function emits a warning and returns nullopt.