OpenImpala
OpenImpala is a high-performance framework for computing effective transport properties — tortuosity, effective diffusivity tensors, and effective conductivity — directly from 3D voxel images of porous media (X-ray CT, FIB-SEM, synthetic microstructures). It solves the governing PDEs on the Cartesian voxel grid using finite differences, bypassing mesh generation, and scales across MPI ranks and CUDA GPUs via AMReX and HYPRE.
Outputs parameterise continuum-scale models such as PyBaMM.
📖 Documentation: https://base-laboratory.github.io/OpenImpala/
📓 Tutorials: tutorials/ (runnable on Google Colab)
Quick example
import numpy as np
import openimpala as oi
image = np.zeros((64, 64, 64), dtype=np.int32)
image[:, :, 16:48] = 1 # solid slab through the middle
with oi.Session():
vf = oi.volume_fraction(image, phase=0)
tau = oi.tortuosity(image, phase=0, direction="z", solver="mlmg")
print(f"Volume fraction: {vf.value:.4f}")
print(f"Tortuosity: {tau.value:.4f}")
Install
Python (recommended)
pip install openimpala # CPU + optional CuPy GPU acceleration
pip install openimpala-cuda # compiled HYPRE/AMReX CUDA wheel (Linux x86_64)
OpenImpala uses MPI for distributed parallelism — install an MPI runtime
(libopenmpi-dev, openmpi, brew install open-mpi, or
conda install -c conda-forge openmpi) before pip install. See
Getting Started
for full details.
Container (HPC)
Pre-built Apptainer/Singularity images are attached to each GitHub Release:
apptainer exec -B "$(pwd):/data" openimpala-vX.Y.Z.sif \
/usr/local/bin/Diffusion /data/inputs
For batch SLURM scripts, see HPC Usage.
Build from source
See CONTRIBUTING.md for the native and containerised developer build, code style, and test workflow.
Features
- Steady-state diffusion / conduction on segmented 3D voxel images
- Tortuosity factor, full 3×3 effective diffusivity tensor, multi-phase transport
- Microstructural metrics: volume fraction, percolation, particle size, specific surface area
- TIFF / HDF5 / RAW / DAT image input; JSON output compatible with BPX / BattINFO
- Solvers: HYPRE (PCG, FlexGMRES, BiCGSTAB; SMG / PFMG preconditioners) and AMReX MLMG (matrix-free, GPU-native)
- MPI + OpenMP + CUDA parallelism — scales from a laptop to multi-node HPC
Citation
If you use OpenImpala in published work, please cite:
@article{LeHoux2021OpenImpala,
title = {{OpenImpala}: {OPEN} source {IMage} based {PArallisable} {Linear} {Algebra} solver},
author = {Le Houx, James and Kramer, Denis},
year = {2021},
journal = {SoftwareX},
volume = {15},
pages = {100729},
doi = {10.1016/j.softx.2021.100729},
}
If you use the homogenisation-based effective diffusivity workflow, additionally cite Le Houx et al., Transport in Porous Media 150, 71–88 (2023), doi:10.1007/s11242-023-01993-7.
License
BSD 3-Clause. See LICENSE.
Acknowledgements
This work was financially supported by the EPSRC Centre for Doctoral Training in Energy Storage and its Applications [EP/R021295/1]; the Ada Lovelace Centre (STFC) project CANVAS-NXtomo; the EPSRC prosperity partnership with Imperial College, INFUSE [EP/V038044/1]; the Rutherford Appleton Laboratory; the Faraday Institution Emerging Leader Fellowship [FIELF001]; and Research England's Expanding Excellence in England grant at the University of Greenwich via the M34Impact programme. We acknowledge the use of the IRIDIS HPC facility, Diamond Light Source's Wilson cluster, STFC SCARF, and the University of Greenwich M34Impact cluster, and thank the developers of AMReX, HYPRE, libtiff, and HDF5.
Contact
Issues and feature requests: https://github.com/BASE-Laboratory/OpenImpala/issues. Questions: GitHub Discussions.
1 maintainer
Release files for openimpala 4.4.9
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| openimpala-4.4.9-cp312-cp312-manylinux_2_28_x86_64.whl | CPython 3.12 | CPython 3.12 | Linux glibc 2.28+ x86-64 | Details |
| openimpala-4.4.9-cp311-cp311-manylinux_2_28_x86_64.whl | CPython 3.11 | CPython 3.11 | Linux glibc 2.28+ x86-64 | Details |
| openimpala-4.4.9-cp310-cp310-manylinux_2_28_x86_64.whl | CPython 3.10 | CPython 3.10 | Linux glibc 2.28+ x86-64 | Details |
| openimpala-4.4.9-cp39-cp39-manylinux_2_28_x86_64.whl | CPython 3.9 | CPython 3.9 | Linux glibc 2.28+ x86-64 | Details |
Total release size: 27.5 MB
Release files / openimpala-4.4.9-cp312-cp312-manylinux_2_28_x86_64.whl
| Download URL | openimpala-4.4.9-cp312-cp312-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 6.9 MB |
| Tags | CPython 3.12 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
8aab3faae9467a3ba55b57c5d7aff7069538dbe6fb9f2d7c93c537e77d8c459f
|
|
BLAKE2b-256 checksum How to use checksums |
ec5e5d8f7ed910fe2d98aec65cf9a2ded33702c9f9f105894a837b27e1ff2026
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 13, 2026.
Transparency logRelease files / openimpala-4.4.9-cp311-cp311-manylinux_2_28_x86_64.whl
| Download URL | openimpala-4.4.9-cp311-cp311-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 6.9 MB |
| Tags | CPython 3.11 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
66d6b61400cd71254bd24855f4e4a5d71efe482103ac8b429bf83d0f59b2159f
|
|
BLAKE2b-256 checksum How to use checksums |
2de9d3f25ccae3b374ada3b937ff66e2a5ee09070c419f58f68777eddf0829ff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 13, 2026.
Transparency logRelease files / openimpala-4.4.9-cp310-cp310-manylinux_2_28_x86_64.whl
| Download URL | openimpala-4.4.9-cp310-cp310-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 6.9 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
4f5402bd9901b7926fcba0dea0c30dbcf78f69461eab79d3305273f97e7815a0
|
|
BLAKE2b-256 checksum How to use checksums |
1465adc2c12252ee802ea9e7742b8ac6e8b4e4d0af6227d86a868d51ca80edae
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 13, 2026.
Transparency logRelease files / openimpala-4.4.9-cp39-cp39-manylinux_2_28_x86_64.whl
| Download URL | openimpala-4.4.9-cp39-cp39-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 6.9 MB |
| Tags | CPython 3.9 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
17ae72eee643debbc69e095146b81634214c5492f45ca875a6fbacb71cdb38f3
|
|
BLAKE2b-256 checksum How to use checksums |
05c613bea39d4927a488584a206c0b0f94dab7052bf2333455cac48553de8dcf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 13, 2026.
Transparency log
