Struct chemfiles::Frame[][src]

pub struct Frame { /* fields omitted */ }
Expand description

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

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

Example

let frame = Frame::new();

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

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");

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");

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

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

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]);

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");

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]]);

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

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]]);

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");

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

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

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

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

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]);

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]);

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();
assert_eq!(velocities.len(), 67);
assert_eq!(velocities[0], [0.0, 0.0, 0.0]);

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();
    assert_eq!(velocities[0], [0.0, 0.0, 0.0]);
    velocities[0] = [1.0, 2.0, 3.0];
}

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

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

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

Get a reference to the UnitCell from this frame.

Example

let frame = Frame::new();

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

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

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]);

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

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");

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

Example

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

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

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

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());

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

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

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));
    }
}

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Executes the destructor for this type. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Performs the conversion.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.