Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# 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 pure Python reader `pygsd.py`.

## Binaries

### Conda package

gsd is available on conda-forge on the linux-64, linux-aarch64, linux-ppc64le, osx-64, osx-arm64 and win-64 platforms. To install, download and install miniforge or miniconda Then install gsd from the conda-forge channel:

    $ conda install -c conda-forge gsd

### Singularity / Docker images

See the glotzerlab-software documentation for instructions to install and use the containers.

### PyPI

Use pip to install gsd binaries:

    $ python3 -m pip install gsd

## Compile from source

To build the gsd Python package from source:

1. Install prerequisites:

       $ <package-manager> install cmake cython git numpy python pytest

2. Obtain the source:

       $ git clone https://github.com/glotzerlab/gsd

3. Install with setuptools:

       $ python3 -m pip install -e gsd

   OR Build with CMake for development:

       $ cmake -B build/gsd -S gsd
       $ cmake --build build/gsd

To run the tests (optional):

1. Run tests:

       $ pytest --pyargs gsd

To build the documentation from source (optional):

1. Install prerequisites:

       $ <package-manager> install breathe doxygen sphinx furo ipython

2. Build the documentation:

       $ cd gsd && doxygen && cd ..
       $ sphinx-build -b html gsd/doc build/gsd-documentation

The sections below provide details on each of these steps.

### Install prerequisites

gsd requires a number of tools and libraries to build.

Note

This documentation is generic. Replace `<package-manager>` with your package or module manager. You may need to adjust package names and/or install additional packages, such as `-dev` packages that provide headers needed to build gsd.

Tip

Create or use an existing virtual environment, one place where you can install dependencies and gsd:

    $ python3 -m venv gsd-venv

You will need to activate your environment before installing or configuring gsd:

    $ source gsd-venv/bin/activate

General requirements:

- C compiler (tested with gcc 9-12, clang 10-14, visual studio 2019-2022)

- Python >= 3.8

- numpy >= 1.17.3

- Cython >= 0.22

To build the documentation:

- breathe

- Doxygen

- Sphinx

- IPython

- furo

- an internet connection

To execute unit tests:

- pytest >= 3.9.0

### Obtain the source

Clone using Git:

    $ git clone https://github.com/glotzerlab/gsd

Release tarballs are also available on the GitHub release pages.

See also

See the git book to learn how to work with Git repositories.

### Install with setuptools

Use pip to install the Python module into your virtual environment:

    $ python3 -m pip install -e gsd

### Build with CMake for development

In addition to the setuptools build system. GSD also provides a CMake configuration for development and testing. You can assemble a functional Python module in the given build directory. First, configure the build with `cmake`.

    $ cmake -B build/gsd -S gsd

Then, build the code:

    $ cmake --build build/gsd

When modifying code, you only need to repeat the build step to update your build - it will automatically reconfigure as needed.

Tip

Use Ninja to perform incremental builds in less time:

    $ cmake -B build/gsd -S gsd -GNinja

Tip

Place your build directory in `/tmp` or `/scratch` for faster builds. CMake performs out-of-source builds, so the build directory can be anywhere on the filesystem.

Tip

Pass the following options to `cmake` to optimize the build for your processor: `-DCMAKE_CXX_FLAGS=-march=native -DCMAKE_C_FLAGS=-march=native`.

Important

When using a virtual environment, activate the environment and set the cmake prefix path before running CMake: `$ export CMAKE_PREFIX_PATH=<path-to-environment>`.

### Run tests

Use pytest to execute unit tests:

    $ python3 -m pytest --pyargs gsd

Add the `--validate` option to include longer-running validation tests:

    $ python3 -m pytest --pyargs gsd -p gsd.pytest_plugin_validate --validate

Tip

When using CMake builds, change to the build directory before running `pytest`:

    $ cd build/gsd

### Build the documentation

Run Doxygen to generate the C documentation:

    $ cd gsd
    $ doxygen
    $ cd ..

Run Sphinx to build the HTML documentation:

    $ sphinx-build -b html gsd/doc build/gsd-documentation

Open the file `build/gsd-documentation/index.html` in your web browser to view the documentation.

Tip

When iteratively modifying the documentation, the sphinx options `-a -n -W -T --keep-going` are helpful to produce docs with consistent links in the side panel and to see more useful error messages:

    $ sphinx-build -a -n -W -T --keep-going -b html gsd/doc build/gsd-documentation

Tip

When using CMake builds, set PYTHONPATH to the build directory before running `sphinx-build`:

    $ PYTHONPATH=build/gsd sphinx-build -b html gsd/doc build/gsd-documentation

## Embedding GSD in your project

### Using the C library

gsd is implemented in a single C file. Copy `gsd/gsd.h` and `gsd/gsd.c` into your project.

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