Pigreads¶
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-compatible API that allows users to define and run simulations while offloading the costly computations to accelerators via OpenCL kernels executed through 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 or here. 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.
@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:
You can use clinfo to verify you have an OpenCL platform installed.
If instead of the GPU, you want to use CPUs, you can install 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 or from a local copy of this repository, see the Python
documentation for details. 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, or the examples directory in the Pigreads repository.
Showcase¶
Pigreads can be used to solve reaction-diffusion systems in up to three dimensions. A. Cardiac action potentials for the model by Courtemanche, Ramirez, and Nattel (1998) in the 0D case, i.e., without diffusion. B. Three travelling pulses in a cable (1D) followed by a fourth blocked pulse in the same model. C. A spiral wave in a circular 2D domain in the model by Marcotte and Grigoriev (2017) that was stimulated by increasing the main variable on a line between high and low values of the recovery variable. D. Pseudo-electrograms for a travelling wave in a 2D piece of tissue with periodic boundary conditions on the top and bottom and different cell types for mid-wall, endo-, and epi-cardial cells following the model by ten Tusscher and Panfilov (2006) with 15% fibrosis, stimulated three pulses at the locations and times labelled S0–2. E. Three-dimensional cardiac electrophysiology simulations in human bi-ventricular (Hren 1996, Kelderman et al. 2009, Hren 1998) and human bi-atrial (De Coster et al. 2018, Dössel et al. 2011) geometries with faster diffusion along muscle fibres. A single pulse is sent out from the apex or the sino-atrial node, respectively. We use the models by ten Tusscher and Panfilov (2006) for the ventricles and by Courtemanche, Ramirez, and Nattel (1998) for the atria.
Scripts to generate the figures presented in this documentation are available in a separate Git repository.