GSD documentation¶
GSD (General Simulation Data) is a file format specification and a library to read and write it. The package also contains a python module that reads and writes hoomd schema gsd files with an easy to use syntax.
GSD files:
- Efficiently store many frames of data from simulation runs.
- High performance file read and write.
- Support arbitrary chunks of data in each frame (position, orientation, type, etc…).
- Append frames to an existing file with a monotonically increasing frame number.
- Resilient to job kills.
- Variable number of named chunks in each frame.
- Variable size of chunks in each frame.
- Each chunk identifies data type.
- Common use cases: NxM arrays in double, float, int, char types.
- Generic use case: binary blob of N bytes.
- Easy to integrate into other tools with python, or a C API (< 1k lines).
- Fast random access to frames.
Installation¶
GSD binaries are available in the glotzerlab-software
Docker/Singularity images and in packages on
conda-forge and PyPI. You can also compile GSD from source,
embed gsd.c
in your code, or read gsd files with a single file pure python reader pygsd.py
.
Binaries¶
Anaconda package¶
GSD is available on conda-forge. To install, first download and install
miniconda.
Then add the conda-forge
channel and install GSD:
$ conda config --add channels conda-forge
$ conda install gsd
You can update GSD with:
$ conda update gsd
Docker images¶
Pull the glotzerlab-software image to get GSD along with many other tools commonly used in simulation and analysis workflows. See full usage information in the glotzerlab-software documentation.
Singularity:
$ singularity pull shub://glotzerlab/software
Docker:
$ docker pull glotzerlab/software
Compile from source¶
Download source releases directly from the web: https://glotzerlab.engin.umich.edu/Downloads/gsd
$ curl -O https://glotzerlab.engin.umich.edu/Downloads/gsd/gsd-v1.6.1.tar.gz
Or, clone using git:
$ git clone https://github.com/glotzerlab/gsd
Prerequisites¶
- A standards compliant C compiler
- Python >= 2.7
- numpy
Optional dependencies¶
- Cython >= 0.22 (only needed for non-tagged releases)
- nose (unit tests)
- sphinx (documentation)
- ipython (documentation)
- an internet connection (documentation)
- cmake (for development builds)
- Python >= 3.2 (to execute unit tests)
Install with setuptools¶
Use python setup.py
to install the python module with setuptools. For example, to install into
your home directory, execute:
$ python setup.py install --user
When using conda, you can install into your conda site-packages with:
$ python setup.py install
Uninstall using pip:
$ pip uninstall gsd
Build with cmake for development¶
You can assemble a functional python module in the build directory. Configure with cmake and compile with make.
$ mkdir build
$ cd build
$ cmake ../
$ make
Add /path/to/build
to your PYTHONPATH
to test GSD, where /path/to
is the directory containing your
build
directory.
$ export PYTHONPATH=$PYTHONPATH:/path/to/build
Run tests¶
GSD has extensive unit tests to verify correct execution. Tests require python 3.2 or newer to execute.
Run nosetests
in the source directory to execute all unit tests. This requires that the
python module is on the python path.
$ cd /path/to/gsd
$ nosetests
Build user documentation¶
Build the user documentation with sphinx. ipython
is also required to build the documentation, as is an active
internet connection. To build the documentation:
$ cd /path/to/gsd
$ cd doc
$ make html
$ open _build/html/index.html
Using the C library¶
GSD is implemented in less than 1k lines of C code. It doesn’t build a shared library, just
copy gsd/gsd.h
and gsd/gsd.c
into your project and compile it directly in.
Using the pure python reader¶
If you only need to read files, you can skip installing and just extract the module modules gsd/pygsd.py
and
gsd/hoomd.py
. Together, these implement a pure-python reader for GSD and hoomd files - no C compiler required.
Change Log¶
gsd releases follow semantic versioning.
v1.6.1 (2019-03-05)¶
- Documentation updates
v1.6.0 (2018-12-20)¶
- The length of sliced HOOMDTrajectory objects can be determined with the built-in
len()
function.
v1.5.5 (2018-11-28)¶
- Silence numpy deprecation warnings
v1.5.4 (2018-10-04)¶
- Add
pyproject.toml
file that definesnumpy
as a proper build dependency (requires pip >= 10) - Reorganize documentation
v1.5.3 (2018-05-22)¶
- Revert
setup.py
changes in v1.5.2 - these do not work in most circumstances. - Include
sys/stat.h
on all architectures.
v1.5.2 (2018-04-04)¶
- Close file handle on errors in
gsd_open
. - Always close file handle in
gsd_close
. setup.py
now correctly pulls in the numpy dependency.
v1.5.1 (2018-02-26)¶
- Documentation fixes.
v1.5.0 (2018-01-18)¶
- Read and write HPMC shape state data.
v1.4.0 (2017-12-04)¶
- Support reading and writing chunks with 0 length. No schema changes are necessary to support this.
v1.3.0 (2017-11-17)¶
- Document
state
entries in the HOOMD schema. - No changes to the gsd format or reader code in v1.3.
v1.2.0 (2017-02-21)¶
- Add
gsd.hoomd.open()
method which can create and open hoomd gsd files. - Add
gsd.fl.open()
method which can create and open gsd files. - The previous create/class
GSDFile
instantiation is still supported for backward compatibility.
v1.1.0 (2016-10-04)¶
- Add special pairs section pairs/ to HOOMD schema.
- HOOMD schema version is now 1.1.
v1.0.1 (2016-06-15)¶
- Fix compile error on more strict POSIX systems.
v1.0.0 (2016-05-24)¶
Initial release.
User community¶
hoomd-users mailing list¶
GSD primarily exists as a file format for HOOMD-blue, so please use the hoomd-users mailing list. Subscribe for release announcements, to post questions questions for advice on using the software, and discuss potential new features.
Issue tracker¶
File bug reports on GSD’s issue tracker.
Contribute¶
GSD is an open source project. Contributions are accepted via pull request to GSD’s github repository.
Please review CONTRIBUTING.MD
in the repository before starting development. You are encouraged to discuss your proposed contribution with the
GSD user and developer community who can help you design your contribution to fit smoothly into the existing ecosystem.
HOOMD¶
gsd.hoomd
provides high-level access to HOOMD schema GSD files.
View the page source to find unformatted example code that can be easily copied.
Define a snapshot¶
In [1]: s = gsd.hoomd.Snapshot()
In [2]: s.particles.N = 4
In [3]: s.particles.types = ['A', 'B']
In [4]: s.particles.typeid = [0,0,1,1]
In [5]: s.particles.position = [[0,0,0],[1,1,1], [-1,-1,-1], [1,-1,-1]]
In [6]: s.configuration.box = [3, 3, 3, 0, 0, 0]
gsd.hoomd
represents the state of a single frame with an instance of the
class gsd.hoomd.Snapshot
. Instantiate this class to create a system
configuration. All fields default to None
and are only written into the file
if not None
and do not match the data in the first frame, or defaults specified
in the schema.
Create a hoomd gsd file¶
In [7]: gsd.hoomd.open(name='test.gsd', mode='wb')
Out[7]: <gsd.hoomd.HOOMDTrajectory at 0x7f81fdc7fd30>
Append frames to a gsd file¶
In [8]: def create_frame(i):
...: s = gsd.hoomd.Snapshot()
...: s.configuration.step = i
...: s.particles.N = 4+i
...: s.particles.position = numpy.random.random(size=(4+i,3))
...: return s
...:
In [9]: t = gsd.hoomd.open(name='test.gsd', mode='wb')
In [10]: t.extend( (create_frame(i) for i in range(10)) )
In [11]: t.append( create_frame(11) )
# length is 12 because extend added 10, and append added 1
In [12]: len(t)
Out[12]: 11
Use gsd.hoomd.open()
to open a GSD file with the high level interface
gsd.hoomd.HOOMDTrajectory
. It behaves like a python list
, with
gsd.hoomd.HOOMDTrajectory.append()
and gsd.hoomd.HOOMDTrajectory.extend()
methods.
Note
gsd.hoomd.HOOMDTrajectory
currently doesn’t support files opened in
append mode.
Tip
When using gsd.hoomd.HOOMDTrajectory.extend()
, pass in a generator or
generator expression to avoid storing the entire trajectory in RAM before
writing it out.
Randomly index frames¶
In [13]: t = gsd.hoomd.open(name='test.gsd', mode='rb')
In [14]: snap = t[5]
In [15]: snap.configuration.step
Out[15]: 5
In [16]: snap.particles.N