Installation
Stable releases can be found on the GitHub Release page and are distributed via the Python Packaging Index, PyPI.
Installation in Python
The gratopy toolbox can easily be installed using pip
pip install gratopy
Alternatively, the release can be downloaded from https://github.com/kbredies/gratopy and installed (after unpacking inside the corresponding folder) via
pip install .
In case installation fails due to the dependency on other packages (see pyproject.toml), it is advised to install the packages by hand before retrying to install gratopy.
In particular, the PyOpenCL package may require some additional effort as it depends on additional drivers and C libraries which might needed to be installed by hand. We refer to the documentation of PyOpenCL.
For development, we recommend installing the project and dependency management tool uv. The local development environment is then setup from within the cloned repository by running
uv sync
Testing correct installation
The release archive (or GitHub repository) includes a tests folder which contains a variety of tests that allow to observe visually and numerically whether gratopy was installed correctly and works as desired.
One can perform these tests by using, for instance, pytest (which, if you are not using uv
for managing a local development environment, needs to be installed by running
pip install pytest). The tests are then executed by running
pytest
or uv run pytest when using uv.
In case multiple OpenCL devices are registered in pyopencl, but the default device is not suitably configured for the tests to work, one might need to choose the context to use manually. This a-priori choice of context to use in pyopencl can be done via
export PYOPENCL_CTX=<context_number>
The context number can, for instance, be determined in Python by
import pyopencl
pyopencl.create_some_context()
following the interactive instructions and observing the console output.
By default, the plots of the tests are disabled, but can be activated, e.g., by
export GRATOPY_TEST_PLOT=true
Moreover, the Getting started guide contains two example code segments which can be executed to quickly check that no errors occur and the output is as desired.
Requirements
The pyproject.toml file specifies Python packages
required for the use of gratopy. Amongst them the most relevant are
Most users aiming for scientific computing applications will probably have these packages already installed as they can be considered standard for numerical computations in Python. Let us again point out that correctly installing PyOpenCL might take some time and effort though, as dependent on the used hardware/GPU, the installation of suitable drivers might be required, see, for instance, https://documen.tician.de/pyopencl/.