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.

property application#

Name of the generating application.

Type:

str

chunk_exists(frame, name)#

Test if a chunk exists.

Parameters:
  • frame (int) – Index of the frame to check

  • name (str) – Name of the chunk

Returns:

True if the chunk exists in the file. False if it does not.

Return type:

bool

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.

Parameters:

match (str) – Start of the chunk name to match

Returns:

Matching chunk names

Return type:

list[str]

property gsd_version#

GSD file layer version number.

The tuple is in the order (major, minor).

Type:

tuple[int, int]

property mode#

Mode of the open file.

Type:

str

property name#

file.name.

Type:

(str)

property nframes#

Number of frames in the file.

Type:

int

read_chunk(frame, name)#

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

Parameters:
  • frame (int) – Index of the frame to read

  • name (str) – Name of the chunk

Returns:

Data read from file.

Return type:

numpy.ndarray

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#

Name of the data schema.

Type:

str

property schema_version#

Schema version number.

The tuple is in the order (major, minor).

Type:

tuple[int, int]

truncate()#

Not implemented.

write_chunk(name, data)#

Not implemented.