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.

EncoderFunction[source]#: Type alias for point encoders. These transform points from one search space to another.

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] | trieste.types.TensorType, ub: Sequence[float] | trieste.types.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] | trieste.types.TensorType, ub: Sequence[float] | trieste.types.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.

_embed_constraint(constraint: Constraint, offset: int, part_dim: int, combined_dim: int) → Constraint[source]#

Re-express a constraint defined on a part_dim-wide sub-vector so it applies to a wider combined_dim-wide flat vector, with the sub-vector occupying columns [offset, offset + part_dim) and all other columns ignored.

Used to carry a search space’s (positional) constraints through a Cartesian product, where the space’s columns are relocated to a contiguous block of the combined flat vector.

Parameters:

constraint – A LinearConstraint or NonlinearConstraint over the part_dim-wide sub-vector.
offset – Index of the sub-vector’s first column in the combined vector.
part_dim – Width of the sub-vector the constraint was defined on.
combined_dim – Width of the combined vector.

Returns:

An equivalent constraint over the combined vector.

Raises:

NotImplementedError – For an unsupported constraint type.

class SearchSpace[source]#

Bases: abc.ABC

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

abstract sample(num_samples: int, seed: int | None = 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]#

Abstractmethod:

The number of inputs in this search space.

property has_bounds: bool[source]#

Abstractmethod:

Whether the search space has meaningful numerical bounds.

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

Abstractmethod:

The lowest value taken by each search space dimension.

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

Abstractmethod:

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. Subclasses that do not support a same-type product should raise NotImplementedError; __mul__() then falls back to a TaggedProductSearchSpace.

__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 (and have no constraints) 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 GeneralDiscreteSearchSpace(points: trieste.types.TensorType)[source]#

Bases: SearchSpace

An ABC representing different types of discrete search spaces (not just numerical). This contains a default implementation using explicitly provided points which subclasses may ignore.

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 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: int | None = 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.

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

Bases: GeneralDiscreteSearchSpace

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 has_bounds: bool[source]#: Whether the search space has meaningful numerical bounds.

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.

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 BooleanSearchSpace(dtype: tensorflow.DType = DEFAULT_DTYPE)[source]#

Bases: DiscreteSearchSpace

A 1-D DiscreteSearchSpace restricted to \(\{0, 1\}\), representing a single Boolean indicator variable from the GDP formulation. Provides a distinct type for dispatch in validation and downstream consumers (e.g. GA bitflip mutation, kernel active/inactive checks).

Example:

>>> space = BooleanSearchSpace()
>>> assert space.dimension == 1
>>> assert tf.constant([0.0], dtype=tf.float64) in space
>>> assert tf.constant([1.0], dtype=tf.float64) in space
>>> assert tf.constant([2.0], dtype=tf.float64) not in space

Parameters:: dtype – The dtype of the points. Defaults to DEFAULT_DTYPE.

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

Parameters:: other – A search space.
Returns:: Whether the search space is identical to this one.

class HasOneHotEncoder[source]#

Bases: typing_extensions.Protocol

A categorical search space that contains default logic for one-hot encoding.

property one_hot_encoder: EncoderFunction[source]#

Abstractmethod:

A one-hot encoder for points in the search space.

one_hot_encoder(space: SearchSpace) → EncoderFunction[source]#: A utility function for one-hot encoding a search space when it supports it.

cast_encoder(encoder: EncoderFunction, input_dtype: tensorflow.DType | None = None, output_dtype: tensorflow.DType | None = None) → EncoderFunction[source]#: A utility function for casting the input and/or output of an encoder.

one_hot_encoded_space(space: SearchSpace) → SearchSpace[source]#: A bounded search space corresponding to the one-hot encoding of the given space.

class CategoricalSearchSpace(categories: int | Sequence[int] | Sequence[str] | Sequence[Sequence[str]], dtype: tensorflow.DType = DEFAULT_DTYPE)[source]#

Bases: GeneralDiscreteSearchSpace, HasOneHotEncoder

A categorical SearchSpace representing a finite set \(\mathcal{C}\) of categories, or a finite Cartesian product \(\mathcal{C}_1 \times \cdots \times \mathcal{C}_n\) of such sets.

For example:

>>> CategoricalSearchSpace(5)
CategoricalSearchSpace([('0', '1', '2', '3', '4')])
>>> CategoricalSearchSpace(["Red", "Green", "Blue"])
CategoricalSearchSpace([('Red', 'Green', 'Blue')])
>>> CategoricalSearchSpace([2,3])
CategoricalSearchSpace([('0', '1'), ('0', '1', '2')])
>>> CategoricalSearchSpace([["R", "G", "B"], ["Y", "N"]])
CategoricalSearchSpace([('R', 'G', 'B'), ('Y', 'N')])

Note that internally categories are represented by numeric indices:

>>> rgb = CategoricalSearchSpace(["Red", "Green", "Blue"])
>>> assert tf.constant([1], dtype=tf.float64) in rgb
>>> assert tf.constant([3], dtype=tf.float64) not in rgb
>>> rgb.to_tags(tf.constant([[1], [0], [2]]))
<tf.Tensor: shape=(3, 1), dtype=string, numpy=
array([[b'Green'],
       [b'Red'],
       [b'Blue']], dtype=object)>

Parameters:

categories – Number of categories or category names. Can be an array for multidimensional spaces.
dtype – The dtype of the returned indices, either tf.float32 or tf.float64.

property has_bounds: bool[source]#: Whether the search space has meaningful numerical bounds.

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.

property tags: Sequence[Sequence[str]][source]#: The tags of the categories.

property one_hot_encoder: EncoderFunction[source]#: A one-hot encoder for the numerical indices. Note that binary categories are left unchanged instead of adding an unnecessary second feature.

to_tags(indices: trieste.types.TensorType) → trieste.types.TensorType[source]#

Convert a tensor of indices (such as one returned by sample()) to one of category tags.

Parameters:: indices – A tensor of integer indices.
Returns:: A tensor of string tags.

product(other: CategoricalSearchSpace) → CategoricalSearchSpace[source]#

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

>>> rgb = CategoricalSearchSpace(["Red", "Green", "Blue"])
>>> yn = CategoricalSearchSpace(["Yes", "No"])
>>> rgb * yn
CategoricalSearchSpace([('Red', 'Green', 'Blue'), ('Yes', 'No')])

Parameters:: other – A CategoricalSearchSpace.
Returns:: The Cartesian product of the two CategoricalSearchSpaces.

__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: Sequence[Constraint] | None = None, ctol: float | trieste.types.TensorType = 1e-07)[source]#

class Box(lower: trieste.types.TensorType, upper: trieste.types.TensorType, constraints: Sequence[Constraint] | None = None, ctol: float | trieste.types.TensorType = 1e-07)

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 or equal to lower across all dimensions.

property has_bounds: bool[source]#: Whether the search space has meaningful numerical bounds.

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: int | None = 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: int | None = 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: int | None = 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: int | None = 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: int | None = 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: int | None = 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 CollectionSearchSpace(spaces: Sequence[SearchSpace], tags: Sequence[str] | None = None)[source]#

Bases: SearchSpace

An abstract SearchSpace consisting of a collection of multiple SearchSpace objects, each with a unique tag. This class provides functionality for accessing each individual space.

Note that the individual spaces are not combined in any way.

Build a CollectionSearchSpace 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 has_bounds: bool[source]#: Whether the search space has meaningful numerical bounds.

property subspace_lower: Sequence[trieste.types.TensorType][source]#: The lowest values taken by each space dimension, in the same order as specified when initializing the space.

property subspace_upper: Sequence[trieste.types.TensorType][source]#: The highest values taken by each space dimension, in the same order as specified when initializing the space.

property subspace_tags: tuple[str, Ellipsis][source]#: Return the names of the subspaces contained in this space.

property subspace_dimension: Sequence[trieste.types.TensorType][source]#: The number of inputs in each subspace, in the same order as specified when initializing the 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.

subspace_sample(num_samples: int, seed: int | None = None) → Sequence[trieste.types.TensorType][source]#

Sample randomly from the space by sampling from each subspace and returning the resulting samples in the same order as specified when initializing the space.

Parameters:

num_samples – The number of points to sample from each subspace.
seed – Optional tf.random seed.

Returns:

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

__eq__(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: Sequence[str] | None = None)[source]#

Bases: CollectionSearchSpace, HasOneHotEncoder

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. This class is useful for defining mixed search spaces, for example:

context_space = DiscreteSearchSpace(tf.constant([[-0.5, 0.5]])) decision_space = Box([-1, -2], [2, 3]) mixed_space = TaggedProductSearchSpace(spaces=[context_space, decision_space])

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

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 dimension: trieste.types.TensorType[source]#: The number of inputs in this product search space.

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:

tag – Subspace tag.
values – Points from the TaggedProductSearchSpace of shape [N,Dprod].

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: int | None = 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.

property one_hot_encoder: EncoderFunction[source]#: An encoder that one-hot-encodes all subpsaces that support it (and leaves the other subspaces unchanged).

_reject_duplicate_tags(seq_name: str, tags: Sequence[str]) → None[source]#: Raise ValueError if tags contains duplicates (shared by the hierarchy helper and HierarchicalSearchSpace).

_build_tag_to_columns_map(tag_sizes: Sequence[tuple[str, int]]) → dict[str, list[int]][source]#

Lay tags out in order along the flat vector, each occupying size consecutive columns.

Parameters:: tag_sizes – (tag, dimension) pairs in flat-vector order.
Returns:: a mapping from tag to its flat-vector column indices.

class HierarchyNode[source]#

Tag-based specification of one node in a HierarchicalSearchSpace hierarchy.

A node owns a set of non-indicator (feature) subspaces, referenced by tag, and is active only when its gating indicators take the required values (also by tag). References are by tag; the owning HierarchicalSearchSpace resolves them to the flat-vector column layout (and to a gpflow.kernels.HierarchyNode) internally, so subspaces is supplied once – to the space – rather than to every node.

Parameters:

name – Human-readable label for the node (also the kernel-association identifier).
subspace_tags – Tags of the non-indicator subspaces owned by this node. Each must be a key of the space’s subspaces and define numerical bounds (e.g. a Box). Must be non-empty and contain no duplicates.
activity_condition_tags – {indicator_tag: required_value} gating this node; empty (the default) means the node is unconditionally active.

_resolve_node(node: HierarchyNode, subspaces: Mapping[str, SearchSpace], tag_to_columns: Mapping[str, Sequence[int]]) → gpflow.kernels.HierarchyNode[source]#

Resolve a tag-based HierarchyNode to the gpflow column-based node.

The GPflow type is keyed on integer column indices (feature_dims) and an ActivityCondition whose keys are also flat-vector columns, in the layout given by tag_to_columns (one column per dimension of each subspace, in subspaces order). Values are coerced to int so K-ary categorical category indices survive without bool-coercion. GPflow performs node-local validation downstream.

INACTIVE_CONSTRAINT_RESIDUAL: float = 10000000000.0[source]#: Large positive residual returned for an inactive ConditionalConstraint, so the point is trivially feasible with respect to that constraint. This is inspired by the “big-M” MI(N)LP reformulation of a generalized disjunctive program: allocating feasible-with-huge- margin on the inactive branch.

class ConditionalConstraint[source]#

A disjunctive constraint \(h(x) \leq 0\) enforced only when a set of indicator variables take specified values.

When the indicator_conditions all hold for a point, the wrapped constraint is evaluated on the slice of that point identified by active_subspace_tags (concatenated in the given order). When they do not hold, the residual is set to INACTIVE_CONSTRAINT_RESIDUAL, making the point feasible with respect to this constraint. References are by tag, so a conditional constraint survives HierarchicalSearchSpace.product() unchanged.

Parameters:

constraint – The underlying LinearConstraint / NonlinearConstraint, defined on the concatenated active_subspace_tags slice.
indicator_conditions – {indicator_tag: required_value} gating the constraint.
active_subspace_tags – Non-indicator subspace tags whose columns the constraint reads.

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

Constraint residuals, big-M where the indicator conditions are not met.

Parameters:

points – Points in the flat-vector representation, shape [..., D].
space – The owning HierarchicalSearchSpace (provides tag slicing).

Returns:

Residuals with shape [..., C] matching the wrapped constraint.

class LogicalProposition[source]#

A feasibility constraint on the indicator variables alone, \(\Omega(Y)\).

fun receives {indicator_tag: values} where each value has shape [..., 1] (values in the indicator’s permitted set) and must return a boolean tensor of shape [...]. Logical propositions are checked by HierarchicalSearchSpace.is_feasible() but are not included in HierarchicalSearchSpace.constraints_residuals(), as they have no useful gradient for continuous optimizers. They reference indicators by tag, so they survive HierarchicalSearchSpace.product() unchanged.

Parameters:

fun – Maps {indicator_tag: [..., 1]} to a boolean feasibility tensor [...].
name – Optional human-readable label.

class HierarchicalSearchSpace(subspaces: Mapping[str, SearchSpace], hierarchy: Sequence[HierarchyNode], constraints: Sequence[Constraint] | None = None, conditional_constraints: Sequence[ConditionalConstraint] = (), logical_propositions: Sequence[LogicalProposition] = (), ctol: float | trieste.types.TensorType = 1e-07)[source]#

Bases: CollectionSearchSpace

A SearchSpace that extends CollectionSearchSpace with a hierarchy specification describing conditional activation of subspaces.

The hierarchy is described by a sequence of tag-based HierarchyNode objects (each owning subspace_tags and gated by activity_condition_tags); the space resolves them to gpflow’s column-based representation internally (see to_gpflow_hierarchy()). Variables fall into three roles:

Indicators (BooleanSearchSpace or dimension-1 CategoricalSearchSpace), inferred by role as the subspaces referenced as activity_condition_tags keys in the hierarchy. Boolean indicators take values in \(\{0, 1\}\), K-ary categorical indicators in \(\{0, \ldots, K-1\}\). Indicators are always unconditional; they must not appear in any node’s subspace_tags.
Unconditional variables owned by a node with empty activity_condition_tags. Always active.
Conditional variables owned by a node with non-empty activity_condition_tags. Active only when the referenced indicators take the required values.

Points are represented as flat vectors concatenated in the iteration order of subspaces (a dict preserves insertion order in Python 3.7+), the same convention as TaggedProductSearchSpace.

Note

sample and contains operate on the full flat vector and do not enforce “active-branch” semantics: every subspace always contributes its columns regardless of the indicator values, and inactive-branch columns are neither masked nor ignored. This matches the flat-vector convention expected by the hierarchical GP kernel, which reads the indicator columns itself to decide which features are active.

Note

Non-indicator subspaces must define numerical bounds (e.g. Box). Categorical (non-indicator) subspaces are not supported, since the hierarchy encodes each non-indicator dimension as a (lower, upper) bound and there is no one-hot handling here; constructing such a space raises ValueError.

Example:

subspaces = {
    "x1": Box([0.0], [1.0]),
    "y1": BooleanSearchSpace(),
    "x2": Box([0.0], [5.0]),
    "x4": Box([-2.0], [2.0]),
    "x3": Box([-1.0], [1.0]),
}
hierarchy = [
    HierarchyNode("shared", subspace_tags=["x1"]),
    HierarchyNode("branch_A", subspace_tags=["x2", "x4"],
                  activity_condition_tags={"y1": 1}),
    HierarchyNode("branch_B", subspace_tags=["x3"],
                  activity_condition_tags={"y1": 0}),
]
space = HierarchicalSearchSpace(subspaces, hierarchy)

Parameters:

subspaces – Tag-keyed mapping of subspaces; iteration order defines the flat-vector layout.
hierarchy – A sequence of tag-based HierarchyNode objects defining the conditional structure. Every non-indicator subspace tag must appear in at least one node’s subspace_tags. Indicators are inferred by role: a subspace referenced as an activity_condition_tags key is an indicator and must be a BooleanSearchSpace or a dimension-1 CategoricalSearchSpace.
constraints – Optional explicit (global) constraints enforced on the full flat-vector representation, following the same constraints contract as Box. Consumed by constraints_residuals() and is_feasible(), so a constrained space plugs into the usual Bayesian optimization machinery unchanged.
conditional_constraints – Disjunctive constraints, each enforced only when its indicator conditions hold (see ConditionalConstraint); inactive rows contribute INACTIVE_CONSTRAINT_RESIDUAL.
logical_propositions – Indicator-only feasibility constraints (see LogicalProposition); applied in is_feasible() but excluded from constraints_residuals() (no continuous gradient).
ctol – Tolerance used by is_feasible() when checking that residuals are non-negative.

Raises:

ValueError – If any validation rule is violated.

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

Parameters:: other – A search space.
Returns:: Whether the search space is identical to this one, including its hierarchy and indicator tags (the base-class comparison only covers the subspaces and their tags).

property hierarchy: tuple[HierarchyNode, Ellipsis][source]#: The tag-based hierarchy specification (the HierarchyNodes as supplied).

to_gpflow_hierarchy() → list[gpflow.kernels.HierarchyNode][source]#: The hierarchy resolved to gpflow’s column-based gpflow.kernels.HierarchyNodes, ready to build a hierarchical kernel, e.g. ArcHierarchical(space.to_gpflow_hierarchy(), active_dims=...).

property indicator_tags: tuple[str, Ellipsis][source]#: The declared indicator tags (Boolean or categorical).

property indicator_dims: list[int][source]#

Flat-vector column indices corresponding to indicator_tags, in declared order.

These are the columns referenced by the keys of each node’s activity_condition.requirements (gpflow’s convention). Each indicator subspace contributes exactly one column (dimension 1).

property indicator_value_sets: dict[str, tuple[int, Ellipsis]][source]#: The permitted integer-valued set for each indicator tag, as built during validation. (0, 1) for a BooleanSearchSpace indicator and (0, ..., K-1) for a K-ary CategoricalSearchSpace indicator.

property non_indicator_tags: tuple[str, Ellipsis][source]#: All subspace tags that are not indicators, in tag order.

property constraints: Sequence[Constraint][source]#: The explicit (global) constraints enforced on the full flat-vector representation.

property ctol: float | trieste.types.TensorType[source]#: The tolerance applied when checking the explicit constraints.

property conditional_constraints: tuple[ConditionalConstraint, Ellipsis][source]#: The disjunctive constraints gated by indicator conditions.

property logical_propositions: tuple[LogicalProposition, Ellipsis][source]#: The indicator-only feasibility constraints.

property has_constraints: bool[source]#: True if any global, conditional, or logical constraints are present.

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

Return residuals for all global and conditional constraints in this search space. Global constraints are evaluated on the full flat vector; conditional constraints return INACTIVE_CONSTRAINT_RESIDUAL on rows where their indicator conditions do not hold. Logical propositions are excluded (no continuous gradient); use is_feasible() to account for them.

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 constraint residual columns.
Raises:: NotImplementedError – If this search space has no global or conditional constraints.

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

Check whether points satisfy all constraints of this search space — global and conditional (via residuals) and logical propositions. Note that membership of the space (the conditional activity structure) is not checked here.

Parameters:: points – The points to check, with shape [..., D].
Returns:: A boolean tensor of shape [...], True where the point is feasible.

property dimension: trieste.types.TensorType[source]#: The total number of dimensions across all subspaces.

property lower: trieste.types.TensorType[source]#: The lowest values taken by each dimension, concatenated across subspaces.

property upper: trieste.types.TensorType[source]#: The highest values taken by each dimension, concatenated across subspaces.

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

Sample from the space by sampling each subspace and concatenating.

Every subspace is sampled and contributes its columns; this does not enforce active-branch semantics (inactive-branch columns are still filled). See the class docstring.

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

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

Extract the columns of values corresponding to a particular subspace.

Parameters:

tag – The subspace tag.
values – Points from this space, shape [N, D].

Returns:

The sub-components, shape [N, D_sub].

_node_subspace_tags(node: HierarchyNode) → list[str][source]#: The (unique, ordered) non-indicator subspace tags a node owns.

active_subspace_tags(indicator_config: Mapping[str, int]) → list[str][source]#

Return the non-indicator subspace tags that are active for a given indicator configuration.

Parameters:: indicator_config – A mapping {indicator_tag: value} providing a value for every indicator of this space. Extra keys are ignored.
Returns:: List of active non-indicator subspace tags.
Raises:: ValueError – If indicator_config omits any indicator.

enumerate_tasks(feasible_only: bool = False) → list[dict[str, int]][source]#

Return indicator configurations as the Cartesian product of each indicator’s permitted value set.

Both Boolean and K-ary categorical indicators contribute the integer values [0, 1, ..., K-1] (with K = 2 for Boolean indicators); the total number of configurations equals \(\prod_k |\mathcal{C}_k|\).

Parameters:: feasible_only – By default the full Cartesian product is returned, ignoring any LogicalPropositions. When True, configurations that violate any logical proposition are dropped (global/conditional constraints, which involve the continuous variables, are not considered here).
Returns:: A list of {indicator_tag: value} dictionaries, one per task.

is_active(tag: str, indicator_config: Mapping[str, int]) → bool[source]#

Check whether a non-indicator subspace is active for a given indicator configuration.

Parameters:

tag – A non-indicator subspace tag.
indicator_config – A mapping {indicator_tag: value} providing a value for every indicator of this space. Extra keys are ignored.

Returns:

True if the subspace is active.

Raises:

ValueError – If indicator_config omits any indicator.

node_for_subspace(tag: str) → list[HierarchyNode][source]#

Return the HierarchyNode objects that own the given subspace tag.

Parameters:: tag – A non-indicator subspace tag.
Returns:: List of nodes containing this tag.

_require_complete_config(indicator_config: Mapping[str, int]) → None[source]#: Reject a partial configuration: indicator_config must provide a value for every indicator of this space (extra keys are ignored). Catches forgotten or mistyped indicator keys, which would otherwise be silently treated as unsatisfied.

product(other: HierarchicalSearchSpace) → HierarchicalSearchSpace[source]#

Return a new HierarchicalSearchSpace that is the combination of this space and other. Tags in the two spaces must be disjoint. The (tag-based) hierarchy nodes, conditional constraints and logical propositions reference subspaces and indicators by tag, so they compose across the disjoint-tag product unchanged and are simply concatenated; the combined space re-resolves the nodes against the merged column layout. Global (positional) constraints are remapped via _embed_constraint(): self’s keep columns [0, D_self) and other’s shift to [D_self, D_self + D_other). The combined space takes the tighter (minimum) of the two operands’ constraint tolerances.

Parameters:: other – Another HierarchicalSearchSpace.
Returns:: The combined hierarchical space.
Raises:: ValueError – If the two spaces share any tags.

_node_is_active(node: HierarchyNode, indicator_config: Mapping[str, int]) → bool[source]#: Check whether a node’s activity_condition_tags are all satisfied by indicator_config (both keyed by indicator tag). Uses integer equality so that K-ary categorical indicators are compared exactly rather than via Boolean truthiness. Assumes a complete config (see _require_complete_config(), enforced by the public callers).

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

Bases: CollectionSearchSpace

A SearchSpace made up of a collection of multiple SearchSpace subspaces, each with a unique tag. All subspaces must have the same dimensionality.

Each subspace is treated as an independent space and not combined in any way. This class provides functionality for accessing all the subspaces at once by using the usual search space methods, as well as for accessing individual subspaces.

When accessing all subspaces at once from this class (e.g. lower(), upper(), sample()), the returned tensors have an extra dimension corresponding to the subspaces.

This class can be useful to represent a collection of search spaces that do not interact with each other. For example, it is used to implement batch trust region rules in the BatchTrustRegion class.

Build a TaggedMultiSearchSpace 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.
ValueError (or tf.errors.InvalidArgumentError) – If spaces has a different dimension to each other.

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

Returns the stacked lower bounds of all the subspaces.

Returns:: The lower bounds of shape [V, D], where V is the number of subspaces and D is the dimensionality of each subspace.

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

Returns the stacked upper bounds of all the subspaces.

Returns:: The upper bounds of shape [V, D], where V is the number of subspaces and D is the dimensionality of each subspace.

property dimension: trieste.types.TensorType[source]#: The number of inputs in this search space.

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

Sample randomly from the space by sampling from each subspace and returning the resulting samples stacked along the second axis in the same order as specified when initializing the space.

Parameters:

num_samples – The number of points to sample from each subspace.
seed – Optional tf.random seed.

Returns:

num_samples i.i.d. random points, sampled uniformly, from each search subspace with shape ‘[num_samples, V, D]’ , where V is the number of subspaces and D is the search space dimension.

_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 it is a member of any of the subspaces.

Parameters:: value – A point or points to check for membership of this SearchSpace.
Returns:: A boolean array showing membership for each point in value.

product(other: TaggedMultiSearchSpace) → TaggedMultiSearchSpace[source]#

Return a bigger collection of two TaggedMultiSearchSpaces, regenerating the tags.

Parameters:: other – A search space of the same type as this search space.
Returns:: The product of this search space with the other.

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.