Space Builder

Create Space objects from configuration

Functions which build Dimension and Space objects for defining problem’s search space.

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 orion.core.io.space_builder.DimensionBuilder, 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)'.

Note

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.

class orion.core.io.space_builder.DimensionBuilder

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 orion.algo.space.Real dimension, while uniform(-3, 5, discrete=True) will return an orion.algo.space.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 orion.algo.space.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!

Examples

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

Methods

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

build(name, expression)

Check DimensionBuilder._build for documentation.

Note

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

choices(*args, **kwargs)

Create a orion.algo.space.Categorical dimension.

fidelity(*args, **kwargs)

Create a orion.algo.space.Fidelity dimension.

gaussian(*args, **kwargs)

Synonym for scipy.stats distributions.norm.

loguniform(*args, **kwargs)

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

normal(*args, **kwargs)

Another synonym for scipy.stats distributions.norm.

randint(*args, **kwargs)

Create an orion.algo.space.Integer or orion.algo.space.Real uniformly distributed dimension.

Note

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

uniform(*args, **kwargs)

Create an orion.algo.space.Integer or orion.algo.space.Real uniformly distributed dimension.

Note

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

class orion.core.io.space_builder.SpaceBuilder

Build a orion.algo.space.Space object form user’s configuration.

Methods

build(configuration)	Create a definition of the problem's search space.
build_to(config_path, trial[, experiment])	Create the configuration for the user's script.

build(configuration)

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 orion.algo.space.Space object defining the problem’s search space.

Parameters

configuration: OrderedDict

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

Returns

orion.algo.space.Space

The problem’s search space definition.

build_to(config_path, trial, experiment=None)

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.

Parameters

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 orion.algo.space.Space.

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

Object with information related to the current experiment.

Returns

list

The commandline arguments that must be given to script for execution.

orion.core.io.space_builder.replace_key_in_order(odict, key_prev, key_after)

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.