INSTALLING.rst

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

OR

mamba install gsd

PyPI

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

uv pip install gsd

OR

python3 -m pip install gsd

Compile from source

To build gsd from source:

1. Obtain the source:

   git clone [email protected]:glotzerlab/gsd.git

2. Change to the repository directory:

   cd gsd
   

3. Install with uv:

   uv pip install .
   

4. 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:

1. Run tests:

   python3 -m pytest gsd
   

To build the documentation from source:

1. Install prerequisites:

   micromamba install breathe doxygen sphinx furo ipython sphinx-copybutton
   

2. 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 >= 2.0.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 [email protected]:glotzerlab/gsd.git

Release tarballs are also available on the GitHub release pages.

.. seealso::

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

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