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 or require the gsd Python package as a
dependency, 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.
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, and in-database grid files, 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', 'r') 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, the two implementations can be used interchangeably.Examples
Open a file in read-only mode:
f = GSDFile(open('file.gsd', mode='r')) 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='r')) 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='r')) as f: data = f.read_chunk(frame=0, name='chunk')
- __enter__()¶
Implement the context manager protocol.
- __exit__(exc_type, exc_value, traceback)¶
Implement the context manager protocol.
- __getstate__()¶
Implement the pickle protocol.
- __setstate__(state)¶
Implement the pickle protocol.
- 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='r')) 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.
- end_frame()¶
Not implemented.
- property file¶
File-like object opened.
- find_matching_chunk_names(match)¶
Find chunk names in the file that start with the string match.
- property gsd_version¶
GSD file layer version number.
The tuple is in the order (major, minor).
- read_chunk(frame, name)¶
Read a data chunk from the file and return it as a numpy array.
- Parameters:
- Returns:
Data read from file.
- Return type:
Examples
Read a 1D array:
with GSDFile(name=filename, mode='r') as f: data = f.read_chunk(frame=0, name='chunk1d') # data.shape == [N]
Read a 2D array:
with GSDFile(name=filename, mode='r') as f: data = f.read_chunk(frame=0, name='chunk2d') # data.shape == [N,M]
Read multiple frames:
with GSDFile(name=filename, mode='r') 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 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.
- property schema_version¶
Schema version number.
The tuple is in the order (major, minor).
- truncate()¶
Not implemented.
- write_chunk(name, data)¶
Not implemented.