.. _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** * ``[nonAnalyticSolver]`` (default ``var_str('fallThrough')``) — Selects how solutions are computed when no analytic solution is available. If set to "``fallThrough``" then the solution ignoring heating is used, while if set to "``numerical``" then numerical solvers are used to find solutions. * ``[radiusFractionalDecay]`` (default ``1.0d0``) — The truncation scale radius expressed as a fraction of the virial radius; the exponentially truncated dark matter profile decays as :math:`\exp(-r/r_\mathrm{trunc})` for :math:`r > r_\mathrm{trunc} =` ``[radiusFractionalDecay]`` :math:`\times r_\mathrm{virial}`, suppressing the profile at large radii. * ``[variogramFitOption]`` (default ``var_str('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]`` (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. * ``[radiusTruncateMinimum]`` — The minimum radius to begin truncating the density profile. * ``[radiusTruncateDecay]`` — The exponential decay scale for truncating the density profile. * ``[nonAnalyticSolver]`` (default ``var_str('fallThrough')``) — Selects how solutions are computed when no analytic solution is available. * ``[componentType]`` (default ``var_str('unknown')``) — The component type that this mass distribution represents. * ``[massType]`` (default ``var_str('unknown')``) — The mass type that this mass distribution represents. .. _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]`` (default ``var_str('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]`` (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** * ``[boundaries]`` (default ``[+0.0d0,+1.0d0]``) — A two-element array :math:`[r_\mathrm{min}, r_\mathrm{max}]` specifying the radial extent of the spherically symmetric computational domain. * ``[countCells]`` (default ``3_c_size_t``) — The number of radial grid cells in the spherically symmetric computational domain, controlling the radial resolution of the radiative transfer calculation. * ``[convergencePercentile]`` (default ``0.99d0``) — The percentile of cells (between 0 and 1) used in assessing convergence; only this fraction of cells must satisfy the convergence threshold, allowing outlier cells to be excluded. * ``[convergenceThreshold]`` (default ``2.0d0``) — The threshold value for the convergence measure; the spherical domain is considered converged when the specified percentile of cells has a convergence metric below this value. * ``[convergenceRatioThreshold]`` (default ``1.1d0``) — The threshold for the ratio of the convergence criterion between successive iterations; convergence is accepted when this ratio falls below the threshold, indicating the solution is no longer changing significantly. * ``[boundaries]`` (default ``[0.0d0,1.0d0]``) — A two-element array :math:`[r_\mathrm{min}, r_\mathrm{max}]` specifying the radial extent of the spherically symmetric integration domain. * ``[variogramFitOption]`` (default ``var_str('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]`` (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.