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

PyPI

Use pip to install GSD:

$ pip install gsd

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.5.4.tar.gz

Or, clone using git:

$ git clone https://bitbucket.org/glotzer/gsd.git

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.