Readers & Writers

This is the API documentation for all readers and writers provided by garnett.

Automatic reader/writer

garnett.read(filename_or_fileobj, template=None, fmt=None)[source]

This function reads a file and returns a trajectory, autodetecting the file format unless fmt is specified.

Parameters:
  • filename_or_fileobj (string or file object) – Filename to read.
  • template (string) – Optional template for the GSDHOOMDFileReader.
  • fmt (string) – File format, one of ‘gsd’, ‘gtar’, ‘pos’, ‘cif’, ‘dcd’, ‘xml’ (default: None, autodetected from filename_or_fileobj)
Returns:

Trajectory read from the file.

Return type:

Trajectory

garnett.write(traj, filename_or_fileobj, fmt=None)[source]

This function writes a trajectory to a file, autodetecting the file format unless fmt is specified.

Parameters:
  • traj (Trajectory) – Trajectory to write.
  • filename_or_fileobj (string or file object) – Filename to write.
  • fmt (string) – File format, one of ‘gsd’, ‘gtar’, ‘pos’, ‘cif’ (default: None, autodetected from filename_or_fileobj)

General API

Readers and writers are defined in the reader and writer modules. All readers and writers work with file-like objects and use the following API:

reader = garnett.reader.Reader()
writer = garnett.writer.Writer()

with open('trajectory_file') as infile:
    traj = reader.read(infile)

    # Dump to a string:
    pos = writer.dump(traj)

    # Write to standard out:
    writer.write(traj)

    # or directly to a file:
    with open('dump', 'w') as outfile:
        writer.write(traj, outfile)

Important

Some readers and writers work with binary files, which means that when opening those files for reading or writing you need to use the rb or wb mode. This applies for example to DCD-files:

dcd_reader = garnett.reader.DCDFileReader()
with open('dump.dcd', 'rb') as dcdfile:
    dcd_traj = dcd_reader.read(dcdfile)

File Formats

This table outlines the supported properties of each format reader and writer.

Format Position Box Orientation Velocity Shape Additional Properties (See below)
POS RW RW RW N/A+ RW N/A
GSD RW RW RW RW RW RW
GTAR RW RW RW RW RW RW
CIF RW RW N/A N/A N/A N/A
DCD R R R R N/A N/A
XML R R R R N/A N/A
  • RW indicates garnett can read and write on this format.
  • R indicates garnett can only read.
  • N/A indicates the format does not support storing this property.
  • Additional Properties:
    • Mass
    • Charge
    • Diameter
    • Angular momentum
    • Moment of inertia
    • Image

The following collection of readers and writers is ordered by different file formats.

POS Files

The POS format is a non-standardized text-based format which is human-readable, but very inefficient for storing of trajectory data. The format is used as primary input/output format for the injavis visualization tool. HOOMD-blue provides a writer for this format, which is classified as deprecated since version 2.0.

class garnett.reader.PosFileReader(precision=None)[source]

POS-file reader for the Glotzer Group, University of Michigan.

Authors: Carl Simon Adorf, Richmond Newmann

reader = PosFileReader()
with open('a_posfile.pos', 'r', encoding='utf-8') as posfile:
    return reader.read(posfile)
Parameters:precision (int) – The number of digits to round floating-point values to.
read(stream, default_type='A')[source]

Read text stream and return a trajectory instance.

Parameters:
  • stream (A file-like textstream.) – The stream, which contains the posfile.
  • default_type (str) – The default particle type for posfile dialects without type definition.
class garnett.writer.PosFileWriter(rotate=False)[source]

POS-file writer for the Glotzer Group, University of Michigan.

Author: Carl Simon Adorf

writer = PosFileWriter()
with open('a_posfile.pos', 'w', encoding='utf-8') as posfile:
    writer.write(trajectory, posfile)
Parameters:rotate (bool) – Rotate the system into the view rotation instead of adding it to the metadata with the ‘rotation’ keyword.
dump(trajectory)[source]

Serialize trajectory into pos-format.

Parameters:trajectory (Trajectory) – The trajectory to serialize.
Return type:str
write(trajectory, file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)[source]

Serialize a trajectory into pos-format and write it to file.

Parameters:
  • trajectory (Trajectory) – The trajectory to serialize
  • file – A file-like object.

GSD (HOOMD-blue schema)

The GSD format is a highly efficient and versatile binary format for storing and reading trajectory data. HOOMD-blue provides a writer for this format.

See also: http://gsd.readthedocs.io

class garnett.reader.GSDHOOMDFileReader[source]

HOOMD-blue GSD file reader for the Glotzer Group, University of Michigan.

Author: Carl Simon Adorf

This class provides a wrapper for the trajectory reader implementation as part of the gsd package.

A gsd file may not contain all shape information. To provide additional information it is possible to pass a frame object, whose properties are copied into each frame of the gsd trajectory.

The example is given for a HOOMD-blue XML frame:

xml_reader = HOOMDXMLFileReader()
gsd_reader = GSDHOOMDFileReader()

with open('init.xml') as xmlfile:
    with open('dump.gsd', 'rb') as gsdfile:
        xml_frame = xml_reader.read(xmlfile)[0]
        traj = gsd_reader.read(gsdfile, xml_frame)
About the read_gsd_shape_data parameter: This parameter was removed. By default,
shape information is read from a passed frame object, if one provided. Otherwise, shape information is read from the gsd file.
read(stream, frame=None)[source]

Read binary stream and return a trajectory instance.

Parameters:
  • stream (A file-like binary stream) – The stream, which contains the gsd-file.
  • frame (trajectory.Frame) – A frame containing shape information that is not encoded in the GSD-format. By default, shape information is read from the passed frame object, if one provided. Otherwise, shape information is read from the gsd file.
class garnett.writer.GSDHOOMDFileWriter[source]

GSD file writer for the Glotzer Group, University of Michigan.

Author: Vyas Ramasubramani Author: Bradley Dice

writer = GSDHOOMDFileWriter()
with open('file.gsd', 'wb') as gsdfile:
    writer.write(trajectory, gsdfile)

# For appending to the file
with open('file.gsd', 'ab') as gsdfile:
    writer.write(trajectory, gsdfile)
write(trajectory, stream)[source]

Serialize a trajectory into gsd-format and write it to a file.

Parameters:
  • trajectory (Trajectory) – The trajectory to serialize.
  • stream (File stream) – The file to write to.

GeTAR

The GeTAR format is a highly versatile, binary format for storing and reading trajectory data. HOOMD-blue provides a writer for this format.

See also: https://libgetar.readthedocs.io

class garnett.reader.GetarFileReader[source]

getar-file reader for the Glotzer Group, University of Michigan.

Authors: Matthew Spellings, Carl Simon Adorf

Read GEneric Trajectory ARchive files, a binary format designed for efficient, extensible storage of trajectory data.

This class provides a wrapper for the gtar library.

reader = GetarFileReader()
with open('trajectory.tar', 'rb') as file:
    traj = reader.read(file)
read(stream, default_type='A', default_box=None)[source]

Read binary stream and return a trajectory instance.

Parameters:
  • stream (A file-like binary stream.) – The stream, which contains the GeTarFile.
  • default_type (str) – The default particle type for posfile dialects without type definition.
  • default_box (numpy.ndarray) – The default_box value is used if no box is specified in the libgetar file. Defaults to [Lx=Ly=Lz=1.0].

HOOMD-blue XML

The HOOMD-blue XML format contains topological information about one individual frame. HOOMD-blue provides a writer for this format, which is classified as deprecated since version 2.0.

class garnett.reader.HOOMDXMLFileReader[source]

Reader for XML-files containing HOOMD-blue snapshots.

read(stream)[source]

Read text stream and return a trajectory instance.

Parameters:stream (A file-like textstream.) – The stream, which contains the xmlfile.

DCD

The DCD format is a very storage efficient binary format for storing simple trajectory data. The format contains only data about particle positions and the simulation boxes of individual frames.

HOOMD-blue provides a writer for this format with a special dialect for 2-dimensional systems. The garnett DCD reader is capable of reading both the standard and the 2-dim. dialect.

Note

Unlike most other readers, the DCDFileReader will return an instance of DCDTrajectory, which is optimized for the DCD-format. This special trajectory class provides the xyz() method for accessing xyz-coordinates with minimal overhead.

class garnett.reader.DCDFileReader[source]

DCD-file reader for the Glotzer Group, University of Michigan.

Author: Carl Simon Adorf

A dcd file consists only of positions. To provide additional information it is possible to provide a frame object, whose properties are copied into each frame of the dcd trajectory.

The example is given for a HOOMD-blue xml frame:

xml_reader = HOOMDXMLFileReader()
dcd_reader = DCDFileReader()

with open('init.xml') as xmlfile:
    with open('dump.dcd', 'rb') as dcdfile:
        xml_frame = xml_reader.read(xmlfile)[0]
        traj = reader.read(dcdfile, xml_frame)

Note

If the topology frame is 2-dimensional, the dcd trajectory positions are interpreted such that the first two values contain the xy-coordinates, the third value is an euler angle.

The euler angle is converted to a quaternion and stored in the orientation of the frame.

To retrieve the euler angles, simply convert the quaternion:

alpha = 2 * np.arccos(traj[0].orientations.T[0])
read(stream, frame=None, default_type=None)

Read binary stream and return a trajectory instance.

Parameters:
  • stream (A file-like binary stream) – The stream, which contains the dcd-file.
  • frame (trajectory.Frame) – A frame containing topological information that cannot be encoded in the dcd-format.
  • default_type (str) – A type name to be used when no first frame is provided, defaults to ‘A’.
Returns:

A trajectory instance.

Return type:

DCDTrajectory

class garnett.dcdfilereader.DCDTrajectory(frames=None, dtype=None)[source]
arrays_loaded()[source]

Returns true if arrays are loaded into memory.

See also: load_arrays()

load_arrays()[source]

Load all available trajectory properties into memory.

After calling this function, trajectory properties can be accessed as coherent NumPy arrays:

traj.load_arrays()
traj.N             # M -- frame sizes
traj.position      # MxNx3
traj.orientation   # MxNx4
traj.typeid        # MxN

Note

It is not necessary to call this function again when accessing sub trajectories:

traj.load_arrays()
sub_traj = traj[m:n]
sub_traj.position

However, it may be more efficient to call load_arrays() only for the sub trajectory if other data is not of interest:

sub_traj = traj[m:n]
sub_traj.load_arrays()
sub_traj.position
xyz(xyz=None)[source]

Return the xyz coordinates of the dcd file.

Use this function to access xyz-coordinates with minimal overhead and maximal performance.

You can provide a reference to an existing numpy.ndarray with shape (Mx3xN), where M is the length of the trajectory and N is the number of particles. Please note that the array needs to be of data type float32 and in-memory contiguous.

Parameters:xyz (numpy.ndarray) – A numpy array of shape (Mx3xN).
Returns:A view or a copy of the xyz-array of shape (MxNx3).
Return type:numpy.ndarray
class garnett.reader.PyDCDFileReader[source]

Pure-python DCD-file reader for the Glotzer Group.

This class is a pure python dcd-reader implementation which should only be used when the more efficient cythonized dcd-reader is not available or you want to work with non-standard file-like objects.

See also

The API is identical to: DCDFileReader

CIF

The Crystallographic Information File (CIF) format is a text-based format primarily used in the context of crystallography.

class garnett.reader.CifFileReader(precision=None, tolerance=0.001)[source]

CIF-file reader for the Glotzer Group, University of Michigan.

Requires the PyCifRW package to parse CIF files.

Authors: Matthew Spellings

reader = CifFileReader()
with open('a_ciffile.cif', 'r') as ciffile:
    traj = reader.read(ciffile)
Parameters:
  • precision (int) – The number of digits to round floating-point values to.
  • tolerance (float) – Floating-point tolerance (in fractional coordinates) of particle identity as symmetry operations are applied.
read(stream, default_type='A')[source]

Read text stream and return a trajectory instance.

Parameters:
  • stream (A file-like textstream.) – The stream, which contains the ciffile.
  • default_type (str) – The default particle type for ciffile dialects without type definition.
class garnett.writer.CifFileWriter[source]

cif-file writer for the Glotzer Group, University of Michigan.

Authors: Julia Dshemuchadse, Carl Simon Adorf

writer = CifFileWriter()

# write to screen:
write.write(trajectory)

# write to file:
with open('a_ciffile.pos', 'w') as ciffile:
    writer.write(trajectory, ciffile)
dump(trajectory, data='simulation', occupancy=None, fractional=False, raw=False)[source]

Serialize trajectory into cif-format.

Parameters:
  • trajectory (Trajectory) – The trajectory to serialize.
  • data (str) – Identifier which be will written to the file, signifying the origin of the data.
  • occupancy (numpy.array) – The default occupancy of individual particles.
Return type:

str

write(trajectory, file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, data='simulation', occupancy=None, fractional=False, raw=False)[source]

Serialize a trajectory into cif-format and write it to file.

Parameters:
  • trajectory (Trajectory) – The trajectory to serialize
  • file (A file-like object.) – The file to write the trajectory to.
  • data (str) – Identifier which be will written to the file, signifying the origin of the data.
  • occupancy (int) – The default occupancy of individual particles.
  • fractional (bool) – Whether or not the input coordinates are fractional
  • raw (bool) – Whether or not to write the raw CIF coordinates (with no transformations)