Installation¶

gsd binaries are available 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-forge package¶

gsd is available on conda-forge for the linux-64, linux-aarch64, linux-ppc64le, osx-64, osx-arm64 and win-64 architectures. Execute one of the following command to install gsd:

micromamba install gsd

mamba install gsd

PyPI¶

Use uv or pip to install gsd binaries from PyPI into a virtual environment:

uv pip install gsd

python3 -m pip install gsd

Compile from source¶

To build gsd from source:

Obtain the source:

git clone git@github.com:glotzerlab/gsd.git

Change to the repository directory:
```
cd gsd
```
Install with uv:
```
uv pip install .
```

OR Install prerequisites and Build with CMake for development:

micromamba install cmake cython ninja numpy python pytest

cmake -B build -S . -GNinja
cd build
ninja

To run the tests:

Run tests:
```
python3 -m pytest gsd
```

To build the documentation from source:

Install prerequisites:

micromamba install breathe doxygen sphinx furo ipython sphinx-copybutton

Build the documentation:
```
cd {{ path/to/gsd/repository }}
```

doxygen
sphinx-build -b html doc html

The sections below provide details on each of these steps.

Install prerequisites¶

gsd requires a number of tools and libraries to build.

General requirements:

C compiler (tested with gcc 10-14, clang 10-18, Visual Studio 2019-2022)
Python >= 3.10
numpy >= 1.19.0
Cython >= 0.22

To execute unit tests:

pytest >= 3.9.0

To build the documentation:

breathe
Doxygen
furo
IPython
Sphinx
sphinx-copybutton
an internet connection

Obtain the source¶

Clone using Git:

git clone git@github.com:glotzerlab/gsd.git

Release tarballs are also available on the GitHub release pages.

Install with uv¶

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

cd {{ path/to/gsd/repository }}

uv pip install .

Build with CMake for development¶

GSD also provides CMake scripts for development and testing that build a functional Python module in the build directory. First, configure the build with cmake:

cd {{ path/to/gsd/repository }}

cmake -B build -S . -GNinja

Then, build the code:

cd build
ninja

Execute ninja to rebuild after you modify the code. ninja will automatically reconfigure as needed.

Tip

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

Warning

When using a conda-forge environment for development, make sure that the environment does not contain clang, gcc, or any other compiler or linker. These interfere with the native compilers on your system and will result in compiler errors when building, linker errors when running, or segmentation faults.

Run tests¶

Use pytest to execute unit tests:

python3 -m pytest gsd

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

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

Build the documentation¶

Run Doxygen to generate the C documentation:

cd {{ path/to/gsd/repository }}

doxygen

Run Sphinx to build the HTML documentation:

PYTHONPATH=build sphinx-build -b html doc html

Open the file html/index.html in your web browser to view the documentation.

Tip

Add the sphinx options -a -n -W -T --keep-going to produce docs with consistent links in the side panel and provide more useful error messages.

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¶

The Python modules gsd/pygsd.py and gsd/hoomd.py implement a pure Python reader for gsd and HOOMD files.