trieste.acquisition.rule#

This module contains acquisition rules, which choose the optimal point(s) to query on each step of the Bayesian optimization process.

Module Contents#

ResultType[source]#: Unbound covariant type variable.

SearchSpaceType[source]#: Contravariant type variable bound to SearchSpace.

T[source]#: Unbound type variable.

class AcquisitionRule[source]#

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

The central component of the acquisition API.

An AcquisitionRule can produce any value from the search space for this step, and the historic data and models. This value is typically a set of query points, either on its own as a TensorType (see e.g. EfficientGlobalOptimization), or within some context (see e.g. BatchTrustRegion). Indeed, to use an AcquisitionRule in the main BayesianOptimizer Bayesian optimization loop, the rule must return either a TensorType or State-ful TensorType.

Note that an AcquisitionRule might only support models with specific features (for example, if it uses an acquisition function that relies on those features). The type of models supported by a rule is indicated by the generic type variable class:ProbabilisticModelType.

abstract acquire(search_space: SearchSpaceType, models: collections.abc.Mapping[trieste.types.Tag, trieste.models.interfaces.ProbabilisticModelType], datasets: collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset] | None = None) → ResultType[source]#

Return a value of type T_co. Typically this will be a set of query points, either on its own as a TensorType (see e.g. EfficientGlobalOptimization), or within some context (see e.g. BatchTrustRegion). We assume that this requires at least models, but it may sometimes also need data.

Type hints:

The search space must be a SearchSpace. The exact type of SearchSpace depends on the specific AcquisitionRule.

Parameters:

search_space – The local acquisition search space for this step.
models – The model for each tag.
datasets – The known observer query points and observations for each tag (optional).

Returns:

A value of type T_co.

acquire_single(search_space: SearchSpaceType, model: trieste.models.interfaces.ProbabilisticModelType, dataset: trieste.data.Dataset | None = None) → ResultType[source]#

A convenience wrapper for acquire() that uses only one model, dataset pair.

Parameters:

search_space – The global search space over which the optimization problem is defined.
model – The model to use.
dataset – The known observer query points and observations (optional).

Returns:

A value of type T_co.

filter_datasets(models: collections.abc.Mapping[trieste.types.Tag, trieste.models.interfaces.ProbabilisticModelType], datasets: collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset]) → collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset] | trieste.types.State[Any | None, collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset]][source]#

Filter the post-acquisition datasets before they are used for model training. For example, this can be used to remove points from the post-acquisition datasets that are no longer in the search space. Rules that need to update their internal state should return a State callable.

Parameters:

models – The model for each tag.
datasets – The updated datasets after previous acquisition step.

Returns:

The filtered datasets.

class LocalDatasetsAcquisitionRule[source]#

Bases: AcquisitionRule[ResultType, SearchSpaceType, trieste.models.interfaces.ProbabilisticModelType]

An AcquisitionRule that requires local datasets. For example, this is implemented by BatchTrustRegion.

property num_local_datasets: int[source]#

Abstractmethod:

The number of local datasets required by this rule.

abstract initialize_subspaces(search_space: SearchSpaceType) → None[source]#: Create local subspaces for when no initial subspaces are provided.

class EfficientGlobalOptimization(builder: None = None, optimizer: trieste.acquisition.optimizer.AcquisitionOptimizer[SearchSpaceType] | None = None, num_query_points: int = 1, initial_acquisition_function: trieste.acquisition.interface.AcquisitionFunction | None = None)[source]#

class EfficientGlobalOptimization(builder: trieste.acquisition.interface.AcquisitionFunctionBuilder[trieste.models.interfaces.ProbabilisticModelType] | trieste.acquisition.interface.GreedyAcquisitionFunctionBuilder[trieste.models.interfaces.ProbabilisticModelType] | trieste.acquisition.interface.SingleModelAcquisitionBuilder[trieste.models.interfaces.ProbabilisticModelType] | trieste.acquisition.interface.SingleModelGreedyAcquisitionBuilder[trieste.models.interfaces.ProbabilisticModelType], optimizer: trieste.acquisition.optimizer.AcquisitionOptimizer[SearchSpaceType] | None = None, num_query_points: int = 1, initial_acquisition_function: trieste.acquisition.interface.AcquisitionFunction | None = None)

Bases: AcquisitionRule[trieste.types.TensorType, SearchSpaceType, trieste.models.interfaces.ProbabilisticModelType]

Implements the Efficient Global Optimization, or EGO, algorithm.

Parameters:

builder – The acquisition function builder to use. Defaults to ExpectedImprovement.
optimizer – The optimizer with which to optimize the acquisition function built by builder. This should maximize the acquisition function, and must be compatible with the global search space. Defaults to automatic_optimizer_selector().
num_query_points – The number of points to acquire.
initial_acquisition_function – The initial acquisition function to use. Defaults to using the builder to construct one, but passing in a previously constructed function can occasionally be useful (e.g. to preserve random seeds).

__repr__() → str[source]#: Return repr(self).

property acquisition_function: trieste.acquisition.interface.AcquisitionFunction | None[source]#: The current acquisition function, updated last time acquire() was called.

acquire(search_space: SearchSpaceType, models: collections.abc.Mapping[trieste.types.Tag, trieste.models.interfaces.ProbabilisticModelType], datasets: collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset] | None = None) → trieste.types.TensorType[source]#

Return the query point(s) that optimizes the acquisition function produced by builder (see __init__()).

Parameters:

search_space – The local acquisition search space for this step.
models – The model for each tag.
datasets – The known observer query points and observations. Whether this is required depends on the acquisition function used.

Returns:

The single (or batch of) points to query.

class AsynchronousRuleState[source]#

Stores pending points for asynchronous rules. These are points which were requested but are not observed yet.

property has_pending_points: bool[source]#: Returns True if there is at least one pending point, and False otherwise.

remove_points(points_to_remove: trieste.types.TensorType) → AsynchronousRuleState[source]#

Removes all rows from current pending_points that are present in points_to_remove. If a point to remove occurs multiple times in the list of pending points, only first occurrence of it will be removed.

Parameters:: points_to_remove – Points to remove.
Returns:: New instance of AsynchronousRuleState with updated pending points.

add_pending_points(new_points: trieste.types.TensorType) → AsynchronousRuleState[source]#

Adds new_points to the already known pending points.

Parameters:: new_points – Points to add.
Returns:: New instance of AsynchronousRuleState with updated pending points.

class AsynchronousOptimization(builder: None = None, optimizer: trieste.acquisition.optimizer.AcquisitionOptimizer[SearchSpaceType] | None = None, num_query_points: int = 1)[source]#

class AsynchronousOptimization(builder: trieste.acquisition.interface.AcquisitionFunctionBuilder[trieste.models.interfaces.ProbabilisticModelType] | trieste.acquisition.interface.SingleModelAcquisitionBuilder[trieste.models.interfaces.ProbabilisticModelType], optimizer: trieste.acquisition.optimizer.AcquisitionOptimizer[SearchSpaceType] | None = None, num_query_points: int = 1)

Bases: AcquisitionRule[trieste.types.State[Optional[AsynchronousRuleState], trieste.types.TensorType], SearchSpaceType, trieste.models.interfaces.ProbabilisticModelType]

AsynchronousOptimization rule is designed for asynchronous BO scenarios. By asynchronous BO we understand a use case when multiple objective function can be launched in parallel and are expected to arrive at different times. Instead of waiting for the rest of observations to return, we want to immediately use acquisition function to launch a new observation and avoid wasting computational resources. See [ARC+19] or [KKSP18] for more details.

To make the best decision about next point to observe, acquisition function needs to be aware of currently running observations. We call such points “pending”, and consider them a part of acquisition state. We use AsynchronousRuleState to store these points.

AsynchronousOptimization works with non-greedy batch acquisition functions. For example, it would work with BatchMonteCarloExpectedImprovement, but cannot be used with ExpectedImprovement. If there are P pending points and the batch of size B is requested, the acquisition function is used with batch size P+B. During optimization first P points are fixed to pending, and thus we optimize and return the last B points only.

Parameters:

builder – Batch acquisition function builder. Defaults to BatchMonteCarloExpectedImprovement with 10 000 samples.
optimizer – The optimizer with which to optimize the acquisition function built by builder. This should maximize the acquisition function, and must be compatible with the global search space. Defaults to automatic_optimizer_selector().
num_query_points – The number of points to acquire.

__repr__() → str[source]#: Return repr(self).

Constructs a function that, given AsynchronousRuleState, returns a new state object and points to evaluate. The state object contains currently known pending points, that is points that were requested for evaluation, but observation for which was not received yet. To keep them up to date, pending points are compared against the given dataset, and whatever points are in the dataset are deleted.

Let’s suppose we have P pending points. To optimize the acquisition function we call it with batches of size P+1, where first P points are fixed to pending points. Optimization therefore happens over the last point only, which is returned.

Parameters:

search_space – The local acquisition search space for this step.
models – The model of the known data. Uses the single key OBJECTIVE.
datasets – The known observer query points and observations.

Returns:

A function that constructs the next acquisition state and the recommended query points from the previous acquisition state.

class AsynchronousGreedy(builder: trieste.acquisition.interface.GreedyAcquisitionFunctionBuilder[trieste.models.interfaces.ProbabilisticModelType] | trieste.acquisition.interface.SingleModelGreedyAcquisitionBuilder[trieste.models.interfaces.ProbabilisticModelType], optimizer: trieste.acquisition.optimizer.AcquisitionOptimizer[SearchSpaceType] | None = None, num_query_points: int = 1)[source]#

Bases: AcquisitionRule[trieste.types.State[Optional[AsynchronousRuleState], trieste.types.TensorType], SearchSpaceType, trieste.models.interfaces.ProbabilisticModelType]

AsynchronousGreedy rule, as name suggests, is designed for asynchronous BO scenarios. To see what we understand by asynchronous BO, see documentation for AsynchronousOptimization.

AsynchronousGreedy rule works with greedy batch acquisition functions and performs B steps of a greedy batch collection process, where B is the requested batch size.

Parameters:

builder – Acquisition function builder. Only greedy batch approaches are supported, because they can be told what points are pending.
optimizer – The optimizer with which to optimize the acquisition function built by builder. This should maximize the acquisition function, and must be compatible with the global search space. Defaults to automatic_optimizer_selector().
num_query_points – The number of points to acquire.

__repr__() → str[source]#: Return repr(self).

Parameters:

search_space – The local acquisition search space for this step.
models – The model of the known data. Uses the single key OBJECTIVE.
datasets – The known observer query points and observations.

Returns:

A function that constructs the next acquisition state and the recommended query points from the previous acquisition state.

class RandomSampling(num_query_points: int = 1)[source]#

Bases: AcquisitionRule[trieste.types.TensorType, trieste.space.SearchSpace, trieste.models.ProbabilisticModel]

This class performs random search for choosing optimal points. It uses sample method from SearchSpace to take random samples from the search space that are used as optimal points. Hence, it does not use any acquisition function. This acquisition rule can be useful as a baseline for other acquisition functions of interest.

Parameters:: num_query_points – The number of points to acquire. By default set to 1 point.
Raises:: ValueError – If num_query_points is less or equal to 0.

__repr__() → str[source]#: Return repr(self).

acquire(search_space: trieste.space.SearchSpace, models: collections.abc.Mapping[trieste.types.Tag, trieste.models.ProbabilisticModel], datasets: collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset] | None = None) → trieste.types.TensorType[source]#

Sample num_query_points (see __init__()) points from the search_space.

Parameters:

search_space – The acquisition search space.
models – Unused.
datasets – Unused.

Returns:

The num_query_points points to query.

class DiscreteThompsonSampling(num_search_space_samples: int, num_query_points: int, thompson_sampler: None = None, select_output: Callable[[trieste.types.TensorType], trieste.types.TensorType] = select_nth_output)[source]#

class DiscreteThompsonSampling(num_search_space_samples: int, num_query_points: int, thompson_sampler: trieste.acquisition.sampler.ThompsonSampler[trieste.models.interfaces.ProbabilisticModelType] | None = None, select_output: Callable[[trieste.types.TensorType], trieste.types.TensorType] = select_nth_output)

Bases: AcquisitionRule[trieste.types.TensorType, trieste.space.SearchSpace, trieste.models.interfaces.ProbabilisticModelType]

Implements Thompson sampling for choosing optimal points.

This rule returns the minimizers of functions sampled from our model and evaluated across a discretization of the search space (containing N candidate points).

The model is sampled either exactly (with an \(O(N^3)\) complexity), or sampled approximately through a random Fourier M feature decompisition (with an \(O(\min(n^3,M^3))\) complexity for a model trained on n points). The number M of Fourier features is specified when building the model.

Parameters:

num_search_space_samples – The number of points at which to sample the posterior.
num_query_points – The number of points to acquire.
thompson_sampler – Sampler to sample maximisers from the underlying model.
select_output – A method that returns the desired trajectory from a trajectory sampler with shape […, B], where B is a batch dimension. Defaults to the :func:~`trieste.acquisition.utils.select_nth_output` function with output dimension 0.

__repr__() → str[source]#: Return repr(self).

acquire(search_space: trieste.space.SearchSpace, models: collections.abc.Mapping[trieste.types.Tag, trieste.models.interfaces.ProbabilisticModelType], datasets: collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset] | None = None) → trieste.types.TensorType[source]#

Sample num_search_space_samples (see __init__()) points from the search_space. Of those points, return the num_query_points points at which random samples yield the minima of the model posterior.

Parameters:

search_space – The local acquisition search space for this step.
models – The model of the known data. Uses the single key OBJECTIVE.
datasets – The known observer query points and observations.

Returns:

The num_query_points points to query.

Raises:

ValueError – If models do not contain the key OBJECTIVE, or it contains any other key.

class UpdatableSearchSpace[source]#

Bases: trieste.space.SearchSpace

A search space that can be updated.

property requires_initialization: bool[source]#: Return True if the search space needs to be re-initialized with the latest models and datasets, and False if it can be just updated.

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

Initialize the search space using the given models and datasets.

Extending classes must set self._initialized to True after initialization in this method.

Parameters:

models – The model for each tag.
datasets – The dataset for each tag.

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

Update the search space using the given models and datasets.

Parameters:

models – The model for each tag.
datasets – The dataset for each tag.

class UpdatableTrustRegion(region_index: int | None = None, input_active_dims: slice | Sequence[int] | None = None)[source]#

Bases: UpdatableSearchSpace

An updatable trust region with a concept of a location within a global search space.

Parameters:

region_index – The index of the region in a multi-region search space. This is used to identify the local models and datasets to use for acquisition. If None, the global models and datasets are used.
input_active_dims –
The active dimensions of the input space, either a slice or list of indices into the columns of the space. If None, all dimensions are active.

When this region is part of a product search-space (via UpdatableTrustRegionProduct), this is used to select the active dimensions of the full input space that belong to this region.

_init_location(models: collections.abc.Mapping[trieste.types.Tag, trieste.models.interfaces.ProbabilisticModelType] | None = None, datasets: collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset] | None = None, location_candidate: trieste.types.TensorType | None = None) → None[source]#

Initialize the location of the region, either by sampling a new location from the global search space, or by using a candidate location if provided.

Derived classes can override this method to provide custom initialization logic.

Parameters:

models – The model for each tag.
datasets – The dataset for each tag.
location_candidate – A candidate for the location of the search space. If not None, this is used instead of sampling a new location.

property location: trieste.types.TensorType[source]#

Abstractmethod:

The center of the region.

property global_search_space: trieste.space.SearchSpace[source]#

Abstractmethod:

The global search space this region lives in.

with_input_active_dims(value: trieste.types.TensorType) → trieste.types.TensorType[source]#

with_input_active_dims(value: trieste.data.Dataset) → trieste.data.Dataset

with_input_active_dims(value: trieste.models.ProbabilisticModel) → trieste.models.ProbabilisticModel

Select and return active components from the input dimensions of the given value, using input_active_dims of this search space. If input_active_dims is None, all dimensions are returned.

For datasets, the active selection is applied to the query points. For models, no selection is applied; they are returned as is.

Parameters:: value – The value to select the active input dimensions for.
Returns:: The value with the active input dimensions selected.

select_in_region(mapping: None) → None[source]#

select_in_region(mapping: collections.abc.Mapping[trieste.types.Tag, trieste.types.TensorType]) → collections.abc.Mapping[trieste.types.Tag, trieste.types.TensorType]

select_in_region(mapping: collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset]) → collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset]

select_in_region(mapping: collections.abc.Mapping[trieste.types.Tag, trieste.models.ProbabilisticModel]) → collections.abc.Mapping[trieste.types.Tag, trieste.models.ProbabilisticModel]

Select items belonging to this region for, e.g., acquisition.

Parameters:: mapping – The mapping of items for each tag.
Returns:: The items belonging to this region (or None if there aren’t any).

get_datasets_filter_mask(datasets: collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset] | None) → collections.abc.Mapping[trieste.types.Tag, tensorflow.Tensor] | None[source]#

Return a boolean mask that can be used to filter out points from the datasets that belong to this region.

Parameters:: datasets – The dataset for each tag.
Returns:: A mapping for each tag belonging to this region, to a boolean mask that can be used to filter out points from the datasets. A value of True indicates that the corresponding point should be kept.

UpdatableTrustRegionType[source]#: A type variable bound to UpdatableTrustRegion.

class BatchTrustRegionState[source]#

Bases: Generic[UpdatableTrustRegionType]

The acquisition state for the BatchTrustRegion acquisition rule.

subspaces: Sequence[UpdatableTrustRegionType][source]#: The acquisition space’s subspaces.

subspace_tags: Sequence[str][source]#: The subspaces’ tags.

property acquisition_space: trieste.space.TaggedMultiSearchSpace[source]#: The acquisition search space.

class BatchTrustRegion(init_subspaces: None | UpdatableTrustRegionType | Sequence[UpdatableTrustRegionType] = None, rule: AcquisitionRule[trieste.types.TensorType, trieste.space.SearchSpace, trieste.models.interfaces.ProbabilisticModelType] | None = None)[source]#

Bases: LocalDatasetsAcquisitionRule[trieste.types.State[Optional[BatchTrustRegionState[UpdatableTrustRegionType]], trieste.types.TensorType], trieste.space.SearchSpace, trieste.models.interfaces.ProbabilisticModelType], Generic[trieste.models.interfaces.ProbabilisticModelType, UpdatableTrustRegionType]

Abstract class for multi trust region acquisition rules. These are batch algorithms where each query point is optimized in parallel, with its own separate trust region.

Note: to restart or continue an optimization with this rule, either the same instance of the rule must be used, or a new instance must be created with the subspaces from a previous state. This is because the internal state of the rule cannot be restored directly from a state object.

Parameters:

init_subspaces – The initial search spaces for each trust region. If None, default subspaces of type UpdatableTrustRegionType will be created, with length equal to the number of query points in the base rule.
rule –
The acquisition rule that defines how to search for a new query point in each subspace.

If None, defaults to DiscreteThompsonSampling with a batch size of 1 for TURBOBox subspaces, and EfficientGlobalOptimization otherwise.

__repr__() → str[source]#: Return repr(self).

property num_local_datasets: int[source]#: The number of local datasets required by this rule.

Use the rule specified at __init__() to find new query points. Return a function that constructs these points given a previous trust region state.

If state is None, initialize the subspaces by picking new locations. Otherwise, update the existing subspaces.

Re-initialize the subspaces if necessary, potentially looking at the entire group.

Parameters:

search_space – The acquisition search space for this step.
models – The model for each tag.
datasets – The known observer query points and observations for each tag.

Returns:

A function that constructs the next acquisition state and the recommended query points from the previous acquisition state.

maybe_initialize_subspaces(subspaces: Sequence[UpdatableTrustRegionType], models: collections.abc.Mapping[trieste.types.Tag, trieste.models.interfaces.ProbabilisticModelType], datasets: collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset] | None = None) → None[source]#

Initialize subspaces if necessary. Get a mask of subspaces that need to be initialized using an abstract method. Initialize individual subpaces by calling the method of the UpdatableTrustRegionType class.

This method can be overridden by subclasses to change this behaviour.

abstract get_initialize_subspaces_mask(subspaces: Sequence[UpdatableTrustRegionType], models: collections.abc.Mapping[trieste.types.Tag, trieste.models.interfaces.ProbabilisticModelType], datasets: collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset] | None = None) → trieste.types.TensorType[source]#

Return a boolean mask for subspaces that should be initialized. This method is called during the acquisition step to determine which subspaces should be initialized and which should be updated. The subspaces corresponding to True values in the mask will be re-initialized.

Parameters:

subspaces – The sequence of subspaces.
models – The model for each tag.
datasets – The dataset for each tag.

Returns:

A boolean mask of length V, where V is the number of subspaces.

filter_datasets(models: collections.abc.Mapping[trieste.types.Tag, trieste.models.interfaces.ProbabilisticModelType], datasets: collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset]) → trieste.types.State[BatchTrustRegionState[UpdatableTrustRegionType] | None, collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset]][source]#

Parameters:

models – The model for each tag.
datasets – The updated datasets after previous acquisition step.

Returns:

The filtered datasets.

class HypercubeTrustRegion(beta: float = 0.7, kappa: float = 0.0001, zeta: float = 0.5, min_eps: float = 0.01)[source]#

Bases: UpdatableTrustRegion

An abstract updatable trust region that defines a hypercube region in the global search space. The region is defined by a location and a size in each dimension. This class is used to implement different types of search spaces, e.g. continuous (SingleObjectiveTrustRegionBox) and discrete (SingleObjectiveTrustRegionDiscrete).

Derived classes must implement the _update_domain method to update the domain of the region based on the location and size.

In the default implementation, the region is updated based on the minimum observed value in the region from a single objective dataset. The region is expanded if the minimum is improved, and contracted otherwise. Derived classes can override how this minimum is calculated, e.g. by utilizing multiple datasets.

Calculates the bounds of the region from the location/center and global bounds.

Parameters:

beta – The inverse of the trust region contraction factor.
kappa – Scales the threshold for the minimal improvement required for a step to be considered a success.
zeta – The initial size of the trust region is zeta times the size of the global search space.
min_eps – The minimal size of the search space. If the size of the search space is smaller than this, the search space is reinitialized.

abstract _update_domain() → None[source]#: Update the local domain of the region.

property requires_initialization: bool[source]#

Return True if the search space needs to be initialized, and False otherwise.

If uninitialized, or the size of the region is less than the minimum size, re-initialize the region.

initialize(models: collections.abc.Mapping[trieste.types.Tag, trieste.models.interfaces.ProbabilisticModelType] | None = None, datasets: collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset] | None = None, location_candidate: trieste.types.TensorType | None = None) → None[source]#

Initialize the region by sampling a location from the global search space and setting the local region bounds around it.

Parameters:

models – The model for each tag.
datasets – The dataset for each tag.
location_candidate – A candidate for the location of the search space. If not None, this is used instead of sampling a new location.

update(models: collections.abc.Mapping[trieste.types.Tag, trieste.models.interfaces.ProbabilisticModelType] | None = None, datasets: collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset] | None = None) → None[source]#

Update this region, including center/location, using the given dataset.

If the new optimum improves over the previous optimum by some threshold (that scales linearly with kappa), the previous acquisition is considered successful.

If the previous acquisition was successful, the size is increased by a factor 1 / beta. Conversely, if it was unsuccessful, the size is reduced by the factor beta.

Parameters:

models – The model for each tag.
datasets – The dataset for each tag.

get_values_min(query_points: trieste.types.TensorType, values: trieste.types.TensorType, num_query_points: int | None = None, in_region_only: bool = True) → Tuple[trieste.types.TensorType, trieste.types.TensorType][source]#

Calculate the minimum of the region over the given values, returning the query point and value of the minimum. Optionally, only consider query points that are contained in the region.

Parameters:

query_points – The query points corresponding to the values.
values – The values to find the minimum over.
num_query_points – The number of latest query points to use for calculating the minimum. If None, all query points are used.
in_region_only – If True, only consider points contained in the region.

Returns:

The query point and value of the minimum.

get_dataset_min(datasets: collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset] | None) → Tuple[trieste.types.TensorType, trieste.types.TensorType][source]#

Calculate the minimum of the region using the given dataset, returning the query point and value of the minimum.

The default implementation supports a single objective dataset only. This can be overridden by subclasses to support multiple datasets.

Parameters:: datasets – The datasets to use for finding the minimum.
Returns:: The query point and value of the minimum.

class UpdatableTrustRegionBox(global_search_space: trieste.space.Box, region_index: int | None = None, input_active_dims: slice | Sequence[int] | None = None)[source]#

Bases: trieste.space.Box, UpdatableTrustRegion

A simple updatable box search space with a center location and an associated global search space.

Parameters:

global_search_space – The global search space this search space lives in.
region_index – The index of the region in a multi-region search space. This is used to identify the local models and datasets to use for acquisition. If None, the global models and datasets are used.
input_active_dims – The active dimensions of the input space, either a slice or list of indices into the columns of the space. If None, all dimensions are active.

property location: trieste.types.TensorType[source]#: The center of the region.

property global_search_space: trieste.space.Box[source]#: The global search space this region lives in.

class SingleObjectiveTrustRegionBox(global_search_space: trieste.space.Box, beta: float = 0.7, kappa: float = 0.0001, zeta: float = 0.5, min_eps: float = 0.01, region_index: int | None = None, input_active_dims: slice | Sequence[int] | None = None)[source]#

Bases: UpdatableTrustRegionBox, HypercubeTrustRegion

An updatable continuous trust region that defines a box region in the global search space. The region is updated based on the best point found in the region.

Calculates the bounds of the box from the location/center and global bounds.

Parameters:

global_search_space – The global search space this search space lives in.
beta – The inverse of the trust region contraction factor.
kappa – Scales the threshold for the minimal improvement required for a step to be considered a success.
zeta – The initial size of the trust region is zeta times the size of the global search space.
min_eps – The minimal size of the search space. If the size of the search space is smaller than this, the search space is reinitialized.
region_index – The index of the region in a multi-region search space. This is used to identify the local models and datasets to use for acquisition. If None, the global models and datasets are used.
input_active_dims – The active dimensions of the input space, either a slice or list of indices into the columns of the space. If None, all dimensions are active.

_update_domain() → None[source]#: Update the local domain of the region.

class BatchTrustRegionBox(init_subspaces: None | UpdatableTrustRegionType | Sequence[UpdatableTrustRegionType] = None, rule: AcquisitionRule[trieste.types.TensorType, trieste.space.SearchSpace, trieste.models.interfaces.ProbabilisticModelType] | None = None)[source]#

Bases: BatchTrustRegion[trieste.models.interfaces.ProbabilisticModelType, UpdatableTrustRegionBox]

Implements the BatchTrustRegion trust region acquisition rule for box regions. This is intended to be used for single-objective optimization with batching.

Parameters:

init_subspaces – The initial search spaces for each trust region. If None, default subspaces of type UpdatableTrustRegionType will be created, with length equal to the number of query points in the base rule.
rule –
The acquisition rule that defines how to search for a new query point in each subspace.

If None, defaults to DiscreteThompsonSampling with a batch size of 1 for TURBOBox subspaces, and EfficientGlobalOptimization otherwise.

initialize_subspaces(search_space: trieste.space.SearchSpace) → None[source]#: Create local subspaces for when no initial subspaces are provided.

Use the rule specified at __init__() to find new query points. Return a function that constructs these points given a previous trust region state.

If state is None, initialize the subspaces by picking new locations. Otherwise, update the existing subspaces.

Re-initialize the subspaces if necessary, potentially looking at the entire group.

Parameters:

search_space – The acquisition search space for this step.
models – The model for each tag.
datasets – The known observer query points and observations for each tag.

Returns:

A function that constructs the next acquisition state and the recommended query points from the previous acquisition state.

get_initialize_subspaces_mask(subspaces: Sequence[UpdatableTrustRegionBox], models: collections.abc.Mapping[trieste.types.Tag, trieste.models.interfaces.ProbabilisticModelType], datasets: collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset] | None = None) → trieste.types.TensorType[source]#

Parameters:

subspaces – The sequence of subspaces.
models – The model for each tag.
datasets – The dataset for each tag.

Returns:

A boolean mask of length V, where V is the number of subspaces.

class TREGOBox(global_search_space: trieste.space.Box, beta: float = 0.7, kappa: float = 0.0001, zeta: float = 0.5, min_eps: float = 0.01, region_index: int | None = None, input_active_dims: slice | Sequence[int] | None = None)[source]#

Bases: SingleObjectiveTrustRegionBox

A box trust region algorithm that alternates between regular EGO steps and local steps within a trust region. See [DPRP22] for details.

At construction, starts in global mode using global_search_space as the search space for the first step. Subsequent re-initializations use the trust region as the search space for the next step.

If the previous acquisition was successful, global_search_space is used as the new search space. If the previous step was unsuccessful, the search space is changed to the trust region if it was global, and vice versa.

If the previous acquisition was over the trust region, the size of the trust region is modified.

Note: The acquisition search space will never extend beyond the boundary of the global_search_space. For a local search, the actual search space will be the intersection of the trust region and global_search_space.

Calculates the bounds of the box from the location/center and global bounds.

Parameters:

global_search_space – The global search space this search space lives in.
beta – The inverse of the trust region contraction factor.
kappa – Scales the threshold for the minimal improvement required for a step to be considered a success.
zeta – The initial size of the trust region is zeta times the size of the global search space.
min_eps – The minimal size of the search space. If the size of the search space is smaller than this, the search space is reinitialized.
region_index – The index of the region in a multi-region search space. This is used to identify the local models and datasets to use for acquisition. If None, the global models and datasets are used.
input_active_dims – The active dimensions of the input space, either a slice or list of indices into the columns of the space. If None, all dimensions are active.

property eps: trieste.types.TensorType[source]#: The size of the search space.

_update_domain() → None[source]#: Update the local domain of the region.

Initialize the search space using the given models and datasets.

Extending classes must set self._initialized to True after initialization in this method.

Parameters:

models – The model for each tag.
datasets – The dataset for each tag.

get_datasets_filter_mask(datasets: collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset] | None) → collections.abc.Mapping[trieste.types.Tag, tensorflow.Tensor] | None[source]#

Return a boolean mask that can be used to filter out points from the datasets that belong to this region.

Parameters:: datasets – The dataset for each tag.
Returns:: A mapping for each tag belonging to this region, to a boolean mask that can be used to filter out points from the datasets. A value of True indicates that the corresponding point should be kept.

get_dataset_min(datasets: collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset] | None) → Tuple[trieste.types.TensorType, trieste.types.TensorType][source]#

Calculate the minimum of the region using the given dataset, returning the query point and value of the minimum.

The default implementation supports a single objective dataset only. This can be overridden by subclasses to support multiple datasets.

Parameters:: datasets – The datasets to use for finding the minimum.
Returns:: The query point and value of the minimum.

Bases: UpdatableTrustRegionBox

Implements the TURBO algorithm as detailed in [EPG+19].

Note that the optional parameters are set by a heuristic if not given by the user.

Parameters:

global_search_space – The global search space.
L_min – Minimum allowed length of the trust region.
L_init – Initial length of the trust region.
L_max – Maximum allowed length of the trust region.
success_tolerance – Number of consecutive successes before changing region size.
tolerance (failure) – Number of consecutive failures before changing region size.
region_index – The index of the region in a multi-region search space. This is used to identify the local models and datasets to use for acquisition. If None, the global models and datasets are used.
input_active_dims – The active dimensions of the input space, either a slice or list of indices into the columns of the space. If None, all dimensions are active.

Initialize the search space using the given models and datasets.

Extending classes must set self._initialized to True after initialization in this method.

Parameters:

models – The model for each tag.
datasets – The dataset for each tag.

Update the search space using the given models and datasets.

Parameters:

models – The model for each tag.
datasets – The dataset for each tag.

get_dataset_min(datasets: collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset] | None) → Tuple[trieste.types.TensorType, trieste.types.TensorType][source]#: Calculate the minimum of the box using the given dataset.

class UpdatableTrustRegionDiscrete(global_search_space: trieste.space.GeneralDiscreteSearchSpace, region_index: int | None = None, input_active_dims: slice | Sequence[int] | None = None)[source]#

Bases: trieste.space.DiscreteSearchSpace, UpdatableTrustRegion

An updatable discrete search space with an associated global search space.

Parameters:

global_search_space – The global search space this search space lives in.
region_index – The index of the region in a multi-region search space. This is used to identify the local models and datasets to use for acquisition. If None, the global models and datasets are used.
input_active_dims – The active dimensions of the input space, either a slice or list of indices into the columns of the space. If None, all dimensions are active.

property location: trieste.types.TensorType[source]#: The center of the region.

property global_search_space: trieste.space.GeneralDiscreteSearchSpace[source]#: The global search space this region lives in.

class FixedPointTrustRegionDiscrete(global_search_space: trieste.space.GeneralDiscreteSearchSpace, region_index: int | None = None, input_active_dims: slice | Sequence[int] | None = None)[source]#

Bases: UpdatableTrustRegionDiscrete

A discrete trust region with a fixed point location that does not change across active learning steps. The fixed point is selected at random from the global (discrete) search space at initialization time.

Parameters:

global_search_space – The global search space this search space lives in.
region_index – The index of the region in a multi-region search space. This is used to identify the local models and datasets to use for acquisition. If None, the global models and datasets are used.
input_active_dims – The active dimensions of the input space, either a slice or list of indices into the columns of the space. If None, all dimensions are active.

Initialize the search space using the given models and datasets.

Extending classes must set self._initialized to True after initialization in this method.

Parameters:

models – The model for each tag.
datasets – The dataset for each tag.

Update the search space using the given models and datasets.

Parameters:

models – The model for each tag.
datasets – The dataset for each tag.

class SingleObjectiveTrustRegionDiscrete(global_search_space: trieste.space.GeneralDiscreteSearchSpace, beta: float = 0.7, kappa: float = 0.0001, zeta: float = 0.5, min_eps: float = 0.01, region_index: int | None = None, input_active_dims: slice | Sequence[int] | None = None)[source]#

Bases: UpdatableTrustRegionDiscrete, HypercubeTrustRegion

An updatable discrete trust region that maintains a set of neighboring points around a single location point, allowing for local exploration of the search space. The region is updated based on the best point found in the region.

This trust region is designed for discrete numerical variables. As it uses axis-aligned Euclidean distance to determine the neighbors within the region, it is not suitable for qualitative (categorical, ordinal and binary) variables.

When using this trust region, it is important to consider the scaling of the number of value combinations. Since the region computes pairwise distances between points, the computational and memory complexity increases quadratically with the number of points. For example, 1000 3D points will result in the distances matrix containing 1000x1000x3 entries. Therefore, this trust region is not suitable for problems with a large number of points.

Select a random initial location from the global search space and select the initial neighbors within the trust region.

Parameters:

global_search_space – The global search space this search space lives in.
beta – The inverse of the trust region contraction factor.
kappa – Scales the threshold for the minimal improvement required for a step to be considered a success.
zeta – The initial size of the trust region is zeta times the size of the global search space.
min_eps – The minimal size of the search space. If the size of the search space is smaller than this, the search space is reinitialized.
region_index – The index of the region in a multi-region search space. This is used to identify the local models and datasets to use for acquisition. If None, the global models and datasets are used.
input_active_dims – The active dimensions of the input space, either a slice or list of indices into the columns of the space. If None, all dimensions are active.

_update_domain() → None[source]#: Update the local domain of the region.

class UpdatableTrustRegionProduct(regions: Sequence[UpdatableTrustRegion], tags: Sequence[str] | None = None, region_index: int | None = None)[source]#

Bases: trieste.space.TaggedProductSearchSpace, UpdatableTrustRegion

An updatable mixed search space that is the product of multiple updatable trust sub-regions.

This is useful for combining different types of search spaces, such as continuous and discrete, to form a mixed search space for trust region acquisition rules.

Note: the dtype of all the component search spaces must be the same.

Parameters:

regions – The trust sub-regions to be combined to create a product trust region.
tags – An optional list of tags giving the unique identifiers of the region’s sub-regions.
region_index – The index of the region in a multi-region search space. This is used to identify the local models and datasets to use for acquisition. If None, the global models and datasets are used.

property requires_initialization: bool[source]#

Return True if the search space needs to be initialized, and False otherwise.

Re-initialize the whole product region if any of the sub-regions need to be re-initialized.

property region_index: int | None[source]#: The index of the region in a multi-region search space.

property regions: collections.abc.Mapping[str, UpdatableTrustRegion][source]#: The sub-regions of the product trust region.

property location: trieste.types.TensorType[source]#: The location of the product trust region, concatenated from the locations of the sub-regions.

property global_search_space: trieste.space.TaggedProductSearchSpace[source]#: The global search space this search space lives in.

initialize(models: collections.abc.Mapping[trieste.types.Tag, trieste.models.interfaces.ProbabilisticModelType] | None = None, datasets: collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset] | None = None, *args: Any, **kwargs: Any) → None[source]#

Initialize the search space using the given models and datasets.

Extending classes must set self._initialized to True after initialization in this method.

Parameters:

models – The model for each tag.
datasets – The dataset for each tag.

update(models: collections.abc.Mapping[trieste.types.Tag, trieste.models.interfaces.ProbabilisticModelType] | None = None, datasets: collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset] | None = None, *args: Any, **kwargs: Any) → None[source]#

Update the search space using the given models and datasets.

Parameters:

models – The model for each tag.
datasets – The dataset for each tag.

get_datasets_filter_mask(datasets: collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset] | None) → collections.abc.Mapping[trieste.types.Tag, tensorflow.Tensor] | None[source]#

Return a boolean mask that can be used to filter out points from the datasets that belong to this region.

Parameters:: datasets – The dataset for each tag.
Returns:: A mapping for each tag belonging to this region, to a boolean mask that can be used to filter out points from the datasets. A value of True indicates that the corresponding point should be kept.

class BatchTrustRegionProduct(init_subspaces: None | UpdatableTrustRegionType | Sequence[UpdatableTrustRegionType] = None, rule: AcquisitionRule[trieste.types.TensorType, trieste.space.SearchSpace, trieste.models.interfaces.ProbabilisticModelType] | None = None)[source]#

Bases: BatchTrustRegion[trieste.models.interfaces.ProbabilisticModelType, UpdatableTrustRegionProduct]

Implements the BatchTrustRegion trust region acquisition rule for mixed search spaces. This is intended to be used for single-objective optimization with batching.

Parameters:

init_subspaces – The initial search spaces for each trust region. If None, default subspaces of type UpdatableTrustRegionType will be created, with length equal to the number of query points in the base rule.
rule –
The acquisition rule that defines how to search for a new query point in each subspace.

If None, defaults to DiscreteThompsonSampling with a batch size of 1 for TURBOBox subspaces, and EfficientGlobalOptimization otherwise.

initialize_subspaces(search_space: SearchSpaceType) → None[source]#: Create local subspaces for when no initial subspaces are provided.

Use the rule specified at __init__() to find new query points. Return a function that constructs these points given a previous trust region state.

If state is None, initialize the subspaces by picking new locations. Otherwise, update the existing subspaces.

Re-initialize the subspaces if necessary, potentially looking at the entire group.

Parameters:

search_space – The acquisition search space for this step.
models – The model for each tag.
datasets – The known observer query points and observations for each tag.

Returns:

A function that constructs the next acquisition state and the recommended query points from the previous acquisition state.

get_initialize_subspaces_mask(subspaces: Sequence[UpdatableTrustRegionProduct], models: collections.abc.Mapping[trieste.types.Tag, trieste.models.interfaces.ProbabilisticModelType], datasets: collections.abc.Mapping[trieste.types.Tag, trieste.data.Dataset] | None = None) → trieste.types.TensorType[source]#

Parameters:

subspaces – The sequence of subspaces.
models – The model for each tag.
datasets – The dataset for each tag.

Returns:

A boolean mask of length V, where V is the number of subspaces.

class BatchHypervolumeSharpeRatioIndicator(num_query_points: int = 1, ga_population_size: int = 500, ga_n_generations: int = 200, filter_threshold: float = 0.1, noisy_observations: bool = True)[source]#

Bases: AcquisitionRule[trieste.types.TensorType, trieste.space.SearchSpace, trieste.models.ProbabilisticModel]

Implements the Batch Hypervolume Sharpe-ratio indicator acquisition rule, designed for large batches, introduced by Binois et al, 2021. See [BCO21] for details.

Parameters:

num_query_points – The number of points in a batch. Defaults to 5.
ga_population_size – The population size used in the genetic algorithm that finds points on the Pareto front. Defaults to 500.
ga_n_generations – The number of genenrations to run in the genetic algorithm. Defaults to 200.
filter_threshold – The probability of improvement below which to exlude points from the Sharpe ratio optimisation. Defaults to 0.1.
noisy_observations – Whether the observations have noise. Defaults to True.

__repr__() → str[source]#: Return repr(self).

_find_non_dominated_points(model: trieste.models.ProbabilisticModel, search_space: SearchSpaceType) → tuple[trieste.types.TensorType, trieste.types.TensorType][source]#: Uses NSGA-II to find high-quality non-dominated points

Acquire a batch of points to observe based on the batch hypervolume Sharpe ratio indicator method. This method uses NSGA-II to create a Pareto set of the mean and standard deviation of the posterior of the probabilistic model, and then selects points to observe based on maximising the Sharpe ratio.

Parameters:

search_space – The local acquisition search space for this step.
models – The model for each tag.
datasets – The known observer query points and observations.

Returns:

The batch of points to query.

class _MeanStdTradeoff(probabilistic_model: trieste.models.ProbabilisticModel, search_space: SearchSpaceType)[source]#

Bases: pymoo.core.problem.Problem

Inner class that formulates the mean/std optimisation problem as a pymoo problem

Parameters:

probabilistic_model – The probabilistic model to find optimal mean/stds from
search_space – The search space for the optimisation