runsim 0.1.0
Unified interface for running reservoir simulators
Requires Python: >=3.11

# runsim

> **Note:** This package is under active development. APIs and CLI interfaces may change.

Unified runner for reservoir simulators, data assimilation, and optimization on macOS.

## Structure

```
runsim/
├── runsim.sh                 # Unified CLI entry point
├── pyproject.toml            # Python package config (uv + hatchling)
├── runsim/                   # Python package (flat layout)
│   ├── __init__.py
│   ├── base.py               #   Abstract Simulator class
│   ├── opm.py                #   OPM Flow wrapper
│   └── dumux.py              #   DuMux wrapper (stub)
├── simulators/
│   ├── common.sh             # Shared helpers + path resolution
│   ├── setup_env.sh          # Create venv, install packages, Docker setup
│   ├── opm/                  # OPM Flow simulator
│   │   ├── README.md
│   │   ├── install.sh        #   Build from source (macOS)
│   │   ├── install-docker.sh #   Install via Docker
│   │   ├── run.sh            #   Run bundled test suite (native)
│   │   ├── run-docker.sh     #   Run bundled test suite (Docker)
│   │   └── Dockerfile
│   ├── pet/                  # Python Ensemble Toolbox
│   │   ├── README.md
│   │   ├── install.sh        #   Download repos + pip install
│   │   └── run.sh            #   Run PET examples (DA/optimization)
│   ├── jutuldarcy/           # JutulDarcy simulator
│   │   ├── README.md
│   │   ├── install.sh        #   Install Python/Julia mode
│   │   └── run.sh            #   Run simulations
│   └── dumux/                # DuMux simulator
│       ├── README.md
│       ├── install.sh        #   Build from source (macOS)
│       ├── run.sh            #   Run simulations
│       └── Dockerfile
└── .venv/                    # Python virtual environment (auto-created)
```

## Quick Start

```bash
# 1. Set up environment (venv + packages + OPM Docker)
./runsim.sh setup

# 2. List available PET examples
./runsim.sh pet --list

# 3. Run an example
./runsim.sh pet Quadratic           # Analytic (no Docker needed)
./runsim.sh pet 3dBox/tiny          # OPM Flow (~2 min)
```

## CLI

```
./runsim.sh <command> [args...]

Commands:
  flow [flow-args...]           Run native OPM Flow (passthrough to binary)
  flow-docker [flow-args...]    Run OPM Flow via Docker (passthrough)
  jutuldarcy [args...]          Run JutulDarcy simulation
  dumux [args...]               Run DuMux simulation
  dumux-docker [args...]        Run DuMux via Docker
  pet [options] <example>       Run PET example (data assimilation / optimization)
  setup                         Bootstrap environment (venv, PET, Docker)
  help                          Show help
```

### Running Simulators

```bash
# OPM Flow (native) -- passthrough to flow binary
./runsim.sh flow --version
./runsim.sh flow --output-dir=./out SPE1CASE1.DATA

# OPM Flow (Docker)
./runsim.sh flow-docker --version
./runsim.sh flow-docker --output-dir=./out SPE1CASE1.DATA

# JutulDarcy
./runsim.sh jutuldarcy --test
./runsim.sh jutuldarcy /path/to/DECK.DATA

# DuMux
./runsim.sh dumux /path/to/executable
```

### Running PET Examples

```bash
./runsim.sh pet --list                                # List available examples
./runsim.sh pet LinearModel                           # Analytic DA
./runsim.sh pet 3dBox/tiny                            # 10x10x2 grid (~2 min)
./runsim.sh pet --simulator flow 3dBox/tiny           # Native OPM Flow (default)
./runsim.sh pet --simulator flow-docker 3dBox/tiny    # Docker
./runsim.sh pet 3SpotRobust --variant bhp             # Specific variant
./runsim.sh pet --clean 3dBox/tiny                    # Clean outputs then run
```

### Bundled Test Suites

Per-simulator test suites are available via direct script access:

```bash
./simulators/opm/run.sh                               # Native OPM, all cases
./simulators/opm/run-docker.sh                         # Docker, all cases
./simulators/jutuldarcy/run.sh --test                  # JutulDarcy SPE1
```

## Simulators

### OPM Flow (Docker) -- Recommended for quick start

Runs via Docker on any platform. Simplest setup.

```bash
./simulators/opm/install-docker.sh          # Pull image + create flow wrapper
./simulators/opm/install-docker.sh --test   # + run SPE1 validation
```

> Apple Silicon note: The Docker image is `linux/amd64` and runs under Rosetta/QEMU emulation.

### OPM Flow (Native macOS)

Full ARM-native performance. Builds Dune 2.10 + OPM from source.

```bash
./simulators/opm/install.sh              # Full build (~30-60 min, skips if installed)
./simulators/opm/install.sh --deps-only  # Homebrew + Dune only
./simulators/opm/install.sh --test       # Build + SPE1 test
./simulators/opm/install.sh --rebuild    # Force full rebuild
```

Requires: Xcode CLI tools, Homebrew, cmake, boost, suite-sparse, cjson, fmt.

### JutulDarcy

Differentiable reservoir simulator (Julia). Two modes available:

```bash
./simulators/jutuldarcy/install.sh              # Python mode (pip install jutuldarcy)
./simulators/jutuldarcy/install.sh --julia      # Julia mode (JutulDarcy.jl + juliacall)
./simulators/jutuldarcy/install.sh --both       # Both modes
./simulators/jutuldarcy/install.sh --test       # Install + verify
```

### DuMux

DUNE-based porous media simulator. Builds from source.

```bash
./simulators/dumux/install.sh              # Full build (shares Dune with OPM if available)
./simulators/dumux/install.sh --deps-only  # Homebrew + Dune only
./simulators/dumux/install.sh --rebuild    # Force full rebuild
```

### PET (Python Ensemble Toolbox)

Download PET repositories and install Python packages:

```bash
./simulators/pet/install.sh            # Download repos + pip install PET/SimulatorWrap
./simulators/pet/install.sh --status   # Show which repos/packages are present
```

### Verifying Installations

```bash
./runsim.sh flow --version             # e.g. "flow 2026.04-pre"
./runsim.sh flow-docker --version      # e.g. "flow 2025.10"

# JutulDarcy (Python mode)
.venv/bin/python -c "import jutuldarcy; print(jutuldarcy.__version__)"

# runsim Python package
.venv/bin/python -c "from runsim import OPMFlow; print(OPMFlow().version())"
```

## Python Package

The `runsim` package provides a programmatic interface to simulators:

```python
from runsim import OPMFlow

sim = OPMFlow()                         # auto-detect native binary
sim = OPMFlow(mode="docker")            # use Docker wrapper

# Check availability
print(sim.version())                    # "flow 2026.04-pre"
print(sim.is_available())               # True

# Run a simulation
result = sim.run("SPE1CASE1.DATA", output_dir="./output")
print(result.returncode)                # 0 on success
```

## PET Examples

```
EXAMPLE                TYPE   SIMULATOR  NOTES
───────                ────   ─────────  ─────
LinearModel            DA     none
3dBox/tiny             DA     flow       needs data generation
3dBox/small            DA     flow       needs data generation
3dBox/medium           DA     flow       needs data generation
3dBox/large            DA     flow       needs data generation
3dBox/flowrock         DA     flow       needs data generation
Spe11b                 DA     flow       needs data generation
3Spot                  Opt    flow
3SpotRobust            Opt    flow       variants: bhp, rate
3SpotEcalc             Opt    flow
5SpotInverted          Opt    flow
5SpotLineSearch        Opt    flow
Rosenbrock             Opt    none
Quadratic              Opt    none
```

Type: **DA** = Data Assimilation (ES-MDA), **Opt** = Optimization

## Dependencies

- **Python 3.11+**
- **uv** (recommended) or pip
- **Docker Desktop** (for OPM Flow Docker mode)
- [PET](https://github.com/Python-Ensemble-Toolbox) -- data assimilation framework
- [SimulatorWrap](https://github.com/Python-Ensemble-Toolbox) -- simulator wrappers
- [OPM Flow](https://opm-project.org/) -- reservoir simulator
- [JutulDarcy.jl](https://github.com/sintefmath/JutulDarcy.jl) -- differentiable simulator (optional)
- [DuMux](https://dumux.org/) -- porous media simulator (optional)

## Parent Repository Layout

```
project/
├── runsim/                   # This project
├── pet-repos/
│   ├── PET-main/             # Python Ensemble Toolbox source
│   ├── SimulatorWrap-main/   # Simulator wrapper source
│   └── Examples-main/        # PET example cases
├── opm-repos/
│   └── opm-data-master/      # Standard OPM test data (SPE1-9, Norne)
├── opm-build/                # Native OPM build artifacts (if built)
└── dumux-build/              # Native DuMux build artifacts (if built)
```