MPSlib: A C++ class for MPS simulation

MPSlib provides a C++ class, and a set of algorithms for simulation of models based on a multiple point statistical (MPS) models inferred from a training image:

• ENESIM [GUARDIANO].

• Generalized ENESIM [HANSEN2016].

• Direct Sampling [MARIETHOZ2010].

• SNESIM using tree structures [STREBELLE2002].

• SNESIM using list structures [STRAUBHAAR2011].

The above list of algorithms are implemented in two types of algorithms that differ in the way information is inferred from the training image. ENESIM type algorithms samples directly from the training image during simulation, while SNESIM type algorithms scan the training image prior to simulation, and stores the statistics in memory.

• GENESIM:: mps_genesim

mps_genesim is an implementation of the generalized ENESIM algorithm [GUARDIANO]. It can run as a pure ENESIM algorithm, in which the whole training image is scanned at each iteration, or it can run as a Direct Sampling DS algorithm [MARIETHOZ2010], in which the training image is scanned for the first matching event. It can can also run as generalized ENESIM GENESIM algorithm in which the training image is scanned for the first N matching event [HANSEN2016].

• SNESIM:: mps_snesim_tree/mps_snesim_list

Two types of SNESIM type simulation methods are implemented.

mps_snesim_tree stores statistics from the training image in a tree structure, as proposed by [STREBELLE2002] . mps_snesim_list stores statistics from the training image in a list structure, as proposed by [STRAUBHAAR2011].

mps_snesim_tree`and `mps_snesim_list differ only in how the information from the training image is store in memory.

Conditional data

All algorithms can handle hard and co-loccated soft data. mps_genesim can also handle non-colocated soft data [HANSEN2018].

Entropy

The entropy of the (unknown) probability distribution related to a specific choice of 1) training image, 2) simulation algorithm, and 3) options for running the simulation algorithm, can optionally be computed as part of simulation. [HANSEN2020].

Estimation

All algorithms can optionally be run in estimation mode in which the 1D marginal conditional distribution is directly computed (similar to Etype statistics from a number of realizations) [JOHANNSSON2021].

PYTHON and MATLAB interface

Interfaces to Python and Matlab/Octave interface are available.

Python notebooks are a good starting point for using MPSlib with Python.

Source Code

The latest stable code can be downloaded from http://ergosimulation.github.io/mpslib/.

The current development version is available through GitHub at https://github.com/ergosimulation/mpslib/.

Background

The goal of developing these codes has been to produce a set of algorithms, based on sequential simulation, for simulation of multiple point statistical models. The code should be easy to compile and extend, and should be allowed for both commercial and non-commercial use.

MPSlib (version 1.0) has been developed by I-GIS and Solid Earth Physics, Niels Bohr Institute.

Development was initially funded by the Danish National Hightech Foundation (now: the Innovation fund) through the ERGO (Effective high-resolution Geological Modeling) project, a collaboration between IGIS, GEUS, and Niels Bohr Institute.

Referencing

Along with the first version of MPSlib a manuscript was published in SoftwareX. Please use this for referencing MPSlib:

Hansen, T.M., Vu. L.T., and Bach, T. 2016. MPSLIB: A C++ class for sequential simulation of multiple-point statistical models, in SoftwareX, doi:10.1016/j.softx.2016.07.001. [pdf,www].

To cite the use of soft data and the preferential path, please use:

Hansen, T. M., Mosegaard, K., & Cordua, K. S. (2018). Multiple point statistical simulation using uncertain (soft) conditional data. Computers & geosciences, 114, 1-10. doi:10.1016/j.cageo.2018.01.017.

To cite the use of MPS based simulation, please use:

Jóhannsson, Óli D., and Thomas Mejer Hansen (2021). Estimation using multiple-point statistics. Computers & Geosciences 156 (2021): 104894. doi:10.1016/j.cageo.2021.104894 <https://doi.org/10.1016/j.cageo.2021.104894>

License (LGPL)

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

The manual

• Installation and compilation
  • Download
  • Compilation
    • LINUX (Ubuntu Linux (>16.04))
    • OSX (XCODE+GCC)
    • Windows: (mingw-w64)
• Running MPS algorithms
  • General options
    • Number of realizations
    • Random Seed
    • Simulation grid size X, Y, Z
    • Simulation grid origin X, Y, Z
    • Simulation grid grid cell size X
    • Training image file
    • Output folder (spaces in name not allowed)
    • Shuffle Simulation Grid path (2: preferential, 1: random, 0: sequential) # 2
    • Entropy factor
    • Shuffle Training Image path (1 : random, 0 : sequential)
    • HardData filename
    • HardData search radius
    • Softdata categories
    • Soft datafilenames
    • Number of threads (minimum 1, maximum 8 - depend on your CPU)
    • Debug mode
    • MASK file
    • Entropy
    • Estimation
  • GENESIM: Generalized ENESIM
    • line 3: Maximum number of counts for conditional pdf, n_max_count_cpdf
    • line 4: Max number for conditional points, n_cond
    • line 5:Max number of iterations, n_max_ite
    • line 6: distance_measure, and, distance_measure, maximum distance, distance_max, and distance_pow
    • line 6: ‘max_search_radius’
    • line 7:’colocate_dimension’
    • debug mode
  • SNESIM: Single normal equation simulation
    • line 3, n_mul_grids
    • line 4, n_min_node
    • line 5, n_cond
    • lines 6-8, the search template, tem_nx, tem_ny, tem_nz
• Training image format
• Examples
  • Ex: Varying template size in SNESIM
  • Ex: Soft/uncertain data
    • Co-located soft data
    • Non Co-located soft data
• Matlab interface
  • Getting started in Matlab
  • SNESIM type simulation
  • GENESIM type simulation
    • GENESIM as ENESIM
    • GENESIM as DIRECT SAMPLING
    • GENESIM, a hybrid between ENESIM and DIRECT SAMPLING
  • Plot simulation results
  • Parallel simulation
  • Sequential Estimation
  • Self-information and Entropy
• scikit-mps: a Python interface to MPSlib
  • mps.mpslib: The main interface to MPSlib
  • mps.eas: reading and writing EAS formatted files
    • Read EAS point set
    • Write EAS point set
    • Read EAS volume set
    • Write EAS volume set
  • mps.trainingimages: Easy access to training images.
  • mps.plot: Plotting utilities
    • plot_reals_3d()
• Pyhthon Notebook examples
  • MPSlib: Getting started with MPSlib/scikit-mps in Python
    • Setup MPSLib
    • Choose training image
    • Run MPSlib
    • Plot some realizations using matplotlib
  • MPSlib: hard and soft data in MPSlib
    • Define hard data
    • Define soft/uncertain data
    • Preferential path
    • Hard data
    • Soft/uncertain data
  • MPSlib: Using masks
  • MPSlib: Training images in scikit-mps
    • List the available training images
    • Plot training images
    • Coarsen a 2D training to a 3D
  • MPSlib: estimation
    • Estimation
    • Simulation
  • MPSlib: computation of entropy and self-information
    • Setup MPSLib
    • Plot entropy
    • Entropy as a function of number of conditional data
  • MPSlib: variable template size in mps_snesim_tree and mps_snesim_list
  • GENESIM with distance weighing
  • Example: Mapping buried valleys in Kasted, Denmark
    • Get the training image and conditional data
    • Plot the training image and the conditional data
  • MPSlib in Kasted
    • Setup and run MPSlib
  • Conditional simulation - hard data
  • Conditional simulation - soft data
  • Conditional simulation - Setup MPSlib to use both conditional hard well data, aoft conditional data related to ELEVATION and RESISTIVITY
  • Conditional estimation
• Implementation
  • EX: The ENESIM Class
• Contributions
• References