GeoStatsLib

GeoStatsLib is a C++ geostatistics library focused on spatial interpolation and stochastic simulation workflows for environmental and subsurface modeling.

The repository includes:

• Core geostatistics headers under include/geostatslib/
• Utility components for geometry and nearest-neighbor search under include/utils/
• Examples for kriging and simulation under examples/
• Third-party dependencies under external/

Scope

GeoStatsLib provides algorithms for:

• Simple Kriging (SK)
• Ordinary Kriging (OK)
• Indicator Kriging (IK)
• Sequential Gaussian Simulation (sGs)
• Sequential Indicator Simulation (SIS)
• Supporting preprocessing methods such as histogram smoothing and declustering

The library is designed for uncertainty-aware modeling, where multiple equiprobable realizations are generated to quantify variability while honoring input data and inferred spatial continuity.

Stochastic Simulation Framework

The value of stochastic simulation lies in uncertainty evaluation through multiple equiprobable scenarios that honor both observed data and modeled spatial continuity.

Within this framework, GeoStatsLib implements two primary families of sequential simulation algorithms to address different variable types.

Sequential Gaussian Simulation (sGs)

Continuous variables (for example porosity, permeability, and concentration fields) are simulated using Sequential Gaussian Simulation.

Under the multi-Gaussian assumption, input data are transformed to standard normal space using normal-score transformation. Simulation then proceeds sequentially with local simple-kriging conditioning:

1. A random visiting path is defined over all unsampled locations.
2. At each location, a local conditional Gaussian distribution is estimated from nearby original data and already simulated values.
3. One value is sampled from that conditional distribution.
4. Final realizations are back-transformed to the original variable domain.

This procedure reproduces input statistics and spatial continuity while preserving stochastic variability.

Sequential Indicator Simulation (SIS)

Categorical variables (for example lithology or land-use classes) are simulated using Sequential Indicator Simulation.

Each class is represented by binary indicators, and local conditional probabilities are estimated by Indicator Kriging. Realizations are obtained through multinomial sampling from the local class probability vector.

This approach supports:

• Reproduction of class proportions
• Category-specific spatial structures
• Connectivity patterns
• Simulation without Gaussian assumptions

Unified Workflow Design

In GeoStatsLib, sGs and SIS follow a consistent data-driven workflow:

• Variography outputs are used as simulation inputs.
• Variable type is inferred from metadata and processing context.
• Processing is structured to improve traceability, reduce manual intervention, and increase reproducibility.

Spatial Support and Data Handling

GeoStatsLib is designed to work with flexible geometric support and simulation indexing strategies.

Key practical goals are:

• Support for complex and irregular spatial domains
• Compatibility with numerical modeling workflows
• Efficient storage of simulation outputs as indexed scalar values
• Interoperability with external post-processing pipelines

Preprocessing in the Stochastic Chain

As part of the stochastic workflow, GeoStatsLib includes:

1. Histogram smoothing
2. Declustering

Histogram smoothing can be performed with a simulated-annealing strategy to reduce sparse-distribution artifacts while preserving target moments.

Declustering is handled through cell-based weighting to correct spatial sampling bias by downweighting clustered data and improving representativity.

Repository Layout

include/
	geostatslib/
	utils/
examples/
	simple_kriging/
	ordinary_kriging/
	indicator_kr/
	indicator_sim/
	sGs_example/
	histogram_smoothing/
	mpi_sgs/
	mpi_sgs_gslib/
external/
	flann-lib/
	LBFGSpp-master/
	CVT/
	sobol_code/
	tetrahedron_grid/

Build

This repository contains multiple standalone example builds (each with its own CMakeLists.txt).

Typical example build flow:

cd examples/simple_kriging
cmake -S . -B build
cmake --build build -j
./build/main

Repeat the same pattern for other example folders.

Examples

Selected examples include:

• examples/simple_kriging/: Simple Kriging workflow
• examples/ordinary_kriging/: Ordinary Kriging workflow
• examples/indicator_kr/idkr/: Indicator Kriging for categorical analysis
• examples/indicator_sim/sis/: Sequential Indicator Simulation
• examples/sGs_example/: Sequential Gaussian Simulation
• examples/histogram_smoothing/: Histogram smoothing preprocessing
• examples/mpi_sgs/ and examples/mpi_sgs_gslib/: MPI-enabled simulation variants

License

GeoStatsLib is distributed under a dual-license model.

• Open-source use: GNU GPL v3.0 or later.
• Commercial use: available under a separate commercial license.

See the LICENSE and COPYING files for details.

Cite us

Citing us

GeoStatsLib is part of MUSE. If you use GeoStatsLib for you accademic activities, please cite the following, currently under review paper:

{
@article{MIOLA2026_muse,
title = {MUSE: A Mesh-Based Geostatistics Framework for Modeling Spatial Uncertainty},
journal = {Computers & Geosciences},
volume = {},
pages = {},
year = {},
issn = {},
doi = {},
url = {},
author = {Marianna Miola and Daniela Cabiddu and Simone Pittaluga and Marino {Vetuschi Zuccolini}}
}