Frame class

class chemfiles.Frame

A Frame contains data from one simulation step: the current unit cell, the topology, the positions, and the velocities of the particles in the system. If some information is missing (topology or velocity or unit cell), the corresponding data is filled with a default value.

Create an empty Frame that will be resized by the runtime as needed.

add_atom(atom, position, velocity=None)

Add a copy of the Atom atom and the corresponding position and velocity to this Frame.

velocity can be None if no velocity is associated with the atom.

add_bond(i, j, order=None)

Add a bond between the atoms at indexes i and j in this Frame’s topology, optionally setting the bond order.

add_residue(residue)

Add the Residue residue to this Frame’s topology.

The residue id must not already be in the topology, and the residue must contain only atoms that are not already in another residue.

add_velocities()

Add velocity data to this Frame.

The velocities are initialized to zero. If the frame already contains velocities, this function does nothing.

angle(i, j, k)

Get the angle (in radians) formed by the atoms at indexes i, j and k in this Frame, taking periodic boundary conditions into account.

property cell

Get a mutable reference to the UnitCell of this Frame. Any modification to the cell will be reflected in the frame.

dihedral(i, j, k, m)

Get the dihedral angle (in radians) formed by the atoms at indexes i, j, k and m in this Frame, taking periodic boundary conditions into account.

distance(i, j)

Get the distance (in Ångströms) between the atoms at indexes i and j in this Frame, taking periodic boundary conditions into account.

guess_bonds()

Guess the bonds, angles and dihedrals in this Frame.

The bonds are guessed using a distance-based algorithm, and then angles and dihedrals are guessed from the bonds.

has_velocities()

Check if this Frame contains velocity.

list_properties()

Get the name of all properties in this frame.

out_of_plane(i, j, k, m)

Get the out of plane distance (in Ångströms) formed by the atoms at indexes i, j, k and m in this Frame, taking periodic boundary conditions into account.

This is the distance betweent 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.

property positions

Get a view into the positions of this Frame.

This function gives direct access to the positions as a numpy array. Modifying the array will change the positions in the frame.

If the frame is resized (by writing to it, calling Frame.resize(), Frame.add_atom(), Frame.remove()), the array is invalidated. Accessing it can cause a segfault.

properties_count()

Get the number of properties in this frame.

remove(index)

Remove the atom at the given index in this Frame.

This shifts all the atoms indexes larger than index by 1 (n becomes n - 1); and invalidate any array obtained using Frame.positions() or Frame.velocities().

remove_bond(i, j)

Remove any existing bond between the atoms at indexes i and j in this Frame’s topology.

This function does nothing if there is no bond between i and j.

resize(count)

Resize the positions, velocities and topology in this Frame, to have space for count atoms.

This function may invalidate any array of the positions or the velocities if the new size is bigger than the old one. In all cases, previous data is conserved. This function conserve the presence or absence of velocities.

property step

Get the step of this Frame, i.e. the frame number in the trajectory.

property topology

Get read-only access to the Topology of this Frame.

property velocities

Get a view into the velocities of this Frame.

This function gives direct access to the velocities as a numpy array. Modifying the array will change the velocities in the frame.

If the frame is resized (by writing to it, calling Frame.resize(), Frame.add_atom(), Frame.remove()), the array is invalidated. Accessing it can cause a segfault.