Input/Output (IO)#

Directory: libfly/io

The io folder contains a routines for reading and writing simulation snapshots. Everything is contained within the namespace fly::io.

GSD formatted binary IO#

File: libfly/io/gsd.hpp

Binary IO support in the GSD format.

LibFLY supports writing HOOMD-blue’s GSD file format. This file format is widely supported, see the GSD documentation for details. In summary GSD is a binary file with efficient random access to frames. GSD allows all particle properties to vary from one frame to the next.

The GSD format models a hierarchical data structure, the outermost hierarchy is the frame which are index numerically. Each frame may contain one or more data chunks, chunks are indexed by strings and map to values - N by M arrays of data. Values are well defined for all fields at all frames. When a data chunk is present in frame i, it defines the values for the frame. When it is not present, the data chunk of the same name at frame 0 defines the values for frame i. When N is zero, an index entry may be written for a data chunk with no actual data written to the file for that chunk.

enum fly::io::Flags#

Flags for file permissions.

Values:

enumerator read_only#: Open with read only permissions.

enumerator read_write#: Open with read and write permissions.

enumerator create#: Open with read and write permissions, overwrite existing files.

class BinaryFile#

A handle to a GSD formatted binary file.

Public Functions

explicit BinaryFile(std::string_view fname, Flags flag = read_only)#

Open a GSD file.

Parameters:

fname – The name of the file.
flag – Read/Write/Create permissions.

~BinaryFile() noexcept#

auto clear() -> void#

Clear the current file.

After truncating, a file will have no frames and no data chunks. The file size will be that of a newly created gsd file. The application, schema, and schema version metadata will be kept. Clear does not close and reopen the file, so it is suitable for writing restart files on Lustre file.

template<typename F = noop> inline auto commit(F &&f = {}) -> void#

Commit the current frame to disk.

Example:

#include "libfly/io/gsd.hpp"

#include "libfly/system/property.hpp"
#include "libfly/system/supercell.hpp"

void example_gsd(fly::system::Supercell<fly::system::TypeMap<>, fly::Position> const& cell) {
  //

  fly::io::BinaryFile file("example.gsd", fly::io::create);

  std::uint32_t N = fly::safe_cast<std::uint32_t>(cell.size());  // Hoomd Schema requires uint32

  file.commit([&] {
    file.write(cell.box());        //< Write the box to frame 0.
    file.write(cell.map());        //< Write the map to frame 0.
    file.write("particles/N", N);  //< Write the number of atoms to frame 0.
    file.write(fly::id_, cell);    //< Write the TypeID's of the atoms to frame 0.
    file.write(fly::r_, cell);     //< Write the positions of the atoms to frame 0.
  });

  // Do some data processing and compute new positions for each atom //

  file.commit([&] {
    file.write(fly::r_, cell);  //< Write the positions of the atoms to frame 1.

    // We do not need to duplicate box, map, etc. as they have not changed //
  });
}

Parameters:: f – An optional nullery-invokable to call before committing the writes.

auto n_frames() const noexcept -> std::uint64_t#

Get the number of frames in the GSD file.

Returns:: The number of committed frames in the file.

template<typename T> inline auto read(std::uint64_t i, char const *name) const -> std::enable_if_t<std::is_arithmetic_v<T>, T>#

Read and return a value stored in the file.

Template Parameters:

T – The type of the value to read, must be arithmetic.

Parameters:

i – Index of frame to read from.
name – Name of the chunk to read from (null terminated).

Returns:

The value read from the file.

auto read_box(std::uint64_t i) const -> system::Box #

Read a fly::system::Box stored at frame i and return it.

Parameters:: i – Index of frame to read from.
Returns:: A fly::system::Box read from the ith frame of the file.

template<typename ...U> inline auto read_map(std::uint64_t i) const -> system::TypeMap<U...>#

Read a Box stored at frame i and return it.

Template Parameters:: U – A pack of properties.
Parameters:: i – Index of frame to read from.
Returns:: A fly::system::TypeMap<U…> read from the ith frame of the file.

template<typename T, typename ...U> inline auto read_to(std::uint64_t i, T tag, system::SoA<U...> &out) const -> std::enable_if_t<std::is_arithmetic_v<typename T::scalar_t>>#

Read a property to a fly::system::SoA.

Parameters:

i – Index of frame to read from.
tag – Property of you would like to read.
out – A fly::system::SoA to write the read data to.

Returns:

void.

template<typename T> inline auto write(char const *name, T const &value) -> std::enable_if_t<std::is_arithmetic_v<T>>#

Write a chunk to the current frame.

Template Parameters:

T – The type of value, must be arithmetic.

Parameters:

name – The chunk label (null terminated).
value – Value to write to the chunk.

Returns:

void.

auto write(system::Box const &box) -> void#

Write a fly::system::Box to the current frame.

Warning

This is a lossy operation as GSD schema requires the basis vector must be stored as single precision floats.

Parameters:: box – A box to write to the current frame.

template<typename ...U> inline auto write(system::TypeMap<U...> const &map) -> void#

Write a fly::system::TypeMap to the current frame.

Parameters:: map – A map to write to the current frame.

template<typename T, typename ...U> inline auto write(T tag, system::SoA<U...> const &in) -> std::enable_if_t<std::is_arithmetic_v<typename T::scalar_t>>#

Write a tagged property of a fly::system::SoA to the current frame.

Parameters:

tag – Property of in you would like to write.
in – A fly::system::SoA containing the data to write to the file.

Returns:

void.