Domain Defines the optimisation domain of the objective function.
Sample Defines a sample from the optimisation domain.
Trial High-level API class for running hyperparameter optimisation.

API documentation

class Domain(dct, seed=None)[source]

Defines the optimisation domain of the objective function. It can be a continuous interval or a discrete set of numeric or non-numeric values. The latter is also designated as a categorical domain. It is represented as a Python dict object with the keys naming the variables and the values defining the set of allowed values. A Domain can also be recursively specified. That is, a key can name a subdomain represented as a Python dict.

For continuous sets use Python list to define an interval in the form [a, b], a < b. For discrete sets use Python sets, e.g. {1, 2, 5, -0.1} or {“option_a”, “option_b”}.


>>> simple_domain = {"x": {0, 1},
>>>                  "y": [-1, 1],
>>>                  "z": {-1, 2, 4}}
>>> nested_domain = {"discrete": {"x": {1, 2, 3}, "y": {4, 5, 6}}
>>>                  "continuous": {"x": [-4, 4], "y": [0, 1]}
>>>                  "categorical": {"opt1", "opt2"}}
__init__(dct, seed=None)[source]

Initialise the Domain.

  • dctdict. The mapping of variable names to sets of allowed values.
  • seed – (optional) int. Seed for the randomised sampling.

Iterate over the domain if it is fully discrete.

The iterations are over the Cartesian product of all 1-dim discrete subdomains.

  • DomainNotIterableError – if the domain has a at least one
  • continuous subdomain.
classmethod get_type(subdomain)[source]

Return the type of the set of values in a subdomain.

Parameters:subdomain – one of dict, list or set. The subdomain to get the type for.
Returns:One of Domain.Continuous, Domain.Discrete, Domain.Categorical or Domain.Invalid.
property is_continuous

Return True if at least one subdomain is continuous.


Draw a sample from the domain. All subdomains are sampled uniformly.

Returns:A Sample object.

Split the domain into discrete, categorical and continuous subdomains respectively.

Returns:A tuple of three Domain objects for the discrete numerical, categorical and continuous subdomains.
class Sample(dct)[source]

Defines a sample from the optimisation domain.

It has the same recursive structure a Domain object, however each dimension is represented by one value only. The keys are exactly as the keys of the respective domain.


>>> domain = Domain({"x": {"y": {0, 1, 2}}, "z": [3, 4]})
>>> domain.sample()
{'x': {'y': 0}, 'z': 3.1415926535897932}

Initialise the Sample object from a dict.


Iterate over all values in the sample.

Yields:A tuple of keys and a single value, where the keys are a tuple of strings.
class Trial(objective, domain, optimiser='bo', reporter='table', device='local', **kwargs)[source]

High-level API class for running hyperparameter optimisation. This class encapsulates optimiser querying, job building, scheduling and results collection as well as checkpointing and report generation.

run(n_steps, n_parallel=1, **kwargs)[source]

Run the optimisation and objective function evaluation.

  • n_stepsint. The total number of optimisation steps.
  • n_parallel – (optional) int. The number of jobs that can be scheduled at once.
  • **kwargs – additional keyword arguments for the optimisation, supplied to the run_step() method of the Optimiser instance.
Keyword Arguments:
  • batch_size – (optional) int. The number of samples that are suggested at once. Default is 1.
  • minimise – (optional) bool. If the optimiser is BayesianOptimisation then this flag tells whether the objective function is being minimised or maximised. Otherwise it has no effect. Default is False.