botorch.acquisition¶

Abstract Acquisition Function APIs¶

Abstract base module for all botorch acquisition functions.

Analytic Acquisition Function API¶

class botorch.acquisition.analytic.AnalyticAcquisitionFunction(model, posterior_transform=None)[source]¶

Bases: AcquisitionFunction, ABC

Base class for analytic acquisition functions.

Parameters:

• model (Model) –

• posterior_transform (Optional[PosteriorTransform]) –

Base constructor for analytic acquisition functions.

Parameters:

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

• posterior_transform (Optional[PosteriorTransform]) – A PosteriorTransform. If using a multi-output model, a PosteriorTransform that transforms the multi-output posterior into a single-output posterior is required.

set_X_pending(X_pending=None)[source]¶

Informs the acquisition function about pending design points.

Parameters:

X_pending (Tensor | None) – n x d Tensor with n d-dim design points that have been submitted for evaluation but have not yet been evaluated.

Return type:

None

Cached Cholesky Acquisition Function API¶

Abstract class for acquisition functions leveraging a cached Cholesky decomposition of the posterior covariance over f(X_baseline).

botorch.acquisition.cached_cholesky.supports_cache_root(model)[source]¶

Checks if a model supports the cache_root functionality. The two criteria are that the model is not multi-task and the model produces a GPyTorchPosterior.

Parameters:

model (Model) –

Return type:

bool

class botorch.acquisition.cached_cholesky.CachedCholeskyMCAcquisitionFunction(model, cache_root=False, sampler=None)[source]¶

Bases: CachedCholeskyMCSamplerMixin

DEPRECATED - USE CachedCholeskyMCSamplerMixin instead.

Set class attributes and perform compatibility checks.

Parameters:

• model (Model) – A model.

• cache_root (bool) – A boolean indicating whether to cache the Cholesky. This might be overridden in the model is not compatible.

• sampler (Optional[MCSampler]) – An optional MCSampler object.

Decoupled Acquisition Function API¶

Abstract base module for decoupled acquisition functions.

class botorch.acquisition.decoupled.DecoupledAcquisitionFunction(model, X_evaluation_mask=None, **kwargs)[source]¶

Bases: AcquisitionFunction, ABC

Abstract base class for decoupled acquisition functions. A decoupled acquisition function where one may intend to evaluate a design on only a subset of the outcomes. Typically this would be handled by fantasizing, where one would fantasize as to what the partial observation would be if one were to evaluate a design on the subset of outcomes (e.g. you only fantasize at those outcomes). The X_evaluation_mask specifies which outcomes should be evaluated for each design. X_evaluation_mask is q x m, where there are q design points in the batch and m outcomes. In the asynchronous case, where there are n’ pending points, we need to track which outcomes each pending point should be evaluated on. In this case, we concatenate X_pending_evaluation_mask with X_evaluation_mask to obtain the full evaluation_mask.

This abstract class handles generating and updating an evaluation mask, which is a boolean tensor indicating which outcomes a given design is being evaluated on. The evaluation mask has shape (n’ + q) x m, where n’ is the number of pending points and the q represents the new candidates to be generated.

If X(_pending)_evaluation_mas`k is None, it is assumed that `X(_pending) will be evaluated on all outcomes.

Initialize.

Parameters:

• model (ModelList) – A model

• X_evaluation_mask (Optional[Tensor]) – A q x m-dim boolean tensor indicating which outcomes the decoupled acquisition function should generate new candidates for.

property X_evaluation_mask: Tensor | None¶

Get the evaluation indices for the new candidate.

set_X_pending(X_pending=None, X_pending_evaluation_mask=None)[source]¶

Informs the AF about pending design points for different outcomes.

Parameters:

• X_pending (Tensor | None) – A n’ x d Tensor with n’ d-dim design points that have been submitted for evaluation but have not yet been evaluated.

• X_pending_evaluation_mask (Tensor | None) – A n’ x m-dim tensor of booleans indicating for which outputs the pending point is being evaluated on. If X_pending_evaluation_mask is None, it is assumed that X_pending will be evaluated on all outcomes.

Return type:

None

construct_evaluation_mask(X)[source]¶

Construct the boolean evaluation mask for X and X_pending

Parameters:

X (Tensor) – A batch_shape x n x d-dim tensor of designs.

Returns:

A n + n’ x m-dim tensor of booleans indicating which outputs should be evaluated.

Return type:

Tensor | None

Monte-Carlo Acquisition Function API¶

class botorch.acquisition.monte_carlo.MCAcquisitionFunction(model, sampler=None, objective=None, posterior_transform=None, X_pending=None)[source]¶

Bases: AcquisitionFunction, MCSamplerMixin, ABC

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

Parameters:

• model (Model) – A fitted model.

• sampler (Optional[MCSampler]) – The sampler used to draw base samples. If not given, a sampler is generated on the fly within the get_posterior_samples method using botorch.sampling.get_sampler. NOTE: For posteriors that do not support base samples, a sampler compatible with intended use case must be provided. See ForkedRNGSampler and StochasticSampler as examples.

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

• posterior_transform (Optional[PosteriorTransform]) – A PosteriorTransform (optional).

• X_pending (Optional[Tensor]) – A batch_shape, 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 batch_shape x q x d X Tensor of t-batches with q d-dim design points each, and returns a Tensor with shape batch_shape’, where batch_shape’ is the broadcasted batch shape of model and input X. Should utilize the result of set_X_pending as needed to account for pending function evaluations.

Parameters:

X (Tensor) –

Return type:

Tensor

Multi-Objective Analytic Acquisition Function API¶

class botorch.acquisition.multi_objective.analytic.MultiObjectiveAnalyticAcquisitionFunction(model, posterior_transform=None)[source]¶

Bases: AcquisitionFunction

Abstract base class for Multi-Objective batch acquisition functions.

Constructor for the MultiObjectiveAnalyticAcquisitionFunction base class.

Parameters:

• model (Model) – A fitted model.

• posterior_transform (Optional[PosteriorTransform]) – A PosteriorTransform (optional).

abstract forward(X)[source]¶

Takes in a batch_shape x 1 x d X Tensor of t-batches with 1 d-dim design point each, and returns a Tensor with shape batch_shape’, where batch_shape’ is the broadcasted batch shape of model and input X.

Parameters:

X (Tensor) –

Return type:

Tensor

set_X_pending(X_pending=None)[source]¶

Informs the acquisition function about pending design points.

Parameters:

X_pending (Tensor | None) – n x d Tensor with n d-dim design points that have been submitted for evaluation but have not yet been evaluated.

Return type:

None

Multi-Objective Monte-Carlo Acquisition Function API¶

class botorch.acquisition.multi_objective.monte_carlo.MultiObjectiveMCAcquisitionFunction(model, sampler=None, objective=None, constraints=None, eta=0.001, X_pending=None)[source]¶

Bases: AcquisitionFunction, MCSamplerMixin, ABC

Abstract base class for Multi-Objective batch acquisition functions.

NOTE: This does not inherit from MCAcquisitionFunction to avoid circular imports.

Parameters:

• _default_sample_shape – The sample_shape for the default sampler.

• model (Model) –

• sampler (Optional[MCSampler]) –

• objective (Optional[MCMultiOutputObjective]) –

• constraints (Optional[List[Callable[[Tensor], Tensor]]]) –

• eta (Optional[Union[Tensor, float]]) –

• X_pending (Optional[Tensor]) –

Constructor for the MCAcquisitionFunction base class.

Parameters:

• model (Model) – A fitted model.

• sampler (Optional[MCSampler]) – The sampler used to draw base samples. If not given, a sampler is generated using get_sampler. NOTE: For posteriors that do not support base samples, a sampler compatible with intended use case must be provided. See ForkedRNGSampler and StochasticSampler as examples.

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

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

• eta (Optional[Union[Tensor, float]]) – The temperature parameter for the sigmoid function used for the differentiable approximation of the constraints. In case of a float the same eta is used for every constraint in constraints. In case of a tensor the length of the tensor must match the number of provided constraints. The i-th constraint is then estimated with the i-th eta value.

• 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 batch_shape x q x d X Tensor of t-batches with q d-dim design points each, and returns a Tensor with shape batch_shape’, where batch_shape’ is the broadcasted batch shape of model and input X. Should utilize the result of set_X_pending as needed to account for pending function evaluations.

Parameters:

X (Tensor) –

Return type:

Tensor

Analytic Acquisition Functions¶

Analytic Acquisition Functions that evaluate the posterior without performing Monte-Carlo sampling.

class botorch.acquisition.analytic.LogProbabilityOfImprovement(model, best_f, posterior_transform=None, maximize=True)[source]¶

Bases: AnalyticAcquisitionFunction

Single-outcome Log Probability of Improvement.

Logarithm of the probability of improvement 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.

The logarithm of the probability of improvement is numerically better behaved than the original function, which can lead to significantly improved optimization of the acquisition function. This is analogous to the common practice of optimizing the log likelihood of a probabilistic model - rather the likelihood - for the sake of maximium likelihood estimation.

logPI(x) = log(P(y >= best_f)), y ~ f(x)

Example

>>> model = SingleTaskGP(train_X, train_Y)
>>> LogPI = LogProbabilityOfImprovement(model, best_f=0.2)
>>> log_pi = LogPI(test_X)

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

• posterior_transform (Optional[PosteriorTransform]) – A PosteriorTransform. If using a multi-output model, a PosteriorTransform that transforms the multi-output posterior into a single-output posterior is required.

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

forward(X)[source]¶

Evaluate the Log Probability of 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.

Returns:

A (b1 x … bk)-dim tensor of Log Probability of Improvement values at the given design points X.

Return type:

Tensor

class botorch.acquisition.analytic.ProbabilityOfImprovement(model, best_f, posterior_transform=None, maximize=True)[source]¶

Bases: AnalyticAcquisitionFunction

Single-outcome Probability of Improvement.

Probability of improvement 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 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).

• posterior_transform (Optional[PosteriorTransform]) – A PosteriorTransform. If using a multi-output model, a PosteriorTransform that transforms the multi-output posterior into a single-output posterior is required.

• 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 (b1 x … bk) x 1 x d-dim batched tensor of d-dim design points.

Returns:

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

Return type:

Tensor

class botorch.acquisition.analytic.qAnalyticProbabilityOfImprovement(model, best_f, posterior_transform=None, maximize=True)[source]¶

Bases: AnalyticAcquisitionFunction

Approximate, single-outcome batch Probability of Improvement using MVNXPB.

This implementation uses MVNXPB, a bivariate conditioning algorithm for approximating P(a <= Y <= b) for multivariate normal Y. See [Trinh2015bivariate]. This (analytic) approximate q-PI is given by approx-qPI(X) = P(max Y >= best_f) = 1 - P(Y < best_f), Y ~ f(X), X = (x_1,…,x_q), where P(Y < best_f) is estimated using MVNXPB.

qPI using an analytic approximation.

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

• posterior_transform (Optional[PosteriorTransform]) – A PosteriorTransform. If using a multi-output model, a PosteriorTransform that transforms the multi-output posterior into a single-output posterior is required.

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

forward(X)[source]¶

Evaluate approximate qPI on the candidate set X.

Parameters:

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

Returns:

A batch_shape-dim Tensor of approximate Probability of Improvement values at the given design points X, where batch_shape’ is the broadcasted batch shape of model and input X.

Return type:

Tensor

class botorch.acquisition.analytic.ExpectedImprovement(model, best_f, posterior_transform=None, maximize=True)[source]¶

Bases: AnalyticAcquisitionFunction

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(f(x) - best_f, 0)),

where the expectation is taken over the value of stochastic function f at x.

Example

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

NOTE: It is strongly recommended to use LogExpectedImprovement instead of regular EI, because it solves the vanishing gradient problem by taking special care of numerical computations and can lead to substantially improved BO performance.

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

• posterior_transform (Optional[PosteriorTransform]) – A PosteriorTransform. If using a multi-output model, a PosteriorTransform that transforms the multi-output posterior into a single-output posterior is required.

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

Returns:

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

Return type:

Tensor

class botorch.acquisition.analytic.LogExpectedImprovement(model, best_f, posterior_transform=None, maximize=True)[source]¶

Bases: AnalyticAcquisitionFunction

Logarithm of single-outcome Expected Improvement (analytic).

Computes the logarithm of the classic Expected Improvement acquisition function, in a numerically robust manner. In particular, the implementation takes special care to avoid numerical issues in the computation of the acquisition value and its gradient in regions where improvement is predicted to be virtually impossible.

See [Ament2023logei] for details. Formally,

LogEI(x) = log(E(max(f(x) - best_f, 0))),

where the expectation is taken over the value of stochastic function f at x.

Example

>>> model = SingleTaskGP(train_X, train_Y)
>>> LogEI = LogExpectedImprovement(model, best_f=0.2)
>>> ei = LogEI(test_X)

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

• posterior_transform (Optional[PosteriorTransform]) – A PosteriorTransform. If using a multi-output model, a PosteriorTransform that transforms the multi-output posterior into a single-output posterior is required.

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

forward(X)[source]¶

Evaluate logarithm of 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.

Returns:

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

Return type:

Tensor

class botorch.acquisition.analytic.LogConstrainedExpectedImprovement(model, best_f, objective_index, constraints, maximize=True)[source]¶

Bases: AnalyticAcquisitionFunction

Log Constrained Expected Improvement (feasibility-weighted).

Computes the logarithm of 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 non-batch mode (i.e. q=1). The model should be multi-outcome, with the index of the objective and constraints passed to the constructor.

See [Ament2023logei] for details. Formally,

LogConstrainedEI(x) = log(EI(x)) + Sum_i log(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 the 0th output has a non-negativity constraint and # the 1st output is the objective >>> model = SingleTaskGP(train_X, train_Y) >>> constraints = {0: (0.0, None)} >>> LogCEI = LogConstrainedExpectedImprovement(model, 0.2, 1, constraints) >>> cei = LogCEI(test_X)

Analytic Log Constrained Expected Improvement.

Parameters:

• model (Model) – A fitted multi-output model.

• best_f (Union[float, Tensor]) – Either a scalar or a b-dim Tensor (batch mode) representing the best feasible 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 Log 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.

Returns:

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

Return type:

Tensor

class botorch.acquisition.analytic.ConstrainedExpectedImprovement(model, best_f, objective_index, constraints, maximize=True)[source]¶

Bases: AnalyticAcquisitionFunction

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 non-batch mode (i.e. 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 the 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 multi-output model.

• best_f (Union[float, Tensor]) – Either a scalar or a b-dim Tensor (batch mode) representing the best feasible 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.

Returns:

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

Return type:

Tensor

class botorch.acquisition.analytic.LogNoisyExpectedImprovement(model, X_observed, num_fantasies=20, maximize=True, posterior_transform=None)[source]¶

Bases: AnalyticAcquisitionFunction

Single-outcome Log Noisy Expected Improvement (via fantasies).

This computes Log Noisy Expected Improvement by averaging over the Expected Improvement 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.

See [Ament2023logei] for details. Formally,

LogNEI(x) = log(E(max(y - max Y_base), 0))), (y, Y_base) ~ f((x, X_base)),

where X_base are previously observed points.

Note: This acquisition function currently relies on using a SingleTaskGP with known observation noise. In other words, train_Yvar must be passed to the model. (required for noiseless fantasies).

Example

>>> model = SingleTaskGP(train_X, train_Y, train_Yvar=train_Yvar)
>>> LogNEI = LogNoisyExpectedImprovement(model, train_X)
>>> nei = LogNEI(test_X)

Single-outcome Noisy Log Expected Improvement (via fantasies).

Parameters:

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

• X_observed (Tensor) – A n 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.

• posterior_transform (Optional[PosteriorTransform]) –

forward(X)[source]¶

Evaluate logarithm of the mean 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.

Returns:

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

Return type:

Tensor

class botorch.acquisition.analytic.NoisyExpectedImprovement(model, X_observed, num_fantasies=20, maximize=True)[source]¶

Bases: ExpectedImprovement

Single-outcome Noisy Expected Improvement (via fantasies).

This computes Noisy Expected Improvement by averaging over the Expected Improvement 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 SingleTaskGP with known observation noise. In other words, train_Yvar must be passed to the model. (required for noiseless fantasies).

Example

>>> model = SingleTaskGP(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 n 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.

Returns:

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

Return type:

Tensor

class botorch.acquisition.analytic.UpperConfidenceBound(model, beta, posterior_transform=None, maximize=True)[source]¶

Bases: AnalyticAcquisitionFunction

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

• posterior_transform (Optional[PosteriorTransform]) – A PosteriorTransform. If using a multi-output model, a PosteriorTransform that transforms the multi-output posterior into a single-output posterior is required.

• 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 (b1 x … bk) x 1 x d-dim batched tensor of d-dim design points.

Returns:

A (b1 x … bk)-dim tensor of Upper Confidence Bound values at the given design points X.

Return type:

Tensor

class botorch.acquisition.analytic.PosteriorMean(model, posterior_transform=None, maximize=True)[source]¶

Bases: AnalyticAcquisitionFunction

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)

Single-outcome Posterior Mean.

Parameters:

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

• posterior_transform (Optional[PosteriorTransform]) – A PosteriorTransform. If using a multi-output model, a PosteriorTransform that transforms the multi-output posterior into a single-output posterior is required.

• maximize (bool) – If True, consider the problem a maximization problem. Note that if maximize=False, the posterior mean is negated. As a consequence optimize_acqf(PosteriorMean(gp, maximize=False)) actually returns -1 * minimum of the posterior mean.

forward(X)[source]¶

Evaluate the posterior mean on the candidate set X.

Parameters:

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

Returns:

A (b1 x … bk)-dim tensor of Posterior Mean values at the given design points X.

Return type:

Tensor

class botorch.acquisition.analytic.ScalarizedPosteriorMean(model, weights, posterior_transform=None)[source]¶

Bases: AnalyticAcquisitionFunction

Scalarized Posterior Mean.

This acquisition function returns a scalarized (across the q-batch) posterior mean given a vector of weights.

Scalarized Posterior Mean.

Parameters:

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

• weights (Tensor) – A tensor of shape q for scalarization. In order to minimize the scalarized posterior mean, pass -weights.

• posterior_transform (Optional[PosteriorTransform]) – A PosteriorTransform. If using a multi-output model, a PosteriorTransform that transforms the multi-output posterior into a single-output posterior is required.

forward(X)[source]¶

Evaluate the scalarized posterior mean on the candidate set X.

Parameters:

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

Returns:

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

Return type:

Tensor

class botorch.acquisition.analytic.PosteriorStandardDeviation(model, posterior_transform=None, maximize=True)[source]¶

Bases: AnalyticAcquisitionFunction

Single-outcome Posterior Standard Deviation.

An acquisition function for pure exploration. Only supports the case of q=1. Requires the model’s posterior to have mean and variance properties. The model must be either single-outcome or combined with a posterior_transform to produce a single-output posterior.

Example

>>> import torch
>>> from botorch.models.gp_regression import SingleTaskGP
>>> from botorch.models.transforms.input import Normalize
>>> from botorch.models.transforms.outcome import Standardize
>>>
>>> # Set up a model
>>> train_X = torch.rand(20, 2, dtype=torch.float64)
>>> train_Y = torch.sin(train_X).sum(dim=1, keepdim=True)
>>> model = SingleTaskGP(
...     train_X, train_Y, outcome_transform=Standardize(m=1),
...     input_transform=Normalize(d=2),
... )
>>> # Now set up the acquisition function
>>> PSTD = PosteriorStandardDeviation(model)
>>> test_X = torch.zeros((1, 2), dtype=torch.float64)
>>> std = PSTD(test_X)
>>> std.item()
0.16341639895667773

Single-outcome Posterior Mean.

Parameters:

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

• posterior_transform (Optional[PosteriorTransform]) – A PosteriorTransform. If using a multi-output model, a PosteriorTransform that transforms the multi-output posterior into a single-output posterior is required.

• maximize (bool) – If True, consider the problem a maximization problem. Note that if maximize=False, the posterior standard deviation is negated. As a consequence, optimize_acqf(PosteriorStandardDeviation(gp, maximize=False)) actually returns -1 * minimum of the posterior standard deviation.

forward(X)[source]¶

Evaluate the posterior standard deviation on the candidate set X.

Parameters:

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

Returns:

A (b1 x … bk)-dim tensor of Posterior Mean values at the given design points X.

Return type:

Tensor

Monte-Carlo Acquisition Functions¶

Batch acquisition functions using the reparameterization trick in combination with (quasi) Monte-Carlo sampling. See [Rezende2014reparam], [Wilson2017reparam] and [Balandat2020botorch].

References

class botorch.acquisition.monte_carlo.SampleReductionProtocol(*args, **kwargs)[source]¶

Bases: Protocol

For static type check of SampleReducingMCAcquisitionFunction’s mc_reduction.

class botorch.acquisition.monte_carlo.SampleReducingMCAcquisitionFunction(model, sampler=None, objective=None, posterior_transform=None, X_pending=None, sample_reduction=<built-in method mean of type object>, q_reduction=<built-in method amax of type object>, constraints=None, eta=0.001, fat=False)[source]¶

Bases: MCAcquisitionFunction

MC-based batch acquisition function that reduces across samples and implements a general treatment of outcome constraints.

This class’s forward computes the - possibly constrained - acquisition value by (1) computing the unconstrained utility for each MC sample using _sample_forward, (2) weighing the utility values by the constraint indicator per MC sample, and (3) reducing (e.g. averaging) the weighted utility values over the MC dimension.

NOTE: Do NOT override the forward method, unless you have thought about it well.

forward is implemented generically to incorporate constraints in a principled way, and takes care of reducing over the Monte Carlo and batch dimensions via the sample_reduction and q_reduction arguments, which default to torch.mean and torch.max, respectively.

In order to implement a custom SampleReducingMCAcquisitionFunction, we only need to implement the _sample_forward(obj: Tensor) -> Tensor method, which maps objective samples to acquisition utility values without reducing the Monte Carlo and batch (i.e. q) dimensions (see details in the docstring of _sample_forward).

A note on design choices:

The primary purpose of SampleReducingMCAcquisitionFunction`is to support outcome constraints. On the surface, designing a wrapper `ConstrainedMCAcquisitionFunction could be an elegant solution to this end, but it would still require the acquisition functions to implement a _sample_forward method to weigh acquisition utilities at the sample level. Further, qNoisyExpectedImprovement is a special case that is hard to encompass in this pattern, since it requires the computation of the best feasible objective, which requires access to the constraint functions. However, if the constraints are stored in a wrapper class, they will be inaccessible to the forward pass. These problems are circumvented by the design of this class.

Constructor of SampleReducingMCAcquisitionFunction.

Parameters:

• model (Model) – A fitted model.

• sampler (Optional[MCSampler]) – The sampler used to draw base samples. If not given, a sampler is generated on the fly within the get_posterior_samples method using botorch.sampling.get_sampler. NOTE: For posteriors that do not support base samples, a sampler compatible with intended use case must be provided. See ForkedRNGSampler and StochasticSampler as examples.

• objective (Optional[MCAcquisitionObjective]) – The MCAcquisitionObjective under which the samples are evaluated. Defaults to IdentityMCObjective(). NOTE: ConstrainedMCObjective for outcome constraints is deprecated in favor of passing the constraints directly to this constructor.

• posterior_transform (Optional[PosteriorTransform]) – A PosteriorTransform (optional).

• X_pending (Optional[Tensor]) – A batch_shape, 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.

• sample_reduction (SampleReductionProtocol) – A callable that takes in a sample_shape x batch_shape Tensor of acquisition utility values, a keyword-argument dim that specifies the sample dimensions to reduce over, and returns a batch_shape-dim Tensor of acquisition values.

• q_reduction (SampleReductionProtocol) – A callable that takes in a sample_shape x batch_shape x q Tensor of acquisition utility values, a keyword-argument dim that specifies the q dimension to reduce over (i.e. -1), and returns a sample_shape x batch_shape-dim Tensor of acquisition values.

• constraints (Optional[List[Callable[[Tensor], Tensor]]]) – A list of constraint callables which map a Tensor of posterior samples of dimension sample_shape x batch-shape x q x m-dim to a sample_shape x batch-shape x q-dim Tensor. The associated constraints are considered satisfied if the output is less than zero. NOTE: Constraint-weighting is only compatible with non-negative acquistion utilities, e.g. all improvement-based acquisition functions.

• eta (Union[Tensor, float]) – Temperature parameter(s) governing the smoothness of the sigmoid approximation to the constraint indicators. For more details, on this parameter, see the docs of compute_smoothed_feasibility_indicator.

• fat (bool) – Wether to apply a fat-tailed smooth approximation to the feasibility indicator or the canonical sigmoid approximation.

forward(X)[source]¶

Computes the acquisition value associated with the input X. Weighs the acquisition utility values by smoothed constraint indicators if constraints was passed to the constructor of the class. Applies self.sample_reduction and self.q_reduction to reduce over the Monte Carlo and batch (q) dimensions.

NOTE: Do NOT override the forward method for a custom acquisition function. Instead, implement the _sample_forward method. See the docstring of this class for details.

Parameters:

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

Returns:

A Tensor with shape batch_shape’, where batch_shape’ is the broadcasted batch shape of model and input X.

Return type:

Tensor

class botorch.acquisition.monte_carlo.qExpectedImprovement(model, best_f, sampler=None, objective=None, posterior_transform=None, X_pending=None, constraints=None, eta=0.001)[source]¶

Bases: SampleReducingMCAcquisitionFunction

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(1024)
>>> 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 objective value observed so far (assumed noiseless). Can be a scalar, or a batch_shape-dim tensor. In case of a batched model, the tensor can specify different values for each element of the batch.

• sampler (Optional[MCSampler]) – The sampler used to draw base samples. See MCAcquisitionFunction more details.

• objective (Optional[MCAcquisitionObjective]) – The MCAcquisitionObjective under which the samples are evaluated. Defaults to IdentityMCObjective(). NOTE: ConstrainedMCObjective for outcome constraints is deprecated in favor of passing the constraints directly to this constructor.

• posterior_transform (Optional[PosteriorTransform]) – A PosteriorTransform (optional).

• X_pending (Optional[Tensor]) – A m x d-dim Tensor of m design 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.

• constraints (Optional[List[Callable[[Tensor], Tensor]]]) – A list of constraint callables which map a Tensor of posterior samples of dimension sample_shape x batch-shape x q x m-dim to a sample_shape x batch-shape x q-dim Tensor. The associated constraints are considered satisfied if the output is less than zero.

• eta (Union[Tensor, float]) – Temperature parameter(s) governing the smoothness of the sigmoid approximation to the constraint indicators. For more details, on this parameter, see the docs of compute_smoothed_feasibility_indicator.

class botorch.acquisition.monte_carlo.qNoisyExpectedImprovement(model, X_baseline, sampler=None, objective=None, posterior_transform=None, X_pending=None, prune_baseline=True, cache_root=True, constraints=None, eta=0.001, marginalize_dim=None)[source]¶

Bases: SampleReducingMCAcquisitionFunction, CachedCholeskyMCSamplerMixin

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(1024)
>>> qNEI = qNoisyExpectedImprovement(model, train_X, sampler)
>>> qnei = qNEI(test_X)

q-Noisy Expected Improvement.

Parameters:

• model (Model) – A fitted model.

• X_baseline (Tensor) – A batch_shape x 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. See MCAcquisitionFunction more details.

• objective (Optional[MCAcquisitionObjective]) – The MCAcquisitionObjective under which the samples are evaluated. Defaults to IdentityMCObjective(). NOTE: ConstrainedMCObjective for outcome constraints is deprecated in favor of passing the constraints directly to this constructor.

• posterior_transform (Optional[PosteriorTransform]) – A PosteriorTransform (optional).

• X_pending (Optional[Tensor]) – A batch_shape x 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.

• prune_baseline (bool) – If True, remove points in X_baseline that are highly unlikely to be the best point. This can significantly improve performance and is generally recommended. In order to customize pruning parameters, instead manually call botorch.acquisition.utils.prune_inferior_points on X_baseline before instantiating the acquisition function.

• cache_root (bool) – A boolean indicating whether to cache the root decomposition over X_baseline and use low-rank updates.

• constraints (Optional[List[Callable[[Tensor], Tensor]]]) – A list of constraint callables which map a Tensor of posterior samples of dimension sample_shape x batch-shape x q x m-dim to a sample_shape x batch-shape x q-dim Tensor. The associated constraints are considered satisfied if the output is less than zero.

• eta (Union[Tensor, float]) – Temperature parameter(s) governing the smoothness of the sigmoid approximation to the constraint indicators. For more details, on this parameter, see the docs of compute_smoothed_feasibility_indicator.

• marginalize_dim (Optional[int]) – The dimension to marginalize over.

TODO: similar to qNEHVI, when we are using sequential greedy candidate selection, we could incorporate pending points X_baseline and compute the incremental qNEI from the new point. This would greatly increase efficiency for large batches.

compute_best_f(obj)[source]¶

Computes the best (feasible) noisy objective value.

Parameters:

obj (Tensor) – sample_shape x batch_shape x q-dim Tensor of objectives in forward.

Returns:

A sample_shape x batch_shape-dim Tensor of best feasible objectives.

Return type:

Tensor

class botorch.acquisition.monte_carlo.qProbabilityOfImprovement(model, best_f, sampler=None, objective=None, posterior_transform=None, X_pending=None, tau=0.001, constraints=None, eta=0.001)[source]¶

Bases: SampleReducingMCAcquisitionFunction

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-differentiation, 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(1024)
>>> 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 objective value observed so far (assumed noiseless). Can be a batch_shape-shaped tensor, which in case of a batched model specifies potentially different values for each element of the batch.

• sampler (Optional[MCSampler]) – The sampler used to draw base samples. See MCAcquisitionFunction more details.

• objective (Optional[MCAcquisitionObjective]) – The MCAcquisitionObjective under which the samples are evaluated. Defaults to IdentityMCObjective(). NOTE: ConstrainedMCObjective for outcome constraints is deprecated in favor of passing the constraints directly to this constructor.

• posterior_transform (Optional[PosteriorTransform]) – A PosteriorTransform (optional).

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

• constraints (Optional[List[Callable[[Tensor], Tensor]]]) – A list of constraint callables which map posterior samples to a scalar. The associated constraint is considered satisfied if this scalar is less than zero.

• eta (Union[Tensor, float]) – Temperature parameter(s) governing the smoothness of the sigmoid approximation to the constraint indicators. For more details, on this parameter, see the docs of compute_smoothed_feasibility_indicator.

class botorch.acquisition.monte_carlo.qSimpleRegret(model, sampler=None, objective=None, posterior_transform=None, X_pending=None)[source]¶

Bases: SampleReducingMCAcquisitionFunction

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)

Constraints should be provided as a ConstrainedMCObjective. Passing constraints as an argument is not supported. This is because SampleReducingMCAcquisitionFunction computes the acquisition values on the sample level and then weights the sample-level acquisition values by a soft feasibility indicator. Hence, it expects non-log acquisition function values to be non-negative. qSimpleRegret acquisition values can be negative, so we instead use a ConstrainedMCObjective which applies constraints to the objectives (e.g. before computing the acquisition function) and shifts negative objective values using by an infeasible cost to ensure non-negativity (before applying constraints and shifting them back).

Example

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

q-Simple Regret.

Parameters:

• model (Model) – A fitted model.

• sampler (Optional[MCSampler]) – The sampler used to draw base samples. See MCAcquisitionFunction more details.

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

• posterior_transform (Optional[PosteriorTransform]) – A PosteriorTransform (optional).

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

class botorch.acquisition.monte_carlo.qUpperConfidenceBound(model, beta, sampler=None, objective=None, posterior_transform=None, X_pending=None)[source]¶

Bases: SampleReducingMCAcquisitionFunction

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

Constraints should be provided as a ConstrainedMCObjective. Passing constraints as an argument is not supported. This is because SampleReducingMCAcquisitionFunction computes the acquisition values on the sample level and then weights the sample-level acquisition values by a soft feasibility indicator. Hence, it expects non-log acquisition function values to be non-negative. qSimpleRegret acquisition values can be negative, so we instead use a ConstrainedMCObjective which applies constraints to the objectives (e.g. before computing the acquisition function) and shifts negative objective values using by an infeasible cost to ensure non-negativity (before applying constraints and shifting them back).

Example

>>> model = SingleTaskGP(train_X, train_Y)
>>> sampler = SobolQMCNormalSampler(1024)
>>> 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. See MCAcquisitionFunction more details.

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

• posterior_transform (Optional[PosteriorTransform]) – A PosteriorTransform (optional).

• X_pending (Optional[Tensor]) – A batch_shape x 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.

Monte-Carlo variants of the LogEI family of improvements-based acquisition functions, see [Ament2023logei] for details.

References

class botorch.acquisition.logei.qLogExpectedImprovement(model, best_f, sampler=None, objective=None, posterior_transform=None, X_pending=None, constraints=None, eta=0.001, fat=True, tau_max=0.01, tau_relu=1e-06)[source]¶

Bases: LogImprovementMCAcquisitionFunction

MC-based batch Log Expected Improvement.

This computes qLogEI by (1) sampling the joint posterior over q points, (2) evaluating the smoothed log improvement over the current best for each sample, (3) smoothly maximizing over q, and (4) averaging over the samples in log space.

See [Ament2023logei] for details. Formally,

qLogEI(X) ~ log(qEI(X)) = log(E(max(max Y - best_f, 0))).

where Y ~ f(X), and X = (x_1,…,x_q), .

Example

>>> model = SingleTaskGP(train_X, train_Y)
>>> best_f = train_Y.max()[0]
>>> sampler = SobolQMCNormalSampler(1024)
>>> qLogEI = qLogExpectedImprovement(model, best_f, sampler)
>>> qei = qLogEI(test_X)

q-Log Expected Improvement.

Parameters:

• model (Model) – A fitted model.

• best_f (Union[float, Tensor]) – The best objective value observed so far (assumed noiseless). Can be a scalar, or a batch_shape-dim tensor. In case of a batched model, the tensor can specify different values for each element of the batch.

• sampler (Optional[MCSampler]) – The sampler used to draw base samples. See MCAcquisitionFunction more details.

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

• posterior_transform (Optional[PosteriorTransform]) – A PosteriorTransform (optional).

• X_pending (Optional[Tensor]) – A m x d-dim Tensor of m design 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.

• constraints (Optional[List[Callable[[Tensor], Tensor]]]) – A list of constraint callables which map a Tensor of posterior samples of dimension sample_shape x batch-shape x q x m-dim to a sample_shape x batch-shape x q-dim Tensor. The associated constraints are satisfied if constraint(samples) < 0.

• eta (Union[Tensor, float]) – Temperature parameter(s) governing the smoothness of the sigmoid approximation to the constraint indicators. See the docs of compute_(log_)smoothed_constraint_indicator for details.

• fat (bool) – Toggles the logarithmic / linear asymptotic behavior of the smooth approximation to the ReLU.

• tau_max (float) – Temperature parameter controlling the sharpness of the smooth approximations to max.

• tau_relu (float) – Temperature parameter controlling the sharpness of the smooth approximations to ReLU.

class botorch.acquisition.logei.qLogNoisyExpectedImprovement(model, X_baseline, sampler=None, objective=None, posterior_transform=None, X_pending=None, constraints=None, eta=0.001, fat=True, prune_baseline=False, cache_root=True, tau_max=0.01, tau_relu=1e-06, **kwargs)[source]¶

Bases: LogImprovementMCAcquisitionFunction, CachedCholeskyMCSamplerMixin

MC-based batch Log 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. A smooth approximation to the canonical improvement over previously observed points is computed for each sample and the logarithm of the average is returned.

See [Ament2023logei] for details. Formally,

qLogNEI(X) ~ log(qNEI(X)) = Log 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(1024)
>>> qLogNEI = qLogNoisyExpectedImprovement(model, train_X, sampler)
>>> acqval = qLogNEI(test_X)

q-Noisy Expected Improvement.

Parameters:

• model (Model) – A fitted model.

• X_baseline (Tensor) – A batch_shape x 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. See MCAcquisitionFunction more details.

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

• posterior_transform (Optional[PosteriorTransform]) – A PosteriorTransform (optional).

• X_pending (Optional[Tensor]) – A batch_shape x 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.

• constraints (Optional[List[Callable[[Tensor], Tensor]]]) – A list of constraint callables which map a Tensor of posterior samples of dimension sample_shape x batch-shape x q x m-dim to a sample_shape x batch-shape x q-dim Tensor. The associated constraints are satisfied if constraint(samples) < 0.

• eta (Union[Tensor, float]) – Temperature parameter(s) governing the smoothness of the sigmoid approximation to the constraint indicators. See the docs of compute_(log_)smoothed_constraint_indicator for details.

• fat (bool) – Toggles the logarithmic / linear asymptotic behavior of the smooth approximation to the ReLU.

• prune_baseline (bool) – If True, remove points in X_baseline that are highly unlikely to be the best point. This can significantly improve performance and is generally recommended. In order to customize pruning parameters, instead manually call botorch.acquisition.utils.prune_inferior_points on X_baseline before instantiating the acquisition function.

• cache_root (bool) – A boolean indicating whether to cache the root decomposition over X_baseline and use low-rank updates.

• tau_max (float) – Temperature parameter controlling the sharpness of the smooth approximations to max.

• tau_relu (float) – Temperature parameter controlling the sharpness of the smooth approximations to ReLU.

• kwargs (Any) – Here for qNEI for compatibility.

TODO: similar to qNEHVI, when we are using sequential greedy candidate selection, we could incorporate pending points X_baseline and compute the incremental q(Log)NEI from the new point. This would greatly increase efficiency for large batches.

compute_best_f(obj)[source]¶

Computes the best (feasible) noisy objective value.

Parameters:

obj (Tensor) – sample_shape x batch_shape x q-dim Tensor of objectives in forward.

Returns:

A sample_shape x batch_shape-dim Tensor of best feasible objectives.

Return type:

Tensor

botorch.acquisition.logei.check_tau(tau, name)[source]¶

Checks the validity of the tau arguments of the functions below, and returns tau if it is valid.

Parameters:

• tau (FloatOrTensor) –

• name (str) –

Return type:

FloatOrTensor

Multi-Objective Analytic Acquisition Functions¶

Analytic Acquisition Functions for Multi-objective Bayesian optimization.

References

class botorch.acquisition.multi_objective.analytic.ExpectedHypervolumeImprovement(model, ref_point, partitioning, posterior_transform=None)[source]¶

Bases: MultiObjectiveAnalyticAcquisitionFunction

Expected Hypervolume Improvement supporting m>=2 outcomes.

This implements the computes EHVI using the algorithm from [Yang2019], but additionally computes gradients via auto-differentiation as proposed by [Daulton2020qehvi].

Note: this is currently inefficient in two ways due to the binary partitioning algorithm that we use for the box decomposition:

• We have more boxes in our decomposition

• If we used a box decomposition that used inf as the upper bound for

  the last dimension in all hypercells, then we could reduce the number of terms we need to compute from 2^m to 2^(m-1). [Yang2019] do this by using DKLV17 and LKF17 for the box decomposition.

TODO: Use DKLV17 and LKF17 for the box decomposition as in [Yang2019] for greater efficiency.

TODO: Add support for outcome constraints.

Example

>>> model = SingleTaskGP(train_X, train_Y)
>>> ref_point = [0.0, 0.0]
>>> EHVI = ExpectedHypervolumeImprovement(model, ref_point, partitioning)
>>> ehvi = EHVI(test_X)

Parameters:

• model (Model) – A fitted model.

• ref_point (List[float]) – A list with m elements representing the reference point (in the outcome space) w.r.t. to which compute the hypervolume. This is a reference point for the outcome values (i.e., after applying posterior_transform if provided).

• partitioning (NondominatedPartitioning) – A NondominatedPartitioning module that provides the non- dominated front and a partitioning of the non-dominated space in hyper- rectangles.

• posterior_transform (Optional[PosteriorTransform]) – A PosteriorTransform.

psi(lower, upper, mu, sigma)[source]¶

Compute Psi function.

For each cell i and outcome k:

Psi(lower_{i,k}, upper_{i,k}, mu_k, sigma_k) = ( sigma_k * PDF((upper_{i,k} - mu_k) / sigma_k) + ( mu_k - lower_{i,k} ) * (1 - CDF(upper_{i,k} - mu_k) / sigma_k) )

See Equation 19 in [Yang2019] for more details.

Parameters:

• lower (Tensor) – A num_cells x m-dim tensor of lower cell bounds

• upper (Tensor) – A num_cells x m-dim tensor of upper cell bounds

• mu (Tensor) – A batch_shape x 1 x m-dim tensor of means

• sigma (Tensor) – A batch_shape x 1 x m-dim tensor of standard deviations (clamped).

Returns:

A batch_shape x num_cells x m-dim tensor of values.

Return type:

Tensor

nu(lower, upper, mu, sigma)[source]¶

Compute Nu function.

For each cell i and outcome k:

nu(lower_{i,k}, upper_{i,k}, mu_k, sigma_k) = ( upper_{i,k} - lower_{i,k} ) * (1 - CDF((upper_{i,k} - mu_k) / sigma_k))

See Equation 25 in [Yang2019] for more details.

Parameters:

• lower (Tensor) – A num_cells x m-dim tensor of lower cell bounds

• upper (Tensor) – A num_cells x m-dim tensor of upper cell bounds

• mu (Tensor) – A batch_shape x 1 x m-dim tensor of means

• sigma (Tensor) – A batch_shape x 1 x m-dim tensor of standard deviations (clamped).

Returns:

A batch_shape x num_cells x m-dim tensor of values.

Return type:

Tensor

forward(X)[source]¶

Takes in a batch_shape x 1 x d X Tensor of t-batches with 1 d-dim design point each, and returns a Tensor with shape batch_shape’, where batch_shape’ is the broadcasted batch shape of model and input X.

Parameters:

X (Tensor) –

Return type:

Tensor

Multi-Objective Hypervolume Knowledge Gradient Acquisition Functions¶

The hypervolume knowledge gradient acquisition function (HVKG).

References:

class botorch.acquisition.multi_objective.hypervolume_knowledge_gradient.qHypervolumeKnowledgeGradient(model, ref_point, num_fantasies=8, num_pareto=10, sampler=None, objective=None, inner_sampler=None, X_evaluation_mask=None, X_pending=None, X_pending_evaluation_mask=None, current_value=None, use_posterior_mean=True, cost_aware_utility=None, **kwargs)[source]¶

Bases: DecoupledAcquisitionFunction, MultiObjectiveMCAcquisitionFunction, OneShotAcquisitionFunction

Batch Hypervolume Knowledge Gradient using one-shot optimization.

The hypervolume knowledge gradient seeks to maximize the difference in hypervolume of the hypervolume-maximizing set of a fixed size after conditioning the unknown observation(s) that would be recevied if X where evalauted. See [Daulton2023hvkg] for details.

This computes the batch Hypervolume Knowledge Gradient using fantasies for the outer expectation and MC-sampling for the inner expectation.

In addition to the design variables, the input X also includes variables for the optimal designs for each of the fantasy models (Note this is N x N_pareto optimal designs). For a fixed number of fantasies, all points in X can be optimized in a “one-shot” fashion.

q-Hypervolume Knowledge Gradient.

Parameters:

• model (Model) – A fitted model. Must support fantasizing.

• ref_point (Tensor) – A m-dim tensor containing the reference point.

• num_fantasies (int) – The number of fantasy points to use. More fantasy points result in a better approximation, at the expense of memory and wall time. Unused if sampler is specified.

• num_pareto (int) – The number of pareto optimal designs to consider.

• sampler (ListSampler | None) – The sampler used to sample fantasy observations. Optional if num_fantasies is specified. The optimization performance does not seem particularly sensitive to the number of fantasies. As the number of fantasies increases, the estimation of the expectation over fantasies becomes more accurate, but the one- shot optimization problem gets harder as there are more “fantasy” designs that need to be optimized.

• objective (MCMultiOutputObjective | None) – The objective under which the samples are evaluated. If None, then the analytic posterior mean is used. Otherwise, the objective is MC-evaluated (using inner_sampler).

• inner_sampler (MCSampler | None) – The sampler used for inner sampling. Ignored if the objective is None.

• X_evaluation_mask (List[Tensor] | None) – A q x m-dim tensor of booleans indicating which objective(s) each of the q points should be evaluated on.

• X_pending (Tensor | None) – A n’ x d-dim Tensor of m design points that have points that have been submitted for function evaluation but have not yet been evaluated.

• X_pending_evaluation_mask (Tensor | None) – A n’ x m-dim tensor of booleans indicating which objective(s) each of the n’ pending points are being evaluated on.

• current_value (Tensor | None) – The current value, i.e. the expected best objective given the observed points D. If omitted, forward will not return the actual KG value, but the expected best objective given the data set D u X. If pending points are used, this should be the current value under the fantasy model conditioned on the pending points so that the incremental KG value from the new candidates (not pending points) is used.

• use_posterior_mean (bool) – If true, optimize the hypervolume of the posterior mean, otherwise optimize the expected hypervolume. See [Daulton2023hvkg] for details.

• cost_aware_utility (CostAwareUtility | None) – A CostAwareUtility specifying the cost function for evaluating the X on the objectives indicated by evaluation_mask.

• kwargs (Any) –

property cost_sampler¶

forward(X)[source]¶

Evaluate qKnowledgeGradient on the candidate set X.

Parameters:

X (Tensor) –

A b x (q + num_fantasies) x d Tensor with b t-batches of q + num_fantasies design points each. We split this X tensor into two parts in the q dimension (dim=-2). The first q are the q-batch of design points and the last num_fantasies are the current solutions of the inner optimization problem.

X_fantasies = X[…, -num_fantasies:, :] X_fantasies.shape = b x num_fantasies x d

X_actual = X[…, :-num_fantasies, :] X_actual.shape = b x q x d

Returns:

A Tensor of shape b. For t-batch b, the q-KG value of the design

X_actual[b] is averaged across the fantasy models, where X_fantasies[b, i] is chosen as the final selection for the i-th fantasy model. NOTE: If current_value is not provided, then this is not the true KG value of X_actual[b], and X_fantasies[b, : ] must be maximized at fixed X_actual[b].

Return type:

Tensor

get_augmented_q_batch_size(q)[source]¶

Get augmented q batch size for one-shot optimization.

Parameters:

q (int) – The number of candidates to consider jointly.

Returns:

The augmented size for one-shot optimization (including variables parameterizing the fantasy solutions).

Return type:

int

extract_candidates(X_full)[source]¶

We only return X as the set of candidates post-optimization.

Parameters:

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

Returns:

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

Return type:

Tensor

class botorch.acquisition.multi_objective.hypervolume_knowledge_gradient.qMultiFidelityHypervolumeKnowledgeGradient(model, ref_point, target_fidelities, num_fantasies=8, num_pareto=10, sampler=None, objective=None, inner_sampler=None, X_pending=None, X_evaluation_mask=None, X_pending_evaluation_mask=None, current_value=None, cost_aware_utility=None, project=<function qMultiFidelityHypervolumeKnowledgeGradient.<lambda>>, valfunc_cls=None, valfunc_argfac=None, use_posterior_mean=True, **kwargs)[source]¶

Bases: qHypervolumeKnowledgeGradient

Batch Hypervolume Knowledge Gradient for multi-fidelity optimization.

See [Daulton2023hvkg] for details.

A version of qHypervolumeKnowledgeGradient that supports multi-fidelity optimization via a CostAwareUtility and the project and expand operators. If none of these are set, this acquisition function reduces to qHypervolumeKnowledgeGradient. Through valfunc_cls and valfunc_argfac, this can be changed into a custom multi-fidelity acquisition function.

Multi-Fidelity q-Knowledge Gradient (one-shot optimization).

Parameters:

• model (Model) – A fitted model. Must support fantasizing.

• ref_point (Tensor) – A m-dim tensor containing the reference point.

• num_fantasies (int) – The number of fantasy points to use. More fantasy points result in a better approximation, at the expense of memory and wall time. Unused if sampler is specified.

• num_pareto (int) – The number of pareto optimal designs to consider.

• sampler (MCSampler | None) – The sampler used to sample fantasy observations. Optional if num_fantasies is specified.

• objective (MCMultiOutputObjective | None) – The objective under which the samples are evaluated. If None, then the analytic posterior mean is used. Otherwise, the objective is MC-evaluated (using inner_sampler).

• inner_sampler (MCSampler | None) – The sampler used for inner sampling. Ignored if the objective is None.

• X_evaluation_mask (Tensor | None) – A q x m-dim tensor of booleans indicating which objective(s) each of the q points should be evaluated on.

• X_pending (Tensor | None) – A n’ x d-dim Tensor of m design points that have points that have been submitted for function evaluation but have not yet been evaluated.

• X_pending_evaluation_mask (Tensor | None) – A n’ x m-dim tensor of booleans indicating which objective(s) each of the n’ pending points are being evaluated on.

• current_value (Tensor | None) – The current value, i.e. the expected best objective given the observed points D. If omitted, forward will not return the actual KG value, but the expected best objective given the data set D u X. If pending points are used, this should be the current value under the fantasy model conditioned on the pending points so that the incremental KG value from the new candidates (not pending points) is used.

• use_posterior_mean (bool) – A boolean indicating whether to use the to optimize the hypervolume of the posterior mean or whether to optimize the expected hypervolume. See [Daulton2023hvkg] for details.

• cost_aware_utility (CostAwareUtility | None) – A CostAwareUtility specifying the cost function for evaluating the X on the objectives indicated by evaluation_mask.

• project (Callable[[Tensor], Tensor]) – A callable mapping a batch_shape x q x d tensor of design points to a tensor with shape batch_shape x q_term x d projected to the desired target set (e.g. the target fidelities in case of multi-fidelity optimization). For the basic case, q_term = q.

• valfunc_cls (Type[AcquisitionFunction] | None) – An acquisition function class to be used as the terminal value function.

• valfunc_argfac (Callable[[Model], Dict[str, Any]] | None) – An argument factory, i.e. callable that maps a Model to a dictionary of kwargs for the terminal value function (e.g. best_f for ExpectedImprovement).

• target_fidelities (Dict[int, float]) –

• kwargs (Any) –

forward(X)[source]¶

Evaluate qMultiFidelityKnowledgeGradient on the candidate set X.

Parameters:

X (Tensor) –

A b x (q + num_fantasies) x d Tensor with b t-batches of q + num_fantasies design points each. We split this X tensor into two parts in the q dimension (dim=-2). The first q are the q-batch of design points and the last num_fantasies are the current solutions of the inner optimization problem.

X_fantasies = X[…, -num_fantasies:, :] X_fantasies.shape = b x num_fantasies x d

X_actual = X[…, :-num_fantasies, :] X_actual.shape = b x q x d

In addition, X may be augmented with fidelity parameteres as part of thee d-dimension. Projecting fidelities to the target fidelity is handled by project.

Returns:

A Tensor of shape b. For t-batch b, the q-KG value of the design

X_actual[b] is averaged across the fantasy models, where X_fantasies[b, i] is chosen as the final selection for the i-th fantasy model. NOTE: If current_value is not provided, then this is not the true KG value of X_actual[b], and X_fantasies[b, : ] must be maximized at fixed X_actual[b].

Return type:

Tensor

Multi-Objective Joint Entropy Search Acquisition Functions¶

Acquisition functions for joint entropy search for Bayesian optimization (JES).

References:

class botorch.acquisition.multi_objective.joint_entropy_search.LowerBoundMultiObjectiveEntropySearch(model, pareto_sets, pareto_fronts, hypercell_bounds, X_pending=None, estimation_type='LB', num_samples=64, **kwargs)[source]¶

Bases: AcquisitionFunction, MCSamplerMixin

Abstract base class for the lower bound multi-objective entropy search acquisition functions.

Lower bound multi-objective entropy search acquisition function.

Parameters:

• model (Model) – A fitted batch model with ‘M’ number of outputs.

• pareto_sets (Tensor) – A num_pareto_samples x num_pareto_points x d-dim Tensor containing the sampled Pareto optimal sets of inputs.

• pareto_fronts (Tensor) – A num_pareto_samples x num_pareto_points x M-dim Tensor containing the sampled Pareto optimal sets of outputs.

• hypercell_bounds (Tensor) – A num_pareto_samples x 2 x J x M-dim Tensor containing the hyper-rectangle bounds for integration, where J is the number of hyper-rectangles. In the unconstrained case, this gives the partition of the dominated space. In the constrained case, this gives the partition of the feasible dominated space union the infeasible space.

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

• estimation_type (str) – A string to determine which entropy estimate is computed: “0”, “LB”, “LB2”, or “MC”.

• num_samples (int) – The number of Monte Carlo samples for the Monte Carlo estimate.

• kwargs (Any) –

abstract forward(X)[source]¶

Compute lower bound multi-objective entropy search at the design points X.

Parameters:

• X (Tensor) – A batch_shape x q x d-dim Tensor of batch_shape t-batches with q

• each. (d-dim design points) –

Returns:

A batch_shape-dim Tensor of acquisition values at the given design points X.

Return type:

Tensor

class botorch.acquisition.multi_objective.joint_entropy_search.qLowerBoundMultiObjectiveJointEntropySearch(model, pareto_sets, pareto_fronts, hypercell_bounds, X_pending=None, estimation_type='LB', num_samples=64, **kwargs)[source]¶

Bases: LowerBoundMultiObjectiveEntropySearch

The acquisition function for the multi-objective joint entropy search, where the batches q > 1 are supported through the lower bound formulation.

This acquisition function computes the mutual information between the observation at a candidate point X and the Pareto optimal input-output pairs.

See [Tu2022] for a discussion on the estimation procedure.

NOTES: (i) The estimated acquisition value could be negative.

(ii) The lower bound batch acquisition function might not be monotone in the sense that adding more elements to the batch does not necessarily increase the acquisition value. Specifically, the acquisition value can become smaller when more inputs are added.

Lower bound multi-objective joint entropy search acquisition function.

Parameters:

• model (Model) – A fitted batch model with ‘M’ number of outputs.

• pareto_sets (Tensor) – A num_pareto_samples x num_pareto_points x d-dim Tensor containing the sampled Pareto optimal sets of inputs.

• pareto_fronts (Tensor) – A num_pareto_samples x num_pareto_points x M-dim Tensor containing the sampled Pareto optimal sets of outputs.

• hypercell_bounds (Tensor) – A num_pareto_samples x 2 x J x M-dim Tensor containing the hyper-rectangle bounds for integration. In the unconstrained case, this gives the partition of the dominated space. In the constrained case, this gives the partition of the feasible dominated space union the infeasible space.

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

• estimation_type (str) – A string to determine which entropy estimate is computed: “0”, “LB”, “LB2”, or “MC”.

• num_samples (int) – The number of Monte Carlo samples used for the Monte Carlo estimate.

• kwargs (Any) –

forward(X)[source]¶

Evaluates qLowerBoundMultiObjectiveJointEntropySearch at the design points X.

Parameters:

• X (Tensor) – A batch_shape x q x d-dim Tensor of batch_shape t-batches with q

• each. (d-dim design points) –

Returns:

A batch_shape-dim Tensor of acquisition values at the given design points X.

Return type:

Tensor

Multi-Objective Max-value Entropy Search Acquisition Functions¶

Acquisition functions for max-value entropy search for multi-objective Bayesian optimization (MESMO).

References

class botorch.acquisition.multi_objective.max_value_entropy_search.qMultiObjectiveMaxValueEntropy(model, sample_pareto_frontiers, num_fantasies=16, X_pending=None, sampler=None, **kwargs)[source]¶

Bases: qMaxValueEntropy, MultiObjectiveMCAcquisitionFunction

The acquisition function for MESMO.

This acquisition function computes the mutual information of Pareto frontier and a candidate point. See [Belakaria2019] for a detailed discussion.

q > 1 is supported through cyclic optimization and fantasies.

Noisy observations are support by computing information gain with observation noise as in Appendix C in [Takeno2020mfmves].

Note: this only supports maximization.

_default_sample_shape¶

The sample_shape for the default sampler.

Example

>>> model = SingleTaskGP(train_X, train_Y)
>>> MESMO = qMultiObjectiveMaxValueEntropy(model, sample_pfs)
>>> mesmo = MESMO(test_X)

Multi-objective max-value entropy search acquisition function.

Parameters:

• model (Model) – A fitted multi-output model.

• sample_pareto_frontiers (Callable[[Model], Tensor]) – A callable that takes a model and returns a num_samples x n’ x m-dim tensor of outcomes to use for constructing num_samples sampled Pareto frontiers.

• num_fantasies (int) – Number of fantasies to generate. The higher this number the more accurate the model (at the expense of model complexity, wall time and memory). Ignored if X_pending is None.

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

• sampler (Optional[MCSampler]) –

• kwargs (Any) –

set_X_pending(X_pending=None)[source]¶

Set pending points.

Informs the acquisition function about pending design points, fantasizes the model on the pending points and draws max-value samples from the fantasized model posterior.

Parameters:

X_pending (Tensor | None) – 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

forward(X)[source]¶

Compute max-value entropy at the design points X.

Parameters:

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

Returns:

A batch_shape-dim Tensor of MVE values at the given design points X.

Return type:

Tensor

class botorch.acquisition.multi_objective.max_value_entropy_search.qLowerBoundMultiObjectiveMaxValueEntropySearch(model, hypercell_bounds, X_pending=None, estimation_type='LB', num_samples=64, **kwargs)[source]¶

Bases: LowerBoundMultiObjectiveEntropySearch

The acquisition function for the multi-objective Max-value Entropy Search, where the batches q > 1 are supported through the lower bound formulation.

This acquisition function computes the mutual information between the observation at a candidate point X and the Pareto optimal outputs.

See [Tu2022] for a discussion on the estimation procedure.

NOTES: (i) The estimated acquisition value could be negative.

(ii) The lower bound batch acquisition function might not be monotone in the sense that adding more elements to the batch does not necessarily increase the acquisition value. Specifically, the acquisition value can become smaller when more inputs are added.

Lower bound multi-objective max-value entropy search acquisition function.

Parameters:

• model (Model) – A fitted batch model with ‘M’ number of outputs.

• hypercell_bounds (Tensor) – A num_pareto_samples x 2 x J x M-dim Tensor containing the hyper-rectangle bounds for integration, where J is the number of hyper-rectangles. In the unconstrained case, this gives the partition of the dominated space. In the constrained case, this gives the partition of the feasible dominated space union the infeasible space.

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

• estimation_type (str) – A string to determine which entropy estimate is computed: “0”, “LB”, “LB2”, or “MC”.

• num_samples (int) – The number of Monte Carlo samples for the Monte Carlo estimate.

• kwargs (Any) –

forward(X)[source]¶

Evaluates qLowerBoundMultiObjectiveMaxValueEntropySearch at the design points X.

Parameters:

• X (Tensor) – A batch_shape x q x d-dim Tensor of batch_shape t-batches with q

• each. (d-dim design points) –

Returns:

A batch_shape-dim Tensor of acquisition values at the given design points X.

Return type:

Tensor

Multi-Objective Monte-Carlo Acquisition Functions¶

Monte-Carlo Acquisition Functions for Multi-objective Bayesian optimization. In particular, this module contains implementations of 1) qEHVI [Daulton2020qehvi], and 2) qNEHVI [Daulton2021nehvi].

References

class botorch.acquisition.multi_objective.monte_carlo.qExpectedHypervolumeImprovement(model, ref_point, partitioning, sampler=None, objective=None, constraints=None, X_pending=None, eta=0.001, fat=False)[source]¶

Bases: MultiObjectiveMCAcquisitionFunction, SubsetIndexCachingMixin

q-Expected Hypervolume Improvement supporting m>=2 outcomes.

See [Daulton2020qehvi] for details.

Example

>>> model = SingleTaskGP(train_X, train_Y)
>>> ref_point = [0.0, 0.0]
>>> qEHVI = qExpectedHypervolumeImprovement(model, ref_point, partitioning)
>>> qehvi = qEHVI(test_X)

Parameters:

• model (Model) – A fitted model.

• ref_point (Union[List[float], Tensor]) – A list or tensor with m elements representing the reference point (in the outcome space) w.r.t. to which compute the hypervolume. This is a reference point for the objective values (i.e. after applying`objective` to the samples).

• partitioning (NondominatedPartitioning) – A NondominatedPartitioning module that provides the non- dominated front and a partitioning of the non-dominated space in hyper- rectangles. If constraints are present, this partitioning must only include feasible points.

• sampler (Optional[MCSampler]) – The sampler used to draw base samples. If not given, a sampler is generated using get_sampler.

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

• constraints (Optional[List[Callable[[Tensor], Tensor]]]) – A list of callables, each mapping a Tensor of dimension sample_shape x batch-shape x q x m to a Tensor of dimension sample_shape x batch-shape x q, where negative values imply feasibility. The acquisition function will compute expected feasible hypervolume.

• X_pending (Optional[Tensor]) – A batch_shape x 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.

• eta (Optional[Union[Tensor, float]]) – The temperature parameter for the sigmoid function used for the differentiable approximation of the constraints. In case of a float the same eta is used for every constraint in constraints. In case of a tensor the length of the tensor must match the number of provided constraints. The i-th constraint is then estimated with the i-th eta value.

• fat (bool) – A Boolean flag indicating whether to use the heavy-tailed approximation of the constraint indicator.

forward(X)[source]¶

Takes in a batch_shape x q x d X Tensor of t-batches with q d-dim design points each, and returns a Tensor with shape batch_shape’, where batch_shape’ is the broadcasted batch shape of model and input X. Should utilize the result of set_X_pending as needed to account for pending function evaluations.

Parameters:

X (Tensor) –

Return type:

Tensor

Multi-objective variants of the LogEI family of acquisition functions, see [Ament2023logei] for details.

class botorch.acquisition.multi_objective.logei.qLogExpectedHypervolumeImprovement(model, ref_point, partitioning, sampler=None, objective=None, constraints=None, X_pending=None, eta=0.01, fat=True, tau_relu=1e-06, tau_max=0.01)[source]¶

Bases: MultiObjectiveMCAcquisitionFunction, SubsetIndexCachingMixin

Parallel Log Expected Hypervolume Improvement supporting m>=2 outcomes.

See [Ament2023logei] for details and the methodology behind the LogEI family of acquisition function. Line-by-line differences to the original differentiable expected hypervolume formulation of [Daulton2020qehvi] are described via inline comments in forward.

Example

>>> model = SingleTaskGP(train_X, train_Y)
>>> ref_point = [0.0, 0.0]
>>> acq = qLogExpectedHypervolumeImprovement(model, ref_point, partitioning)
>>> value = acq(test_X)

Parameters:

• model (Model) – A fitted model.

• ref_point (Union[List[float], Tensor]) – A list or tensor with m elements representing the reference point (in the outcome space) w.r.t. to which compute the hypervolume. This is a reference point for the objective values (i.e. after applying`objective` to the samples).

• partitioning (NondominatedPartitioning) – A NondominatedPartitioning module that provides the non- dominated front and a partitioning of the non-dominated space in hyper- rectangles. If constraints are present, this partitioning must only include feasible points.

• sampler (Optional[MCSampler]) – The sampler used to draw base samples. If not given, a sampler is generated using get_sampler.

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

• constraints (Optional[List[Callable[[Tensor], Tensor]]]) – A list of callables, each mapping a Tensor of dimension sample_shape x batch-shape x q x m to a Tensor of dimension sample_shape x batch-shape x q, where negative values imply feasibility. The acquisition function will compute expected feasible hypervolume.

• X_pending (Optional[Tensor]) – A batch_shape x 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.

• eta (Optional[Union[Tensor, float]]) – The temperature parameter for the sigmoid function used for the differentiable approximation of the constraints. In case of a float the same eta is used for every constraint in constraints. In case of a tensor the length of the tensor must match the number of provided constraints. The i-th constraint is then estimated with the i-th eta value.

• fat (bool) – Toggles the logarithmic / linear asymptotic behavior of the smooth approximation to the ReLU and the maximum.

• tau_relu (float) – Temperature parameter controlling the sharpness of the approximation to the ReLU over the q candidate points. For further details, see the comments above the definition of TAU_RELU.

• tau_max (float) – Temperature parameter controlling the sharpness of the approximation to the max operator over the q candidate points. For further details, see the comments above the definition of TAU_MAX.

forward(X)[source]¶

Takes in a batch_shape x q x d X Tensor of t-batches with q d-dim design points each, and returns a Tensor with shape batch_shape’, where batch_shape’ is the broadcasted batch shape of model and input X. Should utilize the result of set_X_pending as needed to account for pending function evaluations.

Parameters:

X (Tensor) –

Return type:

Tensor

Multi-Objective Multi-Fidelity Acquisition Functions¶

Multi-Fidelity Acquisition Functions for Multi-objective Bayesian optimization.

References

class botorch.acquisition.multi_objective.multi_fidelity.MOMF(model, ref_point, partitioning, sampler=None, objective=None, constraints=None, eta=0.001, X_pending=None, cost_call=None, **kwargs)[source]¶

Bases: qExpectedHypervolumeImprovement

MOMF acquisition function supporting m>=2 outcomes. The model needs to have train_obj that has a fidelity objective appended to its end. In the following example we consider a 2-D output space but the ref_point is 3D because of fidelity objective.

See [Irshad2021MOMF] for details.

Example

>>> model = SingleTaskGP(train_X, train_Y)
>>> ref_point = [0.0, 0.0, 0.0]
>>> cost_func = lambda X: 5 + X[..., -1]
>>> momf = MOMF(model, ref_point, partitioning, cost_func)
>>> momf_val = momf(test_X)

Parameters:

• model (Model) – A fitted model. There are two default assumptions in the training data. train_X should have fidelity parameter s as the last dimension of the input and train_Y contains a trust objective as its last dimension.

• ref_point (Union[List[float], Tensor]) – A list or tensor with m+1 elements representing the reference point (in the outcome space) w.r.t. to which compute the hypervolume. The ‘+1’ takes care of the trust objective appended to train_Y. This is a reference point for the objective values (i.e. after applying`objective` to the samples).

• partitioning (NondominatedPartitioning) – A NondominatedPartitioning module that provides the non- dominated front and a partitioning of the non-dominated space in hyper- rectangles. If constraints are present, this partitioning must only include feasible points.

• sampler (Optional[MCSampler]) – The sampler used to draw base samples. If not given, a sampler is generated using get_sampler.

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

• constraints (Optional[List[Callable[[Tensor], Tensor]]]) – A list of callables, each mapping a Tensor of dimension sample_shape x batch-shape x q x m to a Tensor of dimension sample_shape x batch-shape x q, where negative values imply feasibility. The acquisition function will compute expected feasible hypervolume.

• X_pending (Optional[Tensor]) – A batch_shape x 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.

• cost_call (Callable[Tensor, Tensor]) – A callable cost function mapping a Tensor of dimension batch_shape x q x d to a cost Tensor of dimension batch_shape x q x m. Defaults to an AffineCostModel with C(s) = 1 + s.

• eta (Optional[Union[Tensor, float]]) – The temperature parameter for the sigmoid function used for the differentiable approximation of the constraints. In case of a float the same eta is used for every constraint in constraints. In case of a tensor the length of the tensor must match the number of provided constraints. The i-th constraint is then estimated with the i-th eta value.

• kwargs (Any) –

forward(X)[source]¶

Takes in a batch_shape x q x d X Tensor of t-batches with q d-dim design points each, and returns a Tensor with shape batch_shape’, where batch_shape’ is the broadcasted batch shape of model and input X. Should utilize the result of set_X_pending as needed to account for pending function evaluations.

Parameters:

X (Tensor) –

Return type:

Tensor

Multi-Objective Predictive Entropy Search Acquisition Functions¶

Acquisition function for predictive entropy search for multi-objective Bayesian optimization (PES). The code does not support constraint handling.

NOTE: The PES acquisition might not be differentiable. As a result, we recommend optimizing the acquisition function using finite differences.

References:

class botorch.acquisition.multi_objective.predictive_entropy_search.qMultiObjectivePredictiveEntropySearch(model, pareto_sets, maximize=True, X_pending=None, max_ep_iterations=250, ep_jitter=0.0001, test_jitter=0.0001, threshold=0.01, **kwargs)[source]¶

Bases: AcquisitionFunction

The acquisition function for Predictive Entropy Search. The code supports both single and multiple objectives as well as batching.

This acquisition function approximates the mutual information between the observation at a candidate point X and the Pareto optimal input using the moment-matching procedure known as expectation propagation (EP).

See the Appendix of [Garrido-Merchan2019] for the description of the EP procedure.

IMPORTANT NOTES: (i) The PES acquisition function estimated using EP is sometimes not differentiable, and therefore we advise using a finite-difference estimate of the gradient as opposed to the gradients identified using automatic differentiation, which occasionally outputs nan values.

The source of this differentiability is in the _update_damping function, which finds the damping factor a that is used to update the EP parameters a * param_new + (1 - a) * param_old. The damping factor has to ensure that the updated covariance matrices, a * cov_f_new + (1 - a) cov_f_old, is positive semi-definiteness. We follow the original paper, which identifies a via a successive halving scheme i.e. we check a=1 then a=0.5 etc. This procedure means a is a function of the test input X. This function is not differentiable in X.

2. EP could potentially fail for a number of reasons:

(a) When the sampled Pareto optimal points x_p is poor compared to the training or testing data x_n.

(b) When the training or testing data x_n is close the Pareto optimal points x_p.

3. When the convergence threshold is set too small.

Problem (a) occurs because we have to compute the variable: alpha = (mean(x_n) - mean(x_p)) / std(x_n - x_p), which becomes very large when x_n is better than x_p with high-probability. This leads to a log(0) error when we compute log(1 - cdf(alpha)). We have preemptively clamped some values depending on 1`alpha in order to mitigate this.

Problem (b) occurs because we have to compute matrix inverses for the two-dimensional marginals (x_n, x_p). To address this we manually add jitter to the diagonal of the covariance matrix i.e. ep_jitter when training and test_jitter when testing. The default choice is not always appropriate because the same jitter is used for the inversion of the covariance and precision matrix, which are on different scales.

TODO: come up with strategy to adaptively update the jitter.

Problem (c) occurs because a smaller threshold usually means that more EP iterations are required. Running too many EP iterations could lead to invertibility problems such as in problem (b). Setting a larger threshold or reducing the number of EP iterations could alleviate this.

3. The estimated acquisition value could be negative.

Multi-objective predictive entropy search acquisition function.

Parameters:

• model (Model) – A fitted batched model with M number of outputs.

• pareto_sets (Tensor) – A num_pareto_samples x P x d-dim tensor containing the Pareto optimal set of inputs, where P is the number of pareto optimal points. The points in each sample have to be discrete otherwise expectation propagation will fail.

• maximize (bool) – If true, we consider a maximization problem.

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

• max_ep_iterations (int) – The maximum number of expectation propagation iterations. (The minimum number of iterations is set at 3.)

• ep_jitter (float) – The amount of jitter added for the matrix inversion that occurs during the expectation propagation update during the training phase.

• test_jitter (float) – The amount of jitter added for the matrix inversion that occurs during the expectation propagation update in the testing phase.

• threshold (float) – The convergence threshold for expectation propagation. This assesses the relative change in the mean and covariance. We default to one percent change i.e. threshold = 1e-2.

• kwargs (Any) –

forward(X)[source]¶

Evaluate qMultiObjectivePredictiveEntropySearch on the candidate set X.

Parameters:

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

Returns:

A batch_shape’-dim Tensor of acquisition values at the given design points X.

Return type:

Tensor

botorch.acquisition.multi_objective.predictive_entropy_search.log_cdf_robust(x)[source]¶

Computes the logarithm of the normal cumulative density robustly. This uses the approximation log(1-z) ~ -z when z is small:

if x > 5:

log(cdf(x)) = log(1-cdf(-x)) approx -cdf(-x)

else:

log(cdf(x)).

Parameters:

x (Tensor) – a x_shape-dim Tensor.

Return type:

Tensor

Returns

A x_shape-dim Tensor.

The One-Shot Knowledge Gradient¶

Batch Knowledge Gradient (KG) via one-shot optimization as introduced in [Balandat2020botorch]. For broader discussion of KG see also [Frazier2008knowledge] and [Wu2016parallelkg].

class botorch.acquisition.knowledge_gradient.qKnowledgeGradient(model, num_fantasies=64, sampler=None, objective=None, posterior_transform=None, inner_sampler=None, X_pending=None, current_value=None)[source]¶

Bases: MCAcquisitionFunction, OneShotAcquisitionFunction

Batch Knowledge Gradient using one-shot optimization.

This computes the batch Knowledge Gradient using fantasies for the outer expectation and either the model posterior mean or MC-sampling for the inner expectation.

In addition to the design variables, the input X also includes variables for the optimal designs for each of the fantasy models. For a fixed number of fantasies, all parts of X can be optimized in a “one-shot” fashion.

q-Knowledge Gradient (one-shot optimization).

Parameters:

• model (Model) – A fitted model. Must support fantasizing.

• num_fantasies (Optional[int]) – The number of fantasy points to use. More fantasy points result in a better approximation, at the expense of memory and wall time. Unused if sampler is specified.

• sampler (Optional[MCSampler]) – The sampler used to sample fantasy observations. Optional if num_fantasies is specified.

• objective (Optional[MCAcquisitionObjective]) – The objective under which the samples are evaluated. If None, then the analytic posterior mean is used. Otherwise, the objective is MC-evaluated (using inner_sampler).

• posterior_transform (Optional[PosteriorTransform]) – An optional PosteriorTransform. If given, this transforms the posterior before evaluation. If objective is None, then the analytic posterior mean of the transformed posterior is used. If objective is given, the inner_sampler is used to draw samples from the transformed posterior, which are then evaluated under the objective.

• inner_sampler (Optional[MCSampler]) – The sampler used for inner sampling. Ignored if the objective is None.

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

• current_value (Optional[Tensor]) – The current value, i.e. the expected best objective given the observed points D. If omitted, forward will not return the actual KG value, but the expected best objective given the data set D u X.

forward(X)[source]¶

Evaluate qKnowledgeGradient on the candidate set X.

Parameters:

X (Tensor) –

A b x (q + num_fantasies) x d Tensor with b t-batches of q + num_fantasies design points each. We split this X tensor into two parts in the q dimension (dim=-2). The first q are the q-batch of design points and the last num_fantasies are the current solutions of the inner optimization problem.

X_fantasies = X[…, -num_fantasies:, :] X_fantasies.shape = b x num_fantasies x d

X_actual = X[…, :-num_fantasies, :] X_actual.shape = b x q x d

Returns:

A Tensor of shape b. For t-batch b, the q-KG value of the design

X_actual[b] is averaged across the fantasy models, where X_fantasies[b, i] is chosen as the final selection for the i-th fantasy model. NOTE: If current_value is not provided, then this is not the true KG value of X_actual[b], and X_fantasies[b, : ] must be maximized at fixed X_actual[b].

Return type:

Tensor

evaluate(X, bounds, **kwargs)[source]¶

Evaluate qKnowledgeGradient on the candidate set X_actual by solving the inner optimization problem.

Parameters:

• X (Tensor) – A b x q x d Tensor with b t-batches of q design points each. Unlike forward(), this does not include solutions of the inner optimization problem.

• bounds (Tensor) – A 2 x d tensor of lower and upper bounds for each column of the solutions to the inner problem.

• kwargs (Any) – Additional keyword arguments. This includes the options for optimization of the inner problem, i.e. num_restarts, raw_samples, an options dictionary to be passed on to the optimization helpers, and a scipy_options dictionary to be passed to scipy.minimize.

Returns:

A Tensor of shape b. For t-batch b, the q-KG value of the design

X[b] is averaged across the fantasy models. NOTE: If current_value is not provided, then this is not the true KG value of X[b].

Return type:

Tensor

get_augmented_q_batch_size(q)[source]¶

Get augmented q batch size for one-shot optimization.

Parameters:

q (int) – The number of candidates to consider jointly.

Returns:

The augmented size for one-shot optimization (including variables parameterizing the fantasy solutions).

Return type:

int

extract_candidates(X_full)[source]¶

We only return X as the set of candidates post-optimization.

Parameters:

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

Returns:

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

Return type:

Tensor

class botorch.acquisition.knowledge_gradient.qMultiFidelityKnowledgeGradient(model, num_fantasies=64, sampler=None, objective=None, posterior_transform=None, inner_sampler=None, X_pending=None, current_value=None, cost_aware_utility=None, project=<function qMultiFidelityKnowledgeGradient.<lambda>>, expand=<function qMultiFidelityKnowledgeGradient.<lambda>>, valfunc_cls=None, valfunc_argfac=None)[source]¶

Bases: qKnowledgeGradient

Batch Knowledge Gradient for multi-fidelity optimization.

A version of qKnowledgeGradient that supports multi-fidelity optimization via a CostAwareUtility and the project and expand operators. If none of these are set, this acquisition function reduces to qKnowledgeGradient. Through valfunc_cls and valfunc_argfac, this can be changed into a custom multi-fidelity acquisition function (it is only KG if the terminal value is computed using a posterior mean).

Multi-Fidelity q-Knowledge Gradient (one-shot optimization).

Parameters:

• model (Model) – A fitted model. Must support fantasizing.

• num_fantasies (Optional[int]) – The number of fantasy points to use. More fantasy points result in a better approximation, at the expense of memory and wall time. Unused if sampler is specified.

• sampler (Optional[MCSampler]) – The sampler used to sample fantasy observations. Optional if num_fantasies is specified.

• objective (Optional[MCAcquisitionObjective]) – The objective under which the samples are evaluated. If None, then the analytic posterior mean is used. Otherwise, the objective is MC-evaluated (using inner_sampler).

• posterior_transform (Optional[PosteriorTransform]) – An optional PosteriorTransform. If given, this transforms the posterior before evaluation. If objective is None, then the analytic posterior mean of the transformed posterior is used. If objective is given, the inner_sampler is used to draw samples from the transformed posterior, which are then evaluated under the objective.

• inner_sampler (Optional[MCSampler]) – The sampler used for inner sampling. Ignored if the objective is None.

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

• current_value (Optional[Tensor]) – The current value, i.e. the expected best objective given the observed points D. If omitted, forward will not return the actual KG value, but the expected best objective given the data set D u X.

• cost_aware_utility (Optional[CostAwareUtility]) – A CostAwareUtility computing the cost-transformed utility from a candidate set and samples of increases in utility.

• project (Callable[[Tensor], Tensor]) – A callable mapping a batch_shape x q x d tensor of design points to a tensor with shape batch_shape x q_term x d projected to the desired target set (e.g. the target fidelities in case of multi-fidelity optimization). For the basic case, q_term = q.

• expand (Callable[[Tensor], Tensor]) – A callable mapping a batch_shape x q x d input tensor to a batch_shape x (q + q_e)’ x d-dim output tensor, where the q_e additional points in each q-batch correspond to additional (“trace”) observations.

• valfunc_cls (Optional[Type[AcquisitionFunction]]) – An acquisition function class to be used as the terminal value function.

• valfunc_argfac (Optional[Callable[[Model], Dict[str, Any]]]) – An argument factory, i.e. callable that maps a Model to a dictionary of kwargs for the terminal value function (e.g. best_f for ExpectedImprovement).

property cost_sampler¶

forward(X)[source]¶

Evaluate qMultiFidelityKnowledgeGradient on the candidate set X.

Parameters:

X (Tensor) –

A b x (q + num_fantasies) x d Tensor with b t-batches of q + num_fantasies design points each. We split this X tensor into two parts in the q dimension (dim=-2). The first q are the q-batch of design points and the last num_fantasies are the current solutions of the inner optimization problem.

X_fantasies = X[…, -num_fantasies:, :] X_fantasies.shape = b x num_fantasies x d

X_actual = X[…, :-num_fantasies, :] X_actual.shape = b x q x d

In addition, X may be augmented with fidelity parameters as part of thee d-dimension. Projecting fidelities to the target fidelity is handled by project.

Returns:

A Tensor of shape b. For t-batch b, the q-KG value of the design

X_actual[b] is averaged across the fantasy models, where X_fantasies[b, i] is chosen as the final selection for the i-th fantasy model. NOTE: If current_value is not provided, then this is not the true KG value of X_actual[b], and X_fantasies[b, : ] must be maximized at fixed X_actual[b].

Return type:

Tensor