Simulator: MiniRes, a pure-Python two-phase forward model

[patnr]

Adds MiniRes -- a 2D, two-phase (water/oil), immiscible
TPFA reservoir simulator -- as a forward simulator for PET, plus a tutorial that runs it.

Why

1. A physical forward model that needs nothing installed. Pure Python,
   pip-installable: no OPM/Eclipse binary, no licence, no deck, no En_* scratch folders,
   no file I/O at all. Tutorials, tests and CI can exercise actual two-phase flow anywhere,
   Colab included. Until now the only models that ran unattended were analytical ones.
2. Fast enough for real ensembles. ~20 ms per member on 16x16 x 12 steps; the bundled
   tutorial does 100 members over 3 ESMDA steps in ~10 s.
3. The first field-scale case for the adjoint path. PET reads self.sim adjoints in
   enkf/enrml/esmda, but no in-repo simulator supplies them. MiniRes differentiates
   its own time stepper (a hand-derived adjoint, minires.tlm), giving d(datum)/d(log K)
   over the whole grid at about one simulation per backward sweep. Checked here against
   central differences to ~1e-7 relative.
4. Likewise for the multilevel machinery: setup_fwd_run(level=...) becomes a real
   fidelity switch (grid, dt), not a stub.
5. A reference case for developing schemes, localization and QA/QC -- heterogeneous,
   nonlinear, with a known truth, reproducible on any machine.
6. It costs PET almost nothing: one optional extra, one module, no change to any
   existing code path. The ForwardSimulator contract already fitted; nothing in the
   ensemble or the schemes was touched.

What's here

• src/simulator/minires.py -- the wrapper. [simulator.model] is passed to
  minires.ResSim as it stands (grid, porosity, wells), less the permeability, which is
  what the ensemble state supplies, one field per member. Each member runs on its own
  deepcopy, so parallel > 1 works through p_map unchanged (MiniRes drops its cached
  pressure preconditioner on copy, which is what makes that safe).
• tests/test_minires_sim.py -- 14 tests: the records' shape and keys, determinism,
  failure returning False rather than raising, the state/grid-ordering mapping, the
  water-cut identity, config errors refused at construction, the fidelity switch, and the
  adjoints against central differences.
• tests/test_simulator_protocol.py -- MiniRes added to the existing parametrisation.
• docs/tutorials/pipt/MiniRes/ -- a history-matching tutorial: a 16x16 five-spot, the
  log-permeability field as the unknown, water cut and oil rate at four producers as the
  data. make_case.py draws the "true" field from the config's own prior and runs MiniRes
  on it, so the observations are made where the reader can see them. The notebook is
  committed with its outputs, as the others are (mkdocs-jupyter does not execute).
• pyproject.toml -- a [minires] extra. It is optional because MiniRes requires
  Python >= 3.12 while PET supports older; the tests skip without it.

Conventions the wrapper owns

MiniRes is agnostic about all three; the module docstring states them.

• Report points are step indices (reporttype = "steps"), MiniRes taking a uniform dt.
  reportdates relabels them if a case wants dates.
• Grid ordering: MiniRes is C-major (x first); Eclipse, and most of PET's tooling, is
  Fortran-ordered. field_order says which the state vector is in, and is applied on the
  way in and on the way out.
• Data types are Eclipse summary names (WOPR:PRD1, FWIR, ...), so observed-data
  files, datatype filters and localization tooling need no adaptation. Rates are positive
  as produced/injected, and areal -- MiniRes has no thickness. Units are whatever the config
  poses the model in (cdarcy = 0.008527 for metric, as Eclipse does).

Verified

• The full suite passes, with the 20 new/changed tests among them; ruff clean.
• End-to-end through the public entry point (read_config.read -> ESMDA.assimilate):
  data misfit 691.6 -> 108.5, and the correlation of the ensemble mean with the truth
  0.169 -> 0.313, in ~10 s. That is the tutorial's own run.
• Adjoints reach the analysis as (nd, nx, ne) -- verified (48, 256, 8) -- and a run with
  compute_adjoints = true logs [approx_update] Using adjoint-based update.
• The gradients agree with central differences to ~1e-7 relative for WWCT/WWPR/WOPR.
  Only rate-controlled completions are covered: a BHP-controlled well's rate is itself a
  function of the state, so it is refused with a message rather than silently wrong.

Questions for the maintainers

1. Placement. src/simulator/README.md points simulator wrappers at SimulatorWrap.
   MiniRes is not a wrapper around a binary -- it is a pip dependency with no external
   anything -- so bundling it beside the analytical models seems right, and is what makes
   the tutorial and CI story work. Happy to move it if you disagree.
2. Data-type separator: WOPR:PRD1 here (matching the refactor's tutorials); older
   configs use WOPR PRD1. Say which and I'll follow.
3. Adjoint coverage: currently the quantities that are a function of saturation at the
   well's cells. Extending to BHP-controlled wells means differentiating the well model into
   the seed; worth doing now, or when someone needs it?

Noticed in passing (not fixed here)

docs/tutorials/pipt/TinyBox/tutorial_pipt.ipynb still calls
DataReader({'truedata': ...}), but DataReader reads info.get('data'), so that cell now
raises ValueError: Data missing: the 'data' key is missing in info dictionary. It is
committed with outputs, which is presumably why it went unnoticed. Not touched here, since
re-executing it needs OPM.

pipt.misc_tools.extract_tools.extract_prior_info mutates the dict it is given and is not
idempotent: it wraps every non-list value in a list, so the nx/ny/nz ints it writes on
the first pass become [16], [16], [1] on the second. Building two ensembles from one
parsed config in the same process therefore fails in StateLayout.from_prior_info with
TypeError: 'list' object cannot be interpreted as an integer. Happy to open an issue or a
separate PR.

🤖 Generated with Claude Code