botorch.acquisition¶

Abstract base class for acquisition functions.

Constructor for the AcquisitionFunction base class.

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.

Base class for analytic acquisition functions.

Constructor for the AcquisitionFunction base class.

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).

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)

Constructor for the AcquisitionFunction base class.

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.

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.

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.

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).

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.

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

Constructor for the MCAcquisitionFunction base class.

forward(X)[source]¶

Takes in a (b) x q x d X Tensor of b t-batches with q d-dim design points each, expands and concatenates self.X_pending and returns a one-dimensional Tensor with b elements.

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.

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.

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.

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.

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.

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.

Abstract base class for MC-based objectives.

Example

>>> # This method is usually not called directly, but via the objective's
>>> # `__call__` method:
>>> samples = sampler(posterior)
>>> outcome = mc_obj(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

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

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 two outcomes
>>> weights = torch.tensor([0.75, 0.25])
>>> linear_objective = LinearMCObjective(weights)
>>> samples = sampler(posterior)
>>> objective = linear_objective(samples)

Linear Objective.

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.

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.

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).

Abstract base class for Samplers.

Subclasses must implement the _construct_base_samples method.

sample_shape¶

The shape of each sample.

resample¶

If True, re-draw samples in each forward evaluation - this results in stochastic acquisition functions (and thus should not be used with deterministic optimization algorithms).

collapse_batch_dims¶

If True, collapse the t-batch dimensions of the produced samples to size 1. This is useful for preventing sampling variance across t-batches.

Example

This method is usually not called directly, but via the sampler’s __call__ method: >>> posterior = model.posterior(test_X) >>> samples = sampler(posterior)

forward(posterior)[source]¶

Draws MC samples from the posterior.

Parameters:	posterior (Posterior) – The Posterior to sample from.
Return type:	Tensor
Returns:	The samples drawn from the posterior.

sample_shape

The shape of a single sample

Return type:	Size

Sampler for MC base samples using iid N(0,1) samples.

Example

>>> sampler = IIDNormalSampler(1000, seed=1234)
>>> posterior = model.posterior(test_X)
>>> samples = sampler(posterior)

Sampler for MC base samples using iid N(0,1) samples.

Sampler for quasi-MC base samples using Sobol sequences.

Example

>>> sampler = SobolQMCNormalSampler(1000, seed=1234)
>>> posterior = model.posterior(test_X)
>>> samples = sampler(posterior)

Sampler for quasi-MC base samples using Sobol sequences.