feat: add gstools.mps — Multiple Point Statistics via Direct Sampling#416
Draft
n0228a wants to merge 5 commits into
Draft
feat: add gstools.mps — Multiple Point Statistics via Direct Sampling#416n0228a wants to merge 5 commits into
n0228a wants to merge 5 commits into
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new
gstools.mpssubpackage implementing Multiple Point Statistics (MPS) simulation via the Direct Sampling algorithm (Mariethoz et al. 2010; Juda et al. 2022). MPS is a fundamentally different paradigm from two-point geostatistics: instead of a parametric covariance model, spatial structure is learned directly from a training image (TI), enabling reproduction of curvilinear, connected patterns (channels, fractures, categorical facies) that variogram-based methods cannot capture.Supersedes #409.
Public API
Three classes, exposed at
gstools.mpsand at the top-levelgstoolsnamespace:TrainingImageThe MPS analogue of
CovModel. Wraps an n-dimensional NumPy array and the distance function used to compare data events. Accepts either a plain array (univariate) or adictof named arrays (multivariate co-simulation). Key options:"l1"(Juda2022 Eq. 7),"l2","lp"(arbitrary Minkowski exponent), or"variation"(Mariethoz2010 Eq. 9) with automatic mean-shift correctiondistance_power— spatial-decay weighting of neighbours (Mariethoz2010 Eq. 5)weights— per-variable distance weights for multivariate TIsMPSModelConfiguration object bundling a
TrainingImagewith validated search parameters:n_neighbors,scan_fraction,threshold,cond_weight,boundary, andmax_radius. Acts as theCovModelcounterpart for theDirectSamplingconstructor.DirectSamplingSubclasses
gstools.field.base.Fieldand follows the same call interface asSRF. Key capabilities:len(shape)driven throughout, no hardcoded 2-D/3-Dscan_fractioncaps the per-node TI scan (Juda2022 §2)threshold=0.0activates DSBC mode (full scan, best-candidate selection)boundary="strict"(default) or"partial"— partial mode drops lags that exceed the TI extent and searches with the reduced template (Mariethoz2010 §6.2)set_condition()— hard-data conditioning with nearest-node snapping and per-variable collision resolutionset_nonstationary()— per-node rotation and anisotropy maps for geometric lag transform, enabling spatially varying orientation without modifying the TIset_mv_transforms()— per-variable mean / normalizer / trend post-processing for multivariate runsnum_threads(ThreadPoolExecutor; also inherited fromgstools.config.NUM_THREADS)path_seed,node_seed) for independent control of visit order vs. TI scan randomnessMultivariate co-simulation
When
TrainingImageis constructed with adict,DirectSamplingruns a joint scan at each node that minimises the weighted aggregate distanceΣ_k w_k d_kover all variables. The selected TI cell's full variable vector is copied to the node's uninformed slots — so cross-variable joint structure is reproduced by construction. Variables already known at the node (via conditioning data) act as collocatedh = 0constraints weighted bycond_weight. The return value is a{variable: ndarray}dict; each variable is also stored as a named field accessible viads["facies"]/ds.all_fields.Module layout
training_image.pyTrainingImage— data and distance functionsdistance.pymodel.pyMPSModel— validated search-parameter configneighbors.pyscan.pyrunner.pysimulate.py_DirectSamplingEngine+ds_simulateentry pointdirect_sampling.pyDirectSampling— publicFieldsubclassUsage
Examples (
examples/13_mps/)00_simple_unconditional.py01_conditional.pyset_condition()02_continuous.py03_channel_strebelle.py00_mps_overview.ipynbReferences