Space Builder – Create Space objects from configuration

Replace actual hyperparam values in your script’s config files or cmd arguments with orion’s keywords for declaring hyperparameter types to be optimized.

Motivation for this way of orion’s configuration is to achieve as minimal intrusion to user’s workflow as possible by:

  • Offering to user the choice to keep the original way of passing hyperparameters to their script, be it through some config file type (e.g. yaml, json, ini, etc) or through command line arguments.
  • Instead of passing the actual hyperparameter values, use one of the characteristic keywords, names enlisted in scipy.stats.distributions or, to describe distributions and declare the hyperparameters to be optimized. So that a possible command line argument like -lrate0=0.1 becomes -lrate0~'uniform(-3, 1)'.


Use ~ instead of = to denote that a variable “draws from” a distribution. We support limited Python syntax for describing distributions.

  • Module will also use the script’s provided input file/args as a template to fill an appropriate input with proposed values for the script’s execution in each hyperiteration.

Create Dimension objects using a name for it and an string expression which encodes prior and dimension information.

Basically, one must provide a string like a function call to a method that has the name of a distribution, .e.g. alpha, and then provide settings about that distributions and information about the Dimension, if it cannot be inferred. One example for the latter case is:

uniform(-3, 5) will return a Real dimension, while uniform(-3, 5, discrete=True) will return an Integer dimension.

Sometimes there is also a separate name for the same distribution in integers, for the ‘uniform’ example:

randint(-3, 5) will return a uniform Integer dimension.

For categorical dimensions, one can use either enum or random name. random however can be used for uniform reals or integers as well.

Most names are taken from instances contained in scipy.stats.distributions. So, if the distribution you are searching for is there, then DimensionBuilder can build one dimension with that prior!


>>> dimbuilder = DimensionBuilder()
>>>'learning_rate', 'loguniform(0.001, 1, shape=10)')
Real(name=learning_rate, prior={reciprocal: (0.001, 1), {}}, shape=(10,))
>>>'something_else', 'poisson(mu=3)')
Integer(name=something_else, prior={poisson: (), {'mu': 3}}, shape=())
>>> dim ='other2', 'random(-5, 2)')
>>> dim
Real(name=other2, prior={uniform: (-5, 7), {}}, shape=())
>>> dim.interval()
(-5.0, 2.0)


build(self, name, expression) Check DimensionBuilder._build for documentation.
choices(self, *args, **kwargs) Create a Categorical dimension.
fidelity(self, *args, **kwargs) Create a Fidelity dimension.
gaussian(self, *args, **kwargs) Synonym for scipy.stats.distributions.norm.
loguniform(self, *args, **kwargs) Return a Dimension object with scipy.stats.distributions.reciprocal prior distribution.
normal(self, *args, **kwargs) Another synonym for scipy.stats.distributions.norm.
uniform(self, *args, **kwargs) Create an Integer or Real uniformly distributed dimension.
build(self, name, expression)[source]

Check DimensionBuilder._build for documentation.


Warm-up: Fail early if arguments make object not usable.

choices(self, *args, **kwargs)[source]

Create a Categorical dimension.

fidelity(self, *args, **kwargs)[source]

Create a Fidelity dimension.

gaussian(self, *args, **kwargs)[source]

Synonym for scipy.stats.distributions.norm.

loguniform(self, *args, **kwargs)[source]

Return a Dimension object with scipy.stats.distributions.reciprocal prior distribution.

normal(self, *args, **kwargs)[source]

Another synonym for scipy.stats.distributions.norm.

uniform(self, *args, **kwargs)[source]

Create an Integer or Real uniformly distributed dimension.


Changes scipy convention for uniform’s arguments. In scipy, uniform(a, b) means uniform in the interval [a, a+b). Here, it means uniform in the interval [a, b).


Build a Space object form user’s configuration.


build(self, configuration) Create a definition of the problem’s search space.
build_from(self, config) Build a Space object from a configuration.
build_to(self, config_path, trial[, experiment]) Create the configuration for the user’s script.
build(self, configuration)[source]

Create a definition of the problem’s search space.

Using information from the user’s script configuration (if provided) and the command line arguments, will create a Space object defining the problem’s search space.

configuration: OrderedDict

An OrderedDict containing the name and the expression of the parameters.


The problem’s search space definition.

build_from(self, config)[source]

Build a Space object from a configuration.

Initialize a new parser for this commandline and parse the given config then build a Space object from that configuration.


The problem’s search space definition.

build_to(self, config_path, trial, experiment=None)[source]

Create the configuration for the user’s script.

Using the configuration parser, create the commandline associated with the user’s script while replacing the correct instances of parameter distributions by their actual values. If needed, the parser will also create a configuration file.

config_path: str

Path in which the configuration file instance will be created.

trial: `orion.core.worker.trial.Trial`

Object with concrete parameter values for the defined Space.

experiment: `orion.core.worker.experiment.Experiment`, optional

Object with information related to the current experiment.


The commandline arguments that must be given to script for execution., key_prev, key_after)[source]

Replace key_prev of OrderedDict odict with key_after, while leaving its value and the rest of the dictionary intact and in the same order.