Space¶

class sspace.space.Categorical(name: str, options: Dict[str, float], condition: Union[sspace.conditionals._Condition, NoneType] = None, forbidden: Union[sspace.conditionals._Condition, NoneType] = None)[source]¶

Bases: sspace.space.Dimension

Attributes:	choices condition forbidden space weights

Methods

`enable_if`(self, cond)	Enable the underlying hyper-parameter only if the condition is true
`forbid_equal`(self, value)	Forbid the value to be taken by the hyper-parameter
`forbid_in`(self, values)	Forbid a set of values to be taken by the hyper-parameter

visit

choices¶

condition = None¶

forbidden = None¶

space = None¶

visit(self, visitor, *args, **kwargs)[source]¶

weights¶

class sspace.space.Dimension[source]¶

Bases: object

Base Node of a simple graph structure. All node are leaves except ofr the Space node

Methods

`enable_if`(self, cond)	Enable the underlying hyper-parameter only if the condition is true
`forbid_equal`(self, value)	Forbid the value to be taken by the hyper-parameter
`forbid_in`(self, values)	Forbid a set of values to be taken by the hyper-parameter

visit

enable_if(self, cond)[source]¶

Enable the underlying hyper-parameter only if the condition is true

Examples

>>> from sspace import Space
>>> space = Space()
>>> a = space.uniform('a', 1, 2)
>>> b = space.uniform('b', 1, 2)
>>> b.enable_if(either(gt(a, 2), lt(a, 1)))

forbid_equal(self, value)[source]¶

Forbid the value to be taken by the hyper-parameter

Examples

>>> from sspace import Space
>>> space = Space()
>>> a = space.uniform('a', 1, 2)
>>> b = space.uniform('b', 1, 2)
>>> b.forbid_equal(1)

forbid_in(self, values)[source]¶

Forbid a set of values to be taken by the hyper-parameter

Examples

>>> from sspace import Space
>>> space = Space()
>>> a = space.uniform('a', 1, 2)
>>> b = space.uniform('b', 1, 2)
>>> b.forbid_in([1, 2, 3])

visit(self, visitor, *args, **kwargs)[source]¶

exception sspace.space.MissingVariable[source]¶

Bases: Exception

Raised when a variable is missing

class sspace.space.Normal(name: str, loc: Union[int, float], scale: Union[int, float], discrete: bool = False, log: bool = False, quantization: Union[int, float] = None, condition: Union[sspace.conditionals._Condition, NoneType] = None, forbidden: Union[sspace.conditionals._Condition, NoneType] = None)[source]¶

Bases: sspace.space.Dimension

Attributes:	condition forbidden quantization space

Methods

`enable_if`(self, cond)	Enable the underlying hyper-parameter only if the condition is true
`forbid_equal`(self, value)	Forbid the value to be taken by the hyper-parameter
`forbid_in`(self, values)	Forbid a set of values to be taken by the hyper-parameter

visit

condition = None¶

discrete = False¶

forbidden = None¶

log = False¶

quantization = None¶

space = None¶

visit(self, visitor, *args, **kwargs)[source]¶

class sspace.space.Ordinal(name: str, values: List, condition: Union[sspace.conditionals._Condition, NoneType] = None, forbidden: Union[sspace.conditionals._Condition, NoneType] = None)[source]¶

Bases: sspace.space.Dimension

Attributes:	condition forbidden space

Methods

`enable_if`(self, cond)	Enable the underlying hyper-parameter only if the condition is true
`forbid_equal`(self, value)	Forbid the value to be taken by the hyper-parameter
`forbid_in`(self, values)	Forbid a set of values to be taken by the hyper-parameter

visit

condition = None¶

forbidden = None¶

space = None¶

visit(self, visitor, *args, **kwargs)[source]¶

class sspace.space.Space(name=None, backend='ConfigSpace')[source]¶

Bases: sspace.space.Dimension

Multi Dimension hyper-parameter space

Methods

`categorical`(self, name[, options])	Add a categorical hyper-parameters, sampled from a set of values
`choices`(self, name[, options])	Same as `Space.categorical`
`enable_if`(self, cond)	Enable the underlying hyper-parameter only if the condition is true
`forbid_equal`(self, value)	Forbid the value to be taken by the hyper-parameter
`forbid_in`(self, values)	Forbid a set of values to be taken by the hyper-parameter
`from_dict`(data[, space])	Load a serialized space from a python dictionary
`from_json`(file[, space])	Load a serialized space from a json file
`identity`(self, name[, size])	Identity is use to compute a hash to uniquely identify samples.
`instantiate`(self[, backend])	Instantiate the underlying sampler for the defined space
`lognormal`(self, name, loc, scale[, …])	Add a new log-normal hyper-parameter
`loguniform`(self, name, lower, upper[, …])	Add a new normal hyper-parameter
`normal`(self, name, loc, scale[, discrete, …])	Add a new normal hyper-parameter
`ordinal`(self, name, *values[, sequence])	Add a new ordinal hyper-parameter, ordinals are sampled in-order
`sample`(self[, n_samples, seed])	Sample a configuration using the underlying sampler.
`serialize`(self)	Serialize a space into a python dictionary/json
`subspace`(self, name)	Insert a new hyper parameter subspace
`unflatten`(self, dictionary)	Unflatten the a dictionary using the space to know when to unflatten or not
`uniform`(self, name, lower, upper[, …])	Add a new normal hyper-parameter
`variable`(self[, name])	Add a variable parameter, variables are set by outside actors.
`visit`(self, visitor, args, *kwargs)	Run the space builder recursively

categorical(self, name, options=None, **options_w)[source]¶

Add a categorical hyper-parameters, sampled from a set of values

Parameters:	name: str Name of the hyper-parameter options: List List of choices that are available options_w: Dict[str, float] Dictionary with keys as the choices and the values as the weight
Returns:	returns the created hyper-parameter

Examples

>>> space = Space()
>>> space.categorical('a', ['v1', 'v2'])
choices(a, v1=0.5, v2=0.5)
>>> space.sample()
[OrderedDict([('a', 'v2')])]

categorical also accepts custom probability weights

>>> space = Space()
>>> space.categorical('a', {'v1': 0.1, 'v2': 0.2, 'v3': 0.7})
choices(a, v1=0.1, v2=0.2, v3=0.7)
>>> space.sample()
[OrderedDict([('a', 'v3')])]

choices(self, name, options=None, **options_w)[source]¶: Same as Space.categorical

static from_dict(data, space=None)[source]¶

Load a serialized space from a python dictionary

Parameters:	data: serialized space (dictionary) space: space object to use to recreate the space

static from_json(file, space=None)[source]¶

Load a serialized space from a json file

Parameters:	file: load a json file of a serialized space space: space object to use to recreate the space

identity(self, name, size=16)[source]¶

Identity is use to compute a hash to uniquely identify samples. For complex research spaces the seed can be used as an identity proxy as the probabilities for getting two exact same sample for different seed is low.

Parameters:	name: str name of the identity parameter size: int size of the digest to keep

Examples

>>> space = Space()
>>> space.uniform('a', 0, 1)
uniform(a, upper=0, lower=1, discrete=False)
>>> space.identity('uid')
>>> space.sample()
[OrderedDict([('a', 0.5488135039273248), ('uid', 'ac1301101b979371')])]

instantiate(self, backend=None)[source]¶: Instantiate the underlying sampler for the defined space

lognormal(self, name, loc, scale, discrete=False, quantization=None)[source]¶

Add a new log-normal hyper-parameter

Parameters:	name: str Name of the hyper-parameter loc: Union[float, int] scale: Union[float, int] discrete: bool is the distribution integer (discrete=True) of float (discrete=False) quantization: Union[float, int] Truncation factor (quantization=0.01 will limit the number of decimals to 2)
Returns:	returns the created hyper-parameter

Examples

>>> space = Space()
>>> space.lognormal('a', 1, 2, quantization=0.01)
lognormal(a, loc=1, scale=2, discrete=False, q=0.01)
>>> space.sample()
[OrderedDict([('a', 92.58)])]

loguniform(self, name, lower, upper, discrete=False, quantization=None)[source]¶

Add a new normal hyper-parameter

Parameters:	name: str Name of the hyper-parameter lower: Union[float, int] lower value upper: Union[float, int] upper value discrete: bool is the distribution integer (discrete=True) of float (discrete=False) quantization: Union[float, int] Truncation factor (quantization=0.01 will limit the number of decimals to 2)
Returns:	returns the created hyper-parameter

Examples

>>> space = Space()
>>> space.loguniform('a', 1, 2, quantization=0.01)
loguniform(a, upper=1, lower=2, discrete=False, q=0.01)
>>> space.sample()
[OrderedDict([('a', 1.46)])]

normal(self, name, loc, scale, discrete=False, log=False, quantization=None)[source]¶

Add a new normal hyper-parameter

Parameters:

name: str: Name of the hyper-parameter
loc: Union[float, int]: mean of the distribution
scale: Union[float, int]: standard deviation of the distribution
discrete: bool: is the distribution integer (discrete=True) of float (discrete=False)
log: bool: is the distribution log
quantization: Union[float, int]: Truncation factor (quantization=0.01 will limit the number of decimals to 2)

Returns:

returns the created hyper-parameter

Examples

>>> space = Space()
>>> space.normal('a', 1, 2, quantization=0.01)
normal(a, loc=1, scale=2, discrete=False, q=0.01)
>>> space.sample()
[OrderedDict([('a', 4.53)])]

ordinal(self, name, *values, sequence=None)[source]¶

Add a new ordinal hyper-parameter, ordinals are sampled in-order

Parameters:	name: str Name of the hyper-parameter values: List list of values that are sampled in sequence
Returns:	returns the created hyper-parameter

Notes

This is particularly useful if you want to specify something like epoch in your search space, and make your search space change in function of the epoch.

Examples

>>> space = Space()
>>> space.ordinal('a', 1, 2, 3, 4, 5)
ordinal(a, (1, 2, 3, 4, 5))
>>> space.sample()
[OrderedDict([('a', 5)])]
>>> space.sample(seed=1)
[OrderedDict([('a', 4)])]

sample(self, n_samples=1, seed=0, **variables)[source]¶

Sample a configuration using the underlying sampler.

Parameters:	n_samples: int number of samples to generate seed: int seed of PRNG variables: Variable definitions

Notes

Space sampler is entirely deterministic; you need to change the seed to generate different samples

Examples

>>> space = Space()
>>> space.uniform('a', 0, 1)
uniform(a, upper=0, lower=1, discrete=False)
>>> space.sample()
[OrderedDict([('a', 0.5488135039273248)])]
>>> space.sample()
[OrderedDict([('a', 0.5488135039273248)])]
>>> space.sample(seed=1)
[OrderedDict([('a', 0.417022004702574)])]

The samples format makes it easy to transform them into a pandas DataFrame if needed

>>> import pandas as pd
>>> space = Space()
>>> space.uniform('a', 0, 1)
uniform(a, upper=0, lower=1, discrete=False)
>>> samples = pd.DataFrame(space.sample(10))
>>> samples
          a
0  0.548814
1  0.715189
2  0.602763
3  0.544883
4  0.423655
5  0.645894
6  0.437587
7  0.891773
8  0.963663
9  0.383442
>>> dict(zip(samples.keys(), samples.values[0]))
{'a': 0.5488135039273248}

serialize(self)[source]¶: Serialize a space into a python dictionary/json

subspace(self, name)[source]¶

Insert a new hyper parameter subspace

Parameters:	name: str Name of new the hyper-parameter space
Returns:	returns the created hyper-parameter

Examples

>>> space = Space()
>>> space.normal('a', 1, 2, quantization=0.01)
normal(a, loc=1, scale=2, discrete=False, q=0.01)
>>> subspace = space.subspace('b')
>>> subspace.normal('a', 1, 2, quantization=0.01)
normal(a, loc=1, scale=2, discrete=False, q=0.01)
>>> space.sample()
[OrderedDict([('a', 4.53), ('b', OrderedDict([('a', 1.8)]))])]

unflatten(self, dictionary)[source]¶: Unflatten the a dictionary using the space to know when to unflatten or not

uniform(self, name, lower, upper, discrete=False, log=False, quantization=None)[source]¶

Add a new normal hyper-parameter

Parameters:	name: str Name of the hyper-parameter lower: Union[float, int] lower value upper: Union[float, int] upper value discrete: bool is the distribution integer (discrete=True) of float (discrete=False) log: bool is the distribution log quantization: Union[float, int] Truncation factor (quantization=0.01 will limit the number of decimals to 2)
Returns:	returns the created hyper-parameter

Examples

>>> space = Space()
>>> space.uniform('a', 1, 2, quantization=0.01)
uniform(a, upper=1, lower=2, discrete=False, q=0.01)
>>> space.sample()
[OrderedDict([('a', 1.55)])]

variable(self, name=None)[source]¶

Add a variable parameter, variables are set by outside actors. It is a way for hyper parameter optimizer to set constraint before the sampling

Examples

>>> space = Space()
>>> space.variable('epoch')
var(epoch)
>>> space.sample(seed=1, epoch=1)
[OrderedDict([('epoch', 1)])]

visit(self, visitor, *args, **kwargs)[source]¶

Run the space builder recursively

Returns:	returns the created hyper-parameter space

class sspace.space.Uniform(name: str, a: Union[int, float], b: Union[int, float], discrete: bool = False, log: bool = False, quantization: Union[int, float] = None, condition: Union[sspace.conditionals._Condition, NoneType] = None, forbidden: Union[sspace.conditionals._Condition, NoneType] = None)[source]¶

Bases: sspace.space.Dimension

Attributes:	condition forbidden lower quantization space upper

Methods

`enable_if`(self, cond)	Enable the underlying hyper-parameter only if the condition is true
`forbid_equal`(self, value)	Forbid the value to be taken by the hyper-parameter
`forbid_in`(self, values)	Forbid a set of values to be taken by the hyper-parameter

visit

condition = None¶

discrete = False¶

forbidden = None¶

log = False¶

lower¶

quantization = None¶

space = None¶

upper¶

visit(self, visitor, *args, **kwargs)[source]¶

class sspace.space.Variable(name: str)[source]¶

Bases: sspace.space.Dimension

Methods

`enable_if`(self, cond)	Enable the underlying hyper-parameter only if the condition is true
`forbid_equal`(self, value)	Forbid the value to be taken by the hyper-parameter
`forbid_in`(self, values)	Forbid a set of values to be taken by the hyper-parameter

visit

visit(self, visitor, *args, **kwargs)[source]¶

sspace.space.categorical(options=None, **w_options)[source]¶: Space dimension specifier for type hints or decorated functions

sspace.space.compute_identity(sample, size)[source]¶

Compute a unique hash out of a dictionary

Parameters:	sample: dict Dictionary to compute the hash from size: int size of the unique hash

sspace.space.get_space(obj, format=None)[source]¶: Retrieve hyper-parameter space for a given function or object

sspace.space.hyperparameter(**dims)[source]¶: Hyper-parameter decorator

sspace.space.normal(loc, scale, discrete=False, log=False, quantization=None)[source]¶: Space dimension specifier for type hints or decorated functions

sspace.space.ordinal(*values)[source]¶: Space dimension specifier for type hints or decorated functions

sspace.space.uniform(a, b, discrete=False, log=False, quantization=None)[source]¶: Space dimension specifier for type hints or decorated functions

sspace.space.variable()[source]¶: Space dimension specifier for type hints or decorated functions