Struct chemfiles::Trajectory

source ·
pub struct Trajectory { /* private fields */ }
Expand description

The Trajectory type is the main entry point when using chemfiles. A Trajectory behave a bit like a file, allowing to read and/or write Frame.

Implementations§

source§

impl Trajectory

source

pub fn open<P>(path: P, mode: char) -> Result<Trajectory, Error>where P: AsRef<Path>,

Open the file at the given path in the given mode.

Valid modes are 'r' for read, 'w' for write and 'a' for append.

Errors

This function fails if the file is not accessible for the given mode, if it is incorrectly formatted for the corresponding format, or in case of I/O errors from the OS.

Example
let trajectory = Trajectory::open("water.xyz", 'r').unwrap();
source

pub fn open_with_format<'a, P, S>( filename: P, mode: char, format: S ) -> Result<Trajectory, Error>where P: AsRef<Path>, S: Into<&'a str>,

Open the file at the given path using a specific file format and the given mode.

Valid modes are 'r' for read, 'w' for write and 'a' for append.

Specifying a format is needed when the file format does not match the extension, or when there is not standard extension for this format. If format is an empty string, the format will be guessed from the extension.

Errors

This function fails if the file is not accessible for the given mode, if it is incorrectly formatted for the corresponding format, or in case of I/O errors from the OS.

Example
let trajectory = Trajectory::open_with_format("water.zeo", 'r', "XYZ").unwrap();
source

pub fn memory_writer<'a, S>(format: S) -> Result<Trajectory, Error>where S: Into<&'a str>,

Write to a memory buffer as though it was a formatted file.

The format parameter should follow the same rules as in the main Trajectory constructor, except that compression specification is not supported.

The memory_buffer function can be used to retrieve the data written to memory of the Trajectory.

Errors

This function fails if the format do not support in-memory writers.

Example
let trajectory_memory = Trajectory::memory_writer("SMI");

// Binary formats typically do not support this feature
assert!(Trajectory::memory_writer("XTC").is_err());
source

pub fn read(&mut self, frame: &mut Frame) -> Result<(), Error>

Read the next step of this trajectory into a frame.

If the number of atoms in frame does not correspond to the number of atom in the next step, the frame is resized.

Errors

This function fails if the data is incorrectly formatted for the corresponding format, or in case of I/O errors from the OS.

Example
let mut trajectory = Trajectory::open("water.xyz", 'r').unwrap();
let mut frame = Frame::new();

trajectory.read(&mut frame).unwrap();
source

pub fn read_step(&mut self, step: usize, frame: &mut Frame) -> Result<(), Error>

Read a specific step of this trajectory into a frame.

If the number of atoms in frame does not correspond to the number of atom at this step, the frame is resized.

Errors

This function fails if the data is incorrectly formatted for the corresponding format.

Example
let mut trajectory = Trajectory::open("water.xyz", 'r').unwrap();
let mut frame = Frame::new();

trajectory.read_step(10, &mut frame).unwrap();
source

pub fn write(&mut self, frame: &Frame) -> Result<(), Error>

Write a frame to this trajectory.

Errors

This function fails if the data is incorrectly formatted for the corresponding format.

Example
let mut trajectory = Trajectory::open("water.pdb", 'w').unwrap();
let mut frame = Frame::new();

trajectory.write(&mut frame).unwrap();
source

pub fn set_topology(&mut self, topology: &Topology)

Set the topology associated with this trajectory. This topology will be used when reading and writing the files, replacing any topology in the frames or files.

Example
let mut topology = Topology::new();
topology.add_atom(&Atom::new("H"));
topology.add_atom(&Atom::new("O"));
topology.add_atom(&Atom::new("H"));
topology.add_bond(0, 1);
topology.add_bond(1, 2);

let mut trajectory = Trajectory::open("water.xyz", 'r').unwrap();
trajectory.set_topology(&topology);
source

pub fn set_topology_file<P>(&mut self, path: P) -> Result<(), Error>where P: AsRef<Path>,

Set the topology associated with this trajectory by reading the first frame of the file at the given path using the file format in format; and extracting the topology of this frame.

Errors

This function fails if the topology file is incorrectly formatted for the corresponding format, or in case of I/O errors from the OS.

Example
let mut trajectory = Trajectory::open("water.nc", 'r').unwrap();
trajectory.set_topology_file("topology.pdb").unwrap();
source

pub fn set_topology_with_format<'a, P, S>( &mut self, path: P, format: S ) -> Result<(), Error>where P: AsRef<Path>, S: Into<&'a str>,

Set the topology associated with this trajectory by reading the first frame of the file at the given path using the file format in format; and extracting the topology of this frame.

If format is an empty string, the format will be guessed from the path extension.

Errors

This function fails if the topology file is incorrectly formatted for the corresponding format, or in case of I/O errors from the OS.

Example
let mut trajectory = Trajectory::open("water.nc", 'r').unwrap();
trajectory.set_topology_with_format("topology.mol", "PDB").unwrap();
source

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

Set the unit cell associated with a trajectory. This cell will be used when reading and writing the files, replacing any unit cell in the frames or files.

Example
let mut trajectory = Trajectory::open("water.xyz", 'r').unwrap();
trajectory.set_cell(&UnitCell::new([10.0, 11.0, 12.5]));
source

pub fn nsteps(&mut self) -> usize

Get the number of steps (the number of frames) in a trajectory.

Example
let mut trajectory = Trajectory::open("water.xyz", 'r').unwrap();

println!("This trajectory contains {} steps", trajectory.nsteps());
source

pub fn memory_buffer(&self) -> Result<&str, Error>

Obtain the memory buffer written to by the trajectory.

Errors

This fails if the trajectory was not opened with Trajectory::memory_writer.

Example
let mut trajectory_memory = Trajectory::memory_writer("SMI").unwrap();

let mut frame = Frame::new();
frame.add_atom(&Atom::new("C"), [0.0, 0.0, 0.0], None);
frame.add_atom(&Atom::new("C"), [0.0, 0.0, 0.0], None);
frame.add_bond_with_order(0, 1, BondOrder::Single);

trajectory_memory.write(&frame).unwrap();

let result = trajectory_memory.memory_buffer();
assert_eq!(result.unwrap(), "CC\n");
source

pub fn path(&self) -> String

Get file path for this trajectory.

Example
let trajectory = Trajectory::open("water.xyz", 'r').unwrap();

assert_eq!(trajectory.path(), "water.xyz");

Trait Implementations§

source§

impl Debug for Trajectory

source§

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

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

impl Drop for Trajectory

source§

fn drop(&mut self)

Executes the destructor for this type. Read more

Auto Trait Implementations§

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