Struct GsdFile 

pub struct GsdFile { /* private fields */ }

Interact with GSD files on the filesystem.

Overview

Open files with:

• open
• create
• create_new

Access file metadata with:

• n_frames
• schema
• schema_version
• name_id
• find_chunk

Write data with:

• write_scalars
• write_arrays
• write_string
• end_frame
• sync_all

Read data with:

• iter_scalars
• iter_arrays
• read_string

Implementations

impl GsdFile

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

Open a GSD file with the given mode.

Examples

Open a file for reading:

use hoomd_gsd::file_layer::{GsdFile, Mode};
let gsd_file = GsdFile::open(path, Mode::Read);

Open a file for both reading and writing:

use hoomd_gsd::file_layer::{GsdFile, Mode};
let gsd_file = GsdFile::open(path, Mode::Write);

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 create<P: AsRef<Path>>( path: P, application: &str, schema: &str, schema_version: (u16, u16), ) -> Result<Self, OpenError>

Overwrite an existing 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 GsdFile opened in write mode.

Each GSD file contains metadata describing which application created the file, the data chunk schema, and the schema’s version. application and schema are strings (and must each be less than 80 bytes). schema_version is a tuple listing the major and minor version numbers. In your code, replace "example" with the name of your application.

Example

use hoomd_gsd::file_layer::{GsdFile, Mode};
let gsd_file = GsdFile::create(path, "example", "hoomd", (1, 4))?;

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, application: &str, schema: &str, schema_version: (u16, u16), ) -> Result<Self, OpenError>

Create a new GSD file.

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

Each GSD file contains metadata describing which application created the file, the data chunk schema, and the schema’s version. application and schema are strings (and must each be less than 80 bytes). schema_version is a tuple listing the major and minor version numbers. In your code, replace "example" with the name of your application.

Example

use hoomd_gsd::file_layer::{GsdFile, Mode};
let gsd_file = GsdFile::create_new(path, "example", "hoomd", (1, 4))?;

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 find_chunk(&self, frame: u64, name: &str) -> Option<IndexEntry>

Find a chunk in the index.

Returns Some(index_entry) when the data chunk is present in the file and None when it is not.

Example

use hoomd_gsd::file_layer::{DataType, GsdFile};
let mut gsd_file = GsdFile::create_new(path, "example", "hoomd", (1, 4))?;
gsd_file.write_scalars("configuration/step", [100_000_u64])?;
gsd_file.end_frame()?;
gsd_file.sync_all()?;

let configuration_box = gsd_file.find_chunk(0, "configuration/box");
assert_eq!(configuration_box, None);

let step = gsd_file.find_chunk(0, "configuration/step");
assert!(step.is_some());
if let Some(index) = step {
    assert_eq!(index.frame(), 0);
    assert_eq!(index.rows(), 1);
    assert_eq!(index.columns(), 1);
    assert_eq!(index.data_type(), Some(DataType::U64));
}

pub fn iter_scalars<T: Type>( &self, frame: u64, name: &str, ) -> Result<impl ExactSizeIterator<Item = T> + use<'_, T>, ReadError>

Iterate over an array of scalars in the given frame.

Returns Ok(iterator) when the data chunk is present in the file and Err(ReadError::ChunkNotFound) when it is not. Collect the iterator into a Vec to make a copy of the data, or process the data in place while iterating.

Data written to a file is not available for reading until the file is closed or after a call to sync_all.

Example

use hoomd_gsd::file_layer::{DataType, GsdFile};
let mut gsd_file = GsdFile::create_new(path, "example", "hoomd", (1, 4))?;
gsd_file.write_scalars(
    "configuration/box",
    [10.0_f32, 20.0, 15.0, 0.0, 0.0, 0.0],
)?;
gsd_file.end_frame()?;
gsd_file.sync_all()?;

let box_iter = gsd_file.iter_scalars::<f32>(0, "configuration/box")?;
let box_vec = box_iter.collect::<Vec<_>>();
assert_eq!(box_vec, vec![10.0_f32, 20.0, 15.0, 0.0, 0.0, 0.0]);

Errors

Returns a ReadError when any of the following occur:

• A chunk by the given name is not present in the given frame.
• The data type stored in the file does not match T.
• The array stored in the file does not have dimensions N x 1.
• The file is corrupt, unreadable, or there is an I/O error (see DecodeError).

pub fn iter_arrays<T: Type, const M: usize>( &self, frame: u64, name: &str, ) -> Result<impl ExactSizeIterator<Item = [T; M]> + use<'_, T, M>, ReadError>

Iterate over an array of arrays in the given frame.

Returns Ok(iterator) when the data chunk is present in the file and Err(ReadError::ChunkNotFound) when it is not. Collect the iterator into a Vec to make a copy of the data, or process the data in place while iterating.

Data written to a file is not available for reading until the file is closed or after a call to sync_all.

Example

use hoomd_gsd::file_layer::{DataType, GsdFile};
let position = vec![[5.0_f32, 3.0, -4.0], [-2.0, 3.0, -6.0]];

let mut gsd_file = GsdFile::create_new(path, "example", "hoomd", (1, 4))?;
gsd_file.write_arrays("particles/position", position.iter().copied())?;
gsd_file.end_frame()?;
gsd_file.sync_all()?;

let position_iter =
    gsd_file.iter_arrays::<f32, 3>(0, "particles/position")?;
let position_vec = position_iter.collect::<Vec<_>>();
assert_eq!(position_vec, position);

Errors

Returns a ReadError when any of the following occur:

• A chunk by the given name is not present in the given frame.
• The data type stored in the file does not match T.
• The array stored in the file does not have dimensions N x M.
• The file is corrupt, unreadable, or there is an I/O error (see DecodeError).

pub fn read_string(&self, frame: u64, name: &str) -> Result<String, ReadError>

Read a string in the given frame.

Returns Ok(String) when the data chunk is present in the file and Err(ReadError::ChunkNotFound) when it is not.

Data written to a file is not available for reading until the file is closed or after a call to sync_all.

Example

use hoomd_gsd::file_layer::{DataType, GsdFile};
let mut gsd_file = GsdFile::create_new(path, "example", "hoomd", (1, 4))?;
gsd_file.write_string("log/my_string", "Hello, GSD.")?;
gsd_file.end_frame()?;
gsd_file.sync_all()?;

let string = gsd_file.read_string(0, "log/my_string")?;
assert_eq!(string, "Hello, GSD.");

Errors

Returns a ReadError when any of the following occur:

• A chunk by the given name is not present in the given frame.
• The data type stored in the file is not a UTF-8 string.
• The array stored in the file does not have dimensions N x 1.
• The file is corrupt, unreadable, or there is an I/O error (see DecodeError).

pub fn write_scalars<T, I>( &mut self, name: &str, data: I, ) -> Result<(), WriteError>

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

Append an array of scalar values to the current frame.

write_scalars writes one-dimensional array data to a named chunk in the current frame of the GSD file. Call end_frame to complete the frame and start the next.

Dropping a GsdFile will also drop any pending data chunks in incomplete frames.

Example

use hoomd_gsd::file_layer::{DataType, GsdFile};
let mut gsd_file = GsdFile::create_new(path, "example", "hoomd", (1, 4))?;
gsd_file.write_scalars(
    "configuration/box",
    [10.0_f32, 20.0, 15.0, 0.0, 0.0, 0.0],
)?;
gsd_file.end_frame()?;

Errors

Returns a WriteError when any of the following occur:

• The file is not opened in a write mode.
• There are no available chunk identifiers.
• A chunk with the same name has already been written in this frame.
• There is an I/O error while writing to the file.

pub fn write_arrays<T, I, const M: usize>( &mut self, name: &str, data: I, ) -> Result<(), WriteError>

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

Append an array of array values to the current frame.

write_arrays writes two-dimensional array data to a named chunk in the current frame of the GSD file. Call end_frame to complete the frame and start the next.

Dropping a GsdFile will also drop any pending data chunks in incomplete frames.

Example

use hoomd_gsd::file_layer::{DataType, GsdFile};
let position = vec![[5.0_f32, 3.0, -4.0], [-2.0, 3.0, -6.0]];

let mut gsd_file = GsdFile::create_new(path, "example", "hoomd", (1, 4))?;
gsd_file.write_arrays("particles/position", position.iter().copied())?;
gsd_file.end_frame()?;

Errors

Returns a WriteError when any of the following occur:

• The file is not opened i* n a write mode.
• There are no available chunk identifiers.
• A chunk with the same name has already been written in this frame.
• M is 0.
• M cannot be represented by a u32.

pub fn write_string(&mut self, name: &str, data: &str) -> Result<(), WriteError>

Append a string to the current frame.

write_string writes a UTF-8 string to a named chunk in the* current frame of the GSD file. Call end_frame to complete the frame and start the next.

Dropping a GsdFile will also drop any pending data chunks in incomplete frames.

Example

use hoomd_gsd::file_layer::{DataType, GsdFile};
let mut gsd_file = GsdFile::create_new(path, "example", "hoomd", (1, 4))?;
gsd_file.write_string("log/my_string", "Hello, GSD.")?;
gsd_file.end_frame()?;

Errors

Returns a WriteError when any of the following occur:

• The file is not opened in a write mode.
• There are no available chunk identifiers.
• A chunk with the same name has already been written in this frame.

pub fn end_frame(&mut self) -> Result<(), EncodeError>

Complete the current frame.

Commits previous calls to write_* methods to the current frame. Calls to write_* methods following end_frame will write to the next frame.

Calling end_frame does not ensure that all buffered data is synced to the filesystem. Call sync_all to do so.

Example

use hoomd_gsd::file_layer::{DataType, GsdFile};
let mut gsd_file = GsdFile::create_new(path, "example", "hoomd", (1, 4))?;
gsd_file.write_scalars("configuration/step", [100_000_u64])?;
gsd_file.end_frame()?;

gsd_file.write_scalars("configuration/step", [200_000_u64])?;
gsd_file.end_frame()?;

gsd_file.write_scalars("configuration/step", [300_000_u64])?;
gsd_file.end_frame()?;

Errors

Returns a EncodeError when any of the following occur:

• The file is not opened in a write mode.

pub fn n_frames(&self) -> u64

The number of frames written to the file.

n_frames returns the number of frames available to read from the file. Each call to end_frame increments the number of frames, but they are not written to the file until it is closed or by a call to sync_all.

use hoomd_gsd::file_layer::{DataType, GsdFile};
let mut gsd_file = GsdFile::create_new(path, "example", "hoomd", (1, 4))?;
gsd_file.write_scalars("configuration/step", [100_000_u64])?;
gsd_file.end_frame()?;

gsd_file.write_scalars("configuration/step", [200_000_u64])?;
gsd_file.end_frame()?;

gsd_file.write_scalars("configuration/step", [300_000_u64])?;
gsd_file.end_frame()?;
gsd_file.sync_all()?;

let n_frames = gsd_file.n_frames();
assert_eq!(n_frames, 3);

pub fn name_id(&self) -> &HashMap<String, u16>

Provide the mapping from data chunk names to ids.

The mapping includes keys for all data chunk names in the file.

Example

use hoomd_gsd::file_layer::GsdFile;
let position = vec![[5.0_f32, 3.0, -4.0], [-2.0, 3.0, -6.0]];

let mut gsd_file = GsdFile::create_new(path, "example", "hoomd", (1, 4))?;
gsd_file.write_scalars("configuration/step", [100_000_u64])?;
gsd_file.write_scalars(
    "configuration/box",
    [10.0_f32, 20.0, 15.0, 0.0, 0.0, 0.0],
)?;
gsd_file.write_arrays("particles/position", position.iter().copied())?;
gsd_file.end_frame()?;

let name_id = gsd_file.name_id();
assert!(name_id.contains_key("configuration/step"));
assert!(name_id.contains_key("configuration/box"));
assert!(name_id.contains_key("particles/position"));
assert!(!name_id.contains_key("particles/orientation"));

pub fn application(&self) -> &str

The name of the application used to write the file.

Example

use hoomd_gsd::file_layer::GsdFile;
let mut gsd_file = GsdFile::create_new(path, "example", "hoomd", (1, 4))?;

let application = gsd_file.application();
assert_eq!(application, "example");

pub fn schema(&self) -> &str

The schema that describes the expected data chunks.

Example

use hoomd_gsd::file_layer::GsdFile;
let mut gsd_file = GsdFile::create_new(path, "example", "hoomd", (1, 4))?;

let schema = gsd_file.schema();
assert_eq!(schema, "hoomd");

pub fn schema_version(&self) -> (u16, u16)

The schema version (major, minor).

Example

use hoomd_gsd::file_layer::GsdFile;
let mut gsd_file = GsdFile::create_new(path, "example", "hoomd", (1, 4))?;

let schema_version = gsd_file.schema_version();
assert_eq!(schema_version, (1, 4));

pub fn maximum_write_buffer_size(&self) -> usize

The maximum number of bytes to store in the write buffer.

pub fn maximum_write_buffer_size_mut(&mut self) -> &mut usize

Mutable reference to the maximum number of bytes to store in the write buffer.

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 call sync_all manually. It will be called automatically when a GsdFile is dropped. Call sync_all only when you need to read data arrays written in previous frames or when you want to ensure that all data up to a specific frame are present in the file.

Errors

Returns a SyncError 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 mode(&self) -> &Mode

Get the file mode.

Trait Implementations

impl Debug for GsdFile

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

Formats the value using the given formatter.

impl Drop for GsdFile

Automatically synchronize buffered data before closing the file.

GsdFile automatically calls sync_all when dropped and ignores and errors. To check for any potential errors, call sync_all before dropping a GsdFile.

fn drop(&mut self)

Executes the destructor for this type.