# Pigreads

[![Pipeline Status][pipeline-badge]][pipeline-link]
[![Coverage Report][coverage-badge]][coverage-link]
[![Documentation Status][rtd-badge]][rtd-link]

[![Latest Release][release-badge]][release-link]
[![PyPI platforms][pypi-platforms]][pypi-link]
[![PyPI version][pypi-version]][pypi-link]

<!-- SPHINX-START -->

Pigreads is a streamlined, open-source Python module for efficient numerical
solution of reaction–diffusion systems on graphics cards (GPUs), with CPU
fallback. It exposes a minimal, concise, and
[NumPy](https://numpy.org)-compatible API that allows users to define and run
simulations while offloading the costly computations to accelerators via OpenCL
kernels executed through [PyOpenCL](https://pypi.org/project/pyopencl/). The
module supports 0D–3D uniform Cartesian grids, no-flux and periodic boundary
conditions, anisotropic and spatially varying diffusion and reaction, and
localised source terms. Pigreads includes several built-in models, including
electrophysiology examples, while also allowing users to supply custom reaction
terms, and is fully tested, documented, and distributed with examples and
tutorials.

## Peer-reviewed article

We have published a peer-reviewed article in Computer Physics Communications
introducing Pigreads. It can be found at
[DOI 10.1016/j.cpc.2026.110088](https://doi.org/10.1016/j.cpc.2026.110088) or
[here](https://pigreads.gitlab.io/paper/kabus2026pigreads.pdf). You may cite our
article when using Pigreads:

> Kabus, D., Dierckx, H., & De Coster, T. (2026). Pigreads: The
> Python-integrated GPU-enabled reaction-diffusion solver using OpenCL for
> cardiac electrophysiology and other applications. _Computer Physics
> Communications_, 110088.

```bibtex
@article{kabus2026pigreads,
  doi={10.1016/j.cpc.2026.110088},
  author={Desmond {Kabus} and Hans {Dierckx} and Tim {De Coster}},
  title={{Pigreads}: The {Python}-integrated {GPU}-enabled reaction-diffusion solver
    using {OpenCL} for cardiac electrophysiology and other applications},
  journal={Computer Physics Communications},
  pages={110088},
  year={2026},
  issn={0010-4655}
}
```

## Getting started

### Requirements

Pigreads uses OpenCL for calculations on the graphics cards. OpenCL is usually
included in the drivers for your graphics card.

The following pages may help installing and accessing OpenCL:

- [ArchWiki: OpenCL on Arch Linux][guide-arch]
- [OpenCL-Guide: OpenCL on Ubuntu Linux][guide-ubuntu]
- [OpenCL-Guide: OpenCL on Windows][guide-windows]
- [Documentation of PyOpenCL][pyopencl].

You can use [`clinfo`][clinfo] to verify you have an OpenCL platform installed.

If instead of the GPU, you want to use CPUs, you can [install PoCL][pocl] as an
OpenCL platform to compute on the main processors.

### Installation

Install this Python package in the standard way using `pip`, for instance from
[PyPI][pypi-link] or from a local copy of this repository, see [the Python
documentation for details][py-install]. To also install all optional
dependencies, such as for the command line interface (CLI), run:

```
$ pip install pigreads[all] # from PyPI
$ pip install .[all] # from source
```

Note: If installing from source, you need to run `python prepare.py` first to
render the code templates for the models that are defined as YAML in the
`models` folder, and other preparation.

### Usage

Simulations can be performed via calls to the Python module (API) or using the
CLI. See the [documentation for annotated examples][rtd-link], or the examples
directory in the [Pigreads repository][examples].

<!-- prettier-ignore-start -->
[repo]:           https://gitlab.com/pigreads/pigreads
[examples]:       https://gitlab.com/pigreads/pigreads/-/tree/main/examples
[coverage-badge]: https://gitlab.com/pigreads/pigreads/badges/main/coverage.svg
[coverage-link]:  https://gitlab.com/pigreads/pigreads/-/commits/main
[pipeline-badge]: https://gitlab.com/pigreads/pigreads/badges/main/pipeline.svg
[pipeline-link]:  https://gitlab.com/pigreads/pigreads/-/pipelines
[pypi-link]:      https://pypi.org/project/pigreads/
[pypi-platforms]: https://img.shields.io/pypi/pyversions/pigreads
[pypi-version]:   https://img.shields.io/pypi/v/pigreads
[release-badge]:  https://gitlab.com/pigreads/pigreads/-/badges/release.svg
[release-link]:   https://gitlab.com/pigreads/pigreads/-/releases
[rtd-badge]:      https://readthedocs.org/projects/pigreads/badge/?version=latest
[rtd-link]:       https://pigreads.readthedocs.io/en/latest/?badge=latest
[python]:         https://www.python.org/
[py-install]:     https://packaging.python.org/en/latest/tutorials/installing-packages/
[guide-arch]:     https://wiki.archlinux.org/title/OpenCL
[guide-ubuntu]:   https://github.com/KhronosGroup/OpenCL-Guide/blob/main/chapters/getting_started_linux.md
[guide-windows]:  https://github.com/KhronosGroup/OpenCL-Guide/blob/main/chapters/getting_started_windows.md
[clinfo]:         https://github.com/Oblomov/clinfo
[pocl]:           https://portablecl.org/docs/html/install.html
[pyopencl]:       https://pypi.org/project/pyopencl/
<!-- prettier-ignore-end -->
