See the full GSD documentation at


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.

  • 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.

HOOMD examples

Create a hoomd gsd file.

>>> s = gsd.hoomd.Snapshot()
>>> s.particles.N = 4
>>> s.particles.types = ['A', 'B']
>>> s.particles.typeid = [0,0,1,1]
>>> s.particles.position = [[0,0,0],[1,1,1], [-1,-1,-1], [1,-1,-1]]
>>> = [3, 3, 3, 0, 0, 0]
>>> traj ='test.gsd', mode='wb')
>>> traj.append(s)

Append frames to a gsd file:

>>> 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;
>>> with'test.gsd', 'ab') as t:
...     t.extend( (create_frame(i) for i in range(10)) )
...     print(len(t))

Randomly index frames:

>>> with'test.gsd', 'rb') as t:
...     snap = t[5]
...     print(snap.configuration.step)
...     print(snap.particles.N)
...     print(snap.particles.position)
[[ 0.56993282  0.42243481  0.5502916 ]
 [ 0.36892486  0.38167036  0.27310368]
 [ 0.04739023  0.13603486  0.196539  ]
 [ 0.120232    0.91591144  0.99463677]
 [ 0.79806316  0.16991436  0.15228257]
 [ 0.13724308  0.14253527  0.02505   ]
 [ 0.39287439  0.82519054  0.01613089]
 [ 0.23150323  0.95167434  0.7715748 ]]

Slice frames:

>>> with'test.gsd', 'rb') as t:
...     for s in t[5:-2]:
...         print(s.configuration.step, end=' ')
4 5 6 7

File layer examples

with'file.gsd', mode='wb') as f:
    f.write_chunk(name='position', data=numpy.array([[1,2,3],[4,5,6]], dtype=numpy.float32));
    f.write_chunk(name='angle', data=numpy.array([0, 1], dtype=numpy.float32));
    f.write_chunk(name='box', data=numpy.array([10, 10, 10], dtype=numpy.float32));
with'file.gsd', mode='rb') as f:
    for i in range(1,f.nframes):
        position = f.read_chunk(frame=i, name='position');

Installing the python module

Official GSD binaries are available through a number of methods. Alternately, you can compile from source (see below).


GSD is available on pypi. Install it with pip:

pip install gsd

Conda (conda-forge)

Official binaries of GSD are available via conda through the glotzer and conda-forge channels. To install GSD, first download and install miniconda following conda's instructions. Then add the channel and install GSD from conda-forge:

$ conda config --add channels conda-forge
$ conda install gsd

Or to install from the glotzer channel:

$ conda config --add channels glotzer
$ conda install gsd

Compiling the python module


* 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)
* cmake (for development builds)
* Python >= 3.2 (to execute unit tests)

Get the source

Download source releases directly from the web:

$ curl -O

Or, clone the latest development version using git:

$ git clone

Install with setuptools

Use python to install the python module with setuptools. For example, to install into your home directory, execute:

$ python install --user

When using conda, you can install into your conda site-packages with:

$ python install --user

Uninstall using pip:

$ pip uninstall gsd

Build with cmake for development

You can assemble a functional python module in the build directory using cmake:

$ mkdir build
$ cd build
$ cmake ../
$ make

Then add the directory to your PYTHONPATH temporarily for testing.

export PYTHONPATH=/path/to/build:$PYTHONPATH

Run unit tests

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.

$ nosetests

Build Documentation

Documentation builds with sphinx and requires that the python module is on the python path. ipython is also required to build the documentation. To build the documentation:

$ 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/ and gsd/ Together, these implement a pure-python reader for GSD and hoomd files - no C compiler required.

Change log