gsd.pygsd

GSD reader written in pure python

pygsd.py is a pure python implementation of a GSD reader. If your analysis tool is written in python and you want to embed a GSD reader without requiring C code compilation, then use the following python files from the gsd/ directory to make a pure python reader. It is not as high performance as the C reader, but is reasonable for files up to a few thousand frames.

  • gsd/

    • __init__.py
    • pygsd.py
    • hoomd.py

The reader reads from file-like python objects, which may be useful for reading from in memory buffers, in-database grid files, etc… For regular files on the filesystem, and for writing gsd files, use gsd.fl.

The GSDFile in this module can be used with the gsd.hoomd.HOOMDTrajectory hoomd reader:

>>> with gsd.pygsd.GSDFile('test.gsd', 'rb') as f:
...     t = gsd.hoomd.HOOMDTrajectory(f);
...     pos = t[0].particles.position

Module Contents

__version__ = 1.6.1
logger
gsd_header
gsd_header_struct
gsd_index_entry
gsd_index_entry_struct
gsd_namelist_entry
gsd_namelist_entry_struct
gsd_type_mapping
class GSDFile(file)

Bases:object

GSDFile(file)

GSD file access interface. Implemented in pure python and accepts any python file-like object.

Args:

file: File-like object to read.

GSDFile implements an object oriented class interface to the GSD file layer. Use it to open an existing file in a read-only mode. For read-write access to files, use the full featured C implementation in gsd.fl. Otherwise, this implementation has all the same methods and the two classes can be used interchangeably.

Examples:

Open a file in read-only mode:

f = GSDFile(open('file.gsd', mode='rb'));
if f.chunk_exists(frame=0, name='chunk'):
    data = f.read_chunk(frame=0, name='chunk');

Access file metadata:

f = GSDFile(open('file.gsd', mode='rb'));
print(f.name, f.mode, f.gsd_version);
print(f.application, f.schema, f.schema_version);
print(f.nframes);

Use as a context manager:

with GSDFile(open('file.gsd', mode='rb')) as f:
    data = f.read_chunk(frame=0, name='chunk');

Attributes:

file: File-like object opened (read only). name (str): file.name (read only). mode (str): Mode of the open file (read only). gsd_version (tuple[int]): GSD file layer version number [major, minor] (read only). application (str): Name of the generating application (read only). schema (str): Name of the data schema (read only). schema_version (tuple[int]): Schema version number [major, minor] (read only). nframes (int): Number of frames (read only).
name
file
mode
gsd_version
schema_version
schema
application
nframes
close(self)

close()

Close the file.

Once closed, any other operation on the file object will result in a ValueError. close() may be called more than once. The file is automatically closed when garbage collected or when the context manager exits.

truncate(self)
end_frame(self)
write_chunk(self, name, data)
_find_chunk(self, frame, name)
chunk_exists(self, frame, name)

chunk_exists(frame, name)

Test if a chunk exists.

Args:
frame (int): Index of the frame to check name (str): Name of the chunk
Returns:
bool: True if the chunk exists in the file. False if it does not.

Example:

Handle non-existent chunks:

with GSDFile(open('file.gsd', mode='rb')) as f:
    if f.chunk_exists(frame=0, name='chunk'):
        return f.read_chunk(frame=0, name='chunk');
    else:
        return None;
read_chunk(self, frame, name)

read_chunk(frame, name)

Read a data chunk from the file and return it as a numpy array.

Args:
frame (int): Index of the frame to read name (str): Name of the chunk
Returns:
numpy.ndarray[type, ndim=?, mode='c']: Data read from file.
type is determined by the chunk metadata. If the data is NxM in the file and M > 1, return a 2D array. If the data is Nx1, return a 1D array.

Examples:

Read a 1D array:

with GSDFile(name=filename, mode='rb') as f:
    data = f.read_chunk(frame=0, name='chunk1d');
    # data.shape == [N]

Read a 2D array:

with GSDFile(name=filename, mode='rb') as f:
    data = f.read_chunk(frame=0, name='chunk2d');
    # data.shape == [N,M]

Read multiple frames:

with GSDFile(name=filename, mode='rb') as f:
    data0 = f.read_chunk(frame=0, name='chunk');
    data1 = f.read_chunk(frame=1, name='chunk');
    data2 = f.read_chunk(frame=2, name='chunk');
    data3 = f.read_chunk(frame=3, name='chunk');

Tip

Each call to invokes a disk read and allocation of a new numpy array for storage. To avoid overhead, don’t call read_chunk() on the same chunk repeatedly. Cache the arrays instead.

__enter__(self)
__exit__(self, exc_type, exc_value, traceback)