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.

property
base_sample_shape
¶ The shape of a base sample used for constructing posterior samples.
This function may be overwritten by subclasses in case base_sample_shape and event_shape do not agree (e.g. if the posterior is a Multivariate Gaussian that is not full rank).
 Return type
Size

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 mdim Tensor.
 Return type
Tensor

property
variance
¶ The variance of the posterior as a (b) x n x mdim 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 eventdim 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_shapedim Tensor of samples from the posterior.

property
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 multivariate Normal distributions.
A posterior based on GPyTorch’s multivariate Normal distributions.
 Parameters
mvn (
MultivariateNormal
) – A GPyTorch MultivariateNormal (singleoutput case) or MultitaskMultivariateNormal (multioutput case).

property
base_sample_shape
¶ The shape of a base sample used for constructing posterior samples.
 Return type
Size

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_shapedim 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 multioutput posterior.
 Parameters
posterior (
GPyTorchPosterior
) – The posterior over m outcomes to be scalarized. Supports tbatching.weights (
Tensor
) – A tensor of weights of size m.offset (
float
) – The offset of the affine transformation.
 Return type
 Returns
 The transformed (singleoutput) 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 mdim Tensor.
 Return type
Tensor

property
variance
¶ The variance of the posterior as a (b) x n x mdim 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 eventdim Tensor of samples from the posterior.

property
Higher Order GP Posterior¶

class
botorch.posteriors.higher_order.
HigherOrderGPPosterior
(mvn, joint_covariance_matrix, train_train_covar, test_train_covar, train_targets, output_shape, num_outputs)[source]¶ Bases:
botorch.posteriors.gpytorch.GPyTorchPosterior
Posterior class for a Higher order Gaussian process model [Zhe2019hogp]. Extends the standard GPyTorch posterior class by overwriting the rsample method. The posterior variance is handled internally by the HigherOrderGP model. HOGP is a tensorized GP model so the posterior covariance grows to be extremely large, but is highly structured, which means that we can exploit Kronecker identities to sample from the posterior using Matheron’s rule as described in [Doucet2010sampl]. In general, this posterior should ONLY be used for HOGP models that have highly structured covariances. It should also only be used internally when called from the HigherOrderGP.posterior(…) method.
A Posterior for HigherOrderGP models.
 Parameters
mvn (
MultivariateNormal
) – Posterior multivariate normal distributionjoint_covariance_matrix (
LazyTensor
) – Joint test train covariance matrix over the entire tensortrain_train_covar (
LazyTensor
) – covariance matrix of train points in the data spacetest_train_covar (
LazyTensor
) – covariance matrix of test x train points in the data spacetrain_targets (
Tensor
) – training responses vectorizedoutput_shape (
Size
) – shape output training responsesnum_outputs (
int
) – batch shaping of model

property
base_sample_shape
¶ The shape of a base sample used for constructing posterior samples.

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

rsample
(sample_shape=None, base_samples=None)[source]¶ Sample from the posterior (with gradients).
As the posterior covariance is difficult to draw from in this model, we implement Matheron’s rule as described in [Doucet2010sampl]. This may not work entirely correctly for deterministic base samples unless base samples are provided that are of shape n + 2 * n_train because the sampling method draws 2 * n_train samples as well as the standard n. samples.
 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_shapedim 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 samplelevel transform to a sample_shape x batch_shape x q x mdim 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 2tuple 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 2tuple 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
base_sample_shape
¶ The shape of a base sample used for constructing posterior samples.
 Return type
Size

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 mdim Tensor.
 Return type
Tensor

property
variance
¶ The variance of the posterior as a batch_shape x n x mdim 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 eventdim Tensor of samples from the posterior.