gsd.pygsd module¶
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
-
class
gsd.pygsd.
GSDFile
(file)¶ GSD file access interface. Implemented in pure python and accepts any python file-like object.
Parameters: 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');
-
file
¶ File-like object opened (read only).
Type: file-like
-
chunk_exists
(frame, name)¶ Test if a chunk exists.
Parameters: Returns: True if the chunk exists in the file. False if it does not.
Return type: 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;
-
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.
-
read_chunk
(frame, name)¶ Read a data chunk from the file and return it as a numpy array.
Parameters: Returns: - 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.
Return type: numpy.ndarray[type, ndim=?, mode='c']
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.
-