.. _physics-variogram:

Variograms
==========

Class providing variogram models for Gaussian Process (GP) regression---parametric functions :math:`\gamma(h)` that describe how the variance of a random field increases with separation :math:`h` between evaluation points. Variograms are fitted to empirical semi-variance data and used to define the GP covariance kernel for interpolating or emulating expensive model predictions across parameter space. Implementations include spherical, exponential, and Gaussian variogram families, with methods to fit model parameters and evaluate the semi-variance at any separation.

**Default implementation:** ``variogramSpherical``

Methods
-------

``fit`` → ``void``
   Fit the variogram model parameters to the provided empirical semi-variance data (separation distances and corresponding semi-variances), using the default fitting strategy for this model.

   * ``double precision, intent(in ), dimension(:) :: separations, semiVariances``

``fitGeneric`` → ``void``
   Fit a generic variogram model to the provided separation and semi-variance data using the specified fitting option (mean, median, or maximum), returning the best-fit parameter vector :math:`C` for the model.

   * ``type (enumerationVariogramFitOptionType), intent(in ) :: variogramFitOption``

   * ``double precision , intent(in ) , dimension(:) :: separations , semiVariances``

   * ``double precision , intent( out), allocatable, dimension(:) :: C``

``countParameters`` → ``integer(c_size_t)``
   Return the number of free parameters in the variogram model, which determines the dimension of the parameter vector :math:`C` passed to and returned from the fitting and evaluation methods.

``modelInitialGuess`` → ``double precision, allocatable, dimension(:)``
   Provide an initial guess for the parameters, :math:`C`, of the variogram model.

   * ``double precision, intent(in ), dimension(:) :: separations, semiVariances``

``modelF`` → ``double precision``
   Evaluate the loss function, :math:`f`, of the variogram model for the given parameters, :math:`C`, and separations and semi-variances.

   * ``double precision, intent(in ), dimension(:) :: C, separations, semivariances``

``modelDF`` → ``double precision, allocatable, dimension(:)``
   Evaluate the gradients of the loss function, :math:`\partial f/\partial C`, of the variogram model for the given parameters, :math:`C`, and separations and semi-variances.

   * ``double precision, intent(in ), dimension(:) :: C, separations, semivariances``

``modelFDF`` → ``void``
   Evaluate the loss function, :math:`f`, and its gradients, :math:`\partial f/\partial C`, of the variogram model for the given parameters, :math:`C`, and separations and semi-variances.

   * ``double precision, intent(in ) , dimension(:) :: C , separations, semivariances``

   * ``double precision, intent( out) :: f``

   * ``double precision, intent( out), allocatable, dimension(:) :: dfdC``

``variogram`` → ``double precision``
   Returns the variogram evaluated at the given separation. If no separation is provided the result for infinite separation is returned.

   * ``double precision, intent(in ), optional :: separation``

``correlation`` → ``double precision``
   Return the correlation coefficient :math:`C(h) = 1 - \gamma(h)/\gamma(\infty)` evaluated at the given separation :math:`h`, where :math:`\gamma(h)` is the semi-variance and :math:`\gamma(\infty)` is the sill, used to construct GP covariance matrices.

   * ``double precision, intent(in ) :: separation``

.. _physics-variogramExponential:

``variogramExponential``
------------------------

An exponential variogram model in which the variogram is given by:

.. math::

   C(r) = C_0 + C_1 \left[ 1 - \exp\left( - \frac{r}{C_\mathrm{r}} \right) \right],

where :math:`r` is the separation, and :math:`(C_0,C_1,C_\mathrm{r})` are parameters of the model.

**Parameters**

* ``[variogramFitOption]`` (string; one of ``mean``, ``median``, ``maximum``; default ``median``) — Option controlling how the binned semi-variance data are aggregated before fitting the exponential variogram model; allowed values are ``mean``, ``median`` (default), or ``maximum`` of the residuals within each separation bin.
* ``[assumeZeroVarianceAtZeroLag]`` (boolean; default ``.false.``) — If true, the variogram model is forced to go to zero for states with zero separation (as expected if the likelihood model being emulated is fully deterministic). Otherwise, the variance at zero separation is treated as a free parameter.

.. _physics-variogramGaussian:

``variogramGaussian``
---------------------

A Gaussian variogram model in which the variogram is given by:

.. math::

   C(r) = C_0 + C_1 \left[ 1 - \exp\left( - \frac{r^2}{C_\mathrm{r}^2} \right) \right],

where :math:`r` is the separation, and :math:`(C_0,C_1,C_\mathrm{r})` are parameters of the model.

**Parameters**

* ``[variogramFitOption]`` (string; one of ``mean``, ``median``, ``maximum``; default ``median``) — Option controlling how the binned semi-variance data are aggregated before fitting the Gaussian variogram model; allowed values are ``mean``, ``median`` (default), or ``maximum`` of the residuals within each separation bin.
* ``[assumeZeroVarianceAtZeroLag]`` (boolean; default ``.false.``) — If true, the variogram model is forced to go to zero for states with zero separation (as expected if the likelihood model being emulated is fully deterministic). Otherwise, the variance at zero separation is treated as a free parameter.

.. _physics-variogramSpherical:

``variogramSpherical``
----------------------

A spherical variogram model in which the variogram is given by:

.. math::

   C(r) = C_0 + C_1 \left[ \frac{3}{2} \frac{r}{C_\mathrm{r}} - \frac{1}{2} \left(\frac{r}{C_\mathrm{r}}\right)^3  \right],

where :math:`r` is the separation, and :math:`(C_0,C_1,C_\mathrm{r})` are parameters of the model.

**(Default implementation)**

**Methods**

* ``next`` — Move to the next cell in the domain.

**Parameters**

* ``[variogramFitOption]`` (string; one of ``mean``, ``median``, ``maximum``; default ``median``) — Option controlling how the binned semi-variance data are aggregated before fitting the spherical variogram model; allowed values are ``mean``, ``median`` (default), or ``maximum`` of the residuals within each separation bin.
* ``[assumeZeroVarianceAtZeroLag]`` (boolean; default ``.false.``) — If true, the variogram model is forced to go to zero for states with zero separation (as expected if the likelihood model being emulated is fully deterministic). Otherwise, the variance at zero separation is treated as a free parameter.