feat: add gstools.mps — Multiple Point Statistics via Direct Sampling

[n0228a]

Summary

Supersedes #409. Extends the univariate Direct Sampling implementation from that PR with multivariate co-simulation, a refactored split-module layout, and a new MPSModel interface.

What's new vs #409

• MPSModel — high-level model class mirroring the CovModel API
• Multivariate co-simulation — TrainingImage accepts dict-valued arrays; joint TI scan reproduces cross-variable spatial patterns
• Split module layout — runner.py, scan.py, simulate.py, neighbors.py: each simulation stage independently testable
• NaN masking — simulation domain supports gaps (e.g. irregular geometries)
• set_nonstationary() stub prepared for zone-based non-stationarity

Preserved from #409

• Categorical and continuous distance metrics (L1, L2, variation, Lp) with spatial-decay weighting
• boundary="strict" / "partial" scan modes
• Hard conditioning via set_condition() with nearest-node snapping and collision resolution
• DAG-based parallelism via num_threads
• n-D grid support throughout

Usage

import numpy as np
from gstools import mps

# Univariate
ti = mps.TrainingImage(ti_array, categorical=True)
ds = mps.DirectSampling(ti, n_neighbors=30, scan_fraction=1.0, threshold=0.01)
field = ds([np.arange(100, dtype=float), np.arange(100, dtype=float)], seed=42)

# Multivariate
ti_mv = mps.TrainingImage({"facies": ti_facies, "porosity": ti_poro})
ds_mv = mps.DirectSampling(ti_mv, n_neighbors=30)
result = ds_mv([x, y], seed=42)  # returns dict keyed by variable name

Files (25)

• src/gstools/mps/ — 9 source files
• src/gstools/__init__.py — mps subpackage registration
• tests/test_mps.py — full test suite incl. parallel determinism tests
• examples/13_mps/ — 6 example scripts + preview images + data file

References

• Mariethoz et al. (2010), WRR 46, W11536 — Direct Sampling method
• Juda et al. (2022), MG 54, 1315–1337 — parsimonious DS parametrisation

[n0228a]

Closing — will reopen with full commit history transferred from the multivariate branch.