Skip to content

Latest commit

 

History

History
275 lines (162 loc) · 6.88 KB

INSTALLING.rst

File metadata and controls

275 lines (162 loc) · 6.88 KB

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.

.. seealso::

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