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.

exception SampleTimeoutError[source]#

Bases: Exception

Raised when sampling from a search space has timed out.

Initialize self. See help(type(self)) for accurate signature.

class NonlinearConstraint(fun: Callable[[trieste.types.TensorType], trieste.types.TensorType], lb: Sequence[float] | TensorType, ub: Sequence[float] | TensorType, keep_feasible: bool = False)[source]#

Bases: scipy.optimize.NonlinearConstraint

A wrapper class for nonlinear constraints on variables. The constraints expression is of the form:

lb <= fun(x) <= ub
Parameters

  • fun – The function defining the nonlinear constraints; with input shape […, D] and output shape […, 1], returning a scalar value for each input point.

  • lb – The lower bound of the constraint. Should be a scalar or of shape [1].

  • ub – The upper bound of the constraint. Should be a scalar or of shape [1].

  • keep_feasible – Keep the constraints feasible throughout optimization iterations if this is True.

residual(points: trieste.types.TensorType) → trieste.types.TensorType[source]#

Calculate the residuals between the constraint function and its lower/upper limits.

Parameters

points – The points to calculate the residuals for, with shape […, D].

Returns

A tensor containing the lower and upper residual values with shape […, 2].

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

other – A constraint.

Returns

Whether the constraint is identical to this one.

class LinearConstraint(A: trieste.types.TensorType, lb: Sequence[float] | TensorType, ub: Sequence[float] | TensorType, keep_feasible: bool = False)[source]#

Bases: scipy.optimize.LinearConstraint

A wrapper class for linear constraints on variables. The constraints expression is of the form:

lb <= A @ x <= ub
Parameters

  • A – The matrix defining the linear constraints with shape [M, D], where M is the number of constraints.

  • lb – The lower bound of the constraint. Should be a scalar or of shape [M].

  • ub – The upper bound of the constraint. Should be a scalar or of shape [M].

  • keep_feasible – Keep the constraints feasible throughout optimization iterations if this is True.

residual(points: trieste.types.TensorType) → trieste.types.TensorType[source]#

Calculate the residuals between the constraint function and its lower/upper limits.

Parameters

points – The points to calculate the residuals for, with shape […, D].

Returns

A tensor containing the lower and upper residual values with shape […, M*2].

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

other – A constraint.

Returns

Whether the constraint is identical to this one.

Constraint[source]#

Type alias for constraints.

class SearchSpace[source]#

Bases: abc.ABC

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

abstract sample(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.

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

Method for checking membership.

Parameters

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

Returns

A boolean array showing membership for each point in value.

Raises

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

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

Space-specific implementation of membership. Can assume valid input shape.

Parameters

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

Returns

A boolean array showing membership for each point in value.

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

Method called by in operator. Doesn’t support broadcasting as Python insists on converting the result to a boolean.

Parameters

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

Returns

True if value is a member of this search space, else False.

Raises

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

property dimension → trieste.types.TensorType[source]#

The number of inputs in this search space.

property lower → trieste.types.TensorType[source]#

The lowest value taken by each search space dimension.

property upper → trieste.types.TensorType[source]#

The highest value taken by each search space dimension.

abstract product(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__(other: SearchSpaceType) → SearchSpaceType[source]#
__mul__(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__(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(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.

Raises

NotImplementedError – If this SearchSpace has constraints.

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

other – A search space.

Returns

Whether the search space is identical to this one.

property constraints → Sequence[Constraint][source]#

The sequence of explicit constraints specified in this search space.

abstract constraints_residuals(points: trieste.types.TensorType) → trieste.types.TensorType[source]#

Return residuals for all the constraints in this SearchSpace.

Parameters

points – The points to get the residuals for, with shape […, D].

Returns

A tensor of all the residuals with shape […, C], where C is the total number of constraints.

Raises

NotImplementedError – If this SearchSpace does not support constraints.

is_feasible(points: trieste.types.TensorType) → trieste.types.TensorType[source]#

Checks if points satisfy the explicit constraints of this SearchSpace. Note membership of the search space is not checked.

Parameters

points – The points to check constraints feasibility for, with shape […, D].

Returns

A tensor of booleans. Returns True for each point if it is feasible in this search space, else False.

Raises

NotImplementedError – If this SearchSpace has constraints.

property has_constraints → bool[source]#

Returns True if this search space has any explicit constraints specified.

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 → trieste.types.TensorType[source]#

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

property upper → trieste.types.TensorType[source]#

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

property points → trieste.types.TensorType[source]#

All the points in this space.

property dimension → trieste.types.TensorType[source]#

The number of inputs in this search space.

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

Space-specific implementation of membership. Can assume valid input shape.

Parameters

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

Returns

A boolean array showing membership for each point in value.

sample(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(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__(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], constraints: Optional[Sequence[Constraint]] = None, ctol: float | TensorType = 1e-07)           Box(lower: trieste.types.TensorType, upper: trieste.types.TensorType, constraints: Optional[Sequence[Constraint]] = None, ctol: float | TensorType = 1e-07)[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.

  • constraints – Sequence of explicit input constraints for this search space.

  • ctol – Tolerance to use to check constraints satisfaction.

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 → tensorflow.Tensor[source]#

The lower bounds of the box.

property upper → tensorflow.Tensor[source]#

The upper bounds of the box.

property dimension → trieste.types.TensorType[source]#

The number of inputs in this search space.

property constraints → Sequence[Constraint][source]#

The sequence of explicit constraints specified in this search space.

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

For each point in value, return True if the point 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 or points to check for membership of this SearchSpace.

Returns

A boolean array showing membership for each point in value.

sample(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(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(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.

_sample_feasible_loop(num_samples: int, sampler: Callable[], trieste.types.TensorType], max_tries: int = 100) → trieste.types.TensorType[source]#

Rejection sampling using provided callable. Try max_tries number of times to find num_samples feasible points.

Parameters

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

  • sampler – Callable to return samples. Called potentially multiple times.

  • max_tries – Maximum attempts to sample the requested number of points.

Returns

num_samples feasible points sampled using sampler.

Raises

SampleTimeoutError – If max_tries are exhausted before num_samples are sampled.

sample_feasible(num_samples: int, seed: Optional[int] = None, max_tries: int = 100) → trieste.types.TensorType[source]#

Sample feasible points randomly from the space.

Parameters

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

  • seed – Random seed for reproducibility.

  • max_tries – Maximum attempts to sample the requested number of points.

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.

Raises

SampleTimeoutError – If max_tries are exhausted before num_samples are sampled.

sample_halton_feasible(num_samples: int, seed: Optional[int] = None, max_tries: int = 100) → trieste.types.TensorType[source]#

Sample feasible points 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 feasible points to sample from this search space.

  • seed – Random seed for the halton sequence

  • max_tries – Maximum attempts to sample the requested number of points.

Returns

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

Raises

SampleTimeoutError – If max_tries are exhausted before num_samples are sampled.

sample_sobol_feasible(num_samples: int, skip: Optional[int] = None, max_tries: int = 100) → trieste.types.TensorType[source]#

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

Parameters

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

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

  • max_tries – Maximum attempts to sample the requested number of points.

Returns

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

Raises

SampleTimeoutError – If max_tries are exhausted before num_samples are sampled.

product(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__(other: object) → bool[source]#
Parameters

other – A search space.

Returns

Whether the search space is identical to this one.

constraints_residuals(points: trieste.types.TensorType) → trieste.types.TensorType[source]#

Return residuals for all the constraints in this SearchSpace.

Parameters

points – The points to get the residuals for, with shape […, D].

Returns

A tensor of all the residuals with shape […, C], where C is the total number of constraints.

is_feasible(points: trieste.types.TensorType) → trieste.types.TensorType[source]#

Checks if points satisfy the explicit constraints of this SearchSpace. Note membership of the search space is not checked.

Parameters

points – The points to check constraints feasibility for, with shape […, D].

Returns

A tensor of booleans. Returns True for each point if it is feasible in this search space, else False.

property has_constraints → bool[source]#

Returns True if this search space has any explicit constraints specified.

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 → trieste.types.TensorType[source]#

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

property upper → trieste.types.TensorType[source]#

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

property subspace_tags → tuple[str, Ellipsis][source]#

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

property dimension → trieste.types.TensorType[source]#

The number of inputs in this product search space.

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

Return the domain of a particular subspace.

Parameters

tag – The tag specifying the target subspace.

Returns

Target subspace.

fix_subspace(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(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(value: trieste.types.TensorType) → trieste.types.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(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(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__(other: object) → bool[source]#
Parameters

other – A search space.

Returns

Whether the search space is identical to this one.