Struct chemfiles::Frame

source ·
pub struct Frame { /* private fields */ }
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§

source§

impl Frame

source

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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§

source§

impl Clone for Frame

source§

fn clone(&self) -> Frame

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for Frame

source§

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

Formats the value using the given formatter. Read more
source§

impl Drop for Frame

source§

fn drop(&mut self)

Executes the destructor for this type. Read more

Auto Trait Implementations§

§

impl RefUnwindSafe for Frame

§

impl !Send for Frame

§

impl !Sync for Frame

§

impl Unpin for Frame

§

impl UnwindSafe for Frame

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

const: unstable · source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

const: unstable · source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

const: unstable · source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

const: unstable · source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

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

fn clone_into(&self, target: &mut T)

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

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
const: unstable · source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
const: unstable · source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.