Skip to content

Examples and Notebooks

The notebooks/ directory contains paired Jupyter notebooks and py:percent scripts covering the main voids workflows, from the smallest synthetic pore-network example to image-based sensitivity studies, map-based upscaling, direct-image LBM, and OpenPNM benchmarks.

Each notebook is both a tutorial and a regression artifact: if it no longer runs, some documented scientific workflow has drifted.

Running the Notebooks

With Pixi:

pixi run register-kernels   # register Jupyter kernels once
jupyter lab                  # open JupyterLab

The notebooks rely on environment variables set by Pixi activation (VOIDS_PROJECT_ROOT, VOIDS_DATA_PATH, etc.), so they should be launched from within a Pixi-managed shell.

In practice:

  • use default for most notebooks, including OpenPNM, thermodynamic-viscosity, FVM/FEM map-based, and XLB/LBM workflows
  • use test when you want the full test-suite dependency set around the notebook workflow
  • expect the image-based notebooks to be materially heavier than the minimal demos

Choosing A Notebook

Notebook Best use
01_mwe_singlephase_porosity_perm Learn the minimal solver API
02_mwe_openpnm_crosscheck_optional Verify consistency against OpenPNM
03_mwe_pyvista_visualization Inspect networks visually in 3-D
04_mwe_manufactured_porespy_extraction Start from a controlled synthetic void image
05_mwe_cartesian_mesh_network Generate mesh-like reference networks
06_mwe_real_porespy_extraction Run a realistic extracted-image workflow
07_mwe_synthetic_vug_case Study pruning and disconnected clusters
08 to 11 vug notebooks Run controlled geometry-sensitivity studies
12_mwe_synthetic_volume_openpnm_benchmark Benchmark extracted-volume transport against OpenPNM
13_mwe_synthetic_volume_xlb_benchmark Benchmark direct-image LBM transport against extracted-network PNM
14_mwe_shape_factor_conductance_comparison Compare conductance closures and shape-factor sensitivity
15_mwe_external_pnflow_benchmark Compare voids against a committed external reference CNM workflow
16_mwe_viscosity_model_kabs_benchmark Quantify Kabs drift under constant vs thermodynamic viscosity
17_mwe_solver_options_benchmark Compare direct, UMFPACK, Krylov, nonlinear, PyAMG, and FEM linear-backend choices
18_mwe_drp317_berea_raw_porosity_perm Validate the DRP-317 Berea case and compare snow2, PREGO, and native maximal-ball extraction
19_mwe_drp317_bentheimer_raw_porosity_perm Validate the DRP-317 Bentheimer case and compare snow2, PREGO, and native maximal-ball extraction
20_mwe_drp317_banderagray_raw_porosity_perm Validate the DRP-317 Bandera Gray case and compare snow2, PREGO, and native maximal-ball extraction
21_mwe_drp317_banderabrown_raw_porosity_perm Run the DRP-317 Bandera Brown backend-sensitivity workflow against the Table 1 experimental references
22_mwe_drp317_bereasistergray_raw_porosity_perm Run the DRP-317 Berea Sister Gray backend-sensitivity workflow against the Table 1 experimental references
23_mwe_drp317_bereauppergray_raw_porosity_perm Run the DRP-317 Berea Upper Gray backend-sensitivity workflow against the Table 1 experimental references
24_mwe_drp317_buffberea_raw_porosity_perm Run the DRP-317 Buff Berea backend-sensitivity workflow against the Table 1 experimental references
25_mwe_drp317_castlegate_raw_porosity_perm Run the DRP-317 Castlegate backend-sensitivity workflow against the Table 1 experimental references
26_mwe_drp317_kirby_raw_porosity_perm Run the DRP-317 Kirby backend-sensitivity workflow against the Table 1 experimental references
27_mwe_drp317_leopard_raw_porosity_perm Run the DRP-317 Leopard backend-sensitivity workflow against the Table 1 experimental references
28_mwe_drp317_parker_raw_porosity_perm Run the DRP-317 Parker backend-sensitivity workflow against the Table 1 experimental references
29_mwe_drp443_ifn_raw_porosity_perm Benchmark DRP-443 IFN fractured-media permeability against SPE 212849 Table 2 (LBM reference)
30_mwe_drp443_dilatedifn_raw_porosity_perm Benchmark DRP-443 Dilated IFN fractured-media permeability against SPE 212849 Table 2 (LBM reference)
31_mwe_drp10_estaillades_raw_porosity_perm Benchmark DRP-10 Estaillades v2 carbonate permeability and extraction-backend sensitivity against Muljadi et al. (2016) Table 2 (OpenFOAM reference)
32_mwe_prego_blobs_backend_comparison Compare PoreSpy snow2, PREGO, and native maximal-ball extraction on synthetic 256^3 PoreSpy blobs images
33_mwe_synthetic_porosity_maps Build local porosity and Kozeny-Carman permeability maps from synthetic 300^3 PoreSpy blobs images
34_mwe_macro_micro_synthetic_case Explore a controlled macro/micro synthetic porous-media workflow
35_mwe_trabecular_bone_morphometry Compute trabecular-bone segmentation morphometry with explicit phase conventions
36_mwe_trabecular_bone_slice_porosity_permeability_maps Build trabecular-bone slice porosity/permeability maps and structured field exports
37_mwe_trabecular_bone_slice_pore_network Extract a trabecular-bone 3-D ROI pore network and estimate directional permeability
38_mwe_trabecular_bone_map_resistor_upscaling Compare trabecular-bone 3-D ROI map upscaling and direct-image flow references
40_mwe_drp317_berea_roi_pnm_comparison Consolidate DRP-317 Berea 3-D ROI pore-network results for map-solver comparison
41_mwe_drp317_berea_map_resistor_micro_continuum Compare DRP-317 Berea map upscaling and micro-continuum methods on a 3-D ROI
42_mwe_drp317_berea_block3_same_roi_comparison Compare Berea pore-network, TPFA, FEniCSx FEM, and XLB/LBM backends on the same ROI
43_mwe_drp317_bentheimer_block3_same_roi_comparison Compare Bentheimer pore-network, TPFA, FEniCSx FEM, and XLB/LBM backends on the same ROI
44_mwe_drp317_parker_block3_same_roi_comparison Compare Parker pore-network, TPFA, FEniCSx FEM, and XLB/LBM backends on the same ROI
45_mwe_drp317_lbm_sensitivity Document direct-image LBM setup sensitivity and the recommended Stokes-limit preset

Notebook Overview

01 — Minimal Single-Phase Solve

01_mwe_singlephase_porosity_perm

Demonstrates the canonical single-phase workflow on a small synthetic network:

  • build a Network from scratch
  • compute absolute porosity
  • solve incompressible single-phase flow
  • extract directional permeability

This is the best starting point for understanding the core API.

02 — OpenPNM Cross-Check

02_mwe_openpnm_crosscheck_optional

Imports a PoreSpy/OpenPNM-style dictionary into voids, solves the same flow problem with both voids and OpenPNM, and compares permeability estimates. Requires the test Pixi environment (OpenPNM dependency).

03 — PyVista Visualization

03_mwe_pyvista_visualization

Shows optional 3-D network rendering using PyVista:

  • pore coloring by pressure field
  • throat sizing by conductance
  • export to interactive HTML

04 — Manufactured PoreSpy Extraction

04_mwe_manufactured_porespy_extraction

Creates a deterministic 3D void image, extracts a pore network with PoreSpy, imports it into voids, and serializes the result to HDF5.

05 — Cartesian Mesh Network

05_mwe_cartesian_mesh_network

Generates a configurable 2D or 3D mesh-like pore network, solves single-phase flow, creates a Plotly interactive visualization, and exports to HDF5.

06 — Real PoreSpy Extraction (Ketton)

06_mwe_real_porespy_extraction

Applies the full extraction → import → solve → diagnostics pipeline to a real segmented Ketton carbonate image.

07 — Synthetic Vug Case

07_mwe_synthetic_vug_case

Processes a grayscale synthetic vug volume, extracts the network, solves flow, and compares results with and without pruning isolated void clusters.

08 — Image-Based Vug Shape Sensitivity (3D)

08_mwe_image_based_vug_shape_sensitivity

Controlled sensitivity study comparing a baseline network against networks with spherical or ellipsoidal vugs. Reports porosity, absolute permeability Kabs, and network statistics.

09 — Image-Based Vug Sensitivity (2D)

09_mwe_image_based_vug_sensitivity_2d

Simplified 2D counterpart of notebook 08 using circular and elliptical inclusions. Produces porosity vs. Kabs and K/K0 distributions.

10 — Lattice-Based Vug Sensitivity (3D)

10_mwe_lattice_based_vug_sensitivity

Stochastic lattice-based baselines with spherical and ellipsoidal vug insertions. Reports Kabs/porosity sensitivity curves and K/K0 distributions across multiple realisations.

11 — Lattice-Based Vug Sensitivity (2D)

11_mwe_lattice_based_vug_sensitivity_2d

Simplified 2D lattice counterpart with circular and elliptical vugs, multi-baseline sensitivity study, and K/K0 frequency distributions.

12 — Synthetic Volume OpenPNM Benchmark

12_mwe_synthetic_volume_openpnm_benchmark

Builds synthetic spanning volumes, derives a synthetic grayscale segmentation, extracts a network with PoreSpy, and compares resulting Kabs predictions between voids and OpenPNM.

This notebook is the closest thing in the current tree to an end-to-end extraction and solver-comparison benchmark. The corresponding narrative report is documented in Verification & Validation / Verification / OpenPNM Extracted-Network Cross-Check.

13 — Synthetic Volume XLB Benchmark

13_mwe_synthetic_volume_xlb_benchmark

Builds fifteen synthetic segmented spanning volumes, solves them directly with XLB on the binary image, extracts pore networks with snow2, and compares resulting Kabs predictions between XLB and voids.

This is the notebook to use when the scientific question is whether the extracted PNM workflow tracks a higher-fidelity voxel-scale reference closely enough. It also documents the actual LBM formulation used by the current XLB adapter and includes the shared pressure-drop mapping used to couple PNM and XLB, explains why the preferred high-level input is delta_p rather than an absolute pressure level, and includes a full 15-case steady Stokes-limit rerun alongside the standard benchmark-mode comparison. The corresponding narrative report is documented in Verification & Validation / Verification / XLB Direct-Image Permeability Benchmark.

15 — External Reference CNM Benchmark

15_mwe_external_pnflow_benchmark

Loads a committed external reference dataset, reruns the current voids workflow on the same exact saved binary volumes, and compares permeability, porosity, and extracted-network size.

The notebook now separates two questions explicitly:

  • imported-CNM parity, using the saved external network with a benchmark-specific compatibility switch enabled
  • full workflow mismatch, using snow2 on the original saved binary image

This is the notebook to use when the scientific question is whether the current voids image-to-network workflow tracks an independent external PNM workflow closely enough on controlled synthetic cases. The corresponding narrative report is documented in Verification & Validation / Verification / External Reference CNM Benchmark.

16 — Kabs Benchmark: Constant vs Thermodynamic Viscosity

16_mwe_viscosity_model_kabs_benchmark

Benchmarks the apparent permeability estimate obtained with:

  • a constant viscosity equal to the midpoint viscosity over the pressure interval
  • a pressure-dependent thermodynamic viscosity field tabulated from thermo

This notebook is the right entry point when the scientific question is whether pressure-dependent viscosity materially changes Kabs for a fixed network geometry.

17 — Solver Options Benchmark

17_mwe_solver_options_benchmark

Benchmarks the currently available solver options on constant-viscosity, pressure-dependent-viscosity, and FEM map-solver cases. It is the right notebook when the question is numerical rather than physical: which combination of SciPy direct solve, explicit UMFPACK, Krylov method, nonlinear strategy, pyamg preconditioner, or FEM linear backend is most effective for a given regime.

For setup guidance and stable benchmark plots, see Solver Backends And Performance.

18 — DRP-317 Berea Validation

18_mwe_drp317_berea_raw_porosity_perm

Runs the current image-to-network workflow on the DRP-317 Berea sandstone volume and compares porosity and apparent permeability against the experimental values reported for the same rock sample. The notebook now evaluates PoreSpy snow2, PREGO, and native maximal-ball extraction on the same selected ROI.

The corresponding narrative report is documented in Verification & Validation / Validation / DRP-317 Berea Notebook Report.

19 — DRP-317 Bentheimer Validation

19_mwe_drp317_bentheimer_raw_porosity_perm

Runs the same validation workflow for the Bentheimer sandstone case from DRP-317, including ROI diagnostics, extracted-network porosity, directional permeability, extraction-backend sensitivity, and a same-network conductance-model audit for the current PoreSpy/PREGO transport options.

The corresponding narrative report is documented in Verification & Validation / Validation / DRP-317 Bentheimer Notebook Report.

20 — DRP-317 Bandera Gray Validation

20_mwe_drp317_banderagray_raw_porosity_perm

Runs the DRP-317 Bandera Gray validation case. This low-permeability case remains one of the clearest tests of how strongly the pore-network permeability depends on the extraction backend.

The corresponding narrative report is documented in Verification & Validation / Validation / DRP-317 Bandera Gray Notebook Report.

21-28 - Additional DRP-317 Sandstones

21_mwe_drp317_banderabrown_raw_porosity_perm 22_mwe_drp317_bereasistergray_raw_porosity_perm 23_mwe_drp317_bereauppergray_raw_porosity_perm 24_mwe_drp317_buffberea_raw_porosity_perm 25_mwe_drp317_castlegate_raw_porosity_perm 26_mwe_drp317_kirby_raw_porosity_perm 27_mwe_drp317_leopard_raw_porosity_perm 28_mwe_drp317_parker_raw_porosity_perm

These notebooks extend the DRP-317 workflow to the remaining raw binary volumes under examples/data/drp-317/. They keep the same current PNM setup as notebooks 18-20: ROI-based extraction from the full 1000^3 volume, pressure-dependent water viscosity, and directional Kabs comparison against the Table 1 experimental values from the Scientific Reports paper. Each notebook now runs PoreSpy snow2, PREGO, and native maximal-ball extraction so the validation report can separate experimental mismatch from backend sensitivity.

The published-reference values used by all eleven DRP-317 notebooks are committed in examples/data/drp-317/drp317_experimental_references.csv.

29-30 - DRP-443 Fractured IFN Cases

29_mwe_drp443_ifn_raw_porosity_perm 30_mwe_drp443_dilatedifn_raw_porosity_perm

These notebooks benchmark voids on two DRP-443 induced-fracture-network volumes (IFN and DilatedIFN) using published-reference values from SPE 212849 Table 2.

For DRP-443, both workflows are intentionally full-volume only (no ROI selection/subvolume analysis), matching your fractured-media requirement.

The extracted published-reference values used by these notebooks are committed in examples/data/drp-443/drp443_reference_values.csv.

The corresponding report is documented in Verification & Validation / Verification / DRP-443 Fracture-Network Verification Overview.

31 - DRP-10 Estaillades v2

31_mwe_drp10_estaillades_raw_porosity_perm

This notebook benchmarks voids on the DRP-10 Estaillades v2 carbonate volume using porosity and permeability references from Muljadi et al. (2016). It uses the native maximal-ball extractor as the primary workflow, then compares it against PoreSpy snow2 default settings and a compatibility-repaired snow2 configuration. The notebook solves Kx, Ky, and Kz for each backend and exports directional and mean-Kabs CSV summaries.

The corresponding report is documented in Verification & Validation / Verification / DRP-10 Estaillades Verification Overview.

32 - PREGO Synthetic Blob Backend Comparison

32_mwe_prego_blobs_backend_comparison

This notebook compares extraction backends on synthetic PoreSpy blobs volumes at notebook scale. It generates three spanning 256^3 binary blob images, extracts networks from the same images with PoreSpy snow2, prego, and native_maximal_ball, and compares:

  • pore and throat counts,
  • absolute and effective porosity,
  • coordination number,
  • pore and throat diameter distributions,
  • extraction wall time,
  • and single-phase Kx under the same voids pressure-boundary solve.

The PREGO branch uses the algorithmic spherical seed search and level-queue region-growth mode. The faster cubic seed search and stamped-sphere growth path remain available as explicit opt-in settings for runtime-focused comparisons.

The corresponding rendered notebook report is documented in Examples / Notebook Reports / PREGO Synthetic Blob Backend Comparison.

33 - Synthetic Porosity Maps

33_mwe_synthetic_porosity_maps

This notebook demonstrates the continuum-field porosity-map workflow on a synthetic 300^3 PoreSpy blobs volume. It computes:

  • a binary-image porosity map by block-averaging segmented void fraction,
  • a grayscale-image porosity map using two-point calibration and background porosity,
  • associated Kozeny-Carman permeability maps,
  • HDF5 exports for downstream solver-specific conversion,
  • and a comparison figure for the input slices and local porosity fields.

The grayscale image is a toy partial-volume field derived from the same binary image, so the notebook validates workflow mechanics rather than scanner calibration for a real micro-CT dataset. The full calculation and verification logic is documented in Concepts and Background / Porosity Maps.

DRP-317 Data Source

The DRP-317 notebooks use the following sources and should cite them explicitly in downstream work:

  • 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

For convenience, the Table 1 experimental porosity and permeability values used by the notebooks are also committed in examples/data/drp-317/drp317_experimental_references.csv.

Rendered Notebook Reports

The notebooks below are also rendered directly into the docs from their committed .ipynb outputs, without re-executing them during the docs build:

The DRP-317 experimental-comparison notebooks are documented separately under Verification & Validation / Validation because those pages are written as experimental-validation reports rather than as frozen rendered notebook outputs.