voids 0.1.8

Scientific Python package for pore network modeling (PNM)

voids

voids is a scientific Python package for pore network modeling (PNM) aimed at research workflows where reproducibility, explicit assumptions, and validation matter. The current project emphasis is a clean canonical network model, interoperability with PoreSpy/OpenPNM-style data, and a validated single-phase workflow that now includes shape-aware conductance, pressure-dependent thermodynamic viscosity, and nonlinear solve options before expanding to more complex multiphase physics.

Goals

The intended direction of voids is:

• provide a rigorous internal representation of pore-throat networks
• preserve sample geometry and provenance information needed for reproducible studies
• support import and normalization of extracted networks from external tools
• expose well-scoped physics modules with diagnostics and regression tests
• build confidence on single-phase transport first, then expand toward richer models

This is a research codebase, not a GUI application or a full image-to-network extraction pipeline. Raw segmentation and extraction are intentionally delegated to upstream tools such as PoreSpy.

Current Scope

The current v0.1.x implementation includes:

• canonical Network, SampleGeometry, and Provenance data structures
• import of PoreSpy/OpenPNM-style dictionaries into the canonical model
• geometry normalization helpers for extracted networks, including optional external-reservoir boundary augmentation for image-extracted flow benchmarks
• static petrophysics:
  • absolute porosity
  • effective porosity
  • connectivity metrics
• single-phase incompressible flow with directional permeability estimation
• data-adaptive auto, OpenPNM size-factor, circular hagen_poiseuille, and shape-aware valvatne_blunt_throat / valvatne_blunt conductance closures
• optional PoreSpy/PREGO hydraulic size factors for pyramids-and-cuboids conduit transport
• pressure-dependent water viscosity via thermo and CoolProp
• Picard and damped-Newton nonlinear solves for variable-viscosity problems
• Krylov linear solvers with optional pyamg preconditioning
• HDF5 serialization
• optional Plotly and PyVista network visualization
• interoperability cross-checks against OpenPNM
• optional direct-image permeability benchmarking against XLB
• synthetic and manufactured examples for regression and tutorials

Important boundaries:

• multiphase flow is not implemented yet
• production image acquisition and fully automated "push-button" extraction pipelines are out of scope
• controlled grayscale preprocessing, segmentation helpers, and snow2-based extraction helpers are available in voids.image
• synthetic mesh/manufactured examples are controlled validation cases, not realistic rock reconstructions

For a more formal statement of scope and assumptions, see spec_v0_1.md.

The rendered documentation is intended to live alongside the repository at https://geomech-project.github.io/voids/.

Installation

Install from PyPI

If you want the published package rather than a local editable checkout:

pip install voids

PyPI package page: https://pypi.org/project/voids/

Recommended: Pixi

This repository is configured for Pixi and exposes four main environments:

• default: core runtime + notebooks + plotting + PyVista + thermodynamic backends
• test: everything in default plus test-only dependencies
• lbm: test environment plus the optional XLB stack
• docs: MkDocs, Material for MkDocs, and mkdocstrings

pixi install
pixi run -e default python -c "import voids; print(voids.__version__)"

Pixi activation also provides project path variables used by notebooks:

• VOIDS_PROJECT_ROOT
• VOIDS_NOTEBOOKS_PATH
• VOIDS_EXAMPLES_PATH
• VOIDS_DATA_PATH

Editable pip install

If you prefer a plain Python environment from the repository checkout:

python -m pip install -e .

Optional extras:

python -m pip install -e ".[dev,viz,test,lbm,docs]"

Assumption to keep in mind: the notebooks are exercised primarily through the Pixi environments, so the most reliable setup is still Pixi.

Quick Start

from voids.examples import make_linear_chain_network
from voids.physics.petrophysics import absolute_porosity
from voids.physics.singlephase import FluidSinglePhase, PressureBC, solve

net = make_linear_chain_network()

result = solve(
    net,
    fluid=FluidSinglePhase(viscosity=1.0),
    bc=PressureBC("inlet_xmin", "outlet_xmax", pin=1.0, pout=0.0),
    axis="x",
)

print("phi_abs =", absolute_porosity(net))
print("Q =", result.total_flow_rate)
print("Kx =", result.permeability["x"])
print("mass_balance_error =", result.mass_balance_error)

There is also a small workflow entry point:

pixi run examples-singlephase

Examples And Notebooks

The repository includes paired notebooks and py:percent scripts under notebooks/:

• 01_mwe_singlephase_porosity_perm
  • minimal single-phase solve, porosity, and permeability
• 02_mwe_openpnm_crosscheck_optional
  • roundtrip and OpenPNM cross-check workflow
• 03_mwe_pyvista_visualization
  • optional PyVista-based network rendering
• 04_mwe_manufactured_porespy_extraction
  • manufactured 3D void image, PoreSpy extraction, import into voids, and serialization
• 05_mwe_cartesian_mesh_network
  • configurable 2D/3D mesh-like pore networks, flow solve, Plotly visualization, and HDF5 export
• 06_mwe_real_porespy_extraction
  • real segmented Ketton image, PoreSpy extraction, voids import, solve, and diagnostics
• 07_mwe_synthetic_vug_case
  • grayscale synthetic vug volume preprocessing, extraction, solve, and pruning comparison
• 08_mwe_image_based_vug_shape_sensitivity
  • controlled baseline vs spherical/ellipsoidal vug study with porosity, Kabs, and network statistics
• 09_mwe_image_based_vug_sensitivity_2d
  • simplified 2D image-based baseline vs circular/elliptical vug study with porosity, Kabs, and K/K0 distributions
• 10_mwe_lattice_based_vug_sensitivity
  • lattice-based stochastic baselines with spherical/ellipsoidal vug insertion, Kabs/porosity sensitivity, and K/K0 distributions
• 11_mwe_lattice_based_vug_sensitivity_2d
  • simplified 2D lattice counterpart with circular/elliptical vugs, multi-baseline sensitivity, and K/K0 frequency distributions
• 12_mwe_synthetic_volume_openpnm_benchmark
  • synthetic spanning volumes, synthetic grayscale segmentation, snow2 extraction, and Kabs cross-checks between voids and OpenPNM
• 13_mwe_synthetic_volume_xlb_benchmark
  • synthetic segmented volumes, direct-image XLB solves, extracted-network voids solves, and Kabs comparison between voxel-scale LBM and PNM
• 14_mwe_shape_factor_conductance_comparison
  • synthetic and extracted-network comparison of circular and shape-aware conductance closures, and permeability sensitivity to shape factors
• 15_mwe_external_pnflow_benchmark
  • committed external pnextract/pnflow reference cases, including explicit same-network parity on the saved CNM and a separate snow2 workflow comparison on the original images
• 16_mwe_viscosity_model_kabs_benchmark
  • benchmark of Kabs using constant viscosity versus pressure-dependent thermodynamic viscosity
• 17_mwe_solver_options_benchmark
  • benchmark of the available linear and nonlinear solver options, including pyamg-preconditioned Krylov solves
• 18_mwe_drp317_berea_raw_porosity_perm
  • DRP-317 Berea validation notebook with snow2, PREGO, and native maximal-ball extraction comparisons
• 19_mwe_drp317_bentheimer_raw_porosity_perm
  • DRP-317 Bentheimer validation notebook with snow2, PREGO, and native maximal-ball extraction comparisons
• 20_mwe_drp317_banderagray_raw_porosity_perm
  • DRP-317 Bandera Gray validation notebook with snow2, PREGO, and native maximal-ball extraction comparisons
• 21_mwe_drp317_banderabrown_raw_porosity_perm
  • DRP-317 Bandera Brown backend-sensitivity notebook against the Table 1 experimental values
• 22_mwe_drp317_bereasistergray_raw_porosity_perm
  • DRP-317 Berea Sister Gray backend-sensitivity notebook against the Table 1 experimental values
• 23_mwe_drp317_bereauppergray_raw_porosity_perm
  • DRP-317 Berea Upper Gray backend-sensitivity notebook against the Table 1 experimental values
• 24_mwe_drp317_buffberea_raw_porosity_perm
  • DRP-317 Buff Berea backend-sensitivity notebook against the Table 1 experimental values
• 25_mwe_drp317_castlegate_raw_porosity_perm
  • DRP-317 Castlegate backend-sensitivity notebook against the Table 1 experimental values
• 26_mwe_drp317_kirby_raw_porosity_perm
  • DRP-317 Kirby backend-sensitivity notebook against the Table 1 experimental values
• 27_mwe_drp317_leopard_raw_porosity_perm
  • DRP-317 Leopard backend-sensitivity notebook against the Table 1 experimental values
• 28_mwe_drp317_parker_raw_porosity_perm
  • DRP-317 Parker backend-sensitivity notebook against the Table 1 experimental values
• 29_mwe_drp443_ifn_raw_porosity_perm
  • DRP-443 IFN fractured-media permeability benchmark against SPE 212849 Table 2
• 30_mwe_drp443_dilatedifn_raw_porosity_perm
  • DRP-443 Dilated IFN fractured-media permeability benchmark against SPE 212849 Table 2
• 31_mwe_drp10_estaillades_raw_porosity_perm
  • DRP-10 Estaillades v2 carbonate benchmark with native maximal-ball and snow2 extraction-backend comparisons
• 32_mwe_prego_blobs_backend_comparison
  • synthetic 256^3 PoreSpy blobs comparison of PoreSpy snow2, PREGO, and native maximal-ball extraction

Example data under examples/data/ includes a deterministic manufactured void image and generated artifacts from the extraction/mesh notebooks.

Verification & Validation

The project documentation now separates two kinds of evidence:

• Verification: benchmarks against software references and controlled numerical workflows
• Validation: benchmarks against experimental data

Software-verification reports live under docs/verification/. Experimental-validation reports for the DRP-317 sandstones live under docs/validation/.

DRP-317 Data Citation

The DRP-317 notebooks and validation reports use the following sources:

• Dataset: Neumann, R., ANDREETA, M., Lucas-Oliveira, E. (2020, October 7). 11 Sandstones: raw, filtered and segmented data [Dataset]. Digital Porous Media Portal. https://www.doi.org/10.17612/f4h1-w124
• Experimental reference paper: Neumann, R. F., Barsi-Andreeta, M., Lucas-Oliveira, E., Barbalho, H., Trevizan, W. A., Bonagamba, T. J., & Steiner, M. B. (2021). High accuracy capillary network representation in digital rock reveals permeability scaling functions. Scientific Reports, 11, 11370. https://doi.org/10.1038/s41598-021-90090-0

The full Table 1 sample references used by the DRP-317 notebooks are committed in examples/data/drp-317/drp317_experimental_references.csv.

Scientific Notes

Several assumptions are deliberate and should be stated explicitly:

• extracted-network predictions depend strongly on upstream segmentation and extraction quality
• imported geometry fields may be incomplete or model-dependent across tools
• single-phase OpenPNM cross-checks compare solver/assembly consistency, not universal physical truth
• throat visualization may use arithmetic averaging of pore scalars when no throat scalar field is provided; that is a visualization choice, not a constitutive model

If any of those assumptions are inappropriate for a study, the corresponding workflow should be tightened before using results quantitatively.

Development

Useful commands:

pixi run test
pixi run test-cov
pixi run lint
pixi run typecheck
pixi run precommit
pixi run notebooks-smoke

Version updates are handled with:

pixi run bump-version <new-version>

Status

voids is still pre-alpha. The codebase is already useful for controlled PNM experiments, solver validation, and interoperability studies, but it should not be described as a complete pore-network simulation platform yet.

AI Usage Statement

Starting with v0.1.7, voids development is aided by AI tools, including Codex and GitHub Copilot. These tools are used to assist with refactoring, fast code changes, code review, and documentation writing.

All scientific choices, implementation decisions, and final content remain under human review and responsibility. This statement is intended as a transparency measure aligned with current scientific-integrity expectations for AI-assisted research and software development.

Institutional Support

voids receives institutional support from the Laboratório Nacional de Computação Científica (LNCC), a research unit of the Ministério da Ciência, Tecnologia e Inovação (MCTI), Brazil.