# ddsirota/reservoir-neural-bench architecture

> Architecture diagram of the GitHub repository ddsirota/reservoir-neural-bench, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ddsirota/reservoir-neural-bench
- Repository: https://github.com/ddsirota/reservoir-neural-bench

## Overview

ReservoirNeuralBench benchmarks neural surrogates for one-step, three-phase Norne reservoir forecasts and evaluates them through 60-step autoregressive rollouts, including out-of-distribution well controls. The product workflow runs from dataset preparation and actual-rate inputs through model training to rollout validation and reporting. Its model portfolio spans spectral, convolutional, operator-learning, and graph architectures. The README documents the benchmark stages and capabilities; source excerpts and the SOURCE INDEX support selected implementation links, so unsampled subsystem connections are not assumed.

Main entry points: [`train_norne.py`](https://github.com/ddsirota/reservoir-neural-bench/blob/main/train_norne.py) (Model training), [`tools/norne_generate_dataset.py`](https://github.com/ddsirota/reservoir-neural-bench/blob/main/tools/norne_generate_dataset.py) (Dataset generation), [`validate_rollout_norne.py`](https://github.com/ddsirota/reservoir-neural-bench/blob/main/validate_rollout_norne.py) (Rollout validation), [`make_report_norne.py`](https://github.com/ddsirota/reservoir-neural-bench/blob/main/make_report_norne.py) (Benchmark report)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Norne data"]
  node_generation["Dataset generation"]
  node_actualrates["Realized rates"]
  node_wellfeatures["Well features"]
  node_graphbuild["Graph construction"]
  node_export["Dataset export"]
  node_loader["Norne loader<br/>[norne_loader.py]"]
end

subgraph group_models["Surrogate models"]
  node_tfno["TFNO<br/>[tfno.py]"]
  node_fourier["Multi-input Fourier<br/>[fourier_mionet.py]"]
  node_ufno["U-FNO<br/>[u_fno.py]"]
  node_deeponet["DeepONet<br/>[deeponet.py]"]
  node_mionet["MIONet variants<br/>[mionet_deeponet.py]"]
  node_deepxde["DeepXDE branches"]
  node_gnn["Message passing GNN<br/>[gnn.py]"]
  node_meshgraph["MeshGraphNet<br/>[meshgraphnet.py]"]
  node_mgn["Multiscale graph net<br/>[mgn.py]"]
  node_flux["Flux GNN<br/>[flux_gnn.py]"]
  node_tpfa["TPFA GNN<br/>[tpfa_gnn.py]"]
  node_unet["3D U-Net<br/>[unet3d.py]"]
  node_resunet["Residual U-Net<br/>[resunet3d_hdc.py]"]
  node_residual["Conv3D residual<br/>[residual.py]"]
end

subgraph group_evaluation["Training and evaluation"]
  node_train["Model training<br/>[train_norne.py]"]
  node_rollout["Rollout validation"]
  node_massbalance["Mass balance<br/>[mass_balance.py]"]
  node_fluid["Fluid properties"]
end

subgraph group_analysis["Benchmark analysis"]
  node_report["Benchmark report"]
  node_figures["Figures<br/>[make_figures.py]"]
  node_curves["Rollout error curves"]
end

node_user(("Benchmark user"))

node_user -->|"generate data"| node_generation
node_generation -.->|"extract rates"| node_actualrates
node_generation -.->|"derive well features"| node_wellfeatures
node_generation -.->|"build graph"| node_graphbuild
node_generation -.->|"export dataset"| node_export
node_user -->|"train models"| node_train
node_train -->|"loads batches"| node_loader
node_train -->|"uses model registry"| node_tfno
node_train -->|"selects model"| node_fourier
node_fourier -->|"uses backbone"| node_tfno
node_user -->|"validate forecasts"| node_rollout
node_rollout -->|"loads scenarios"| node_loader
node_rollout -->|"checks balance"| node_massbalance
node_rollout -->|"uses fluid properties"| node_fluid
node_user -->|"review results"| node_report
node_report -.->|"summarizes benchmark"| node_figures
node_report -.->|"presents rollout errors"| node_curves
node_train -->|"selects model"| node_gnn
node_train -->|"selects model"| node_meshgraph
node_train -->|"selects model"| node_mgn
node_train -->|"selects model"| node_flux
node_train -->|"selects model"| node_tpfa
node_train -->|"selects model"| node_deeponet
node_train -->|"selects model"| node_mionet
node_train -->|"selects model"| node_deepxde
node_train -->|"selects model"| node_unet
node_train -->|"selects model"| node_resunet
node_train -->|"uses component"| node_residual
node_train -->|"selects model"| node_ufno

click node_generation "https://github.com/ddsirota/reservoir-neural-bench/blob/main/tools/norne_generate_dataset.py"
click node_actualrates "https://github.com/ddsirota/reservoir-neural-bench/blob/main/tools/norne_extract_actual_rates.py"
click node_wellfeatures "https://github.com/ddsirota/reservoir-neural-bench/blob/main/tools/norne_extract_well_index.py"
click node_graphbuild "https://github.com/ddsirota/reservoir-neural-bench/blob/main/tools/norne_build_graph.py"
click node_export "https://github.com/ddsirota/reservoir-neural-bench/blob/main/tools/norne_export_dataset.py"
click node_loader "https://github.com/ddsirota/reservoir-neural-bench/blob/main/data/norne_loader.py"
click node_train "https://github.com/ddsirota/reservoir-neural-bench/blob/main/train_norne.py"
click node_rollout "https://github.com/ddsirota/reservoir-neural-bench/blob/main/validate_rollout_norne.py"
click node_massbalance "https://github.com/ddsirota/reservoir-neural-bench/blob/main/tools/mass_balance.py"
click node_fluid "https://github.com/ddsirota/reservoir-neural-bench/blob/main/tools/norne_fluid_props.py"
click node_tfno "https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/tfno.py"
click node_fourier "https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/fourier_mionet.py"
click node_ufno "https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/u_fno.py"
click node_deeponet "https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/deeponet.py"
click node_mionet "https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/mionet_deeponet.py"
click node_deepxde "https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/deepxde_branch_deeponet.py"
click node_gnn "https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/gnn.py"
click node_meshgraph "https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/meshgraphnet.py"
click node_mgn "https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/mgn.py"
click node_flux "https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/flux_gnn.py"
click node_tpfa "https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/tpfa_gnn.py"
click node_unet "https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/unet3d.py"
click node_resunet "https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/resunet3d_hdc.py"
click node_residual "https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/residual.py"
click node_report "https://github.com/ddsirota/reservoir-neural-bench/blob/main/make_report_norne.py"
click node_figures "https://github.com/ddsirota/reservoir-neural-bench/blob/main/tools/make_figures.py"
click node_curves "https://github.com/ddsirota/reservoir-neural-bench/blob/main/tools/make_rollout_error_curves.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_generation,node_actualrates,node_wellfeatures,node_graphbuild,node_export,node_loader,node_user toneBlue
class node_tfno,node_fourier,node_ufno,node_deeponet,node_mionet,node_deepxde,node_gnn,node_meshgraph,node_mgn,node_flux,node_tpfa,node_unet,node_resunet,node_residual toneAmber
class node_train,node_rollout,node_massbalance,node_fluid toneMint
class node_report,node_figures,node_curves toneRose
```

## Components

### Norne data

- [Dataset generation](https://github.com/ddsirota/reservoir-neural-bench/blob/main/tools/norne_generate_dataset.py): `tools/norne_generate_dataset.py`
- [Realized rates](https://github.com/ddsirota/reservoir-neural-bench/blob/main/tools/norne_extract_actual_rates.py): `tools/norne_extract_actual_rates.py`
- [Well features](https://github.com/ddsirota/reservoir-neural-bench/blob/main/tools/norne_extract_well_index.py): `tools/norne_extract_well_index.py`
- [Graph construction](https://github.com/ddsirota/reservoir-neural-bench/blob/main/tools/norne_build_graph.py): `tools/norne_build_graph.py`
- [Dataset export](https://github.com/ddsirota/reservoir-neural-bench/blob/main/tools/norne_export_dataset.py): `tools/norne_export_dataset.py`
- [Norne loader](https://github.com/ddsirota/reservoir-neural-bench/blob/main/data/norne_loader.py): `data/norne_loader.py`

### Surrogate models

- [TFNO](https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/tfno.py): `models/tfno.py`
- [Multi-input Fourier](https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/fourier_mionet.py): `models/fourier_mionet.py`
- [U-FNO](https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/u_fno.py): `models/u_fno.py`
- [DeepONet](https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/deeponet.py): `models/deeponet.py`
- [MIONet variants](https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/mionet_deeponet.py): `models/mionet_deeponet.py`
- [DeepXDE branches](https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/deepxde_branch_deeponet.py): `models/deepxde_branch_deeponet.py`
- [Message passing GNN](https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/gnn.py): `models/gnn.py`
- [MeshGraphNet](https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/meshgraphnet.py): `models/meshgraphnet.py`
- [Multiscale graph net](https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/mgn.py): `models/mgn.py`
- [Flux GNN](https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/flux_gnn.py): `models/flux_gnn.py`
- [TPFA GNN](https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/tpfa_gnn.py): `models/tpfa_gnn.py`
- [3D U-Net](https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/unet3d.py): `models/unet3d.py`
- [Residual U-Net](https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/resunet3d_hdc.py): `models/resunet3d_hdc.py`
- [Conv3D residual](https://github.com/ddsirota/reservoir-neural-bench/blob/main/models/residual.py): `models/residual.py`

### Training and evaluation

- [Model training](https://github.com/ddsirota/reservoir-neural-bench/blob/main/train_norne.py): `train_norne.py`
- [Rollout validation](https://github.com/ddsirota/reservoir-neural-bench/blob/main/validate_rollout_norne.py): `validate_rollout_norne.py`
- [Mass balance](https://github.com/ddsirota/reservoir-neural-bench/blob/main/tools/mass_balance.py): `tools/mass_balance.py`
- [Fluid properties](https://github.com/ddsirota/reservoir-neural-bench/blob/main/tools/norne_fluid_props.py): `tools/norne_fluid_props.py`

### Benchmark analysis

- [Benchmark report](https://github.com/ddsirota/reservoir-neural-bench/blob/main/make_report_norne.py): `make_report_norne.py`
- [Figures](https://github.com/ddsirota/reservoir-neural-bench/blob/main/tools/make_figures.py): `tools/make_figures.py`
- [Rollout error curves](https://github.com/ddsirota/reservoir-neural-bench/blob/main/tools/make_rollout_error_curves.py): `tools/make_rollout_error_curves.py`

### Other components

- **Benchmark user**

## Connections

- Benchmark user → Dataset generation: generate data (evidence: `README.md`)
- Dataset generation → Realized rates: extract rates
- Dataset generation → Well features: derive well features
- Dataset generation → Graph construction: build graph
- Dataset generation → Dataset export: export dataset
- Benchmark user → Model training: train models (evidence: `README.md`)
- Model training → Norne loader: loads batches (evidence: `train_norne.py`)
- Model training → TFNO: uses model registry (evidence: `train_norne.py`)
- Model training → Multi-input Fourier: selects model
- Multi-input Fourier → TFNO: uses backbone (evidence: `models/fourier_mionet.py`)
- Benchmark user → Rollout validation: validate forecasts (evidence: `README.md`)
- Rollout validation → Norne loader: loads scenarios (evidence: `validate_rollout_norne.py`)
- Rollout validation → Mass balance: checks balance (evidence: `validate_rollout_norne.py`)
- Rollout validation → Fluid properties: uses fluid properties (evidence: `validate_rollout_norne.py`)
- Benchmark user → Benchmark report: review results (evidence: `README.md`)
- Benchmark report → Figures: summarizes benchmark
- Benchmark report → Rollout error curves: presents rollout errors
- Model training → Message passing GNN: selects model (evidence: `train_norne.py`)
- Model training → MeshGraphNet: selects model (evidence: `train_norne.py`)
- Model training → Multiscale graph net: selects model (evidence: `train_norne.py`)
- Model training → Flux GNN: selects model (evidence: `train_norne.py`)
- Model training → TPFA GNN: selects model (evidence: `train_norne.py`)
- Model training → DeepONet: selects model
- Model training → MIONet variants: selects model
- Model training → DeepXDE branches: selects model
- Model training → 3D U-Net: selects model
- Model training → Residual U-Net: selects model
- Model training → Conv3D residual: uses component (evidence: `train_norne.py`)
- Model training → U-FNO: selects model