New Open-Source Tool Generates Porous Geometries with Exact Porosity for Lattice Boltzmann Simulations

Pore-scale simulation has become a mainstay of research into how fluids, solutes and heat move through porous materials, from filtration media and underground reservoirs to carbon dioxide storage and geotechnical seepage. The lattice Boltzmann method (LBM) is especially well suited to such problems, because its bounce-back boundary condition handles arbitrary voxel geometries without a meshing step, and mature open-source solvers such as PALABOS offer scalable parallel execution that individual research groups can access. Yet a persistent bottleneck sits at the front of this pipeline: obtaining a suitable geometry in the first place. A newly released open-source package called PorousGen, described in the journal SoftwareX, aims to close that gap by generating porous-media geometries that can be fed directly into an LBM solver with no manual post-processing, while guaranteeing an exact target porosity for several of its architectures.

The problem PorousGen addresses is familiar to anyone who runs pore-scale simulations. When tomographic images of a real specimen are unavailable, or when a parametric study demands controlled, repeatable variation of porosity, grain size or microstructure type, synthetic geometry generation is required. Existing tools cover parts of this territory: PoreSpy provides a rich collection of stochastic generators and image-analysis routines, OpenPNM handles network-scale modelling, and packages such as PuMA compute effective properties from digitized or generated microstructures. But these tools largely presuppose that a representative geometry already exists. According to the authors, Pooriya Ghorbani and Majid Siavashi, no established tool produces output that a lattice Boltzmann solver can consume directly without manual assembly of a voxel file, grid configuration, a surface mesh for visual inspection, and a record of the generator parameters needed for exact reproduction.

That manual assembly is not merely inconvenient. The authors describe the transcription step between geometry generation and solver configuration as a well-known source of silent numerical errors in simulation studies. PorousGen eliminates it with a single export function that produces a complete four-file simulation bundle: a plain-text voxel file in the flag convention expected by PALABOS-type readers, a binary STL surface mesh generated by marching cubes for three-dimensional grids, a PNG preview image, and an info report documenting grid dimensions, measured porosity, voxel size, the full generator parameter set, and XML configuration blocks that can be inserted verbatim into a PALABOS parameter file. The package contains no compiled components; its runtime dependencies are limited to NumPy, SciPy, Matplotlib and scikit-image, the last used exclusively for surface extraction.

The second, more fundamental contribution concerns porosity control. Porosity is arguably the most influential single descriptor of a porous medium, yet many synthetic generators treat it as an output rather than a controllable input: wall thicknesses, threshold values or particle counts are adjusted iteratively until the measured porosity is close enough to the target. For parametric studies in which porosity is the independent variable, that approximation introduces residual scatter that can confound the very trend under investigation. PorousGen makes exact porosity a first-class feature. For four of its eight architectures — the closed-cell foam, the open-cell foam, the gyroid and the Gaussian-random-field blobs — the generated voxel array contains precisely the requested fluid fraction, to within a single voxel.

Achieving that guarantee requires two distinct resolution mechanisms, selected according to the geometric character of the underlying field. For architectures whose solid phase is defined by a discrete geometric skeleton — the Voronoi cell faces of the closed-cell foam and the Voronoi edge graph of the open-cell foam — simple quantile thresholding is unreliable, because the distance-to-skeleton field contains large plateaus of identical values; a quantile threshold falling within a plateau can overshoot the target porosity by several percentage points. PorousGen instead ranks all voxels in ascending order of their distance to the skeleton and marks exactly the number corresponding to the requested solid fraction as solid, breaking ties with an infinitesimal random perturbation. This rule is exact by construction in both directions: when the requested solid fraction is smaller than the raw skeleton volume the skeleton is eroded, and when it is larger the skeleton is dilated.

For the two architectures defined by smooth, continuously valued scalar fields — the gyroid implicit surface, a triply periodic minimal surface widely used in additively manufactured heat exchangers and lattice structures, and the Gaussian-random-field blobs, the established stochastic reconstruction model for consolidated soils and sandstones — no such plateaus exist. There, exact porosity is obtained by thresholding the field directly at the quantile satisfying the target: a closed-form quantile for the blob field, and a 64-iteration bisection search on the threshold for the gyroid, whose cumulative distribution has no closed form. The remaining four architectures — granular packings built by random sequential addition of non-overlapping spheres or discs, fibrous media of randomly oriented finite cylinders, fractured rock represented by randomly oriented planar fractures of prescribed aperture, and overlapping-sphere ‘Swiss-cheese’ media — control porosity indirectly through counts, radii or apertures, a limitation the authors state plainly.

Beyond generation, PorousGen includes a structural-metrics module that interrogates whether a generated medium is physically meaningful, since exact global porosity alone does not rule out isolated pores, floating solid or under-resolved struts. The module reports fluid and solid cluster connectivity, percolating porosity along the flow axis, inlet-accessible porosity, the isolated-pore fraction, the fraction of solid outside the largest connected cluster, the Euler characteristic of the fluid phase, specific surface area by two independent estimators, and pore-size and strut-thickness distributions from the largest-inscribed-sphere method, including the fraction of each phase thinner than three voxels — a warning sign of under-resolution. Each metric is validated against geometries with a known analytical answer, such as a sphere’s surface area, a slab’s pore width, a torus’s topology and an enclosed, non-percolating cavity.

The software is distributed with an automated test suite of 203 pytest tests that continuous integration runs on every change across Linux, Windows and macOS with Python 3.9 and 3.12. The suite includes an exact-porosity campaign checking the integer number of fluid voxels — rather than a rounded porosity — for 1,080 geometries covering all porosity-controlled generators, both boundary modes, odd and even grids, and porosity targets from 0.02 to 0.9873. Boundary-convention tests compare periodic distance computations against brute-force minimum-image references, structural metrics are validated against analytical answers, export tests include a round trip of the voxel file and a watertightness check of the surface mesh, and a regression test compares 18 committed reference geometries against their exact fluid-voxel counts and SHA-256 hashes. Every generator accepts a user-specified random seed, so any geometry in a published study can be regenerated by a reader from the info file alone.

To demonstrate that the exported bundle is genuinely solver-ready, the authors fed PorousGen-generated granular and fibrous geometries, exported unmodified, into a coupled four-lattice LBM solver for non-isothermal adsorption: a D3Q19 flow lattice and three D3Q7 advection–diffusion lattices for concentration, adsorbed-phase loading and temperature, coupled through Arrhenius-type kinetics and Langmuir adsorption–desorption. The simulations, run with PALABOS v2.3.0 on a single laptop, show a concentration and adsorption front advancing from the inlet into the initially unloaded bed, a fully percolating and tortuous velocity pattern with no isolated or leaking cells, and localised solid-phase heating from the exothermic adsorption kinetics. The granular and fibrous architectures were deliberately chosen because their porosity emerges from particle placement rather than being exactly prescribed, making them a stress test of solver compatibility independent of the porosity-resolution mechanism. Three-dimensional counterparts on three exact-porosity architectures are reported in the paper’s supplementary material.

Performance figures reported in the paper show three tiers at 512-cubed voxels on the reference machine: granular, gyroid and fractured generation completes in under five seconds using 1.2 to 3.3 gigabytes of memory; fibrous and overlapping spheres take 16 to 18 seconds; and the cellular walls and open-cell foam generators are the most expensive at 111 to 129 seconds and 6.4 gigabytes, sharing a common chunked nearest-seed-query bottleneck. Peak memory scales close to the expected eight-fold increase per resolution doubling for six of the eight generators, and the plain-text voxel export remains under 0.6 seconds at every resolution. The package originated within a doctoral research programme on pore-scale, non-isothermal adsorption of methanol on granular activated carbon, and the authors note that a three-phase composite generator for metal-foam adsorbent beds is scheduled as a ninth module in the next minor version. Released under the MIT licence, PorousGen positions itself not as a replacement for PoreSpy or OpenPNM but as a complement focused on the LBM-facing workflow, replacing a manual, error-prone geometry-to-solver pipeline with a single, reproducible step.

Subject of Research: An open-source software package that generates reproducible porous-media geometries with exact porosity control and direct export to lattice Boltzmann solvers.

Article Title: PorousGen: A LBM-ready porous-media geometry generator with exact porosity control and one-call simulation export

Article References: Ghorbani, P., & Siavashi, M. (2026). PorousGen: A LBM-ready porous-media geometry generator with exact porosity control and one-call simulation export. SoftwareX, 36, Article 103165. https://doi.org/10.1016/j.softx.2026.103165

Image Credits: AI Generated

DOI: 10.1016/j.softx.2026.103165

Keywords: porous media, lattice Boltzmann method, porosity, voxel geometry, PALABOS, open-source software, Voronoi tessellation, gyroid, adsorption, pore-scale simulation, reproducibility, numerical simulation