gpmp.core module¶

The gpmp.core module defines gpmp.core.Model, the low-level GPmp object for exact Gaussian-process / kriging computations. A model stores a mean callable, a covariance callable, and their parameter vectors. From these objects it computes predictions, likelihood criteria, leave-one-out quantities, Fisher-information matrices, and sample paths.

gpmp.core does not choose covariance parameters. Parameter selection belongs to the gpmp.kernel module, which builds ML, REML, REMAP, and related criteria and updates model.covparam. The gpmp.parameter module is an optional display and inspection layer for parameter vectors. gpmp.core.Model works with plain backend arrays.

Mathematical description¶

For one scalar-valued output, GPmp represents observations with a model of the form

\[Z(x) = m(x) + Z_0(x),\]

where m is the mean component and Z_0 is a centered GP with covariance function k. The covariance parameters are stored in model.covparam. The mean parameters, when needed, are stored in model.meanparam.

Backend and shape contract¶

Inputs and outputs use the active gpmp.num backend unless a method documents conversion. With the NumPy backend they are NumPy arrays. With the torch backend they are PyTorch tensors.

The public methods use these shape conventions:

xi: observation points, shape (n, d).
zi: observations, shape (n,) or (n, 1). A column vector is reshaped to (n,) by input validation.
xt: prediction or simulation points, shape (m, d).
covparam: one-dimensional covariance-parameter vector.
meanparam: mean-parameter vector or None.

Methods with convert_in=True convert inputs through gpmp.num.asarray. predict returns NumPy arrays by default because convert_out=True. loo keeps backend arrays by default because convert_out=False. Conditional sample-path methods return NumPy arrays by default.

Model construction contract¶

Model(mean, covariance, meanparam=None, covparam=None, meantype="linear_predictor") expects a mean callable, a covariance callable, and parameter vectors.

The mean callable has signature

mean(x, meanparam)

Its return value depends on meantype:

"zero": mean must be None and meanparam is ignored.
"parameterized": mean(x, meanparam) returns mean values with shape (n,) or (n, 1). Prediction centers observations by this mean and adds the mean back at xt.
"linear_predictor": mean(x, meanparam) returns a design matrix P(x) with shape (n, q). This is the universal / intrinsic kriging case. The linear coefficients are eliminated by the kriging equations and by the restricted likelihood.

The covariance callable has signature

covariance(x, y, covparam, pairwise=False)

It returns:

a covariance matrix with shape (n, m) when pairwise=False.
elementwise covariances with shape (n,) when pairwise=True.
the self-covariance at x when y is None.

For backend-independent models, write mean and covariance with gpmp.num operations and constructors, not direct NumPy or torch calls.

Prediction¶

predict(xi, zi, xt, return_lambdas=False, zero_neg_variances=True, convert_in=True, convert_out=True) returns the posterior mean and marginal posterior variance at xt:

zpm, zpv = model.predict(xi, zi, xt)

zpm and zpv have shape (m,). If return_lambdas=True, the method also returns the kriging weights lambda_t with shape (n, m). Negative posterior variances can appear from roundoff. The method warns and clips them to zero by default.

Lower-level methods kriging_predictor_with_zero_mean and kriging_predictor return kriging weights and posterior variances or covariances. They are useful when a later computation needs the weights directly, for example conditioning sample paths.

Leave-one-out diagnostics¶

loo(xi, zi, convert_in=True, convert_out=False) computes virtual leave-one-out quantities without solving n separate model problems:

zloo, sigma2loo, eloo = model.loo(xi, zi)

The returned arrays have shape (n,). zloo contains leave-one-out predictions, sigma2loo contains leave-one-out variances, and eloo contains leave-one-out errors.

Likelihood criteria¶

The likelihood methods evaluate scalar criteria for fixed covariance parameters:

negative_log_likelihood_zero_mean(covparam, xi, zi) for meantype="zero".
negative_log_likelihood(meanparam, covparam, xi, zi) for a parameterized mean.
negative_log_restricted_likelihood(covparam, xi, zi) for a linear-predictor mean.

These methods do not optimize parameters. They are the criteria used by parameter-selection routines in gpmp.kernel.

Sample paths¶

sample_paths(xt, nb_paths, method="chol", check_result=True) draws unconditional centered GP sample paths at xt. The result has shape (m, nb_paths). method="chol" uses a Cholesky factorization and method="svd" uses an SVD-based square root.

Conditional sample paths are obtained by conditioning unconditional paths with kriging weights:

conditional_sample_paths for "zero" and "linear_predictor" mean types.
conditional_sample_paths_parameterized_mean for "parameterized" mean type.

Both methods take observed values, indices identifying observation and prediction locations in the unconditional path array, and the kriging-weight matrix.

Relation to parameter selection¶

The core object is intentionally parameter-explicit. It can evaluate likelihoods at a supplied covparam and it can predict once model.covparam has been set. It does not infer which covariance convention is being used and it does not choose starting points, bounds, priors, or optimizers. Those responsibilities belong to gpmp.kernel.

Public method reference¶

Low-level exact GP / kriging computations.

The public entry point is gpmp.core.Model. It stores mean and covariance callables, keeps their parameter vectors explicit, and exposes prediction, likelihood, leave-one-out, Fisher-information, and sample-path computations.

class gpmp.core.Model(mean, covariance, meanparam=None, covparam=None, meantype='linear_predictor')[source]¶

Low-level exact Gaussian-process / kriging model.

Model stores a mean callable, a covariance callable, and their parameter vectors. It does not select covariance parameters. Selection routines in gpmp.kernel can update covparam. The core model then evaluates likelihoods, predictions, leave-one-out quantities, and sample paths for those parameter values.

mean¶

Mean callable with signature mean(x, meanparam). For meantype="zero", mean must be None. For meantype="parameterized", it returns mean values. For meantype="linear_predictor", it returns the design matrix P(x) used by universal / intrinsic kriging.

Type:: callable or None

covariance¶

Covariance callable with signature covariance(x, y, covparam, pairwise=False). It returns a covariance matrix when pairwise=False and elementwise covariances when pairwise=True.

Type:: callable

meanparam¶

Parameter vector passed to the mean callable.

Type:: array_like, optional

covparam¶

One-dimensional covariance-parameter vector passed to the covariance callable.

Type:: array_like, optional

meantype¶

Mean handling mode: "zero", "parameterized", or "linear_predictor".

Type:: str, optional

Notes

Public methods use the active gpmp.num backend. Inputs are expected to follow the common GPmp convention xi.shape == (n, d), zi.shape == (n,) or (n, 1), and xt.shape == (m, d).

Main public methods:

predict: posterior mean and variance at target points.
loo: leave-one-out predictions via virtual cross-validation.
negative_log_likelihood_zero_mean: negative log-likelihood with zero mean.
negative_log_likelihood: negative log-likelihood with given mean.
negative_log_restricted_likelihood: REML criterion with a linear predictor.
norm_k_sqrd_with_zero_mean: RKHS norm z^T K^{-1} z for the zero-mean case.
norm_k_sqrd: RKHS norm with a linear predictor.
k_inverses: returns z^T K^{-1} z, K^{-1} 1, and K^{-1} z.
fisher_information: finite-difference Fisher information.
fisher_information_cpd: Fisher information in contrast space.
fisher_information_torch: Fisher information via second-order differentiation.
sample_paths: unconditional GP sample paths on target points.
conditional_sample_paths: conditioning by kriging.
conditional_sample_paths_parameterized_mean: conditioning with a parameterized mean.

Examples

>>> import gpmp as gp
>>> import gpmp.num as gnp
>>> mean = lambda x, meanparam: meanparam[0] + meanparam[1] * x.reshape(-1)
>>> def covariance(x, y, covparam, pairwise=False):
...     p = 0  # smoothness index for Matern nu=3/2
...     return gp.kernel.maternp_covariance(x, y, p, covparam, pairwise)
>>> model = gp.core.Model(
...     mean, covariance, meanparam=gnp.array([0.5, 0.2]),
...     covparam=gnp.array([1.0, 0.1]), meantype="parameterized")
>>> xi = gnp.array([0.0, 1.0, 2.0, 3.0, 5.0]).reshape(-1, 1)
>>> zi = gnp.array([0.0, 1.2, 2.5, 4.2, 4.3])
>>> xt = gnp.linspace(0.0, 5.0, 11).reshape(-1, 1)
>>> zt_mean, zt_var = model.predict(xi, zi, xt)

conditional_sample_paths(ztsim, xi_ind, zi, xt_ind, lambda_t, convert_out=True)[source]¶

Condition sample paths by kriging.

The unconditional path array ztsim must contain rows for both the observation locations and the conditional simulation locations. xi_ind and xt_ind identify those rows. The matrix lambda_t is usually obtained from predict(..., return_lambdas=True) or kriging_predictor.

Parameters:

ztsim (array_like, shape (n_all, nb_paths)) – Unconditional sample paths.
xi_ind (array_like, shape (n,)) – Row indices of observation locations in ztsim.
zi (array_like, shape (n,) or (n, 1)) – Observations.
xt_ind (array_like, shape (m,)) – Row indices of conditional simulation locations in ztsim.
lambda_t (array_like, shape (n, m)) – Kriging weights.
convert_out (bool, optional) – If True, convert output to a NumPy array.

Returns:

ztsimc – Conditional sample paths.

Return type:

array_like, shape (m, nb_paths)

Notes

This method is for meantype="zero" and meantype="linear_predictor". It implements conditioning by kriging as described in Chiles and Delfiner (1999).

conditional_sample_paths_parameterized_mean(ztsim, xi, xi_ind, zi, xt, xt_ind, lambda_t, convert_out=True)[source]¶

Condition sample paths for a parameterized mean.

Parameters:

ztsim (array_like, shape (n_all, nb_paths)) – Unconditional sample paths.
xi (array_like, shape (n, d)) – Observation points.
xi_ind (array_like, shape (n,)) – Row indices of observation locations in ztsim.
zi (array_like, shape (n,) or (n, 1)) – Observations at xi.
xt (array_like, shape (m, d)) – Conditional simulation points.
xt_ind (array_like, shape (m,)) – Row indices of conditional simulation locations in ztsim.
lambda_t (array_like, shape (n, m)) – Kriging weights.
convert_out (bool, optional) – If True, convert output to a NumPy array.

Returns:

ztsimc – Conditional sample paths adjusted for mean(x, meanparam).

Return type:

array_like, shape (m, nb_paths)

fisher_information(xi, covparam=None, epsilon=0.001)[source]¶

Compute Fisher information by finite differences.

Parameters:

xi (array_like, shape (n, d)) – Observation points.
covparam (array_like, shape (p,), optional) – Covariance-parameter vector. If None, use self.covparam.
epsilon (float, optional) – Central finite-difference step.

Returns:

fisher_info – Fisher information matrix.

Return type:

array_like, shape (p, p)

Notes

This method differentiates the covariance matrix with respect to covariance parameters by central finite differences. It is expensive when the number of covariance parameters is large.

fisher_information_cpd(xi, covparam=None, epsilon=0.001)[source]¶

Compute Fisher information with the CPD contrast-space route.

If the mean is of type “linear_predictor”, the information is computed in contrast space. Otherwise, the standard SPD formula with the covariance matrix is used.

Parameters:

xi (array_like, shape (n, d)) – Observation points.
covparam (array_like, shape (p,), optional) – Covariance-parameter vector. If None, use self.covparam.
epsilon (float, optional) – Central finite-difference step.

Returns:

I – Fisher information matrix.

Return type:

array_like, shape (p, p)

fisher_information_torch(xi, covparam)[source]¶

Compute Fisher information using torch second-order differentiation.

This method requires the torch backend.

k_inverses(xi, zi, covparam)[source]¶

Compute selected quantities involving the inverse covariance matrix.

Parameters:

xi (array_like, shape (n, d)) – Observation points.
zi (array_like, shape (n,)) – Observations at xi.
covparam (array_like, shape (p,)) – Covariance-parameter vector.

Returns:

zTKinvz (scalar) – Value of z^T K^{-1} z.
Kinv1 (array_like, shape (n,)) – Value of K^{-1} 1.
Kinvz (array_like, shape (n,)) – Value of K^{-1} z.

kriging_predictor(xi, xt, return_type=0)[source]¶

Compute kriging weights for a linear-predictor mean.

Parameters:

xi (array_like, shape (n, d)) – Observation points.
xt (array_like, shape (m, d)) – Prediction points.
return_type ({-1, 0, 1}, optional) – If -1, return no posterior variance. If 0, return marginal posterior variances. If 1, return the full posterior covariance matrix.

Returns:

lambda_t (array_like, shape (n, m)) – Kriging weights.
zt_posterior_variance (array_like or None) – Posterior variances, posterior covariance matrix, or None.

kriging_predictor_with_zero_mean(xi, xt, return_type=0)[source]¶

Compute kriging weights for a zero-mean model.

Parameters:

xi (array_like, shape (n, d)) – Observation points.
xt (array_like, shape (m, d)) – Prediction points.
return_type ({-1, 0, 1}, optional) – If -1, return no posterior variance. If 0, return marginal posterior variances. If 1, return the full posterior covariance matrix.

Returns:

lambda_t (array_like, shape (n, m)) – Kriging weights.
zt_posterior_variance (array_like or None) – Posterior variances, posterior covariance matrix, or None.

loo(xi, zi, convert_in=True, convert_out=False)[source]¶

Compute virtual leave-one-out predictions and errors.

The computation uses the virtual cross-validation formula. It does not refit the model n times.

Parameters:

xi (array_like, shape (n, d)) – Observation points.
zi (array_like, shape (n,) or (n, 1)) – Observations at xi.
convert_in (bool, optional) – If True, convert inputs with gpmp.num.asarray.
convert_out (bool, optional) – If True, convert outputs to NumPy arrays.

Returns:

zloo (array_like, shape (n,)) – Leave-one-out predictions at xi.
sigma2loo (array_like, shape (n,)) – Leave-one-out variances.
eloo (array_like, shape (n,)) – Leave-one-out prediction errors.

negative_log_likelihood(meanparam, covparam, xi, zi)[source]¶

Evaluate the negative log-likelihood with a parameterized mean.

Parameters:

meanparam (array_like) – Mean-parameter vector.
covparam (array_like, shape (p,)) – Covariance-parameter vector.
xi (array_like, shape (n, d)) – Observation points.
zi (array_like, shape (n,)) – Observations at xi.

Returns:

nll – Negative log-likelihood value.

Return type:

scalar

negative_log_likelihood_zero_mean(covparam, xi, zi)[source]¶

Evaluate the negative log-likelihood for a zero-mean model.

Parameters:

covparam (array_like, shape (p,)) – Covariance-parameter vector.
xi (array_like, shape (n, d)) – Observation points.
zi (array_like, shape (n,)) – Observations at xi.

Returns:

nll – Negative log-likelihood value.

Return type:

scalar

negative_log_restricted_likelihood(covparam, xi, zi)[source]¶

Evaluate the negative restricted log-likelihood.

This criterion is defined for meantype="linear_predictor". It eliminates the linear mean coefficients through contrasts and evaluates the likelihood in contrast space.

Parameters:

covparam (array_like, shape (p,)) – Covariance-parameter vector.
xi (array_like, shape (n, d)) – Observation points.
zi (array_like, shape (n,)) – Observations at xi.

Returns:

L – Negative log-restricted likelihood value.

Return type:

scalar

norm_k_sqrd(xi, zi, covparam)[source]¶

Compute the contrast-space squared norm for a linear predictor.

Parameters:

xi (array_like, shape (n, d)) – Observation points.
zi (array_like, shape (n,) or (n, 1)) – Observations at xi.
covparam (array_like, shape (p,)) – Covariance-parameter vector.

Returns:

norm_sqrd – Squared norm after eliminating the linear predictor.

Return type:

scalar

norm_k_sqrd_with_zero_mean(xi, zi, covparam)[source]¶

Compute z^T K^{-1} z for the zero-mean case.

Parameters:

xi (array_like, shape (n, d)) – Observation points.
zi (array_like, shape (n,)) – Observations at xi.
covparam (array_like, shape (p,)) – Covariance-parameter vector.

Returns:

norm_sqrd – Squared covariance-induced norm.

Return type:

scalar

predict(xi, zi, xt, return_lambdas=False, zero_neg_variances=True, convert_in=True, convert_out=True)[source]¶

Compute posterior mean and marginal variance at target points.

Parameters:

xi (array_like, shape (n, d)) – Observation points in input space.
zi (array_like, shape (n,) or (n, 1)) – Observations at xi.
xt (array_like, shape (m, d)) – Prediction points.
return_lambdas (bool, optional) – If True, also return the kriging weights.
zero_neg_variances (bool, optional) – If True, replace negative posterior variances by zero after issuing a warning. Small negative values can occur from numerical roundoff.
convert_in (bool, optional) – If True, convert inputs with gpmp.num.asarray.
convert_out (bool, optional) – If True, convert posterior mean and variance to NumPy arrays.

Returns:

z_posterior_mean (array_like, shape (m,)) – Posterior mean at xt.
z_posterior_variance (array_like, shape (m,)) – Marginal posterior variance at xt.
lambda_t (array_like, shape (n, m), optional) – Kriging weights, returned only when return_lambdas=True.

Notes

The mean is handled according to meantype:

"zero": zero-mean kriging.
"linear_predictor": universal / intrinsic kriging.
"parameterized": observations are centered by mean(xi, meanparam) before zero-mean kriging, then mean(xt, meanparam) is added back to the posterior mean.

sample_paths(xt, nb_paths, method='chol', check_result=True)[source]¶

Draw unconditional centered GP sample paths at target points.

Parameters:

xt (array_like, shape (m, d)) – Points where sample paths are evaluated.
nb_paths (int) – Number of sample paths to generate.
method ({"chol", "svd"}, optional) – Matrix factorization used to draw paths. "chol" uses a Cholesky factorization. "svd" uses an SVD-based square root.
check_result (bool, optional) – If True, check the Cholesky factorization result.

Returns:

ztsim – Unconditional centered sample paths.

Return type:

array_like, shape (m, nb_paths)