Struct Frame 

pub struct Frame<'a> { /* private fields */ }

In-progress frame in a HOOMD GSD file.

Call HoomdGsdFile::append_frame to create a new frame in the file. The Frame it returns has chainable methods you can call to add data chunks to the frame in the file. The frame is complete when the Frame is dropped.

append_frame always writes configuration/step with the given step. Each of the following methods writes the data chunk of the same name (where ‘/’ has been replaced with ‘_’):

Configuration

• configuration_dimensions
• configuration_box

Particles

• particles_diameter
• particles_position
• particles_orientation
• particles_type_id
• particles_types

The first call to any particles_* method (except particles_types) implicitly writes the chunk particles/N. Any subsequent calls to other particles_* methods will return an error if N does not match.

Log

All log_* methods write the chunk “log/{name}”.

• log_scalar
• log_scalars
• log_arrays

Implementations

impl Frame<'_>

pub fn configuration_dimensions( self, dimensions: Dimensions, ) -> Result<Self, AppendError>

Write configuration/dimensions to the current frame in the GSD file.

Example

use hoomd_gsd::hoomd::{Dimensions, HoomdGsdFile};
// let path = "file.gsd";
let mut hoomd_gsd_file = HoomdGsdFile::create(path)?;
hoomd_gsd_file
    .append_frame(1_000)?
    .configuration_dimensions(Dimensions::Two)?
    .end()?;

Errors

Returns an AppendError when any of the following occur:

• The file is not opened in a write mode.
• An I/O error writing to the file.

pub fn configuration_box(self, values: [f64; 6]) -> Result<Self, AppendError>

Write configuration/box to the current frame in the GSD file.

The input f64 values are converted to f32.

Example

use hoomd_gsd::hoomd::HoomdGsdFile;
// let path = "file.gsd";
let mut hoomd_gsd_file = HoomdGsdFile::create(path)?;
hoomd_gsd_file
    .append_frame(1_000)?
    .configuration_box([10.0, 20.0, 30.0, 0.0, 0.0, 0.0])?
    .end()?;

Errors

Returns an AppendError when any of the following occur:

• The file is not opened in a write mode.
• An I/O error writing to the file.

pub fn particles_position<I>(self, position: I) -> Result<Self, AppendError>

where I: IntoIterator<Item = Cartesian<3>>,

Write particles/position to the current frame in the GSD file.

The input Cartesian<3> argument is converted to [f32; 3].

Example

use hoomd_gsd::hoomd::HoomdGsdFile;
// let path = "file.gsd";
let mut hoomd_gsd_file = HoomdGsdFile::create(path)?;
hoomd_gsd_file
    .append_frame(1_000)?
    .particles_position([
        [2.0, 3.0, -1.0].into(),
        [18.0, 4.0, -6.0].into(),
    ])?
    .end()?;

Errors

Returns an AppendError when any of the following occur:

• The file is not opened in a write mode.
• An I/O error writing to the file.
• N does not match a previous particles_* data chunk in this frame.

pub fn particles_orientation<I>( self, orientation: I, ) -> Result<Self, AppendError>

where I: IntoIterator<Item = Versor>,

Write particles/orientation to the current frame in the GSD file.

The input Versor argument is converted to [f32; 4].

Example

use hoomd_gsd::hoomd::HoomdGsdFile;
use hoomd_vector::Versor;
// let path = "file.gsd";
let mut hoomd_gsd_file = HoomdGsdFile::create(path)?;
hoomd_gsd_file
    .append_frame(1_000)?
    .particles_orientation([
        Versor::from_axis_angle([0.0, 0.0, 1.0].try_into()?, 1.2),
        Versor::from_axis_angle([0.0, 1.0, 0.0].try_into()?, -0.3),
    ])?
    .end()?;

Errors

Returns an AppendError when any of the following occur:

• The file is not opened in a write mode.
• An I/O error writing to the file.
• N does not match a previous particles_* data chunk in this frame.

pub fn particles_type_id<I>(self, type_id: I) -> Result<Self, AppendError>

where I: IntoIterator<Item = u32>,

Write particles/typeid to the current frame in the GSD file.

Example

use hoomd_gsd::hoomd::HoomdGsdFile;
// let path = "file.gsd";
let mut hoomd_gsd_file = HoomdGsdFile::create(path)?;
hoomd_gsd_file
    .append_frame(1_000)?
    .particles_type_id([0, 0, 0, 1, 1, 1])?
    .end()?;

Errors

Returns an AppendError when any of the following occur:

• The file is not opened in a write mode.
• An I/O error writing to the file.
• N does not match a previous particles_* data chunk in this frame.

pub fn particles_types<'a, I>(self, types: I) -> Result<Self, AppendError>

where I: IntoIterator<Item = &'a str>,

Write particles/types to the current frame in the GSD file.

Example

use hoomd_gsd::hoomd::HoomdGsdFile;
// let path = "file.gsd";
let mut hoomd_gsd_file = HoomdGsdFile::create(path)?;
hoomd_gsd_file
    .append_frame(1_000)?
    .particles_types(["A", "B", "linker"])?
    .end()?;

Errors

Returns an AppendError when any of the following occur:

• The file is not opened in a write mode.
• An I/O error writing to the file.

Panics

Panics when any type name string is longer than 63 characters. This is a limitation in the hoomd-rs implementation, not the GSD file format. The limitation may be removed in a future release.

pub fn particles_diameter<I>(self, diameter: I) -> Result<Self, AppendError>

where I: IntoIterator<Item = f64>,

Write particles/diameter to the current frame in the GSD file.

Example

use hoomd_gsd::hoomd::HoomdGsdFile;
// let path = "file.gsd";
let mut hoomd_gsd_file = HoomdGsdFile::create(path)?;
hoomd_gsd_file
    .append_frame(1_000)?
    .particles_diameter([1.0, 0.5, 0.25, 2.0])?
    .end()?;

Errors

Returns an AppendError when any of the following occur:

• The file is not opened in a write mode.
• An I/O error writing to the file.
• N does not match a previous particles_* data chunk in this frame.

pub fn log_scalar<T>(self, name: &str, scalar: T) -> Result<Self, AppendError>

where T: Type,

Write log/{name} to the current frame in the GSD file as a 1x1 array of type T.

Example

use hoomd_gsd::hoomd::HoomdGsdFile;
// let path = "file.gsd";
let mut hoomd_gsd_file = HoomdGsdFile::create(path)?;
hoomd_gsd_file
    .append_frame(1_000)?
    .log_scalar("height", 10.0_f64)?
    .end()?;

Errors

Returns an AppendError when any of the following occur:

• The file is not opened in a write mode.
• An I/O error writing to the file.

pub fn log_scalars<T, I>( self, name: &str, scalars: I, ) -> Result<Self, AppendError>

where T: Type, I: IntoIterator<Item = T>,

Write log/{name} to the current frame in the GSD file as a Nx1 array of type T where N is the number of items produced by the scalars iterator.

Example

use hoomd_gsd::hoomd::HoomdGsdFile;
// let path = "file.gsd";
let mut hoomd_gsd_file = HoomdGsdFile::create(path)?;
hoomd_gsd_file
    .append_frame(1_000)?
    .log_scalars("energy", [1.0_f64, 2.0, 3.0])?
    .end()?;

Errors

Returns an AppendError when any of the following occur:

• The file is not opened in a write mode.
• An I/O error writing to the file.

pub fn log_arrays<T, I, const M: usize>( self, name: &str, arrays: I, ) -> Result<Self, AppendError>

where T: Type, I: IntoIterator<Item = [T; M]>,

Write log/{name} to the current frame in the GSD file as a NxM array of type T where N is the number of items produced by the arrays iterator.

Example

use hoomd_gsd::hoomd::HoomdGsdFile;
// let path = "file.gsd";
let mut hoomd_gsd_file = HoomdGsdFile::create(path)?;
hoomd_gsd_file
    .append_frame(1_000)?
    .log_arrays("points", [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])?
    .end()?;

Errors

Returns an AppendError when any of the following occur:

• The file is not opened in a write mode.
• An I/O error writing to the file.

pub fn end(self) -> Result<(), AppendError>

End the frame.

Once the frame is complete, no more data chunks may be added to it. The next call to HoomdGsdFile::append_frame will add a new frame to the file.

Calling end is optional. The frame will automatically end when Frame is dropped. Drop ignores any errors. Call end explicitly to check for errors.

Errors

Returns an I/O error when there is a problem writing to the file.

Example

use hoomd_gsd::hoomd::HoomdGsdFile;
// let path = "file.gsd";
let mut hoomd_gsd_file = HoomdGsdFile::create(path)?;
hoomd_gsd_file.append_frame(1_000)?.end()?;

Trait Implementations

impl Drop for Frame<'_>

End the frame.

Once the frame is complete, no more data chunks may be added to it. The next call to HoomdGsdFile::append_frame will add a new frame to the file.

drop checks the amount of time since the last call to HoomdGsdFile::sync_all. If it has been more than the auto sync delay, drop calls sync_all. drop ignores all errors. Call Frame::end to end the frame and check on potential I/O errors.

Example

use hoomd_gsd::hoomd::HoomdGsdFile;
// let path = "file.gsd";
let mut hoomd_gsd_file = HoomdGsdFile::create(path)?;
hoomd_gsd_file.append_frame(1_000)?;
// ... some I/O errors might be ignored during the implicit drop.

fn drop(&mut self)

Executes the destructor for this type.