ResFlow / README.md

Model card: whole fields need a GPU.

41e5826 verified 4 days ago

6.29 kB

---
license: mit
library_name: resflow
datasets:
- SciLM/SiliciclasticReservoirs
tags:
- geology
- reservoir
- subsurface
- 3d
- flow-matching
- diffusion-transformer
- generative
---
# ResFlow

ResFlow generates 3D reservoir facies (sand and mud) with one flow-matching model for eight simulated
siliciclastic environments: deep-water lobes, a distributary delta, and six fluvial classes. It is conditioned on
geological parameters and wells, and it generates single 64×64×32 volumes or whole fields of any size in one pass.
These are the weights of the paper *SiliciclasticReservoirs: A Million-Reservoir Dataset and Flow-Matching
Foundation Model for 3D Siliciclastic Reservoir Generation* (NeurIPS 2026, Track on Evaluations and Datasets).

**Code:** [github.com/SciLM-ai/ResFlow](https://github.com/SciLM-ai/ResFlow) ·
**Dataset:** [SciLM/SiliciclasticReservoirs](https://huggingface.co/datasets/SciLM/SiliciclasticReservoirs) ·
**Benchmark:** [ResBench](https://github.com/SciLM-ai/ResBench) ·
**Simulator:** [ResMill](https://github.com/SciLM-ai/ResMill)

## Quick start

```bash
pip install git+https://github.com/SciLM-ai/ResFlow
```

```python
import resflow
model = resflow.load_pretrained()                     # this repository
vols = model.generate('meander', n=8)                 # (8, 64, 64, 32) uint8, 1 = sand
vols = model.generate('lobe', n=4, ntg=0.35, width_cells=30, azimuth=45)
column = [0] * 10 + [1] * 8 + [0] * 14                # a well log, base to top: 1 sand, 0 mud, -1 unknown
ens = model.generate('meander', n=32,                 # every realisation honours the well exactly
                     wells=[resflow.Well(x=32, y=32, facies=column)])
field = model.generate_field('lobe', shape=(512, 512, 32), ntg=0.5)
```

A walkthrough notebook is in the code repository at `examples/pretrained/quickstart.ipynb`. A GPU is recommended:
on an NVIDIA GH200 a 64×64×32 volume takes about 0.8 s in batches of 128 and a 512×512×32 field about 2 minutes.
A CPU works for 64×64×32 volumes (tens of minutes per volume on a few cores), but whole fields need a GPU: on CPU the
sliding-window attention holds the full attention matrix in memory, so even a 128×128×32 field takes about 43 GB.

## Inputs

| Input | Meaning |
|---|---|
| environment | `lobe`, `pv_shoestring`, `cb_labyrinth`, `cb_jigsaw`, `sh_distal`, `sh_proximal`, `meander`, `delta` |
| `ntg` | sand fraction of the volume (0–1) |
| `width_cells`, `depth_cells` | characteristic body width and thickness, in cells |
| `azimuth` | flow direction in degrees, 0 = along +x (default 0) |
| `asp` | lobe aspect ratio (lobe) |
| `mCHsinu` | channel sinuosity (channels, delta) |
| `mFFCHprop` | fraction of abandoned channels plugged with mud (channels, delta) |
| `probAvulInside` | in-belt avulsion probability (channels, delta) |
| `trunk_length_fraction` | share of the trunk kept free of bifurcations (delta) |
| `wells` / `observed` | vertical `Well(x, y, facies)`, or an array of known cells: 1 sand, 0 mud, −1 unknown |

Parameters left out take the environment's typical value (the median over its training data), and
`model.parameters(env)` lists each one with its training range. In `generate_field` any parameter can also be an
(X, Y) map, so trends can vary across one reservoir. Volumes have axes (x, y, z) with z = 0 at the base; cells are
100 m laterally for lobes and 10 m for channels and deltas, and 1 m vertically.

## Model

A 32.6M-parameter 3D diffusion transformer (4×4×2 patches, 12 blocks, width 384, 6 heads, QK-norm, 3D rotary
positions with θ = 100, adaptive layer norm) trained with conditional flow matching. The 18-number condition vector
holds the environment one-hot, NTG, width, depth, the sine and cosine of the azimuth, and five environment-specific
parameters; wells enter as two extra input channels. Sampling uses Euler's method with 100 steps and
classifier-free guidance 3. Volumes use global attention as in training; fields switch to sliding-window attention
of ±12 tokens per axis, so any extent is generated whole, without tiling.

Training used 900,000 volumes of SiliciclasticReservoirs (all eight environments) for 40 epochs on 16 NVIDIA GH200
GPUs (global batch 512, AdamW, peak learning rate 5.77×10⁻⁴, cosine schedule, about 7.5 hours). These weights are
the final epoch-40 exponential moving average.

## Evaluation

On ResBench, which scores each check against the simulator's own run-to-run variability (1 means
indistinguishable from the simulator, lower is better), ResFlow scores 1.70 overall: 1.24 on unconditional
volumes, 1.96 on well-conditioned volumes, and 1.90 on fields. It beats single-environment specialists with its own
architecture and recipe in seven of eight environments. Given the same inputs, it is far closer to the simulator
than GANSim-3D and a 3D latent diffusion model, and on par with DiffSIM, a diffusion model five times larger that
is trained per environment and not built for heterogeneous fields (meander 1.67 against 1.81, PV shoestring 1.55
against 1.52, SH proximal 1.84 against 1.67). Details are in the paper.

## Limitations

- Trained only on simulated reservoirs from the ResMill simulator, and not validated on real subsurface data.
  Forecasting a specific real reservoir needs separate calibration.
- Covers the eight training environments only; parameter values outside the training ranges are not supported
  (the API warns).
- Under a fixed input it underestimates the simulator's uncertainty in most channel environments, so its ensembles
  understate uncertainty there.
- At field scale, connectivity and variograms deviate most from the simulator, in shoestring, delta and SH proximal
  fields, and lobe fields carry more isolated sand specks than the simulator's.

## Citation

```bibtex
@inproceedings{baghishov2026siliciclastic,
  title     = {SiliciclasticReservoirs: A Million-Reservoir Dataset and Flow-Matching Foundation Model
               for 3D Siliciclastic Reservoir Generation},
  author    = {Baghishov, Ilgar and Rustamzade, Elnara and Henkelman, Graeme and Foster, John T. and Pyrcz, Michael J.},
  booktitle = {Advances in Neural Information Processing Systems (NeurIPS), Track on Evaluations and Datasets},
  year      = {2026}
}
```

## License

MIT.

	---
	license: mit
	library_name: resflow
	datasets:
	- SciLM/SiliciclasticReservoirs
	tags:
	- geology
	- reservoir
	- subsurface
	- 3d
	- flow-matching
	- diffusion-transformer
	- generative
	---

	# ResFlow

	ResFlow generates 3D reservoir facies (sand and mud) with one flow-matching model for eight simulated
	siliciclastic environments: deep-water lobes, a distributary delta, and six fluvial classes. It is conditioned on
	geological parameters and wells, and it generates single 64×64×32 volumes or whole fields of any size in one pass.
	These are the weights of the paper *SiliciclasticReservoirs: A Million-Reservoir Dataset and Flow-Matching
	Foundation Model for 3D Siliciclastic Reservoir Generation* (NeurIPS 2026, Track on Evaluations and Datasets).

	Code: [github.com/SciLM-ai/ResFlow](https://github.com/SciLM-ai/ResFlow) ·
	Dataset: [SciLM/SiliciclasticReservoirs](https://huggingface.co/datasets/SciLM/SiliciclasticReservoirs) ·
	Benchmark: [ResBench](https://github.com/SciLM-ai/ResBench) ·
	Simulator: [ResMill](https://github.com/SciLM-ai/ResMill)

	## Quick start

	```bash
	pip install git+https://github.com/SciLM-ai/ResFlow
	```

	```python
	import resflow

	model = resflow.load_pretrained() # this repository

	vols = model.generate('meander', n=8) # (8, 64, 64, 32) uint8, 1 = sand
	vols = model.generate('lobe', n=4, ntg=0.35, width_cells=30, azimuth=45)
	column = [0] * 10 + [1] * 8 + [0] * 14 # a well log, base to top: 1 sand, 0 mud, -1 unknown
	ens = model.generate('meander', n=32, # every realisation honours the well exactly
	wells=[resflow.Well(x=32, y=32, facies=column)])
	field = model.generate_field('lobe', shape=(512, 512, 32), ntg=0.5)
	```

	A walkthrough notebook is in the code repository at `examples/pretrained/quickstart.ipynb`. A GPU is recommended:
	on an NVIDIA GH200 a 64×64×32 volume takes about 0.8 s in batches of 128 and a 512×512×32 field about 2 minutes.
	A CPU works for 64×64×32 volumes (tens of minutes per volume on a few cores), but whole fields need a GPU: on CPU the
	sliding-window attention holds the full attention matrix in memory, so even a 128×128×32 field takes about 43 GB.

	## Inputs

	\| Input \| Meaning \|
	\|---\|---\|
	\| environment \| `lobe`, `pv_shoestring`, `cb_labyrinth`, `cb_jigsaw`, `sh_distal`, `sh_proximal`, `meander`, `delta` \|
	\| `ntg` \| sand fraction of the volume (0–1) \|
	\| `width_cells`, `depth_cells` \| characteristic body width and thickness, in cells \|
	\| `azimuth` \| flow direction in degrees, 0 = along +x (default 0) \|
	\| `asp` \| lobe aspect ratio (lobe) \|
	\| `mCHsinu` \| channel sinuosity (channels, delta) \|
	\| `mFFCHprop` \| fraction of abandoned channels plugged with mud (channels, delta) \|
	\| `probAvulInside` \| in-belt avulsion probability (channels, delta) \|
	\| `trunk_length_fraction` \| share of the trunk kept free of bifurcations (delta) \|
	\| `wells` / `observed` \| vertical `Well(x, y, facies)`, or an array of known cells: 1 sand, 0 mud, −1 unknown \|

	Parameters left out take the environment's typical value (the median over its training data), and
	`model.parameters(env)` lists each one with its training range. In `generate_field` any parameter can also be an
	(X, Y) map, so trends can vary across one reservoir. Volumes have axes (x, y, z) with z = 0 at the base; cells are
	100 m laterally for lobes and 10 m for channels and deltas, and 1 m vertically.

	## Model

	A 32.6M-parameter 3D diffusion transformer (4×4×2 patches, 12 blocks, width 384, 6 heads, QK-norm, 3D rotary
	positions with θ = 100, adaptive layer norm) trained with conditional flow matching. The 18-number condition vector
	holds the environment one-hot, NTG, width, depth, the sine and cosine of the azimuth, and five environment-specific
	parameters; wells enter as two extra input channels. Sampling uses Euler's method with 100 steps and
	classifier-free guidance 3. Volumes use global attention as in training; fields switch to sliding-window attention
	of ±12 tokens per axis, so any extent is generated whole, without tiling.

	Training used 900,000 volumes of SiliciclasticReservoirs (all eight environments) for 40 epochs on 16 NVIDIA GH200
	GPUs (global batch 512, AdamW, peak learning rate 5.77×10⁻⁴, cosine schedule, about 7.5 hours). These weights are
	the final epoch-40 exponential moving average.

	## Evaluation

	On ResBench, which scores each check against the simulator's own run-to-run variability (1 means
	indistinguishable from the simulator, lower is better), ResFlow scores 1.70 overall: 1.24 on unconditional
	volumes, 1.96 on well-conditioned volumes, and 1.90 on fields. It beats single-environment specialists with its own
	architecture and recipe in seven of eight environments. Given the same inputs, it is far closer to the simulator
	than GANSim-3D and a 3D latent diffusion model, and on par with DiffSIM, a diffusion model five times larger that
	is trained per environment and not built for heterogeneous fields (meander 1.67 against 1.81, PV shoestring 1.55
	against 1.52, SH proximal 1.84 against 1.67). Details are in the paper.

	## Limitations

	- Trained only on simulated reservoirs from the ResMill simulator, and not validated on real subsurface data.
	Forecasting a specific real reservoir needs separate calibration.
	- Covers the eight training environments only; parameter values outside the training ranges are not supported
	(the API warns).
	- Under a fixed input it underestimates the simulator's uncertainty in most channel environments, so its ensembles
	understate uncertainty there.
	- At field scale, connectivity and variograms deviate most from the simulator, in shoestring, delta and SH proximal
	fields, and lobe fields carry more isolated sand specks than the simulator's.

	## Citation

	```bibtex
	@inproceedings{baghishov2026siliciclastic,
	title = {SiliciclasticReservoirs: A Million-Reservoir Dataset and Flow-Matching Foundation Model
	for 3D Siliciclastic Reservoir Generation},
	author = {Baghishov, Ilgar and Rustamzade, Elnara and Henkelman, Graeme and Foster, John T. and Pyrcz, Michael J.},
	booktitle = {Advances in Neural Information Processing Systems (NeurIPS), Track on Evaluations and Datasets},
	year = {2026}
	}
	```

	## License

	MIT.