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:
-
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)
- traj (
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.
-
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.
- trajectory (
-
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.
- trajectory (
-
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.
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:
-
-
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:
-
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: - trajectory (
-
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)
- trajectory (
-