trieste.space#

This module contains implementations of various types of search space.

Module Contents#

SearchSpaceType[source]#

A type variable bound to SearchSpace.

DEFAULT_DTYPE :tensorflow.DType[source]#

Default dtype to use when none is provided.

class SearchSpace[source]#

Bases: abc.ABC

A SearchSpace represents the domain over which an objective function is optimized.

abstract sample(self, num_samples: int, seed: Optional[int] = None) → trieste.types.TensorType[source]#
Parameters

  • num_samples – The number of points to sample from this search space.

  • seed – Random seed for reproducibility.

Returns

num_samples i.i.d. random points, sampled uniformly from this search space.

abstract __contains__(self, value: trieste.types.TensorType) → bool | TensorType[source]#
Parameters

value – A point to check for membership of this SearchSpace.

Returns

True if value is a member of this search space, else False. May return a scalar boolean TensorType instead of the bool itself.

Raises

ValueError (or tf.errors.InvalidArgumentError) – If value has a different dimensionality from this SearchSpace.

property dimension(self) → trieste.types.TensorType[source]#

The number of inputs in this search space.

property lower(self) → trieste.types.TensorType[source]#

The lowest value taken by each search space dimension.

property upper(self) → trieste.types.TensorType[source]#

The highest value taken by each search space dimension.

abstract product(self: SearchSpaceType, other: SearchSpaceType) → SearchSpaceType[source]#
Parameters

other – A search space of the same type as this search space.

Returns

The Cartesian product of this search space with the other.

__mul__(self: SearchSpaceType, other: SearchSpaceType) → SearchSpaceType[source]#
__mul__(self: SearchSpaceType, other: SearchSpace) → SearchSpace
Parameters

other – A search space.

Returns

The Cartesian product of this search space with the other. If both spaces are of the same type then this calls the product() method. Otherwise, it generates a TaggedProductSearchSpace.

__pow__(self: SearchSpaceType, other: int) → SearchSpaceType[source]#

Return the Cartesian product of other instances of this search space. For example, for an exponent of 3, and search space s, this is s ** 3, which is equivalent to s * s * s.

Parameters

other – The exponent, or number of instances of this search space to multiply together. Must be strictly positive.

Returns

The Cartesian product of other instances of this search space.

Raises

tf.errors.InvalidArgumentError – If the exponent other is less than 1.

discretize(self, num_samples: int) → DiscreteSearchSpace[source]#
Parameters

num_samples – The number of points in the DiscreteSearchSpace.

Returns

A discrete search space consisting of num_samples points sampled uniformly from this search space.

abstract __eq__(self, other: object) → bool[source]#
Parameters

other – A search space.

Returns

Whether the search space is identical to this one.

class DiscreteSearchSpace(points: trieste.types.TensorType)[source]#

Bases: SearchSpace

A discrete SearchSpace representing a finite set of \(D\)-dimensional points in \(\mathbb{R}^D\).

For example:

>>> points = tf.constant([[-1.0, 0.4], [-1.0, 0.6], [0.0, 0.4]])
>>> search_space = DiscreteSearchSpace(points)
>>> assert tf.constant([0.0, 0.4]) in search_space
>>> assert tf.constant([1.0, 0.5]) not in search_space
Parameters

points – The points that define the discrete space, with shape (‘N’, ‘D’).

Raises

ValueError (or tf.errors.InvalidArgumentError) – If points has an invalid shape.

property lower(self) → trieste.types.TensorType[source]#

The lowest value taken across all points by each search space dimension.

property upper(self) → trieste.types.TensorType[source]#

The highest value taken across all points by each search space dimension.

property points(self) → trieste.types.TensorType[source]#

All the points in this space.

property dimension(self) → trieste.types.TensorType[source]#

The number of inputs in this search space.

__contains__(self, value: trieste.types.TensorType) → bool | TensorType[source]#
Parameters

value – A point to check for membership of this SearchSpace.

Returns

True if value is a member of this search space, else False. May return a scalar boolean TensorType instead of the bool itself.

Raises

ValueError (or tf.errors.InvalidArgumentError) – If value has a different dimensionality from this SearchSpace.

sample(self, num_samples: int, seed: Optional[int] = None) → trieste.types.TensorType[source]#
Parameters

  • num_samples – The number of points to sample from this search space.

  • seed – Random seed for reproducibility.

Returns

num_samples i.i.d. random points, sampled uniformly, from this search space.

product(self, other: DiscreteSearchSpace) → DiscreteSearchSpace[source]#

Return the Cartesian product of the two DiscreteSearchSpaces. For example:

>>> sa = DiscreteSearchSpace(tf.constant([[0, 1], [2, 3]]))
>>> sb = DiscreteSearchSpace(tf.constant([[4, 5, 6], [7, 8, 9]]))
>>> (sa * sb).points.numpy()
array([[0, 1, 4, 5, 6],
       [0, 1, 7, 8, 9],
       [2, 3, 4, 5, 6],
       [2, 3, 7, 8, 9]], dtype=int32)
Parameters

other – A DiscreteSearchSpace with points of the same dtype as this search space.

Returns

The Cartesian product of the two DiscreteSearchSpaces.

Raises

TypeError – If one DiscreteSearchSpace has points of a different dtype to the other.

__eq__(self, other: object) → bool[source]#
Parameters

other – A search space.

Returns

Whether the search space is identical to this one.

class Box(lower: Sequence[float], upper: Sequence[float])           Box(lower: trieste.types.TensorType, upper: trieste.types.TensorType)[source]#

Bases: SearchSpace

Continuous SearchSpace representing a \(D\)-dimensional box in \(\mathbb{R}^D\). Mathematically it is equivalent to the Cartesian product of \(D\) closed bounded intervals in \(\mathbb{R}\).

If lower and upper are Sequences of floats (such as lists or tuples), they will be converted to tensors of dtype DEFAULT_DTYPE.

Parameters

  • lower – The lower (inclusive) bounds of the box. Must have shape [D] for positive D, and if a tensor, must have float type.

  • upper – The upper (inclusive) bounds of the box. Must have shape [D] for positive D, and if a tensor, must have float type.

Raises

ValueError (or tf.errors.InvalidArgumentError) –

If any of the following are true:

  • lower and upper have invalid shapes.

  • lower and upper do not have the same floating point type.

  • upper is not greater than lower across all dimensions.

property lower(self) → tensorflow.Tensor[source]#

The lower bounds of the box.

property upper(self) → tensorflow.Tensor[source]#

The upper bounds of the box.

property dimension(self) → trieste.types.TensorType[source]#

The number of inputs in this search space.

__contains__(self, value: trieste.types.TensorType) → bool | TensorType[source]#

Return True if value is a member of this search space, else False. A point is a member if all of its coordinates lie in the closed intervals bounded by the lower and upper bounds.

Parameters

value – A point to check for membership of this SearchSpace.

Returns

True if value is a member of this search space, else False. May return a scalar boolean TensorType instead of the bool itself.

Raises

ValueError (or tf.errors.InvalidArgumentError) – If value has a different dimensionality from the search space.

sample(self, num_samples: int, seed: Optional[int] = None) → trieste.types.TensorType[source]#

Sample randomly from the space.

Parameters

  • num_samples – The number of points to sample from this search space.

  • seed – Random seed for reproducibility.

Returns

num_samples i.i.d. random points, sampled uniformly, from this search space with shape ‘[num_samples, D]’ , where D is the search space dimension.

sample_halton(self, num_samples: int, seed: Optional[int] = None) → trieste.types.TensorType[source]#

Sample from the space using a Halton sequence. The resulting samples are guaranteed to be diverse and are reproducible by using the same choice of seed.

Parameters

  • num_samples – The number of points to sample from this search space.

  • seed – Random seed for the halton sequence

Returns

num_samples of points, using halton sequence with shape ‘[num_samples, D]’ , where D is the search space dimension.

sample_sobol(self, num_samples: int, skip: Optional[int] = None) → trieste.types.TensorType[source]#

Sample a diverse set from the space using a Sobol sequence. If skip is specified, then the resulting samples are reproducible.

Parameters

  • num_samples – The number of points to sample from this search space.

  • skip – The number of initial points of the Sobol sequence to skip

Returns

num_samples of points, using sobol sequence with shape ‘[num_samples, D]’ , where D is the search space dimension.

product(self, other: Box) → Box[source]#

Return the Cartesian product of the two Boxes (concatenating their respective lower and upper bounds). For example:

>>> unit_interval = Box([0.0], [1.0])
>>> square_at_origin = Box([-2.0, -2.0], [2.0, 2.0])
>>> new_box = unit_interval * square_at_origin
>>> new_box.lower.numpy()
array([ 0., -2., -2.])
>>> new_box.upper.numpy()
array([1., 2., 2.])
Parameters

other – A Box with bounds of the same type as this Box.

Returns

The Cartesian product of the two Boxes.

Raises

TypeError – If the bounds of one Box have different dtypes to those of the other Box.

__eq__(self, other: object) → bool[source]#
Parameters

other – A search space.

Returns

Whether the search space is identical to this one.

class TaggedProductSearchSpace(spaces: Sequence[SearchSpace], tags: Optional[Sequence[str]] = None)[source]#

Bases: SearchSpace

Product SearchSpace consisting of a product of multiple SearchSpace. This class provides functionality for accessing either the resulting combined search space or each individual space.

Note that this class assumes that individual points in product spaces are represented with their inputs in the same order as specified when initializing the space.

Build a TaggedProductSearchSpace from a list spaces of other spaces. If tags are provided then they form the identifiers of the subspaces, otherwise the subspaces are labelled numerically.

Parameters

  • spaces – A sequence of SearchSpace objects representing the space’s subspaces

  • tags – An optional list of tags giving the unique identifiers of the space’s subspaces.

Raises

ValueError (or tf.errors.InvalidArgumentError) – If spaces has a different length to tags when tags is provided or if tags contains duplicates.

property lower(self) → trieste.types.TensorType[source]#

The lowest values taken by each space dimension, concatenated across subspaces.

property upper(self) → trieste.types.TensorType[source]#

The highest values taken by each space dimension, concatenated across subspaces.

property subspace_tags(self) → tuple[str, Ellipsis][source]#

Return the names of the subspaces contained in this product space.

property dimension(self) → trieste.types.TensorType[source]#

The number of inputs in this product search space.

get_subspace(self, tag: str) → SearchSpace[source]#

Return the domain of a particular subspace.

Parameters

tag – The tag specifying the target subspace.

Returns

Target subspace.

fix_subspace(self, tag: str, values: trieste.types.TensorType) → TaggedProductSearchSpace[source]#

Return a new TaggedProductSearchSpace with the specified subspace replaced with a DiscreteSearchSpace containing values as its points. This is useful if you wish to restrict subspaces to sets of representative points.

Parameters

  • tag – The tag specifying the target subspace.

  • values – The values used to populate the new discrete subspace.z

Returns

New TaggedProductSearchSpace with the specified subspace replaced with a DiscreteSearchSpace containing values as its points.

get_subspace_component(self, tag: str, values: trieste.types.TensorType) → trieste.types.TensorType[source]#

Returns the components of values lying in a particular subspace.

Parameters
Returns

The sub-components of values lying in the specified subspace, of shape [N, Dsub], where Dsub is the dimensionality of the specified subspace.

__contains__(self, value: trieste.types.TensorType) → bool | TensorType[source]#

Return True if value is a member of this search space, else False. A point is a member if each of its subspace components lie in each subspace.

Recall that individual points in product spaces are represented with their inputs in the same order as specified when initializing the space.

Parameters

value – A point to check for membership of this SearchSpace.

Returns

True if value is a member of this search space, else False. May return a scalar boolean TensorType instead of the bool itself.

Raises

ValueError (or tf.errors.InvalidArgumentError) – If value has a different dimensionality from the search space.

sample(self, num_samples: int, seed: Optional[int] = None) → trieste.types.TensorType[source]#

Sample randomly from the space by sampling from each subspace and concatenating the resulting samples.

Parameters

  • num_samples – The number of points to sample from this search space.

  • seed – Optional tf.random seed.

Returns

num_samples i.i.d. random points, sampled uniformly, from this search space with shape ‘[num_samples, D]’ , where D is the search space dimension.

product(self, other: TaggedProductSearchSpace) → TaggedProductSearchSpace[source]#

Return the Cartesian product of the two TaggedProductSearchSpaces, building a tree of TaggedProductSearchSpaces.

Parameters

other – A search space of the same type as this search space.

Returns

The Cartesian product of this search space with the other.

__eq__(self, other: object) → bool[source]#
Parameters

other – A search space.

Returns

Whether the search space is identical to this one.