v4.1.0

v4.1.0 — Pure-Python Solver Backend

Highlights

pip install openimpala now just works — no compiled extensions, no CUDA toolkit, no MPI required. GPU acceleration is automatic when CuPy is installed.

New Features

• Pure-Python solver backend (openimpala/_solver.py) — a drop-in replacement for the C++ HYPRE solver using SciPy/CuPy sparse matrices
  • 7-point stencil Laplacian with harmonic-mean face coefficients (same algorithm as C++)
  • Dirichlet BCs at inlet/outlet, zero-flux Neumann on sides
  • Sparse CG solve: CuPy on GPU (auto-detected), SciPy on CPU
  • Flood-fill percolation check via scipy.ndimage.label
  • Validated against all analytical benchmarks (uniform block, series/parallel layers)
• Automatic backend detection — Session() transparently selects C++ or Python backend based on what's available
• Two clean install paths:
  • pip install openimpala — pure Python, works everywhere (Colab, laptops, CI)
  • pip install openimpala-cuda — compiled C++ HYPRE backend for HPC clusters

Bug Fixes

• Fix GPU wheel CUDA device linking — added CUDA_SEPARABLE_COMPILATION and CUDA_RESOLVE_DEVICE_SYMBOLS to resolve __cudaRegisterLinkedBinary_* undefined symbols in _core.so
• Fix MLMG solver — reverted boundary coefficient and PFMG stability changes to match master (multiple commits)
• Fix benchmark scripts — corrected PYTHONPATH and solver list in benchmark runners

Build & Packaging

• CPU wheel workflow replaced with pure-Python python -m build (no CMake, no cibuildwheel)
• New python/pyproject.toml for setuptools-based pure-Python wheel build
• scipy>=1.7 added as a core dependency
• _solver.py added to CMake install list for compiled wheels

Documentation

• All 7 tutorials updated: install cell is now !pip install openimpala [extras]
• notebooks/profiling_and_tuning.ipynb simplified install
• README, getting-started, gpu.md, index.rst updated for new install model
• paper.md updated distribution description

What's Changed

• Fix benchmark script not found inside Apptainer container by @jameslehoux in #235
• Fix benchmark PYTHONPATH: use python/ not cmake_build_bench/ by @jameslehoux in #236
• Fix MLMG boundary coefficients and improve PFMG stability by @jameslehoux in #237
• Fix MLMG tortuosity: pin boundary cells to match HYPRE convention by @jameslehoux in #238
• Fix TortuosityMLMG build: add missing cell_active constant by @jameslehoux in #239
• Fix MLMG: adjust face Dirichlet values to match HYPRE cell-centre BCs by @jameslehoux in #240
• Revert MLMG and PFMG solver changes; fix GPU wheel install by @jameslehoux in #241
• Add CUDA runtime packages and fix GPU wheel build issues by @jameslehoux in #242
• Fix benchmark script path and improve solver configurations by @jameslehoux in #243
• Add pure-Python solver backend for simplified installation by @jameslehoux in #245

Full Changelog: v4.0.6...v4.1.0

v4.0.6

What's Changed

• Refactor GPU support and improve solvers with CUDA enhancements by @jameslehoux in #203
• Claude/fix gpu wheels build yptx m by @jameslehoux in #228
• Fix GPU wheels build, distribute via GitHub Releases, and expand test coverage by @jameslehoux in #233
• Enhance GPU support, improve test coverage, and update installation instructions by @jameslehoux in #234

What's Changed

• Refactor GPU support and improve solvers with CUDA enhancements by @jameslehoux in #203
• Claude/fix gpu wheels build yptx m by @jameslehoux in #228
• Fix GPU wheels build, distribute via GitHub Releases, and expand test coverage by @jameslehoux in #233
• Enhance GPU support, improve test coverage, and update installation instructions by @jameslehoux in #234

Full Changelog: v4.0.4...v4.0.6

v4.0.5

What's Changed

• Enhance version extraction and debug GPU wheel PyPI upload by @jameslehoux in #232

Full Changelog: v4.0.3...v4.0.5

What's Changed

• Enhance version extraction and debug GPU wheel PyPI upload by @jameslehoux in #232

Full Changelog: v4.0.3...v4.0.5

v4.0.4

What's Changed

• Enhance version extraction and debug GPU wheel PyPI upload by @jameslehoux in #232

What's Changed

• Enhance version extraction and debug GPU wheel PyPI upload by @jameslehoux in #232

Full Changelog: v4.0.3...v4.0.4

v4.0.3

What's Changed

• Fix GPU wheel versioning and polish JOSS paper for submission by @jameslehoux in #231

Full Changelog: v4.0.2...v4.0.3

v4.0.2

OpenImpala Release Notes (March 29, 2026)

🚀 CI/CD & DevOps

• Automated Releases: Implemented automated semantic versioning and release drafting (#85).
• Performance Benchmarking: Added performance profiling and a new automated CI benchmark workflow (#31).

📦 Build & Packaging

• GPU Wheels: Fixed issues within the GPU wheels build pipeline (#229).
• PyPI Distribution: Resolved PyPI version rejection errors by configuring setuptools_scm.

📄 Documentation & Publications

• JOSS Paper Preparation: Created the initial draft for the OpenImpala paper, drafted bibliography entries, and revised the software architecture and capabilities sections.

What's Changed

• Implement automated versioning, release drafting, and CI benchmarks by @jameslehoux in #229

Full Changelog: v4.0.1...v4.0.2

v4.0.1

v4.0.1 (2026-03-29)

Patch release fixing CUDA GPU wheel builds and adding project documentation.

Bug Fixes

• Fix CUDA compilation errors in GPU wheels — Resolved 7 NVCC compatibility issues that prevented openimpala-cuda wheels from building:
  • Extracted device lambdas from constructors in TortuosityHypre, EffectiveDiffusivityHypre, and ThroughThicknessProfile (NVCC cannot take address of lambda in constructor)
  • Moved TortuosityMLMG::solve() from protected to public (NVCC requires public access for methods containing device lambdas)
  • Added explicit RunOn::Host template parameters for BaseFab::setVal and BaseFab::copy calls in EffectiveDiffusivityHypre and REVStudy (NVCC template deduction failure)
  • Replaced deleted DeviceScalar move-assignment in FloodFill with htod_memcpy
• Fix PyPI wheel version strings — Added fetch-depth: 0 to checkout steps in both CPU and GPU wheel workflows so setuptools_scm finds release tags and produces clean versions (e.g. 4.0.1 instead of 4.0.1.dev0+gXXX)

Documentation

• New Sphinx documentation site with Furo theme, Breathe (Doxygen C++ bridge), and autodoc
  • Getting started guide, solver comparison, input file reference
  • GPU acceleration and HPC/MPI guides
  • Tutorial index linking all 7 Colab notebooks
  • Python and C++ API reference
• Updated GitHub Actions docs workflow to build combined Sphinx + Doxygen site

What's Changed

• Add Sphinx documentation site with Furo theme, Breathe, and autodoc by @jameslehoux in #204
• Fix setuptools_scm version detection in wheel workflows by @jameslehoux in #227

Full Changelog: v4.0.0...v4.0.1

v4.0.0

v4.0.0

This release introduces GPU acceleration via CUDA, a new matrix-free MLMG solver, a comprehensive architectural refactor of the solver infrastructure, expanded tutorials, and a dedicated openimpala-cuda PyPI package for GPU-enabled workflows.

Highlights

• CUDA GPU Acceleration: OpenImpala now supports GPU-accelerated solves via NVIDIA CUDA. All compute kernels, flood fills, and solver loops have been ported to GPU-compatible AMReX ParallelFor lambdas. HYPRE linear solvers can run on GPU when available (#25).
• New openimpala-cuda PyPI Package: A separate GPU-enabled wheel is now published to PyPI, built via a dedicated CI workflow with CUDA 12.6 and GCC 13.
• New TortuosityMLMG Solver: Added a matrix-free tortuosity solver using AMReX's native MLMG geometric multigrid (#171). Lower memory footprint (~3x less than HYPRE) and faster time-to-solution on shared-memory systems for small/medium grids.
• Microstructural Parameterization Engine: New module for computing specific surface area (SSA) with Cauchy-Crofton correction, through-thickness volume fraction profiles, REV study, particle size distribution, and connected components analysis (#170).

Architecture & Refactoring

• HypreStructSolver Base Class: Extracted shared HYPRE infrastructure (grid setup, stencil, solver dispatch) into a reusable base class, eliminating duplication between TortuosityHypre and EffectiveDiffusivityHypre (#15).
• TortuositySolverBase: New shared base class for all tortuosity solvers providing common infrastructure: phase preconditioning, diffusion coefficient field construction, activity mask generation, flux integration, and tortuosity calculation.
• Fortran-to-C++ Kernel Migration: All Fortran compute kernels (matrix fill, flux calculation, ghost cell fill) migrated to native C++ AMReX GPU-compatible lambdas (#52).
• Decomposed Diffusion.cpp: The monolithic main application file has been refactored into reusable modules: DeffTensor, ConnectedComponents, FloodFill, SpecificSurfaceArea, ThroughThicknessProfile, REVStudy, ParticleSizeDistribution (#51).
• Consolidated SolverType Enums: Eliminated duplicated solver/direction enum definitions into a single shared definition (#50).
• Boundary Condition Abstraction Layer: Configurable transport boundary conditions via a new BC abstraction, replacing hardcoded Dirichlet/Neumann logic (#16).
• Shared FloodFill Utility: Extracted and deduplicated four copies of flood-fill logic into a single GPU-compatible utility.

Solver Improvements

• HYPRE PCG Solver: Added Preconditioned Conjugate Gradient as a solver option for TortuosityHypre, with auto-routing that selects the best solver based on problem characteristics.
• Eliminated Redundant Flood Fills: Solver pipeline now avoids repeated percolation checks where unnecessary.
• EffDiff Matrix Fix: Restored correct Neumann BC diagonal and RHS signs from the original Fortran implementation.
• Scientific V&V Pipeline: Added verification and validation benchmarks with exact analytical solutions (uniform block, series layers, parallel layers).

Tutorials & Documentation

• 7-Part Tutorial Series: Comprehensive Colab-ready Jupyter notebooks covering:
  1. Getting started with PyPI wheels
  2. PyBaMM battery modelling integration
  3. REV analysis and uncertainty quantification
  4. Multi-phase transport
  5. Surrogate modelling
  6. Topology optimisation
  7. HPC scaling
• Profiling & Tuning Notebook: Interactive Colab notebook with dual-axis plots, heatmaps, filled area charts, and radar charts for performance analysis.

CUDA Build Fixes

Resolved a series of NVCC compilation issues for GPU wheel builds:

• Extracted __device__ lambdas from constructors into separate public methods (NVCC restriction).
• Made methods containing __device__ lambdas publicly accessible (NVCC access requirement).
• Fixed BaseFab::setVal and BaseFab::copy template deduction failures by explicitly specifying RunOn::Host.
• Replaced deleted DeviceScalar move-assignment with htod_memcpy.
• Fixed atomicAdd type mismatch (replaced long long with int for GPU atomic counters).

Bug Fixes

• Fixed EffDiff solver NaN divergence and SSA ghost cell assertion failures.
• Fixed SSA face counting at box boundaries.
• Fixed ReduceLongLongSum not found in AMReX ParallelDescriptor.
• Fixed const-correctness error in SpecificSurfaceArea.
• Fixed implicit widening conversion in ConnectedComponents.cpp.
• Fixed MLMG convergence logic and plotfile output types.
• Fixed MPI seed handling, OpenMP parallel regions, and GPU launch guards.
• Numerous clang-format and clang-tidy compliance fixes.

Breaking Changes

• Fortran kernel files (TortuosityHypreFill.F90, EffDiffFillMtx.F90, Tortuosity_filcc.F90, Tortuosity_poisson_3d.F90) have been replaced by C++ equivalents. Custom Fortran modifications will need to be ported.
• TortuosityMLMG::solve() is now public (was protected) for CUDA compatibility.
• Several internal class methods have been moved from private/protected to public for NVCC __device__ lambda compatibility.

Resolved Issues

• #15: Extract HypreStructSolver base class
• #16: Boundary condition abstraction layer
• #25: GPU acceleration for HYPRE solvers
• #50: Consolidate duplicated SolverType enums
• #51: Decompose monolithic Diffusion.cpp
• #52: Migrate Fortran kernels to C++
• #109: Test coverage for PCG, Diffusion.cpp, EffDiff
• #170: Microstructural parameterization engine
• #171: TortuosityMLMG matrix-free solver

What's Changed

• Develop Comprehensive Tutorial Series (Tutorials 01-07) by @jameslehoux in #172
• Add scientific verification & validation (V&V) pipeline by @jameslehoux in #173
• Eliminate redundant flood fills, default to PCG, add auto-routing by @jameslehoux in #174
• Consolidate feature branches: GPU acceleration, MLMG solver, microstructural parameterization, and bug fixes by @jameslehoux in #175
• Fix clang-format violations across 23 source files by @jameslehoux in #176
• Add Fortran to project languages to fix AMReX CMake error by @jameslehoux in #177
• Fix FloodFill build error: DeviceScalar has no setVal member by @jameslehoux in #178
• Fix const-correctness error in SpecificSurfaceArea by @jameslehoux in #179
• Fix ReduceLongLongSum not found in AMReX ParallelDescriptor by @jameslehoux in #180
• Add missing AMReX_SPACE.H include in ResultsJSON.H by @jameslehoux in #181
• Guard AMReX includes in ResultsJSON.H for unit test mode by @jameslehoux in #182
• Fix EffDiff solver NaN divergence and SSA ghost cell assertion by @jameslehoux in #183
• Fix SSA face counting at box boundaries and EffDiff PFMG divergence by @jameslehoux in #184
• Fix EffDiff matrix fill: restore Neumann BC diagonal and RHS signs from Fortran by @jameslehoux in #185
• Add CUDA GPU wheel build workflow and profiling tutorial by @jameslehoux in #187
• Major architecture overhaul: modular solvers, Fortran→C++ migration, GPU acceleration by @jameslehoux in #188
• Fix GPU wheel Docker image and add FloodFill/MLMG solver tests by @jameslehoux in #189
• Fix MLMG test expected tau and apply clang-format by @jameslehoux in #190
• Publish GPU wheel as separate openimpala-cuda PyPI package by @jameslehoux in #191
• Fix CUDA build: compile all sources as CUDA when GPU backend is enabled by @jameslehoux in #192
• Fix CUDA atomicAdd: replace long long with int for GPU atomic counters by @jameslehoux in #193
• Fix CUDA: make methods with device lambdas publicly accessible by @jameslehoux in #194
• Fix CUDA: make remaining private methods with GPU lambdas public by @jameslehoux in #195
• Fix CUDA compilation errors: extract device lambdas from constructors and fix setVal overload by @jameslehoux in #196
• Fix CUDA: make device-lambda methods public and fix setVal template deduction by @jameslehoux in #197
• Fix CUDA: replace deleted DeviceScalar move-assignment with htod_memcpy by @jameslehoux in #198
• Fix CUDA: explicit RunOn::Host for BaseFab::copy template deduction in REVStudy by @jameslehoux in #199
• Fix CUDA: extract device lambda from ThroughThicknessProfile constructor by @jameslehoux in #200
• Fix CUDA: move TortuosityMLMG::solve() from protected to public by @jameslehoux in #201
• Fix clang-format violations in ThroughThicknessProfile and EffectiveDiffusivityHypre by @jameslehoux in https://github.co...

v3.1.0

v3.1.0

This release replaces the pyamrex-based Python to AMReX bridge with a native C++ approach using pybind11's NumPy support. By eliminating the pyamrex dependency, OpenImpala can now be installed directly from PyPI without requiring users to compile from source.

Key Features & Improvements

• Native NumPy Ingestion: Replaced Python-level loops with a C++ factory function (VoxelImage.from_numpy()) that copies NumPy data into an iMultiFab using MFIter. This process is MPI-safe and OpenMP-parallel.
• Memory-Safe Workflows: Introduced the VoxelImage handle to decouple data ingestion from solver execution. Users can now ingest a NumPy array into C++, delete the Python array to free RAM, and then run the solver. This prevents Out-Of-Memory (OOM) errors when processing large datasets in memory-constrained environments.
• Simplified Dependencies: The openimpala wheel is now fully self-contained. The pyamrex dependency has been completely removed from pyproject.toml and the CMake build scripts.

Under the Hood

• Added VoxelImage.H: An opaque C++ container holding Geometry, BoxArray, DistributionMapping, and shared_ptr<iMultiFab>, exposed to Python via pybind11.
• Rewrote module.cpp and session.py to manage the AMReX lifecycle (init_amrex, finalize_amrex, amrex_initialized) natively in C++, removing the need for RTLD_GLOBAL flag manipulation.
• Updated io.cpp: reader.threshold() now directly returns a VoxelImage instead of requiring a pre-built iMultiFab argument.
• Updated cli.py to use the new VoxelImage-based API.
• Updated all test suites to validate the VoxelImage API.

Breaking Changes (Low-Level API)

• The pyamrex library is no longer used or supported.
• Low-level openimpala.core C++ class constructors (e.g., TortuosityHypre, EffectiveDiffusivityHypre, VolumeFraction, PercolationCheck) now accept a VoxelImage handle as their first argument instead of separate Geometry, BoxArray, DistributionMapping, and iMultiFab objects.
• Note: The high-level openimpala.facade API (e.g., oi.tortuosity()) remains unchanged and accepts both numpy.ndarray and VoxelImage inputs.

Resolved Issues

• Closes #165: Refactor Python bindings to remove pyamrex dependency for sub-5-second PyPI installs.

---

Example: Memory-Safe Workflow

For large arrays, memory can be freed before invoking the solver:

import gc
import numpy as np
import openimpala as oi

with oi.Session():
    arr = np.random.choice([0, 1], size=(500, 500, 500), dtype=np.int32)
    
    # Ingest to AMReX memory natively in C++
    dataset = oi.core.VoxelImage.from_numpy(arr)

    # Free Python memory before solving
    del arr
    gc.collect()

    result = oi.tortuosity(dataset, phase=1, direction="z")

## What's Changed
* Tutorials: Added preliminary tutorials  by @jameslehoux in https://github.com/BASE-Laboratory/OpenImpala/pull/164
* Updating working branch with all the commits from master by @jameslehoux in https://github.com/BASE-Laboratory/OpenImpala/pull/166
* Remove pyamrex dependency: native C++ NumPy ingestion via VoxelImage by @jameslehoux in https://github.com/BASE-Laboratory/OpenImpala/pull/167
* Fix clang-format violations in python/bindings/ by @jameslehoux in https://github.com/BASE-Laboratory/OpenImpala/pull/168
* Remove pyamrex dependency: native C++ NumPy ingestion via VoxelImage by @jameslehoux in https://github.com/BASE-Laboratory/OpenImpala/pull/169


**Full Changelog**: https://github.com/BASE-Laboratory/OpenImpala/compare/v3.0.2...v3.1.0

v3.0.2

OpenImpala v3.0.2

OpenImpala v3.0.2 is a minor patch release that streamlines the continuous integration (CI) pipeline for PyPI wheel building, fixing a pathing issue introduced in the previous release.

CI/CD & Build Automation

• Optimized Dependency Caching: Fixed the cibuildwheel dependency cache mechanism by writing the environment tarball directly to the /project/.cibw-deps-cache/ bind-mount, rather than the generic /output directory.
• Pipeline Cleanup: Completely removed the hacky "Rescue Cache Tarball" post-processing step from the GitHub Actions workflow (pypi-wheels.yml), as the cache is now natively preserved across the build matrix without polluting the wheelhouse artifacts.

Full Changelog: v3.0.1...v3.0.2

What's Changed

• Fix cache tarball path: write to /project/ bind-mount, not /output/ by @jameslehoux in #163

Full Changelog: v3.0.1...v3.0.2