runsim 0.1.0

Unified interface for running reservoir simulators

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

# 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

# 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

./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:

./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.

./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.

./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:

./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.

./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:

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

Verifying Installations

./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:

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 -- data assimilation framework
• SimulatorWrap -- simulator wrappers
• OPM Flow -- reservoir simulator
• JutulDarcy.jl -- differentiable simulator (optional)
• DuMux -- 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)