trieste.acquisition.interface#

This module contains the interfaces relating to acquisition function — functions that estimate the utility of evaluating sets of candidate points.

Module Contents#

AcquisitionFunction[source]#

Type alias for acquisition functions.

An AcquisitionFunction maps a set of B query points (each of dimension D) to a single value that describes how useful it would be evaluate all these points together (to our goal of optimizing the objective function). Thus, with leading dimensions, an AcquisitionFunction takes input shape […, B, D] and returns shape […, 1].

Note that AcquisitionFunction`s which do not support batch optimization still expect inputs with a batch dimension, i.e. an input of shape `[..., 1, D].

class AcquisitionFunctionClass[source]#

Bases: abc.ABC

An AcquisitionFunctionClass is an acquisition function represented using a class rather than as a standalone function. Using a class to represent an acquisition function makes it easier to update it, to avoid having to retrace the function on every call.

abstract __call__(x: trieste.types.TensorType) → trieste.types.TensorType[source]#: Call acquisition function.

class AcquisitionFunctionBuilder[source]#

Bases: Generic[trieste.models.interfaces.ProbabilisticModelType], abc.ABC

An AcquisitionFunctionBuilder builds and updates an acquisition function.

abstract prepare_acquisition_function(models: Mapping[trieste.types.Tag, trieste.models.interfaces.ProbabilisticModelType], datasets: Mapping[trieste.types.Tag, trieste.data.Dataset] | None = None) → AcquisitionFunction[source]#

Prepare an acquisition function. We assume that this requires at least models, but it may sometimes also need data.

Parameters:

models – The models for each tag.
datasets – The data from the observer (optional).

Returns:

An acquisition function.

update_acquisition_function(function: AcquisitionFunction, models: Mapping[trieste.types.Tag, trieste.models.interfaces.ProbabilisticModelType], datasets: Mapping[trieste.types.Tag, trieste.data.Dataset] | None = None) → AcquisitionFunction[source]#

Update an acquisition function. By default this generates a new acquisition function each time. However, if the function is decorated with @tf.function, then you can override this method to update its variables instead and avoid retracing the acquisition function on every optimization loop.

Parameters:

function – The acquisition function to update.
models – The models for each tag.
datasets – The data from the observer (optional).

Returns:

The updated acquisition function.

class SingleModelAcquisitionBuilder[source]#

Bases: Generic[trieste.models.interfaces.ProbabilisticModelType], abc.ABC

Convenience acquisition function builder for an acquisition function (or component of a composite acquisition function) that requires only one model, dataset pair.

using(tag: trieste.types.Tag) → AcquisitionFunctionBuilder[trieste.models.interfaces.ProbabilisticModelType][source]#

Parameters:: tag – The tag for the model, dataset pair to use to build this acquisition function.
Returns:: An acquisition function builder that selects the model and dataset specified by tag, as defined in prepare_acquisition_function().

abstract prepare_acquisition_function(model: trieste.models.interfaces.ProbabilisticModelType, dataset: trieste.data.Dataset | None = None) → AcquisitionFunction[source]#

Parameters:

model – The model.
dataset – The data to use to build the acquisition function (optional).

Returns:

An acquisition function.

Parameters:

function – The acquisition function to update.
model – The model.
dataset – The data from the observer (optional).

Returns:

The updated acquisition function.

class GreedyAcquisitionFunctionBuilder[source]#

Bases: Generic[trieste.models.interfaces.ProbabilisticModelType], abc.ABC

A GreedyAcquisitionFunctionBuilder builds an acquisition function suitable for greedily building batches for batch Bayesian Optimization. A GreedyAcquisitionFunctionBuilder differs from an AcquisitionFunctionBuilder by requiring that a set of pending points is passed to the builder. Note that this acquisition function is typically called B times each Bayesian optimization step, when building batches of size B.

Generate a new acquisition function. The first time this is called, pending_points will be None. Subsequent calls will be via update_acquisition_function below, unless that has been overridden.

Parameters:

models – The models over each tag.
datasets – The data from the observer (optional).
pending_points – Points already chosen to be in the current batch (of shape [M,D]), where M is the number of pending points and D is the search space dimension.

Returns:

An acquisition function.

Update an acquisition function. By default this generates a new acquisition function each time. However, if the function is decorated with`@tf.function`, then you can override this method to update its variables instead and avoid retracing the acquisition function on every optimization loop.

Parameters:

function – The acquisition function to update.
models – The models over each tag.
datasets – The data from the observer (optional).
pending_points – Points already chosen to be in the current batch (of shape [M,D]), where M is the number of pending points and D is the search space dimension.
new_optimization_step – Indicates whether this call to update_acquisition_function is to start of a new optimization step, of to continue collecting batch of points for the current step. Defaults to True.

Returns:

The updated acquisition function.

class SingleModelGreedyAcquisitionBuilder[source]#

Bases: Generic[trieste.models.interfaces.ProbabilisticModelType], abc.ABC

Convenience acquisition function builder for a greedy acquisition function (or component of a composite greedy acquisition function) that requires only one model, dataset pair.

using(tag: trieste.types.Tag) → GreedyAcquisitionFunctionBuilder[trieste.models.interfaces.ProbabilisticModelType][source]#

Parameters:: tag – The tag for the model, dataset pair to use to build this acquisition function.
Returns:: An acquisition function builder that selects the model and dataset specified by tag, as defined in prepare_acquisition_function().

abstract prepare_acquisition_function(model: trieste.models.interfaces.ProbabilisticModelType, dataset: trieste.data.Dataset | None = None, pending_points: trieste.types.TensorType | None = None) → AcquisitionFunction[source]#

Parameters:

model – The model.
dataset – The data from the observer (optional).
pending_points – Points already chosen to be in the current batch (of shape [M,D]), where M is the number of pending points and D is the search space dimension.

Returns:

An acquisition function.

update_acquisition_function(function: AcquisitionFunction, model: trieste.models.interfaces.ProbabilisticModelType, dataset: trieste.data.Dataset | None = None, pending_points: trieste.types.TensorType | None = None, new_optimization_step: bool = True) → AcquisitionFunction[source]#

Parameters:

function – The acquisition function to update.
model – The model.
dataset – The data from the observer (optional).
pending_points – Points already chosen to be in the current batch (of shape [M,D]), where M is the number of pending points and D is the search space dimension.
new_optimization_step – Indicates whether this call to update_acquisition_function is to start of a new optimization step, of to continue collecting batch of points for the current step. Defaults to True.

Returns:

The updated acquisition function.

class VectorizedAcquisitionFunctionBuilder[source]#

Bases: AcquisitionFunctionBuilder[trieste.models.interfaces.ProbabilisticModelType]

An VectorizedAcquisitionFunctionBuilder builds and updates a vectorized acquisition function These differ from normal acquisition functions only by their output shape: rather than returning a single value, they return one value per potential query point. Thus, with leading dimensions, they take input shape […, B, D] and returns shape […, B].

class SingleModelVectorizedAcquisitionBuilder[source]#

Bases: SingleModelAcquisitionBuilder[trieste.models.interfaces.ProbabilisticModelType]

Convenience acquisition function builder for vectorized acquisition functions (or component of a composite vectorized acquisition function) that requires only one model, dataset pair.

using(tag: trieste.types.Tag) → AcquisitionFunctionBuilder[trieste.models.interfaces.ProbabilisticModelType][source]#

Parameters:: tag – The tag for the model, dataset pair to use to build this acquisition function.
Returns:: An acquisition function builder that selects the model and dataset specified by tag, as defined in prepare_acquisition_function().

PenalizationFunction[source]#: An PenalizationFunction maps a query point (of dimension D) to a single value that described how heavily it should be penalized (a positive quantity). As penalization is applied multiplicatively to acquisition functions, small penalization outputs correspond to a stronger penalization effect. Thus, with leading dimensions, an PenalizationFunction takes input shape […, 1, D] and returns shape […, 1].

class UpdatablePenalizationFunction[source]#

Bases: abc.ABC

An UpdatablePenalizationFunction builds and updates a penalization function. Defining a penalization function that can be updated avoids having to retrace on every call.

abstract __call__(x: trieste.types.TensorType) → trieste.types.TensorType[source]#: Call penalization function..

abstract update(pending_points: trieste.types.TensorType, lipschitz_constant: trieste.types.TensorType, eta: trieste.types.TensorType) → None[source]#: Update penalization function.