botorch.acquisition¶

Abstract base class for acquisition functions.

Constructor for the AcquisitionFunction base class.

Parameters

model (Model) – A fitted model.

abstract forward(X)[source]¶

Evaluate the acquisition function on the candidate set X.

Parameters

X (Tensor) – A (b) x q x d-dim Tensor of (b) t-batches with q d-dim design points each.

Return type

Tensor

Returns

A (b)-dim Tensor of acquisition function values at the given design points X.

set_X_pending(X_pending=None)[source]¶

Informs the acquisition function about pending design points.

Parameters

X_pending (Optional[Tensor]) – m x d Tensor with m d-dim design points that have been submitted for evaluation but have not yet been evaluated.

Return type

None

Base class for analytic acquisition functions.

Base constructor for analytic acquisition functions.

Parameters

• model (Model) – A fitted single-outcome model.

• objective (Optional[ScalarizedObjective]) – A ScalarizedObjective (optional).

set_X_pending(X_pending=None)[source]¶

Informs the acquisition function about pending design points.

Parameters

X_pending (Optional[Tensor]) – m x d Tensor with m d-dim design points that have been submitted for evaluation but have not yet been evaluated.

Return type

None

Single-outcome Expected Improvement (analytic).

Computes classic Expected Improvement over the current best observed value, using the analytic formula for a Normal posterior distribution. Unlike the MC-based acquisition functions, this relies on the posterior at single test point being Gaussian (and require the posterior to implement mean and variance properties). Only supports the case of q=1. The model must be single-outcome.

EI(x) = E(max(y - best_f, 0)), y ~ f(x)

Example

>>> model = SingleTaskGP(train_X, train_Y)
>>> EI = ExpectedImprovement(model, best_f=0.2)
>>> ei = EI(test_X)

Single-outcome Expected Improvement (analytic).

Parameters

• model (Model) – A fitted single-outcome model.

• best_f (Union[float, Tensor]) – Either a scalar or a b-dim Tensor (batch mode) representing the best function value observed so far (assumed noiseless).

• objective (Optional[ScalarizedObjective]) – A ScalarizedObjective (optional).

• maximize (bool) – If True, consider the problem a maximization problem.

forward(X)[source]¶

Evaluate Expected Improvement on the candidate set X.

Parameters

X (Tensor) – A b1 x … bk x 1 x d-dim batched tensor of d-dim design points. Expected Improvement is computed for each point individually, i.e., what is considered are the marginal posteriors, not the joint.

Return type

Tensor

Returns

A b1 x … bk-dim tensor of Expected Improvement values at the given design points X.

Single-outcome Posterior Mean.

Only supports the case of q=1. Requires the model’s posterior to have a mean property. The model must be single-outcome.

Example

>>> model = SingleTaskGP(train_X, train_Y)
>>> PM = PosteriorMean(model)
>>> pm = PM(test_X)

Base constructor for analytic acquisition functions.

Parameters

• model (Model) – A fitted single-outcome model.

• objective (Optional[ScalarizedObjective]) – A ScalarizedObjective (optional).

forward(X)[source]¶

Evaluate the posterior mean on the candidate set X.

Parameters

X (Tensor) – A (b) x 1 x d-dim Tensor of (b) t-batches of d-dim design points each.

Return type

Tensor

Returns

A (b)-dim Tensor of Posterior Mean values at the given design points X.

Single-outcome Probability of Improvement.

Probability of improvment over the current best observed value, computed using the analytic formula under a Normal posterior distribution. Only supports the case of q=1. Requires the posterior to be Gaussian. The model must be single-outcome.

PI(x) = P(y >= best_f), y ~ f(x)

Example

>>> model = SingleTaskGP(train_X, train_Y)
>>> PI = ProbabilityOfImprovement(model, best_f=0.2)
>>> pi = PI(test_X)

Single-outcome analytic Probability of Improvement.

Parameters

• model (Model) – A fitted single-outcome model.

• best_f (Union[float, Tensor]) – Either a scalar or a b-dim Tensor (batch mode) representing the best function value observed so far (assumed noiseless).

• objective (Optional[ScalarizedObjective]) – A ScalarizedObjective (optional).

• maximize (bool) – If True, consider the problem a maximization problem.

forward(X)[source]¶

Evaluate the Probability of Improvement on the candidate set X.

Parameters

X (Tensor) – A (b) x 1 x d-dim Tensor of (b) t-batches of d-dim design points each.

Return type

Tensor

Returns

A (b)-dim tensor of Probability of Improvement values at the given design points X.

Single-outcome Upper Confidence Bound (UCB).

Analytic upper confidence bound that comprises of the posterior mean plus an additional term: the posterior standard deviation weighted by a trade-off parameter, beta. Only supports the case of q=1 (i.e. greedy, non-batch selection of design points). The model must be single-outcome.

UCB(x) = mu(x) + sqrt(beta) * sigma(x), where mu and sigma are the posterior mean and standard deviation, respectively.

Example

>>> model = SingleTaskGP(train_X, train_Y)
>>> UCB = UpperConfidenceBound(model, beta=0.2)
>>> ucb = UCB(test_X)

Single-outcome Upper Confidence Bound.

Parameters

• model (Model) – A fitted single-outcome GP model (must be in batch mode if candidate sets X will be)

• beta (Union[float, Tensor]) – Either a scalar or a one-dim tensor with b elements (batch mode) representing the trade-off parameter between mean and covariance

• objective (Optional[ScalarizedObjective]) – A ScalarizedObjective (optional).

• maximize (bool) – If True, consider the problem a maximization problem.

forward(X)[source]¶

Evaluate the Upper Confidence Bound on the candidate set X.

Parameters

X (Tensor) – A (b) x 1 x d-dim Tensor of (b) t-batches of d-dim design points each.

Return type

Tensor

Returns

A (b)-dim Tensor of Upper Confidence Bound values at the given design points X.

Constrained Expected Improvement (feasibility-weighted).

Computes the analytic expected improvement for a Normal posterior distribution, weighted by a probability of feasibility. The objective and constraints are assumed to be independent and have Gaussian posterior distributions. Only supports the case q=1. The model should be multi-outcome, with the index of the objective and constraints passed to the constructor.

Constrained_EI(x) = EI(x) * Product_i P(y_i in [lower_i, upper_i]), where y_i ~ constraint_i(x) and lower_i, upper_i are the lower and upper bounds for the i-th constraint, respectively.

Example

>>> # example where 0th output has a non-negativity constraint and
... # 1st output is the objective
>>> model = SingleTaskGP(train_X, train_Y)
>>> constraints = {0: (0.0, None)}
>>> cEI = ConstrainedExpectedImprovement(model, 0.2, 1, constraints)
>>> cei = cEI(test_X)

Analytic Constrained Expected Improvement.

Parameters

• model (Model) – A fitted single-outcome model.

• best_f (Union[float, Tensor]) – Either a scalar or a b-dim Tensor (batch mode) representing the best function value observed so far (assumed noiseless).

• objective_index (int) – The index of the objective.

• constraints (Dict[int, Tuple[Optional[float], Optional[float]]]) – A dictionary of the form {i: [lower, upper]}, where i is the output index, and lower and upper are lower and upper bounds on that output (resp. interpreted as -Inf / Inf if None)

• maximize (bool) – If True, consider the problem a maximization problem.

forward(X)[source]¶

Evaluate Constrained Expected Improvement on the candidate set X.

Parameters

X (Tensor) – A (b) x 1 x d-dim Tensor of (b) t-batches of d-dim design points each.

Return type

Tensor

Returns

A (b)-dim Tensor of Expected Improvement values at the given design points X.

Single-outcome Noisy Expected Improvement (via fantasies).

This computes Noisy Expected Improvement by averaging over the Expected Improvemnt values of a number of fantasy models. Only supports the case q=1. Assumes that the posterior distribution of the model is Gaussian. The model must be single-outcome.

NEI(x) = E(max(y - max Y_baseline), 0)), (y, Y_baseline) ~ f((x, X_baseline)), where X_baseline are previously observed points.

Note: This acquisition function currently relies on using a FixedNoiseGP (required for noiseless fantasies).

Example

>>> model = FixedNoiseGP(train_X, train_Y, train_Yvar=train_Yvar)
>>> NEI = NoisyExpectedImprovement(model, train_X)
>>> nei = NEI(test_X)

Single-outcome Noisy Expected Improvement (via fantasies).

Parameters

• model (GPyTorchModel) – A fitted single-outcome model.

• X_observed (Tensor) – A m x d Tensor of observed points that are likely to be the best observed points so far.

• num_fantasies (int) – The number of fantasies to generate. The higher this number the more accurate the model (at the expense of model complexity and performance).

• maximize (bool) – If True, consider the problem a maximization problem.

forward(X)[source]¶

Evaluate Expected Improvement on the candidate set X.

Parameters

X (Tensor) – A b1 x … bk x 1 x d-dim batched tensor of d-dim design points.

Return type

Tensor

Returns

A b1 x … bk-dim tensor of Noisy Expected Improvement values at the given design points X.

A wrapper around AquisitionFunctions to fix a subset of features.

Example

>>> model = SingleTaskGP(train_X, train_Y)  # d = 5
>>> qEI = qExpectedImprovement(model, best_f=0.0)
>>> columns = [2, 4]
>>> values = X[..., columns]
>>> qEI_FF = FixedFeatureAcquisitionFunction(qEI, 5, columns, values)
>>> qei = qEI_FF(test_X)  # d' = 3

Derived Acquisition Function by fixing a subset of input features.

Parameters

• acq_function (AcquisitionFunction) – The base acquisition function, operating on input tensors X_full of feature dimension d.

• d (int) – The feature dimension expected by acq_function.

• columns (List[int]) – d_f < d indices of columns in X_full that are to be fixed to the provided values.

• values (Union[Tensor, List[float]]) – The values to which to fix the columns in columns. Either a full batch_shape x q x d_f tensor of values (if values are different for each of the q input points), or an array-like of values that is broadcastable to the input across t-batch and q-batch dimensions, e.g. a list of length d_f if values are the same across all t and q-batch dimensions.

forward(X)[source]¶

Evaluate base acquisition function under the fixed features.

Parameters

X (Tensor) – Input tensor of feature dimension d’ < d such that d’ + d_f = d.

Returns

Base acquisition function evaluated on tensor X_full constructed by adding values in the appropriate places (see _construct_X_full).

Abstract base class for Monte-Carlo based batch acquisition functions.

Constructor for the MCAcquisitionFunction base class.

Parameters

• model (Model) – A fitted model.

• sampler (Optional[MCSampler]) – The sampler used to draw base samples. Defaults to SobolQMCNormalSampler(num_samples=512, collapse_batch_dims=True).

• objective (Optional[MCAcquisitionObjective]) – The MCAcquisitionObjective under which the samples are evaluated. Defaults to IdentityMCObjective().

• X_pending (Optional[Tensor]) – A m x d-dim Tensor of m design points that have points that have been submitted for function evaluation but have not yet been evaluated.

abstract forward(X)[source]¶

Takes in a (b) x q x d X Tensor of (b) t-batches with q d-dim design points each, and returns a one-dimensional Tensor with (b) elements. Should utilize the result of set_X_pending as needed to account for pending function evaluations.

Return type

Tensor

MC-based batch Expected Improvement.

This computes qEI by (1) sampling the joint posterior over q points (2) evaluating the improvement over the current best for each sample (3) maximizing over q (4) averaging over the samples

qEI(X) = E(max(max Y - best_f, 0)), Y ~ f(X), where X = (x_1,…,x_q)

Example

>>> model = SingleTaskGP(train_X, train_Y)
>>> best_f = train_Y.max()[0]
>>> sampler = SobolQMCNormalSampler(1000)
>>> qEI = qExpectedImprovement(model, best_f, sampler)
>>> qei = qEI(test_X)

q-Expected Improvement.

Parameters

• model (Model) – A fitted model.

• best_f (Union[float, Tensor]) – The best (feasible) function value observed so far (assumed noiseless).

• sampler (Optional[MCSampler]) – The sampler used to draw base samples. Defaults to SobolQMCNormalSampler(num_samples=500, collapse_batch_dims=True)

• objective (Optional[MCAcquisitionObjective]) – The MCAcquisitionObjective under which the samples are evaluated. Defaults to IdentityMCObjective().

• X_pending (Optional[Tensor]) – A m x d-dim Tensor of m design points that have points that have been submitted for function evaluation but have not yet been evaluated. Concatenated into X upon forward call. Copied and set to have no gradient.

forward(X)[source]¶

Evaluate qExpectedImprovement on the candidate set X.

Parameters

X (Tensor) – A (b) x q x d-dim Tensor of (b) t-batches with q d-dim design points each.

Return type

Tensor

Returns

A (b)-dim Tensor of Expected Improvement values at the given design points X.

MC-based batch Noisy Expected Improvement.

This function does not assume a best_f is known (which would require noiseless observations). Instead, it uses samples from the joint posterior over the q test points and previously observed points. The improvement over previously observed points is computed for each sample and averaged.

qNEI(X) = E(max(max Y - max Y_baseline, 0)), where (Y, Y_baseline) ~ f((X, X_baseline)), X = (x_1,…,x_q)

Example

>>> model = SingleTaskGP(train_X, train_Y)
>>> sampler = SobolQMCNormalSampler(1000)
>>> qNEI = qNoisyExpectedImprovement(model, train_X, sampler)
>>> qnei = qNEI(test_X)

q-Noisy Expected Improvement.

Parameters

• model (Model) – A fitted model.

• X_baseline (Tensor) – A r x d-dim Tensor of r design points that have already been observed. These points are considered as the potential best design point.

• sampler (Optional[MCSampler]) – The sampler used to draw base samples. Defaults to SobolQMCNormalSampler(num_samples=500, collapse_batch_dims=True).

• objective (Optional[MCAcquisitionObjective]) – The MCAcquisitionObjective under which the samples are evaluated. Defaults to IdentityMCObjective().

• X_pending (Optional[Tensor]) – A m x d-dim Tensor of m design points that have points that have been submitted for function evaluation but have not yet been evaluated. Concatenated into X upon forward call. Copied and set to have no gradient.

forward(X)[source]¶

Evaluate qNoisyExpectedImprovement on the candidate set X.

Parameters

X (Tensor) – A (b) x q x d-dim Tensor of (b) t-batches with q d-dim design points each.

Return type

Tensor

Returns

A (b)-dim Tensor of Noisy Expected Improvement values at the given design points X.

MC-based batch Probability of Improvement.

Estimates the probability of improvement over the current best observed value by sampling from the joint posterior distribution of the q-batch. MC-based estimates of a probability involves taking expectation of an indicator function; to support auto-differntiation, the indicator is replaced with a sigmoid function with temperature parameter tau.

qPI(X) = P(max Y >= best_f), Y ~ f(X), X = (x_1,…,x_q)

Example

>>> model = SingleTaskGP(train_X, train_Y)
>>> best_f = train_Y.max()[0]
>>> sampler = SobolQMCNormalSampler(1000)
>>> qPI = qProbabilityOfImprovement(model, best_f, sampler)
>>> qpi = qPI(test_X)

q-Probability of Improvement.

Parameters

• model (Model) – A fitted model.

• best_f (Union[float, Tensor]) – The best (feasible) function value observed so far (assumed noiseless).

• sampler (Optional[MCSampler]) – The sampler used to draw base samples. Defaults to SobolQMCNormalSampler(num_samples=500, collapse_batch_dims=True)

• objective (Optional[MCAcquisitionObjective]) – The MCAcquisitionObjective under which the samples are evaluated. Defaults to IdentityMCObjective().

• X_pending (Optional[Tensor]) – A m x d-dim Tensor of m design points that have points that have been submitted for function evaluation but have not yet been evaluated. Concatenated into X upon forward call. Copied and set to have no gradient.

• tau (float) – The temperature parameter used in the sigmoid approximation of the step function. Smaller values yield more accurate approximations of the function, but result in gradients estimates with higher variance.

forward(X)[source]¶

Evaluate qProbabilityOfImprovement on the candidate set X.

Parameters

X (Tensor) – A (b) x q x d-dim Tensor of (b) t-batches with q d-dim design points each.

Return type

Tensor

Returns

A (b)-dim Tensor of Probability of Improvement values at the given design points X.

MC-based batch Simple Regret.

Samples from the joint posterior over the q-batch and computes the simple regret.

qSR(X) = E(max Y), Y ~ f(X), X = (x_1,…,x_q)

Example

>>> model = SingleTaskGP(train_X, train_Y)
>>> sampler = SobolQMCNormalSampler(1000)
>>> qSR = qSimpleRegret(model, sampler)
>>> qsr = qSR(test_X)

Constructor for the MCAcquisitionFunction base class.

Parameters

• model (Model) – A fitted model.

• sampler (Optional[MCSampler]) – The sampler used to draw base samples. Defaults to SobolQMCNormalSampler(num_samples=512, collapse_batch_dims=True).

• objective (Optional[MCAcquisitionObjective]) – The MCAcquisitionObjective under which the samples are evaluated. Defaults to IdentityMCObjective().

• X_pending (Optional[Tensor]) – A m x d-dim Tensor of m design points that have points that have been submitted for function evaluation but have not yet been evaluated.

forward(X)[source]¶

Evaluate qSimpleRegret on the candidate set X.

Parameters

X (Tensor) – A (b) x q x d-dim Tensor of (b) t-batches with q d-dim design points each.

Return type

Tensor

Returns

A (b)-dim Tensor of Simple Regret values at the given design points X.

MC-based batch Upper Confidence Bound.

Uses a reparameterization to extend UCB to qUCB for q > 1 (See Appendix A of [Wilson2017reparam].)

qUCB = E(max(mu + |Y_tilde - mu|)), where Y_tilde ~ N(mu, beta pi/2 Sigma) and f(X) has distribution N(mu, Sigma).

Example

>>> model = SingleTaskGP(train_X, train_Y)
>>> sampler = SobolQMCNormalSampler(1000)
>>> qUCB = qUpperConfidenceBound(model, 0.1, sampler)
>>> qucb = qUCB(test_X)

q-Upper Confidence Bound.

Parameters

• model (Model) – A fitted model.

• beta (float) – Controls tradeoff between mean and standard deviation in UCB.

• sampler (Optional[MCSampler]) – The sampler used to draw base samples. Defaults to SobolQMCNormalSampler(num_samples=500, collapse_batch_dims=True)

• objective (Optional[MCAcquisitionObjective]) – The MCAcquisitionObjective under which the samples are evaluated. Defaults to IdentityMCObjective().

• X_pending (Optional[Tensor]) – A m x d-dim Tensor of m design points that have points that have been submitted for function evaluation but have not yet been evaluated. Concatenated into X upon forward call. Copied and set to have no gradient.

forward(X)[source]¶

Evaluate qUpperConfidenceBound on the candidate set X.

Parameters

X (Tensor) – A (b) x q x d-dim Tensor of (b) t-batches with q d-dim design points each.

Return type

Tensor

Returns

A (b)-dim Tensor of Upper Confidence Bound values at the given design points X.

Affine objective to be used with analytic acquisition functions.

For a Gaussian posterior at a single point (q=1) with mean mu and covariance matrix Sigma, this yields a single-output posterior with mean weights^T * mu and variance weights^T Sigma w.

Example

Example for a model with two outcomes:

>>> weights = torch.tensor([0.5, 0.25])
>>> objective = ScalarizedObjective(weights)
>>> EI = ExpectedImprovement(model, best_f=0.1, objective=objective)

Affine objective.

Parameters

• weights (Tensor) – A one-dimensional tensor with o elements representing the linear weights on the outputs.

• offset (float) – An offset to be added to posterior mean.

forward(posterior)[source]¶

Compute the posterior of the affine transformation.

Parameters

posterior (GPyTorchPosterior) – A posterior with the same number of outputs as the elements in self.weights.

Return type

GPyTorchPosterior

Returns

A single-output posterior.

Abstract base class for MC-based objectives.

abstract forward(samples)[source]¶

Evaluate the objective on the samples.

Parameters

samples (Tensor) – A sample_shape x batch_shape x q x o-dim Tensors of samples from a model posterior.

Returns

A sample_shape x batch_shape x q-dim Tensor of objective values (assuming maximization).

Return type

Tensor

This method is usually not called directly, but via the objectives

Example

>>> # `__call__` method:
>>> samples = sampler(posterior)
>>> outcome = mc_obj(samples)

Trivial objective extracting the last dimension.

Example

>>> identity_objective = IdentityMCObjective()
>>> samples = sampler(posterior)
>>> objective = identity_objective(samples)

forward(samples)[source]¶

Evaluate the objective on the samples.

Parameters

samples (Tensor) – A sample_shape x batch_shape x q x o-dim Tensors of samples from a model posterior.

Returns

A sample_shape x batch_shape x q-dim Tensor of objective values (assuming maximization).

Return type

Tensor

This method is usually not called directly, but via the objectives

Example

>>> # `__call__` method:
>>> samples = sampler(posterior)
>>> outcome = mc_obj(samples)

Linear objective constructed from a weight tensor.

For input samples and mc_obj = LinearMCObjective(weights), this produces mc_obj(samples) = sum_{i} weights[i] * samples[…, i]

Example

Example for a model with two outcomes:

>>> weights = torch.tensor([0.75, 0.25])
>>> linear_objective = LinearMCObjective(weights)
>>> samples = sampler(posterior)
>>> objective = linear_objective(samples)

Linear Objective.

Parameters

weights (Tensor) – A one-dimensional tensor with o elements representing the linear weights on the outputs.

forward(samples)[source]¶

Evaluate the linear objective on the samples.

Parameters

samples (Tensor) – A sample_shape x batch_shape x q x o-dim tensors of samples from a model posterior.

Return type

Tensor

Returns

A sample_shape x batch_shape x q-dim tensor of objective values.

Objective generated from a generic callable.

Allows to construct arbitrary MC-objective functions from a generic callable. In order to be able to use gradient-based acquisition function optimization it should be possible to backpropagate through the callable.

Example

>>> generic_objective = GenericMCObjective(lambda Y: torch.sqrt(Y).sum(dim=-1))
>>> samples = sampler(posterior)
>>> objective = generic_objective(samples)

Objective generated from a generic callable.

Parameters

objective (Callable[[Tensor], Tensor]) – A callable mapping a sample_shape x batch-shape x q x o- dim Tensor to a sample_shape x batch-shape x q-dim Tensor of objective values.

forward(samples)[source]¶

Evaluate the feasibility-weigthed objective on the samples.

Parameters

samples (Tensor) – A sample_shape x batch_shape x q x o-dim Tensors of samples from a model posterior.

Return type

Tensor

Returns

A sample_shape x batch_shape x q-dim Tensor of objective values weighted by feasibility (assuming maximization).

Feasibility-weighted objective.

An Objective allowing to maximize some scalable objective on the model outputs subject to a number of constraints. Constraint feasibilty is approximated by a sigmoid function.

mc_acq(X) = objective(X) * prod_i (1 - sigmoid(constraint_i(X))) TODO: Document functional form exactly.

See botorch.utils.objective.apply_constraints for details on the constarint handling.

Example

>>> bound = 0.0
>>> objective = lambda Y: Y[..., 0]
>>> # apply non-negativity constraint on f(x)[1]
>>> constraint = lambda Y: bound - Y[..., 1]
>>> constrained_objective = ConstrainedMCObjective(objective, [constraint])
>>> samples = sampler(posterior)
>>> objective = constrained_objective(samples)

Feasibility-weighted objective.

Parameters

• objective (Callable[[Tensor], Tensor]) – A callable mapping a sample_shape x batch-shape x q x o- dim Tensor to a sample_shape x batch-shape x q-dim Tensor of objective values.

• constraints (List[Callable[[Tensor], Tensor]]) – A list of callables, each mapping a Tensor of dimension sample_shape x batch-shape x q x o to a Tensor of dimension sample_shape x batch-shape x q, where negative values imply feasibility.

• infeasible_cost (float) – The cost of a design if all associated samples are infeasible.

• eta (float) – The temperature parameter of the sigmoid function approximating the constraint.

forward(samples)[source]¶

Evaluate the feasibility-weighted objective on the samples.

Parameters

samples (Tensor) – A sample_shape x batch_shape x q x o-dim Tensors of samples from a model posterior.

Return type

Tensor

Returns

A sample_shape x batch_shape x q-dim Tensor of objective values weighted by feasibility (assuming maximization).