Add sum model

MANIFEST.in

@@ -1,4 +1,4 @@
 prune **
-recursive-include tests *.py
+recursive-include tests *.py *.txt
 recursive-include src/gstools *.py *.pyx
 include AUTHORS.md LICENSE README.md pyproject.toml setup.py

docs/source/conf.py

@@ -300,6 +300,7 @@ def setup(app):
         "../../examples/08_geo_coordinates/",
         "../../examples/09_spatio_temporal/",
         "../../examples/10_normalizer/",
+        "../../examples/11_sum_model/",
     ],
     # path where to save gallery generated examples
     "gallery_dirs": [
@@ -314,6 +315,7 @@ def setup(app):
         "examples/08_geo_coordinates/",
         "examples/09_spatio_temporal/",
         "examples/10_normalizer/",
+        "examples/11_sum_model/",
     ],
     # Pattern to search for example files
     "filename_pattern": r"\.py",

docs/source/tutorials.rst

@@ -22,6 +22,7 @@ explore its whole beauty and power.
    examples/08_geo_coordinates/index
    examples/09_spatio_temporal/index
    examples/10_normalizer/index
+   examples/11_sum_model/index
    examples/00_misc/index
 
 .. only:: html

examples/11_sum_model/00_simple_sum_model.py

@@ -0,0 +1,61 @@
+r"""
+Creating a Sum Model
+--------------------
+
+This tutorial demonstrates how to create and use sum models in GSTools.
+We'll combine a Spherical and a Gaussian covariance model to construct
+a sum model, visualize its variogram, and generate spatial random fields.
+
+Let's start with importing GSTools and setting up the domain size.
+"""
+
+import gstools as gs
+
+x = y = range(100)
+
+###############################################################################
+# First, we create two individual covariance models: a :any:`Spherical` model and a
+# :any:`Gaussian` model. The Spherical model with its short length scale
+# will emphasize small-scale variability, while the Gaussian model with a larger length scale
+# captures larger-scale patterns.
+
+m0 = gs.Spherical(dim=2, var=2.0, len_scale=5.0)
+m1 = gs.Gaussian(dim=2, var=1.0, len_scale=10.0)
+
+###############################################################################
+# Next, we create a sum model by adding these two models together.
+# Let's visualize the resulting variogram alongside the individual models.
+
+model = m0 + m1
+ax = model.plot(x_max=20)
+m0.plot(x_max=20, ax=ax)
+m1.plot(x_max=20, ax=ax)
+
+###############################################################################
+# As shown, the Spherical model controls the behavior at shorter distances,
+# while the Gaussian model dominates at longer distances. The ratio of influence
+# is thereby controlled by the provided variances of the individual models.
+#
+# Using the sum model, we can generate a spatial random field. Let's visualize
+# the field created by the sum model.
+
+srf = gs.SRF(model, seed=20250107)
+srf.structured((x, y))
+srf.plot()
+
+###############################################################################
+# For comparison, we generate random fields using the individual models
+# to observe their contributions more clearly.
+
+srf0 = gs.SRF(m0, seed=20250107)
+srf0.structured((x, y))
+srf0.plot()
+
+srf1 = gs.SRF(m1, seed=20250107)
+srf1.structured((x, y))
+srf1.plot()
+
+###############################################################################
+# As seen, the Gaussian model introduces large-scale structures, while the
+# Spherical model influences the field's roughness. The sum model combines
+# these effects, resulting in a field that reflects multi-scale variability.

examples/11_sum_model/01_fitting_sum_model.py

@@ -0,0 +1,80 @@
+r"""
+Fitting a Sum Model
+--------------------
+
+In this tutorial, we demonstrate how to fit a sum model consisting of two
+covariance models to an empirical variogram.
+
+We will generate synthetic data, compute an empirical variogram, and fit a
+sum model combining a Spherical and Gaussian model to it.
+"""
+
+import gstools as gs
+
+x = y = range(100)
+
+###############################################################################
+# First, we create a synthetic random field based on a known sum model.
+# This will serve as the ground truth for fitting.
+
+# Define the true sum model
+m0 = gs.Spherical(dim=2, var=2.0, len_scale=5.0)
+m1 = gs.Gaussian(dim=2, var=1.0, len_scale=10.0)
+true_model = m0 + m1
+
+# Generate synthetic field
+srf = gs.SRF(true_model, seed=20250405)
+field = srf.structured((x, y))
+
+###############################################################################
+# Next, we calculate the empirical variogram from the synthetic data.
+
+# Compute empirical variogram
+bin_center, gamma = gs.vario_estimate((x, y), field)
+
+###############################################################################
+# Now we define a sum model to fit to the empirical variogram.
+# Initially, the parameters of the models are arbitrary.
+#
+# A sum model can also be created by a list of model classes together with
+# the common arguments (like dim in this case).
+
+fit_model = gs.SumModel(gs.Spherical, gs.Gaussian, dim=2)
+
+###############################################################################
+# We fit the sum model to the empirical variogram using GSTools' built-in
+# fitting capabilities. We deactivate the nugget fitting to not overparameterize
+# our model.
+
+fit_model.fit_variogram(bin_center, gamma, nugget=False)
+print(f"{true_model=}")
+print(f" {fit_model=}")
+
+###############################################################################
+# The variance of a sum model is the sum of the sub variances (:any:`SumModel.vars`)
+# from the contained models. The length scale is a weighted sum of the sub
+# length scales (:any:`SumModel.len_scales`) where the weights are the ratios
+# of the sub variances to the total variance of the sum model.
+
+print(f"{true_model.var=:.2}, {true_model.len_scale=:.2}")
+print(f" {fit_model.var=:.2},  {fit_model.len_scale=:.2}")
+
+###############################################################################
+# After fitting, we can visualize the empirical variogram alongside the
+# fitted sum model and its components. A Sum Model is subscriptable to access
+# the individual models its contains.
+
+ax = fit_model.plot(x_max=max(bin_center))
+ax.scatter(bin_center, gamma)
+# Extract individual components
+fit_model[0].plot(x_max=max(bin_center), ax=ax)
+fit_model[1].plot(x_max=max(bin_center), ax=ax)
+# True models
+true_model.plot(x_max=max(bin_center), ax=ax, ls="--", c="C0", label="")
+true_model[0].plot(x_max=max(bin_center), ax=ax, ls="--", c="C1", label="")
+true_model[1].plot(x_max=max(bin_center), ax=ax, ls="--", c="C2", label="")
+
+###############################################################################
+# As we can see, the fitted sum model closely matches the empirical variogram,
+# demonstrating its ability to capture multi-scale variability effectively.
+# The "true" variograms are shown with dashed lines for comparison.

examples/11_sum_model/README.rst

@@ -0,0 +1,30 @@
+Summing Covariance Models
+=========================
+
+In geostatistics, the spatial relations of natural phenomena is often represented using covariance models,
+which describe how values of a property correlate over distance.
+A single covariance model may capture specific features of the spatial correlation, such as smoothness or the range of influence.
+However, many real-world spatial processes are complex, involving multiple overlapping structures
+that cannot be adequately described by a single covariance model.
+
+This is where **sum models** come into play.
+A sum model combines multiple covariance models into a single representation,
+allowing for a more flexible and comprehensive description of spatial variability.
+By summing covariance models, we can:
+
+1. **Capture Multi-Scale Variability:** Many spatial phenomena exhibit variability at different scales.
+   For example, soil properties may have small-scale variation due to local heterogeneities and large-scale variation due to regional trends.
+   A sum model can combine short-range and long-range covariance models to reflect this behavior.
+2. **Improve Model Fit and Prediction Accuracy:** By combining models, sum models can better match empirical variograms or other observed data,
+   leading to more accurate predictions in kriging or simulation tasks.
+3. **Enhance Interpretability:** Each component of a sum model can be associated with a specific spatial process or scale,
+   providing insights into the underlying mechanisms driving spatial variability.
+
+The new :any:`SumModel` introduced in GSTools makes it straightforward to define and work with such composite covariance structures.
+It allows users to combine any number of base models, each with its own parameters, in a way that is both intuitive and computationally efficient.
+
+In the following tutorials, we'll explore how to use the :any:`SumModel` in GSTools,
+including practical examples that demonstrate its utility in different scenarios.
+
+Examples
+--------

pyproject.toml

@@ -157,7 +157,7 @@ target-version = [
     max-locals = 50
     max-branches = 30
     max-statements = 85
-    max-attributes = 25
+    max-attributes = 30
     max-public-methods = 80
     max-positional-arguments=20
 

src/gstools/__init__.py

@@ -54,6 +54,7 @@
 
 .. autosummary::
    CovModel
+   SumModel
 
 Covariance Models
 ^^^^^^^^^^^^^^^^^
@@ -62,6 +63,7 @@
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. autosummary::
+   Nugget
    Gaussian
    Exponential
    Matern
@@ -153,9 +155,11 @@
     JBessel,
     Linear,
     Matern,
+    Nugget,
     Rational,
     Spherical,
     Stable,
+    SumModel,
     SuperSpherical,
     TPLExponential,
     TPLGaussian,
@@ -198,6 +202,8 @@
 __all__ += ["transform", "normalizer", "config"]
 __all__ += [
     "CovModel",
+    "SumModel",
+    "Nugget",
     "Gaussian",
     "Exponential",
     "Matern",

src/gstools/covmodel/__init__.py

@@ -19,6 +19,7 @@
    :toctree:
 
    CovModel
+   SumModel
 
 Covariance Models
 ^^^^^^^^^^^^^^^^^
@@ -27,6 +28,7 @@
 .. autosummary::
    :toctree:
 
+   Nugget
    Gaussian
    Exponential
    Matern
@@ -53,7 +55,7 @@
    TPLSimple
 """
 
-from gstools.covmodel.base import CovModel
+from gstools.covmodel.base import CovModel, SumModel
 from gstools.covmodel.models import (
     Circular,
     Cubic,
@@ -64,6 +66,7 @@
     JBessel,
     Linear,
     Matern,
+    Nugget,
     Rational,
     Spherical,
     Stable,
@@ -78,6 +81,8 @@
 
 __all__ = [
     "CovModel",
+    "SumModel",
+    "Nugget",
     "Gaussian",
     "Exponential",
     "Matern",