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