PoreML

PoreML

A data-driven framework for learning multiphase flow in porous media

Chunyang Wang1 Mingrui Zhang1 Yuyan Zhang1 Linqi Zhu1 Xin Ju2,3 Edo Sicco Boek4 Martin J. Blunt1 Gege Wen1,3

1Imperial College London 2Stanford University 3EarthFlow AI 4Queen Mary University of London

Read the paper Framework LBM solver Dataset Watch the film
Non-wetting fluid (blue) invading a 256³-voxel sphere pack. Viscosity ratio M = 0.05, contact angle θ = 120°.

Whether injected CO2 stays underground, whether a fuel cell floods, whether a chip package traps a void: each is decided in pores a few micrometres wide, where an interface pins at a throat and then suddenly floods the next pore. PoreML gives machine learning the data and the yardstick to learn these dynamics in 3D.

Simulation runs
560
Stored 3D time steps
158,546
Open data
3.3 TB
GPU-hours to generate
3,000+

Three parts, one pipeline

From geometry to scored prediction, every stage is open and reproducible.

  1. Simulate

    bob is a GPU-native, JAX-based colour-gradient lattice Boltzmann solver (D3Q19, MRT collision) with geometric wetting control. It shards across GPUs for large domains and is checked against eight analytical and experimental benchmarks.

  2. Store

    PoreML data holds every run as a time series of 3D phase, pressure and velocity fields, sweeping contact angle and viscosity ratio over generated media and micro-CT scans of real rock and fuel-cell paper.

  3. Learn and evaluate

    poreml trains surrogates to predict the next frame and scores them over 64-step autoregressive rollouts, with field errors and Minkowski functionals that check volume, interface area, curvature and topology.

PoreML framework diagram: a 3D LBM solver turns generated and micro-CT geometries into time-resolved fields; models predict the next frame; two transfer challenges, Scale-Up and Geo-Shift.
The PoreML framework. (A) The solver turns geometries and flow conditions into time-resolved fields; models predict the next frame and are scored with field and geometry-aware metrics. (B) Scale-Up trains on small domains and tests on domains twice as wide. (C) Geo-Shift trains on generated geometries and tests on micro-CT scans.

Four ways fluids fight through pores

Each scenario sweeps viscosity ratio M across columns and contact angle θ down rows. Select any simulation to inspect it.

Can a neural network keep up with physics?

Each model sees one true frame, then feeds its own predictions back in for 64 steps. Drag the divider to compare against the lattice Boltzmann ground truth, and scrub through the rollout to watch errors build up.

Ground truth frame
Model prediction frame
Ground truth (LBM) AB-UPT
Loading frames
h = 1 / 64

Compare against

IoU of the blue phase against the ground truth on pore voxels, read at every step. Each case is the median test case by IoU at step 64, not the best one.

Benchmark

Five models, four scenarios, three tests. Pick a combination to compare.

Show all numbers as a table

The events a model has to learn

Capillary forces make pore-scale flow jumpy and non-local. These events change how much fluid is trapped and how easily each phase flows, often without moving bulk saturation at all.

Four panels of pore-scale events: ganglion coalescence in drainage, snap-off in trapping, a Haines jump in a gas diffusion layer, and void entrapment in underfill.
Representative pore-scale dynamics, highlighted in yellow. (A) Coalescence: separate non-wetting bodies merge. (B) Snap-off: wetting films pinch a thread into an isolated ganglion. (C) Haines jump: a meniscus depins and abruptly fills a pore. (D) Void entrapment: encapsulant fronts close around solder balls and trap air.

Geometries: generated and scanned

Gallery of geometry families: micro-CT sandstone, sphere packs, blob media, polydisperse spheres, micro-CT and generated gas diffusion layers, and flip-chip underfill gaps.
Geometry families. Rock-like media (µCT sandstone, sphere packs, Gaussian blobs, polydisperse grains), gas-diffusion layers (µCT carbon paper and generated fibre mats), and flip-chip gaps set by solder-ball diameter, pitch and gap height. Large and small domains share one voxel size, so a larger domain holds more pores rather than finer ones.

Solver validation

Select a case to see what it checks.

Two minutes of pore-scale flow

The full simulation showcase, then ten median-case rollouts of all five models against the ground truth.

Get started

Everything is MIT-licensed. Download a slice of the data, or clone the code.

Download the data

Trajectories use Zstandard compression, so import hdf5plugin before h5py. Filter by scenario, geometry family or run with --include.

Shell
pip install huggingface_hub hdf5plugin h5py
hf download PoreML/PoreML_data --repo-type dataset \
  --include "drainage/runs/sphere/*" --local-dir data

Read a trajectory

Each run is one .h5 file holding the solid mask and, per stored step, phase phi, pressure p and velocity u. The last axis is the flow direction.

Python
import glob, hdf5plugin, h5py

path = glob.glob("data/drainage/runs/sphere/*/*/*.h5")[0]
with h5py.File(path) as f:
    rock = f["rock"][:]                    # 1 = solid
    steps = sorted(f["steps"], key=int)
    phi = f["steps"][steps[-1]]["phi"][:]  # NaN inside solids

Run the code

The solver generates new simulations; the framework trains and scores models with the protocols used in the paper.

Shell
git clone https://github.com/PoreML/bob      # LBM solver
git clone https://github.com/PoreML/poreml   # learning framework

Cite PoreML

Wang, C., Zhang, M., Zhang, Y., Zhu, L., Ju, X., Boek, E. S., Blunt, M. J., & Wen, G. (2026). PoreML: A data-driven framework for learning multiphase flow in porous media. arXiv preprint arXiv:2610.10314.

BibTeX 
@article{wang2026poreml,
  title   = {PoreML: A Data-Driven Framework for Learning Multiphase Flow in Porous Media},
  author  = {Wang, Chunyang and Zhang, Mingrui and Zhang, Yuyan and Zhu, Linqi and
             Ju, Xin and Boek, Edo Sicco and Blunt, Martin J. and Wen, Gege},
  journal = {arXiv preprint arXiv:2610.10314},
  year    = {2026}
}