tune.concepts.space

tune.concepts.space.parameters

class Choice(*args)

Bases: tune.concepts.space.parameters.StochasticExpression

A random choice of values. Please read Space Tutorial.

Parameters

args (Any) – values to choose from

generate(seed=None)

Return a randomly chosen value.

Parameters

seed (Optional[Any]) – if set, it will be used to call seed() , defaults to None

Return type

Any

property jsondict: Dict[str, Any]

Dict representation of the expression that is json serializable

property values: List[Any]

values to choose from

class FuncParam(func, *args, **kwargs)

Bases: object

Function paramter. It defers the function call after all its parameters are no longer tuning parameters

Parameters

• func (Callable) – function to generate parameter value

• args (Any) – list arguments

• kwargs (Any) – key-value arguments

s = Space(a=1, b=FuncParam(lambda x, y: x + y, x=Grid(0, 1), y=Grid(3, 4)))
assert [
    dict(a=1, b=3),
    dict(a=1, b=4),
    dict(a=1, b=4),
    dict(a=1, b=5),
] == list(s)

class Grid(*args)

Bases: tune.concepts.space.parameters.TuningParameterExpression

Grid search, every value will be used. Please read Space Tutorial.

Parameters

args (Any) – values for the grid search

class NormalRand(mu, sigma, q=None)

Bases: tune.concepts.space.parameters.RandBase

Continuous normally distributed random variables. Please read Space Tutorial.

Parameters

• mu (float) – mean of the normal distribution

• sigma (float) – standard deviation of the normal distribution

• q (Optional[float]) – step between adjacent values, if set, the value will be rounded using q, defaults to None

generate(seed=None)

Return a randomly chosen value.

Parameters

seed (Optional[Any]) – if set, it will be used to call seed() , defaults to None

Return type

float

property jsondict: Dict[str, Any]

Dict representation of the expression that is json serializable

class NormalRandInt(mu, sigma, q=1)

Bases: tune.concepts.space.parameters.RandBase

Normally distributed random integer values. Please read Space Tutorial.

Parameters

• mu (int) – mean of the normal distribution

• sigma (float) – standard deviation of the normal distribution

• q (int) –

generate(seed=None)

Return a randomly chosen value.

Parameters

seed (Optional[Any]) – if set, it will be used to call seed() , defaults to None

Return type

int

property jsondict: Dict[str, Any]

Dict representation of the expression that is json serializable

class Rand(low, high, q=None, log=False, include_high=True)

Bases: tune.concepts.space.parameters.RandBase

Continuous uniform random variables. Please read Space Tutorial.

Parameters

• low (float) – range low bound (inclusive)

• high (float) – range high bound (exclusive)

• q (Optional[float]) – step between adjacent values, if set, the value will be rounded using q, defaults to None

• log (bool) – whether to do uniform sampling in log space, defaults to False. If True, low must be positive and lower values get higher chance to be sampled

• include_high (bool) –

generate(seed=None)

Return a randomly chosen value.

Parameters

seed (Optional[Any]) – if set, it will be used to call seed() , defaults to None

Return type

float

property jsondict: Dict[str, Any]

Dict representation of the expression that is json serializable

class RandBase(q=None, log=False)

Bases: tune.concepts.space.parameters.StochasticExpression

Base class for continuous random variables. Please read Space Tutorial.

Parameters

• q (Optional[float]) – step between adjacent values, if set, the value will be rounded using q, defaults to None

• log (bool) – whether to do uniform sampling in log space, defaults to False. If True, lower values get higher chance to be sampled

class RandInt(low, high, q=1, log=False, include_high=True)

Bases: tune.concepts.space.parameters.RandBase

Uniform distributed random integer values. Please read Space Tutorial.

Parameters

• low (int) – range low bound (inclusive)

• high (int) – range high bound (exclusive)

• log (bool) – whether to do uniform sampling in log space, defaults to False. If True, low must be >=1 and lower values get higher chance to be sampled

• q (int) –

• include_high (bool) –

generate(seed=None)

Return a randomly chosen value.

Parameters

seed (Optional[Any]) – if set, it will be used to call seed() , defaults to None

Return type

float

property jsondict: Dict[str, Any]

Dict representation of the expression that is json serializable

class StochasticExpression

Bases: tune.concepts.space.parameters.TuningParameterExpression

Stochastic search base class. Please read Space Tutorial.

generate(seed=None)

Return a randomly chosen value.

Parameters

seed (Optional[Any]) – if set, it will be used to call seed() , defaults to None

Return type

Any

generate_many(n, seed=None)

Generate n randomly chosen values

Parameters

• n (int) – number of random values to generate

• seed (Optional[Any]) – random seed, defaults to None

Returns

a list of values

Return type

List[Any]

property jsondict: Dict[str, Any]

Dict representation of the expression that is json serializable

class TransitionChoice(*args)

Bases: tune.concepts.space.parameters.Choice

An ordered random choice of values. Please read Space Tutorial.

Parameters

args (Any) – values to choose from

property jsondict: Dict[str, Any]

Dict representation of the expression that is json serializable

class TuningParameterExpression

Bases: object

Base class of all tuning parameter expressions

class TuningParametersTemplate(raw)

Bases: object

Parameter template to extract tuning parameter expressions from nested data structure

Parameters

raw (Dict[str, Any]) – the dictionary of input parameters.

Note

Please use to_template() to initialize this class.

# common cases
to_template(dict(a=1, b=1))
to_template(dict(a=Rand(0, 1), b=1))

# expressions may nest in dicts or arrays
template = to_template(
    dict(a=dict(x1=Rand(0, 1), x2=Rand(3,4)), b=[Grid("a", "b")]))

assert [Rand(0, 1), Rand(3, 4), Grid("a", "b")] == template.params
assert dict(
    p0=Rand(0, 1), p1=Rand(3, 4), p2=Grid("a", "b")
) == template.params_dict
assert dict(a=1, x2=3), b=["a"]) == template.fill([1, 3, "a"])
assert dict(a=1, x2=3), b=["a"]) == template.fill_dict(
    dict(p2="a", p1=3, p0=1)
)

concat(other)

Concatenate with another template and generate a new template.

Note

The other template must not have any key existed in this template, otherwise ValueError will be raised

Returns

the merged template

Parameters

other (tune.concepts.space.parameters.TuningParametersTemplate) –

Return type

tune.concepts.space.parameters.TuningParametersTemplate

static decode(data)

Retrieve the template from a base64 string

Parameters

data (str) –

Return type

tune.concepts.space.parameters.TuningParametersTemplate

property empty: bool

Whether the template contains any tuning expression

encode()

Convert the template to a base64 string

Return type

str

fill(params)

Fill the original data structure with values

Parameters

• params (List[Any]) – the list of values to be filled into the original data structure, in depth-first order

• copy – whether to return a deeply copied paramters, defaults to False

Returns

the original data structure filled with values

Return type

Dict[str, Any]

fill_dict(params)

Fill the original data structure with dictionary of values

Parameters

• params (Dict[str, Any]) – the dictionary of values to be filled into the original data structure, keys must be p0, p1, p2, …

• copy – whether to return a deeply copied paramters, defaults to False

Returns

the original data structure filled with values

Return type

Dict[str, Any]

property has_grid: bool

Whether the template contains grid expressions

property has_stochastic: bool

Whether the template contains stochastic expressions

property params: List[tune.concepts.space.parameters.TuningParameterExpression]

Get all tuning parameter expressions in depth-first order

property params_dict: Dict[str, tune.concepts.space.parameters.TuningParameterExpression]

Get all tuning parameter expressions in depth-first order, with correspondent made-up new keys p0, p1, p2, …

product_grid()

cross product all grid parameters

Yield

new templates with the grid paramters filled

Return type

Iterable[tune.concepts.space.parameters.TuningParametersTemplate]

assert [dict(a=1,b=Rand(0,1)), dict(a=2,b=Rand(0,1))] ==                 list(to_template(dict(a=Grid(1,2),b=Rand(0,1))).product_grid())

sample(n, seed=None)

sample all stochastic parameters

Parameters

• n (int) – number of samples, must be a positive integer

• seed (Optional[Any]) – random seed defaulting to None. It will take effect if it is not None.

Yield

new templates with the grid paramters filled

Return type

Iterable[tune.concepts.space.parameters.TuningParametersTemplate]

assert [dict(a=1.1,b=Grid(0,1)), dict(a=1.5,b=Grid(0,1))] ==                 list(to_template(dict(a=Rand(1,2),b=Grid(0,1))).sample(2,0))

property simple_value: Dict[str, Any]

If the template contains no tuning expression, it’s simple and it will return parameters dictionary, otherwise, ValueError will be raised

property template: Dict[str, Any]

The template dictionary, all tuning expressions will be replaced by None

to_template(data)

Convert an oject to TuningParametersTemplate

Parameters

data (Any) – data object (dict or TuningParametersTemplate or str (encoded string))

Returns

the template object

Return type

tune.concepts.space.parameters.TuningParametersTemplate

tune.concepts.space.spaces

class Space(*args, **kwargs)

Bases: object

Search space object

Important

Please read Space Tutorial.

Parameters

kwargs (Any) – parameters in the search space

Space(a=1, b=1)  # static space
Space(a=1, b=Grid(1,2), c=Grid("a", "b"))  # grid search
Space(a=1, b=Grid(1,2), c=Rand(0, 1))  # grid search + level 2 search
Space(a=1, b=Grid(1,2), c=Rand(0, 1)).sample(10, sedd=0)  # grid + random search

# union
Space(a=1, b=Grid(2,3)) + Space(b=Rand(1,5)).sample(10)

# cross product
Space(a=1, b=Grid(2,3)) * Space(c=Rand(1,5), d=Grid("a","b"))

# combo (grid + random + level 2)
space1 = Space(a=1, b=Grid(2,4))
space2 = Space(b=RandInt(10, 20))
space3 = Space(c=Rand(0,1)).sample(10)
space = (space1 + space2) * space3

assert Space(a=1, b=Rand(0,1)).has_stochastic
assert not Space(a=1, b=Rand(0,1)).sample(10).has_stochastic
assert not Space(a=1, b=Grid(0,1)).has_stochastic
assert not Space(a=1, b=1).has_stochastic

# get all configurations
space = Space(a=Grid(2,4), b=Rand(0,1)).sample(100)
for conf in space:
    print(conf)
all_conf = list(space)

property has_stochastic

Whether the space contains any StochasticExpression

sample(n, seed=None)

Draw random samples from the current space. Please read Space Tutorial.

Parameters

• n (int) – number of samples to draw

• seed (Optional[Any]) – random seed, defaults to None

Returns

a new Space containing all samples

Return type

tune.concepts.space.spaces.Space

Note

• it only applies to StochasticExpression

• if has_stochastic() is False, then it will return the original space

• After sampling, no StochasticExpression will exist in the new space.