Struct HoomdGsdFile 

pub struct HoomdGsdFile { /* private fields */ }

Create and write to GSD files with the HOOMD schema.

Files written by HoomdGsdFile can be read by the Ovito, HOOMD-blue, the GSD Python package, and other applications.

Buffering

GSD aggressively buffers data in memory before synchronizing it to the file. Your appended frames may not be present in the file until it is closed or you call sync_all. append_frame will automatically call sync_all when the last sync was more than 10 seconds prior (by default). Set auto_sync_delay to change the timeout.

Example

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

Implementations

impl HoomdGsdFile

pub fn create<P: AsRef<Path>>(path: P) -> Result<Self, OpenError>

Overwrite an existing HOOMD GSD file (or create a new file).

Creates a GSD file at the given path, overwriting any file that may already exist. When successful, return a HoomdGsdFile opened in write mode.

Example

use hoomd_gsd::hoomd::HoomdGsdFile;
// let path = "file.gsd";
let hoomd_gsd_file = HoomdGsdFile::create(path)?;

Errors

Returns a OpenError when any of the following occur:

• The file cannot be created.
• The file is corrupt, unreadable, or there is an I/O error (see DecodeError).

pub fn create_new<P: AsRef<Path>>(path: P) -> Result<Self, OpenError>

Create a new HOOMD GSD file.

Creates a new GSD file at the given path, returning an error when the path already exists. When successful, return a HoomdGsdFile opened in write mode.

Example

use hoomd_gsd::hoomd::HoomdGsdFile;
// let path = "file.gsd";
let hoomd_gsd_file = HoomdGsdFile::create_new(path)?;

Errors

Returns a OpenError when any of the following occur:

• The file cannot be created.
• The file already exists.
• The file is corrupt, unreadable, or there is an I/O error (see DecodeError).

pub fn open<P: AsRef<Path>>(path: P) -> Result<Self, OpenError>

Open an existing HOOMD GSD file in write mode.

Example

use hoomd_gsd::hoomd::HoomdGsdFile;
// let path = "file.gsd";
let hoomd_gsd_file = HoomdGsdFile::open(path)?;

Errors

Returns a OpenError when any of the following occur:

• The file does not exist.
• The file is corrupt, unreadable, or there is an I/O error (see DecodeError).

pub fn sync_all(&mut self) -> Result<(), SyncError>

Write buffered data to the filesystem.

sync_all ensures that the data and indices for all complete frames is written to the filesystem.

In most cases, callers should not invoke sync_all manually. It will be called automatically when a HoomdGsdFile is dropped and after any call to append_frame at least 10 seconds (by default) after a previous call to sync_all.

Call sync_all only want to ensure that all data up to a specific frame are present in the file.

Errors

Returns a WriteError 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 append_frame(&mut self, step: u64) -> Result<Frame<'_>, WriteError>

Append a new frame to the file.

Use chained method calls to concisely write all the data chunks needed for a single frame (see the example):

Ownership

The returned Frame holds a mutable reference to this HoomdGsdFile, so the compiler forces you to complete writing the frame and drop the Frame (either implicitly or explicitly) before you can take any other actions that would mutate the HoomdGsdFile.

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([100.0, 50.0, 80.0, 0.0, 0.0, 0.0])?
    .particles_position([[0.0, 1.0, 2.0].into(), [3.0, 6.0, 12.0].into()])?
    .end()?;

Errors

Returns a WriteError 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 auto_sync_delay(&self) -> &Duration

Get the auto sync delay.

Example

use hoomd_gsd::hoomd::HoomdGsdFile;
use std::time::Duration;
// let path = "file.gsd";
let mut hoomd_gsd_file = HoomdGsdFile::create(path)?;
let auto_sync_delay = hoomd_gsd_file.auto_sync_delay();

assert_eq!(*auto_sync_delay, Duration::new(10, 0));

pub fn auto_sync_delay_mut(&mut self) -> &mut Duration

Get a mutable reference to the auto sync delay.

Example

use hoomd_gsd::hoomd::HoomdGsdFile;
use std::time::Duration;
// let path = "file.gsd";
let mut hoomd_gsd_file = HoomdGsdFile::create(path)?;
*hoomd_gsd_file.auto_sync_delay_mut() = Duration::new(60, 0);