Struct chemfiles::Frame

pub struct Frame { /* private fields */ }

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.

Implementations

impl Frame

pub fn new() -> Frame

Create an empty frame. It will be resized by the library as needed.

Example

let frame = Frame::new();

assert_eq!(frame.size(), 0);

pub fn atom(&self, index: usize) -> AtomRef<'_>

Get a reference to the atom at the given index in this frame.

Panics

If index is out of bounds.

Example

let mut frame = Frame::new();
frame.add_atom(&Atom::new("Zn"), [0.0; 3], None);

let atom = frame.atom(0);
assert_eq!(atom.name(), "Zn");

pub fn atom_mut(&mut self, index: usize) -> AtomMut<'_>

Get a mutable reference to the atom at the given index in this frame.

Panics

If index is out of bounds.

Example

let mut frame = Frame::new();
frame.add_atom(&Atom::new("Zn"), [0.0; 3], None);

assert_eq!(frame.atom(0).name(), "Zn");

frame.atom_mut(0).set_name("Fe");
assert_eq!(frame.atom(0).name(), "Fe");

pub fn size(&self) -> usize

Get the current number of atoms in this frame.

Example

let mut frame = Frame::new();
assert_eq!(frame.size(), 0);

frame.resize(67);
assert_eq!(frame.size(), 67);

pub fn resize(&mut self, natoms: usize)

Resize the positions and the velocities in this frame, to make space for natoms atoms. Previous data is conserved, as well as the presence of absence of velocities.

Example

let mut frame = Frame::new();
frame.resize(67);
assert_eq!(frame.size(), 67);

pub fn add_atom( &mut self, atom: &Atom, position: [f64; 3], velocity: impl Into<Option<[f64; 3]>> )

Add an Atom and the corresponding position and optionally velocity data to this frame.

Example

let mut frame = Frame::new();
frame.add_atom(&Atom::new("Zn"), [1.0, 1.0, 2.0], None);

frame.add_velocities();
frame.add_atom(&Atom::new("Zn"), [-1.0, 1.0, 2.0], [0.2, 0.1, 0.0]);

pub fn remove(&mut self, i: usize)

Remove the atom at index i in this frame.

Example

let mut frame = Frame::new();
frame.add_atom(&Atom::new("Zn"), [0.0; 3], None);
frame.add_atom(&Atom::new("Fe"), [0.0; 3], None);
frame.add_atom(&Atom::new("Sn"), [0.0; 3], None);
assert_eq!(frame.size(), 3);

frame.remove(1);
assert_eq!(frame.size(), 2);
assert_eq!(frame.atom(1).name(), "Sn");

pub fn add_bond(&mut self, i: usize, j: usize)

Add a bond between the atoms at indexes i and j in the frame.

The bond order is set to BondOrder::Unknown.

Example

let mut frame = Frame::new();
assert_eq!(frame.topology().bonds_count(), 0);
frame.resize(5);

frame.add_bond(0, 1);
frame.add_bond(3, 1);
frame.add_bond(2, 4);
assert_eq!(frame.topology().bonds_count(), 3);

assert_eq!(frame.topology().bond_order(0, 1), BondOrder::Unknown);
assert_eq!(frame.topology().bonds(), vec![[0, 1], [1, 3], [2, 4]]);

pub fn add_bond_with_order(&mut self, i: usize, j: usize, order: BondOrder)

Add a bond between the atoms at indexes i and j in the frame with the given bond order.

Example

let mut frame = Frame::new();
assert_eq!(frame.topology().bonds_count(), 0);
frame.resize(2);

frame.add_bond_with_order(0, 1, BondOrder::Double);
assert_eq!(frame.topology().bond_order(0, 1), BondOrder::Double);

pub fn remove_bond(&mut self, i: usize, j: usize)

Remove any existing bond between the atoms at indexes i and j in the frame.

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

Example

let mut frame = Frame::new();
frame.resize(5);

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

let bonds = frame.topology().bonds();
assert_eq!(bonds, vec![[0, 1], [1, 3], [2, 4]]);

frame.remove_bond(2, 4);
let bonds = frame.topology().bonds();
assert_eq!(bonds, vec![[0, 1], [1, 3]]);

pub fn add_residue(&mut self, residue: &Residue) -> Result<(), Error>

Add a copy of residue to this frame.

Errors

This function fails is the residue id is already in this frame’s topology, or if the residue contain atoms that are already in another residue.

Example

let mut frame = Frame::new();

let residue = Residue::new("foo");
frame.add_residue(&residue).unwrap();

let topology = frame.topology();
assert_eq!(topology.residues_count(), 1);
assert_eq!(topology.residue(0).unwrap().name(), "foo");

pub fn distance(&self, i: usize, j: usize) -> f64

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

Example

let mut frame = Frame::new();
frame.add_atom(&Atom::new("A"), [0.0, 0.0, 0.0], None);
frame.add_atom(&Atom::new("B"), [1.0, 2.0, 3.0], None);

assert_eq!(frame.distance(0, 1), f64::sqrt(14.0));

pub fn angle(&self, i: usize, j: usize, k: usize) -> f64

Get the angle formed by the atoms at indexes i, j and k in this frame, accounting for periodic boundary conditions. The result is expressed in radians.

Example

let mut frame = Frame::new();
frame.add_atom(&Atom::new("A"), [1.0, 0.0, 0.0], None);
frame.add_atom(&Atom::new("B"), [0.0, 0.0, 0.0], None);
frame.add_atom(&Atom::new("C"), [0.0, 1.0, 0.0], None);

assert_eq!(frame.angle(0, 1, 2), f64::consts::PI / 2.0);

pub fn dihedral(&self, i: usize, j: usize, k: usize, m: usize) -> f64

Get the dihedral angle formed by the atoms at indexes i, j, k and m in this frame, accounting for periodic boundary conditions. The result is expressed in radians.

Example

let mut frame = Frame::new();
frame.add_atom(&Atom::new("A"), [1.0, 0.0, 0.0], None);
frame.add_atom(&Atom::new("B"), [0.0, 0.0, 0.0], None);
frame.add_atom(&Atom::new("C"), [0.0, 1.0, 0.0], None);
frame.add_atom(&Atom::new("D"), [0.0, 1.0, 1.0], None);

assert_eq!(frame.dihedral(0, 1, 2, 3), f64::consts::PI / 2.0);

pub fn out_of_plane(&self, i: usize, j: usize, k: usize, m: usize) -> f64

Get the out of plane distance formed by the atoms at indexes i, j, k and m in this frame, accounting for periodic boundary conditions. The result 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.

Example

let mut frame = Frame::new();
frame.add_atom(&Atom::new("A"), [0.0, 0.0, 0.0], None);
frame.add_atom(&Atom::new("B"), [0.0, 0.0, 2.0], None);
frame.add_atom(&Atom::new("C"), [1.0, 0.0, 0.0], None);
frame.add_atom(&Atom::new("D"), [0.0, 1.0, 0.0], None);

assert_eq!(frame.out_of_plane(0, 1, 2, 3), 2.0);

pub fn positions(&self) -> &[[f64; 3]]

Get a view into the positions of this frame.

Example

let mut frame = Frame::new();
frame.resize(67);

let positions = frame.positions();
assert_eq!(positions.len(), 67);
assert_eq!(positions[0], [0.0, 0.0, 0.0]);

pub fn positions_mut(&mut self) -> &mut [[f64; 3]]

Get a mutable view into the positions of this frame.

Example

let mut frame = Frame::new();
frame.resize(67);
{
    let positions = frame.positions_mut();
    assert_eq!(positions[0], [0.0, 0.0, 0.0]);
    positions[0] = [1.0, 2.0, 3.0];
}

let positions = frame.positions();
assert_eq!(positions[0], [1.0, 2.0, 3.0]);

pub fn velocities(&self) -> Option<&[[f64; 3]]>

Get a view into the velocities of this frame.

Example

let mut frame = Frame::new();
frame.resize(67);
frame.add_velocities();

let velocities = frame.velocities().expect("missing velocities");
assert_eq!(velocities.len(), 67);
assert_eq!(velocities[0], [0.0, 0.0, 0.0]);

pub fn velocities_mut(&mut self) -> Option<&mut [[f64; 3]]>

Get a mutable view into the velocities of this frame.

Example

let mut frame = Frame::new();
frame.resize(67);
frame.add_velocities();
{
    let velocities = frame.velocities_mut().expect("missing velocities");
    assert_eq!(velocities[0], [0.0, 0.0, 0.0]);
    velocities[0] = [1.0, 2.0, 3.0];
}

let velocities = frame.velocities().expect("missing velocities");
assert_eq!(velocities[0], [1.0, 2.0, 3.0]);

pub fn has_velocities(&self) -> bool

Check if this frame contains velocity data.

Example

let mut frame = Frame::new();
assert_eq!(frame.has_velocities(), false);

frame.add_velocities();
assert_eq!(frame.has_velocities(), true);

pub fn add_velocities(&mut self)

Add velocity data to this frame. If the frame already have velocities, this does nothing.

Example

let mut frame = Frame::new();
assert_eq!(frame.has_velocities(), false);

frame.add_velocities();
assert_eq!(frame.has_velocities(), true);

pub fn cell(&self) -> UnitCellRef<'_>

Get a reference to the UnitCell from this frame.

Example

let frame = Frame::new();

let cell = frame.cell();
assert_eq!(cell.shape(), CellShape::Infinite);

pub fn cell_mut(&mut self) -> UnitCellMut<'_>

Get a mutable reference to the UnitCell from this frame.

Example

let mut frame = Frame::new();

assert_eq!(frame.cell().shape(), CellShape::Infinite);

frame.cell_mut().set_shape(CellShape::Triclinic).unwrap();
assert_eq!(frame.cell().shape(), CellShape::Triclinic);

pub fn set_cell(&mut self, cell: &UnitCell)

Set the UnitCell of this frame to cell.

Example

let mut frame = Frame::new();

frame.set_cell(&UnitCell::new([10.0, 10.0, 10.0]));

let cell = frame.cell();
assert_eq!(cell.shape(), CellShape::Orthorhombic);
assert_eq!(cell.lengths(), [10.0, 10.0, 10.0]);

pub fn topology(&self) -> TopologyRef<'_>

Get a reference to the Topology of this frame.

Example

let mut frame = Frame::new();
frame.resize(42);

let topology = frame.topology();
assert_eq!(topology.size(), 42);

pub fn set_topology(&mut self, topology: &Topology) -> Result<(), Error>

Set the Topology of this frame to topology.

Errors

This function fails if the topology contains a different number of atoms than this frame.

Example

let mut frame = Frame::new();
frame.resize(2);

let mut topology = Topology::new();
topology.add_atom(&Atom::new("Cl"));
topology.add_atom(&Atom::new("Cl"));
topology.add_bond(0, 1);

frame.set_topology(&topology).unwrap();
assert_eq!(frame.atom(0).name(), "Cl");

pub fn step(&self) -> usize

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

Example

let frame = Frame::new();
assert_eq!(frame.step(), 0);

pub fn set_step(&mut self, step: usize)

Set this frame step to step.

Example

let mut frame = Frame::new();
assert_eq!(frame.step(), 0);

frame.set_step(10);
assert_eq!(frame.step(), 10);

pub fn guess_bonds(&mut self) -> Result<(), Error>

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.

Errors

This function can fail if the covalent radius is unknown for some atoms in the frame.

Example

let mut frame = Frame::new();

frame.add_atom(&Atom::new("Cl"), [0.0, 0.0, 0.0], None);
frame.add_atom(&Atom::new("Cl"), [1.5, 0.0, 0.0], None);
assert_eq!(frame.topology().bonds_count(), 0);

frame.guess_bonds().unwrap();
assert_eq!(frame.topology().bonds_count(), 1);

pub fn clear_bonds(&mut self)

Remove all existing bonds, angles, dihedral angles and improper dihedral angles in the topology of the frame.

Example

let mut frame = Frame::new();
frame.add_atom(&Atom::new("H"), [1.0, 0.0, 0.0], None);
frame.add_atom(&Atom::new("O"), [0.0, 0.0, 0.0], None);
frame.add_atom(&Atom::new("H"), [0.0, 1.0, 0.0], None);

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

assert_eq!(frame.topology().bonds().len(), 2);
assert_eq!(frame.topology().angles().len(), 1);

frame.clear_bonds();
assert!(frame.topology().bonds().is_empty());
assert!(frame.topology().angles().is_empty());

pub fn set(&mut self, name: &str, property: impl Into<Property>)

Add a new property with the given name to this frame.

If a property with the same name already exists, this function override the existing property with the new one.

Examples

let mut frame = Frame::new();
frame.set("a string", "hello");
frame.set("a double", 4.3);

assert_eq!(frame.get("a string"), Some(Property::String("hello".into())));
assert_eq!(frame.get("a double"), Some(Property::Double(4.3)));

pub fn get(&self, name: &str) -> Option<Property>

Get a property with the given name in this frame, if it exist.

Examples

let mut frame = Frame::new();
frame.set("foo", Property::Double(22.2));

assert_eq!(frame.get("foo"), Some(Property::Double(22.2)));
assert_eq!(frame.get("Bar"), None);

pub fn properties(&self) -> PropertiesIter<'_>

Get an iterator over all (name, property) pairs for this frame

Examples

let mut frame = Frame::new();
frame.set("foo", Property::Double(22.2));
frame.set("bar", Property::Bool(false));

for (name, property) in frame.properties() {
    if name == "foo" {
        assert_eq!(property, Property::Double(22.2));
    } else if name == "bar" {
        assert_eq!(property, Property::Bool(false));
    }
}

pub fn iter_atoms(&self) -> AtomIter<'_>

Gets an iterator over atoms

Example

let mut frame = Frame::new();

frame.add_atom(&Atom::new("O"), [0.0, 0.0, 0.0], None);
frame.add_atom(&Atom::new("H"), [1.0, 0.0, 0.0], None);

let mut atoms: Vec<AtomRef> = Vec::new();

for atom in frame.iter_atoms() {
    atoms.push(atom);
}

assert_eq!(atoms.len(), 2);

Trait Implementations

impl Clone for Frame

fn clone(&self) -> Frame

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Frame

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Frame

fn drop(&mut self)

Executes the destructor for this type.