Runtime settings#

Quantile gap lower bound#

class gpytorch_qr.settings.quantile_gap_lower_bound(value)[source]

Set the minimum center-gap quantile slope.

Within this context, every adjacent center-gap quantile difference is transformed as

\[\operatorname{softplus}(\mathrm{raw\_gap}) + \mathrm{lower\_bound} \, \Delta q.\]

The setting is read when center-gap latent values are converted to quantiles, so the context must enclose likelihood evaluation and posterior prediction. Nested contexts restore the previously active value on exit.

Parameters:

valuefloat: A finite, non-negative lower bound. The default outside a context is 0.0.

Examples

>>> import gpytorch_qr
>>> with gpytorch_qr.settings.quantile_gap_lower_bound(1e-4):
...     gpytorch_qr.settings.quantile_gap_lower_bound.value()
0.0001

classmethod value(): Return the currently active value.

For center-gap models, the setting changes each adjacent quantile gap from

\[\operatorname{softplus}(\mathrm{raw\_gap})\]

\[\operatorname{softplus}(\mathrm{raw\_gap}) + \mathrm{lower\_bound}\,\Delta q,\]

where \(\Delta q\) is the difference between the corresponding adjacent quantile levels. The default is 0.0, which preserves the original center-gap transformation.

The setting is read when latent center-gap values are converted to quantiles, not when the model or likelihood is constructed. Enclose both likelihood evaluation during training and posterior sampling or summary computation during prediction:

import gpytorch_qr

with gpytorch_qr.settings.quantile_gap_lower_bound(1e-4):
    output = model(train_x)
    loss = -mll(output, train_y)

    posterior = model.joint_quantile_posterior(test_x)
    samples = posterior.sample()
    mean = model.mean_quantiles_delta(test_x)

CenterGapQuantileGP must receive quantile_levels when a nonzero bound is used, because posterior conversion needs the adjacent level differences. The center-gap likelihood already receives quantile levels in its constructor.

Nested contexts are supported and restore the outer value:

with gpytorch_qr.settings.quantile_gap_lower_bound(1e-4):
    # value is 1e-4
    with gpytorch_qr.settings.quantile_gap_lower_bound(1e-3):
        # value is 1e-3
        pass
    # value is 1e-4 again

Quantile reconstruction dtype#

class gpytorch_qr.settings.quantile_reconstruction_dtype(dtype)[source]

Set the dtype used to reconstruct center-gap quantiles.

The center, raw gaps, and quantile-level offsets are converted before the softplus, cumulative-sum, and addition operations. The reconstructed quantiles retain the selected dtype. This prevents a small gap from being rounded away when it is added to a large central quantile.

Parameters:

dtypetorch.dtype or None: A real floating-point dtype. None preserves the dtype of the latent center and gaps and is the default.

classmethod value(): Return the currently active value.

A lower bound can be smaller than the spacing between representable values at the magnitude of a central quantile. For example, adding a gap of 1e-5 to 1000.0 in float32 produces 1000.0 again. Use quantile_reconstruction_dtype to perform the center-gap reconstruction in a higher-precision dtype:

import torch
import gpytorch_qr

with (
    gpytorch_qr.settings.quantile_gap_lower_bound(1e-4),
    gpytorch_qr.settings.quantile_reconstruction_dtype(torch.float64),
):
    posterior = model.joint_quantile_posterior(test_x)
    samples = posterior.sample()
    mean = model.mean_quantiles_delta(test_x)

The conversion happens before softplus, cumulative sums, and additions. The returned quantiles retain the configured dtype; casting them back to a lower precision can collapse the gaps again. The default value is None, which preserves the latent input dtype. This setting changes only center-gap reconstruction precision, not GP covariance computation or posterior sampling precision.

Strict quantile ordering#

class gpytorch_qr.settings.enforce_strict_quantile_order(state=True)[source]

Enforce representably distinct center-gap quantile predictions.

When enabled, each predicted quantile is at least the next representable floating-point value above the preceding quantile. The correction is applied independently to each output dimension and only to model posterior predictions, not to the training likelihood.

This is an inference-oriented, dtype-dependent correction. It guarantees strict order for finite predictions but does not preserve a requested mathematical gap when that gap is smaller than one ULP.

Parameters:

statebool, default=True: Whether to enable strict quantile ordering.

classmethod value(): Return the currently active value.

enforce_strict_quantile_order applies a final torch.nextafter-based correction to center-gap model posterior predictions. Every quantile is made at least the next representable value above its predecessor:

with gpytorch_qr.settings.enforce_strict_quantile_order():
    quantiles = model.mean_quantiles_delta(test_x)

The correction is applied independently within each output dimension. It does not affect center-gap likelihood evaluation during training. It guarantees strict order for finite model predictions, but a corrected gap may be one ULP rather than quantile_gap_lower_bound * delta_q. Consequently, this setting is intended for inference and export, not as a differentiable training constraint. Because the correction is not invertible, transformed-posterior log_prob and inverse-transform operations are unavailable while it is enabled.

Strict ordering is guaranteed at the point where GPyTorch-QR returns the model prediction. Subsequent low-precision operations, such as adding a large external mean or casting to float32, can collapse gaps again. Apply any such operations before the final ordering correction, or retain the higher reconstruction dtype.