botorch.posteriors

Posterior APIs

Abstract Posterior API

Abstract base module for all botorch posteriors.

class botorch.posteriors.posterior.Posterior[source]

Bases: abc.ABC

Abstract base class for botorch posteriors.

abstract property device

The torch device of the posterior.

Return type

device

abstract property dtype

The torch dtype of the posterior.

Return type

dtype

abstract property event_shape

The event shape (i.e. the shape of a single sample).

Return type

Size

property mean

The mean of the posterior as a (b) x n x m-dim Tensor.

Return type

Tensor

property variance

The variance of the posterior as a (b) x n x m-dim Tensor.

Return type

Tensor

abstract rsample(sample_shape=None, base_samples=None)[source]

Sample from the posterior (with gradients).

Parameters

  • sample_shape (Optional[Size]) – A torch.Size object specifying the sample shape. To draw n samples, set to torch.Size([n]). To draw b batches of n samples each, set to torch.Size([b, n]).

  • base_samples (Optional[Tensor]) – An (optional) Tensor of N(0, I) base samples of appropriate dimension, typically obtained from a Sampler. This is used for deterministic optimization.

Return type

Tensor

Returns

A sample_shape x event-dim Tensor of samples from the posterior.

sample(sample_shape=None, base_samples=None)[source]

Sample from the posterior (without gradients).

This is a simple wrapper calling rsample using with torch.no_grad().

Parameters

  • sample_shape (Optional[Size]) – A torch.Size object specifying the sample shape. To draw n samples, set to torch.Size([n]). To draw b batches of n samples each, set to torch.Size([b, n]).

  • base_samples (Optional[Tensor]) – An (optional) Tensor of N(0, I) base samples of appropriate dimension, typically obtained from a Sampler object. This is used for deterministic optimization.

Return type

Tensor

Returns

A sample_shape x event_shape-dim Tensor of samples from the posterior.

Posteriors

GPyTorch Posterior

Posterior Module to be used with GPyTorch models.

class botorch.posteriors.gpytorch.GPyTorchPosterior(mvn)[source]

Bases: botorch.posteriors.posterior.Posterior

A posterior based on GPyTorch’s multi-variate Normal distributions.

A posterior based on GPyTorch’s multi-variate Normal distributions.

Parameters

mvn (MultivariateNormal) – A GPyTorch MultivariateNormal (single-output case) or MultitaskMultivariateNormal (multi-output case).

property device

The torch device of the posterior.

Return type

device

property dtype

The torch dtype of the posterior.

Return type

dtype

property event_shape

The event shape (i.e. the shape of a single sample) of the posterior.

Return type

Size

rsample(sample_shape=None, base_samples=None)[source]

Sample from the posterior (with gradients).

Parameters

  • sample_shape (Optional[Size]) – A torch.Size object specifying the sample shape. To draw n samples, set to torch.Size([n]). To draw b batches of n samples each, set to torch.Size([b, n]).

  • base_samples (Optional[Tensor]) – An (optional) Tensor of N(0, I) base samples of appropriate dimension, typically obtained from a Sampler. This is used for deterministic optimization.

Return type

Tensor

Returns

A sample_shape x event_shape-dim Tensor of samples from the posterior.

property mean

The posterior mean.

Return type

Tensor

property variance

The posterior variance.

Return type

Tensor

botorch.posteriors.gpytorch.scalarize_posterior(posterior, weights, offset=0.0)[source]

Affine transformation of a multi-output posterior.

Parameters

  • posterior (GPyTorchPosterior) – The posterior to be transformed. Must be single-point (q=1). Supports t-batching.

  • weights (Tensor) – An single-dimensional tensor of weights. Number of elements must be the numbe of outputs of the posterior.

  • offset (float) – The offset of the affine transformation.

Return type

GPyTorchPosterior

Returns

The transformed (single-output) posterior. If the input posterior has

mean mu and covariance matrix Sigma, this posterior has mean weights^T * mu and variance weights^T Sigma w.

Example

Example for a model with two outcomes:

>>> X = torch.rand(1, 2)
>>> posterior = model.posterior(X)
>>> weights = torch.tensor([0.5, 0.25])
>>> new_posterior = scalarize_posterior(posterior, weights=weights)

Determinstic Posterior

Deterministic (degenerate) posteriors. Used in conjunction with deterministic models.

class botorch.posteriors.deterministic.DeterministicPosterior(values)[source]

Bases: botorch.posteriors.posterior.Posterior

Deterministic posterior.

property device

The torch device of the posterior.

Return type

device

property dtype

The torch dtype of the posterior.

Return type

dtype

property event_shape

The event shape (i.e. the shape of a single sample).

Return type

Size

property mean

The mean of the posterior as a (b) x n x m-dim Tensor.

Return type

Tensor

property variance

The variance of the posterior as a (b) x n x m-dim Tensor.

As this is a deterministic posterior, this is a tensor of zeros.

Return type

Tensor

rsample(sample_shape=None, base_samples=None)[source]

Sample from the posterior (with gradients).

For the deterministic posterior, this just returns the values expanded to the requested shape.

Parameters

  • sample_shape (Optional[Size]) – A torch.Size object specifying the sample shape. To draw n samples, set to torch.Size([n]). To draw b batches of n samples each, set to torch.Size([b, n]).

  • base_samples (Optional[Tensor]) – An (optional) Tensor of N(0, I) base samples of appropriate dimension, typically obtained from a Sampler. Ignored in construction of the samples (used only for shape validation).

Return type

Tensor

Returns

A sample_shape x event-dim Tensor of samples from the posterior.

Transformed Posterior

class botorch.posteriors.transformed.TransformedPosterior(posterior, sample_transform, mean_transform=None, variance_transform=None)[source]

Bases: botorch.posteriors.posterior.Posterior

An generic transformation of a posterior (implicitly represented)

An implicitly represented transformed posterior

Parameters

  • posterior (Posterior) – The posterior object to be transformed.

  • sample_transform (Callable[[Tensor], Tensor]) – A callable applying a sample-level transform to a sample_shape x batch_shape x q x m-dim tensor of samples from the original posterior, returning a tensor of samples of the same shape.

  • mean_transform (Optional[Callable[[Tensor, Tensor], Tensor]]) – A callable transforming a 2-tuple of mean and variance (both of shape batch_shape x m x o) of the original posterior to the mean of the transformed posterior.

  • variance_transform (Optional[Callable[[Tensor, Tensor], Tensor]]) – A callable transforming a 2-tuple of mean and variance (both of shape batch_shape x m x o) of the original posterior to a variance of the transformed posterior.

property device

The torch device of the posterior.

Return type

device

property dtype

The torch dtype of the posterior.

Return type

dtype

property event_shape

The event shape (i.e. the shape of a single sample).

Return type

Size

property mean

The mean of the posterior as a batch_shape x n x m-dim Tensor.

Return type

Tensor

property variance

The variance of the posterior as a batch_shape x n x m-dim Tensor.

Return type

Tensor

rsample(sample_shape=None, base_samples=None)[source]

Sample from the posterior (with gradients).

Parameters

  • sample_shape (Optional[Size]) – A torch.Size object specifying the sample shape. To draw n samples, set to torch.Size([n]). To draw b batches of n samples each, set to torch.Size([b, n]).

  • base_samples (Optional[Tensor]) – An (optional) Tensor of N(0, I) base samples of appropriate dimension, typically obtained from a Sampler. This is used for deterministic optimization.

Return type

Tensor

Returns

A sample_shape x event-dim Tensor of samples from the posterior.