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 sphinx sphinx_rtd_theme ipython
    
  2. Build the documentation:

    $ 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 7-11, clang 6-13, visual studio 2019-2022)

  • Python >= 3.6

  • numpy >= 1.9.3

  • Cython >= 0.22

To build the documentation:

  • Sphinx

  • IPython

  • 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 Sphinx to build the 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.