# GeoBrain: Differentiable Subsurface Modeling

Welcome to the documentation of **GeoBrain**!
Here you will find detailed instructions for using the framework.
If you want to jump straight to examples, head to the [Tutorials](tutorials/01_geomodel_sim) section.
For the design principles behind GeoBrain, see the [Architecture](architecture) page.

## What is GeoBrain?

**GeoBrain** is an open, modular, and extensible platform for
**Geo**scientific **B**ayesian **R**easoning with **A**rtificial **In**telligence,
designed specifically for **integrated subsurface modeling**.

By combining **differentiable physics**, **Bayesian inference**, and **deep learning**,
GeoBrain enables end-to-end workflows for subsurface characterization —
from geostatistical modeling and rock physics to geophysical simulation and inversion.

```{image} geobrain_logo.png
:alt: GeoBrain Logo
:width: 350px
:align: center
```

---

## Gallery

A selection of representative outputs produced by the tutorials included in
this package. Each image links to the corresponding tutorial page.

```{figure} ../examples/figs/01_realizations.png
:alt: Geostatistical realizations generated by FFT-MA simulation
:width: 100%
:name: fig-realizations

**Geostatistical Simulation** -- Multiple equiprobable realizations of porosity
fields generated with FFT-Moving-Average simulation
([Tutorial 01](tutorials/01_geomodel_sim)).
```

```{figure} ../examples/figs/05_rock_physics_fields.png
:alt: Rock physics property fields (Vp, Vs, density, impedance)
:width: 100%
:name: fig-rock-physics

**Rock Physics Modeling** -- Elastic property fields (P-wave velocity, S-wave
velocity, density, impedance) computed from porosity and fluid saturation using
differentiable rock physics models ([Tutorial 05](tutorials/05_rock_physics)).
```

```{figure} ../examples/figs/acoustic_wavefield.gif
:alt: Animated acoustic wavefield propagation through the Marmousi2 model
:width: 100%
:name: fig-acoustic-wave

**Acoustic Wave Propagation** -- Time-domain finite-difference simulation of an
acoustic wavefield propagating through the Marmousi2 velocity model
([Tutorial 07](tutorials/07_acoustic_forward)).
```

```{figure} ../examples/figs/flow_simulation.gif
:alt: Animated two-phase reservoir flow simulation showing oil saturation evolution
:width: 100%
:name: fig-flow-sim

**Reservoir Flow Simulation** -- Differentiable two-phase (oil--water) flow
simulation showing saturation front evolution over time
([Tutorial 10](tutorials/10_flow_simulation)).
```

```{figure} ../examples/figs/09_fwi_results.png
:alt: Full waveform inversion results showing true, initial, and inverted velocity models
:width: 100%
:name: fig-fwi

**Full Waveform Inversion** -- Velocity model recovered by acoustic FWI with
PyTorch automatic differentiation, compared against the true Marmousi2 model
([Tutorial 09](tutorials/09_acoustic_fwi)).
```

```{figure} ../examples/figs/13_bayesian_avo_comparison.png
:alt: Bayesian AVO inversion posterior comparison across four samplers
:width: 100%
:name: fig-bayesian-avo

**Bayesian AVO Inversion** -- Posterior distributions from four gradient-informed
samplers (SVGD, HMC, NUTS, LDS) applied to amplitude-versus-offset inversion
([Tutorial 13](tutorials/13_bayes_avo_inversion)).
```

---

## Key Features

Differentiable Multiphysics
: Seamlessly integrates geostatistics, reservoir simulation, rock physics, and
  geophysics in a single computational graph. All modules support PyTorch
  automatic differentiation.

Bayesian Inference
: Four gradient-informed samplers (SVGD, HMC, NUTS, LDS) enable rigorous
  uncertainty quantification alongside deterministic inversion.

Deep Learning Integration
: Incorporates neural networks for prior modeling (Deep Image Prior),
  surrogate modeling, latent-space representations, and network-based
  reparameterizations.

70+ Rock Physics Models
: Comprehensive library covering effective medium theories, granular media
  models, fluid substitution, empirical relations, anisotropy, and
  resistivity.

Plug-and-Play Architecture
: Each physics module is self-contained and composable. Add new physics
  (resistivity, fluid flow, etc.) without modifying core logic.

Real-World Applications
: Demonstrated on CO$_2$ storage characterization at the **Illinois Basin –
  Decatur Project (IBDP)** and joint seismic–resistivity inversion for the
  **Sleipner CCS site** in the Norwegian Sea.

## Module Overview

| Module | Description |
|--------|-------------|
| `geobrain.geomodel` | Geostatistical simulation (FFT-MA, SGS), co-simulation, generative models (VAE, GAN, Diffusion) |
| `geobrain.physics.rock` | 70+ rock physics models: effective medium, granular, fluid substitution, empirical, anisotropy |
| `geobrain.physics.wave` | Seismic wave propagation (acoustic & elastic 2D/3D), AVO, wavelets, boundary conditions |
| `geobrain.physics.flow` | Differentiable reservoir fluid flow simulation (oil-water two-phase) |
| `geobrain.optim` | Deterministic inversion: Inverter with Explicit, Latent, Network parameterizations; L-BFGS, Gauss-Newton |
| `geobrain.bayes` | Bayesian samplers (SVGD, HMC, NUTS, LDS), distributions, kernels |
| `geobrain.nn` | Neural network components: Bayesian layers (Flipout), custom activations |
| `geobrain.io` | SEG-Y, LAS, Eclipse reservoir grid I/O |
| `geobrain.vis` | Publication-quality visualization: seismic sections, fields, well logs, production curves |
| `geobrain.data` | Data transforms (Normalize, Sigmoid, Logit) and dataset utilities |
| `geobrain.decision` | Decision under uncertainty: Value of Information (VOPI), closed-loop reservoir management |

## Tutorials

GeoBrain ships with **15 tutorials** that progress from basic geostatistics
through to real-world Bayesian joint inversion. Each tutorial is available as
both a **Python script** (`examples/*.py`) and a **Jupyter notebook**
(`examples/notebooks/*.ipynb`), so you can follow along interactively or run
them from the command line.

| # | Topic | Description |
|---|-------|-------------|
| 01--02 | Geomodeling | FFT-MA simulation, co-simulation, SGS, variograms |
| 03--04 | Implicit Modeling | Differentiable implicit geological modeling, karst cave inversion |
| 05--06 | Rock Physics & AVO | Rock physics workflows, AVO forward modeling |
| 07--08 | Wave Propagation | 2D acoustic & elastic FDTD on Marmousi2 |
| 09 | Full Waveform Inversion | Acoustic FWI with automatic differentiation |
| 10--11 | Flow Simulation | Two-phase reservoir flow, dynamic well control |
| 12 | Seismic Inversion | Deterministic inversion (Explicit, Network, Latent) |
| 13 | Bayesian Inversion | Bayesian AVO with 4 samplers (SVGD, HMC, NUTS, LDS) |
| 14 | IBDP Case Study | CO$_2$ site latent-space SVGD inversion |
| 15 | Sleipner Case Study | Joint seismic--resistivity inversion for CO$_2$ |

## Cite Us

If you use GeoBrain in your research, please cite:

```bibtex
@software{geobrain2026,
  title  = {GeoBrain: An End-to-End Differentiable Platform
            for Integrated Subsurface Modeling},
  author = {Liu, Mingliang},
  year   = {2026},
  url    = {https://github.com/GeoBrain-Project/geobrain}
}
```

Please email [mingliangliu@sdu.edu.cn](mailto:mingliangliu@sdu.edu.cn) for
questions or commercial licensing inquiries.
For bugs and feature requests,
[open an issue](https://github.com/GeoBrain-Project/geobrain/issues/new) on GitHub.