The file layer python module :pygsd.fl
allows direct low level access to read and write GSD files of any schema. The HOOMD reader (:pygsd.hoomd
) provides higher level access to HOOMD schema files, see hoomd-examples
.
View the page source to find unformatted example code.
python
- f = gsd.fl.open(name="file.gsd",
mode='wb', application="My application", schema="My Schema", schema_version=[1,0])
f.close()
Warning
Opening a gsd file with a 'w' or 'x' mode overwrites any existing file with the given name.
python
- f = gsd.fl.open(name="file.gsd",
mode='wb', application="My application", schema="My Schema", schema_version=[1,0]);
f.write_chunk(name='chunk1', data=numpy.array([1,2,3,4], dtype=numpy.float32)) f.write_chunk(name='chunk2', data=numpy.array([[5,6],[7,8]], dtype=numpy.float32)) f.end_frame() f.write_chunk(name='chunk1', data=numpy.array([9,10,11,12], dtype=numpy.float32)) f.write_chunk(name='chunk2', data=numpy.array([[13,14],[15,16]], dtype=numpy.float32)) f.end_frame() f.close()
Call :pygsd.fl.open
to access gsd files on disk. Add any number of named data chunks to each frame in the file with :pygsd.fl.GSDFile.write_chunk()
. The data must be a 1 or 2 dimensional numpy array of a simple numeric type (or a data type that will automatically convert when passed to numpy.array(data)
. Call :pygsd.fl.GSDFile.end_frame()
to end the frame and start the next one.
Note
While supported, implicit conversion to numpy arrays creates a copy of the data in memory and adds conversion overhead.
Warning
Make sure to call end_frame()
before closing the file, or the last frame will be lost.
python
- f = gsd.fl.open(name="file.gsd",
mode='rb', application="My application", schema="My Schema", schema_version=[1,0])
f.read_chunk(frame=0, name='chunk1') f.read_chunk(frame=1, name='chunk2') f.close()
:pygsd.fl.GSDFile.read_chunk
reads the named chunk at the given frame index in the file and returns it as a numpy array.
python
- f = gsd.fl.open(name="file.gsd",
mode='rb', application="My application", schema="My Schema", schema_version=[1,0])
f.chunk_exists(frame=0, name='chunk1') f.chunk_exists(frame=1, name='chunk2') f.chunk_exists(frame=2, name='chunk1') f.close()
:pygsd.fl.GSDFile.chunk_exists
tests to see if a chunk by the given name exists in the file at the given frame.
python
- f = gsd.fl.open(name="file.gsd",
mode='rb', application="My application", schema="My Schema", schema_version=[1,0])
f.find_matching_chunk_names('') f.find_matching_chunk_names('chunk') f.find_matching_chunk_names('chunk1') f.find_matching_chunk_names('other')
:pygsd.fl.GSDFile.find_matching_chunk_names
finds all chunk names present in a GSD file that start with the given string.
python
- f = gsd.fl.open(name="file.gsd",
mode='rb', application="My application", schema="My Schema", schema_version=[1,0])
- if f.chunk_exists(frame=0, name='chunk1'):
data = f.read_chunk(frame=0, name='chunk1')
data # Fails because the file is open read only @okexcept f.write_chunk(name='error', data=numpy.array([1])) f.close()
Writes fail when a file is opened in a read only mode.
python
- f = gsd.fl.open(name="file.gsd",
mode='rb', application="My application", schema="My Schema", schema_version=[1,0])
f.name f.mode f.gsd_version f.application f.schema f.schema_version f.nframes f.close()
File metadata are available as properties.
python
- f = gsd.fl.open(name="file.gsd",
mode='wb+', application="My application", schema="My Schema", schema_version=[1,0])
f.write_chunk(name='double', data=numpy.array([1,2,3,4], dtype=numpy.float64)); f.end_frame() f.nframes f.read_chunk(frame=0, name='double')
Open a file in read/write mode to allow both reading and writing.
python
- f = gsd.fl.open(name="file.gsd",
mode='ab', application="My application", schema="My Schema", schema_version=[1,0])
f.write_chunk(name='int', data=numpy.array([10,20], dtype=numpy.int16)); f.end_frame() f.nframes # Reads fail in append mode @okexcept f.read_chunk(frame=2, name='double') f.close()
Open a file in append mode to write additional chunks to an existing file, but prevent reading.
python
- with gsd.fl.open(name="file.gsd",
mode='rb', application="My application", schema="My Schema", schema_version=[1,0]) as f:
data = f.read_chunk(frame=0, name='double');
data
:pygsd.fl.GSDFile
works as a context manager for guaranteed file closure and cleanup when exceptions occur.
python
- f = gsd.fl.open(name="file.gsd",
mode='wb+', application="My application", schema="My Schema", schema_version=[1,0])
f.mode s = "This is a string" b = numpy.array([s], dtype=numpy.dtype((bytes, len(s)+1))) b = b.view(dtype=numpy.int8) b f.write_chunk(name='string', data=b) f.end_frame() r = f.read_chunk(frame=0, name='string') r r = r.view(dtype=numpy.dtype((bytes, r.shape[0]))); r[0].decode('UTF-8') f.close()
To store a string in a gsd file, convert it to a numpy array of bytes and store that data in the file. Decode the byte sequence to get back a string.
python
- f = gsd.fl.open(name="file.gsd",
mode='ab', application="My application", schema="My Schema", schema_version=[1,0])
f.nframes f.schema, f.schema_version, f.application f.truncate() f.nframes f.schema, f.schema_version, f.application
Truncating a gsd file removes all data chunks from it, but retains the same schema, schema version, and application name. The file is not closed during this process. This is useful when writing restart files on a Lustre file system when file open operations need to be kept to a minimum.