# API-Documentation¶

## ConfigurationSpace¶

class ConfigSpace.configuration_space.ConfigurationSpace(name: Optional[str] = None, seed: Optional[int] = None, meta: Optional[Dict] = None)

A collection-like object containing a set of hyperparameter definitions and conditions.

A configuration space organizes all hyperparameters and its conditions as well as its forbidden clauses. Configurations can be sampled from this configuration space. As underlying data structure, the configuration space uses a tree-based approach to represent the conditions and restrictions between hyperparameters.

Parameters
• name (str, optional) – Name of the configuration space

• seed (int, optional) – random seed

• meta (dict, optional) – Field for holding meta data provided by the user. Not used by the configuration space.

Add a condition to the configuration space. Check if adding the condition is legal:

• The parent in a condition statement must exist

• The condition must add no cycles

The internal array keeps track of all edges which must be added to the DiGraph; if the checks don’t raise any Exception, these edges are finally added at the end of the function.

Parameters

condition (Conditions) – Condition to add

Returns

Same condition as input

Return type

Conditions

Add a list of conditions to the configuration space. They must be legal. Take a look at add_condition().

Parameters

conditions (list(Conditions)) – collection of conditions to add

Returns

Same as input conditions

Return type

list(Conditions)

add_configuration_space(prefix: unicode, configuration_space: ConfigurationSpace, delimiter: unicode = ':', parent_hyperparameter: ConfigSpace.hyperparameters.Hyperparameter = None)

Combine two configuration space by adding one the other configuration space. The contents of the configuration space, which should be added, are renamed to prefix + delimiter + old_name.

Parameters
• prefix (str) – The prefix for the renamed hyperparameter | conditions | forbidden clauses

• configuration_space (ConfigurationSpace) – The configuration space which should be added

• delimiter (str, optional) – Defaults to ‘:’

• parent_hyperparameter (Hyperparameters, optional) – Adds for each new hyperparameter the condition, that parent_hyperparameter is active

Returns

The configuration space, which was added

Return type

ConfigurationSpace

Add a forbidden clause to the configuration space.

Parameters

clause (Forbidden Clauses) – Forbidden clause to add

Returns

Same as input forbidden clause

Return type

Forbidden Clauses

Add a list of forbidden clauses to the configuration space.

Parameters

clauses (list(Forbidden Clauses)) – Collection of forbidden clauses to add

Returns

Same as input clauses

Return type

list(Forbidden Clauses)

Add a hyperparameter to the configuration space.

Parameters

hyperparameter (Hyperparameters) – The hyperparameter to add

Returns

Return type

Hyperparameters

Add hyperparameters to the configuration space.

Parameters

hyperparameters (list(Hyperparameters)) – Collection of hyperparameters to add

Returns

List of added hyperparameters (same as input)

Return type

list(Hyperparameters)

check_configuration(configuration: ConfigSpace.configuration_space.Configuration) None

Check if a configuration is legal. Raises an error if not.

Parameters

configuration (Configuration) – Configuration to check

check_configuration_vector_representation(vector: numpy.ndarray) None

Raise error if configuration in vector representation is not legal.

Parameters

vector (np.ndarray) – Configuration in vector representation

estimate_size() Union[float, int]

Estimate the size of the current configuration space (i.e. unique configurations).

This is np.inf in case if there is a single hyperparameter of size np.inf (i.e. a UniformFloatHyperparameter), otherwise it is the product of the size of all hyperparameters. The function correctly guesses the number of unique configurations if there are no condition and forbidden statements in the configuration spaces. Otherwise, this is an upper bound. Use generate_grid() to generate all valid configurations if required.

Return type

Union[float, int]

generate_all_continuous_from_bounds(bounds: List[List[Any]]) None

Generate UniformFloatHyperparameter from a list containing lists with lower and upper bounds. The generated hyperparameters are added to the configuration space.

Parameters

bounds (list[tuple([Any, Any])]) – List containing lists with two elements: lower and upper bound

get_active_hyperparameters(configuration: ConfigSpace.configuration_space.Configuration) Set

Return a set of active hyperparameter for a given configuration.

Parameters

configuration (Configuration) – Configuration for which the active hyperparameter are returned

Returns

The set of all active hyperparameter

Return type
get_all_conditional_hyperparameters() List[str]

Return a list with names of all conditional hyperparameters.

Returns

List with all conditional hyperparameter

Return type

list[Hyperparameters]

get_all_unconditional_hyperparameters() List[str]

Return a list with names of unconditional hyperparameters.

Returns

List with all parent hyperparameters, which are not part of a condition

Return type

list[Hyperparameters]

get_child_conditions_of(name: Union[str, ConfigSpace.hyperparameters.Hyperparameter]) List[ConfigSpace.conditions.AbstractCondition]

Return a list with conditions of all children of a given hyperparameter referenced by its name.

Parameters

name (str, Hyperparameters) – Hyperparameter or its name, for which conditions are requested

Returns

List with the conditions on the children of the given hyperparameter

Return type

list(Conditions)

get_children_of(name: Union[str, ConfigSpace.hyperparameters.Hyperparameter]) List[ConfigSpace.hyperparameters.Hyperparameter]

Return a list with all children of a given hyperparameter.

Parameters

name (str, Hyperparameters) – Hyperparameter or its name, for which all children are requested

Returns

Children of the hyperparameter

Return type

list(Hyperparameters)

get_conditions() List[ConfigSpace.conditions.AbstractCondition]

Return a list with all conditions from the configuration space.

Returns

Conditions of the configuration space

Return type

list(Conditions)

get_default_configuration()

Return a configuration containing hyperparameters with default values.

Returns

Configuration with the set default values

Return type

Configuration

get_forbiddens() List[ConfigSpace.forbidden.AbstractForbiddenComponent]

Return a list with all forbidden clauses from the configuration space.

Returns

List with the forbidden clauses

Return type

list(Forbidden Clauses)

get_hyperparameter(name: unicode) ConfigSpace.hyperparameters.Hyperparameter

Gives the hyperparameter from the configuration space given its name.

Parameters

name (str) – Name of the searched hyperparameter

Returns

Hyperparameter with the name name

Return type

Hyperparameters

get_hyperparameter_by_idx(idx: int) unicode

Return the name of a hyperparameter from the configuration space given its id.

Parameters

idx (int) – Id of a hyperparameter

Returns

Name of the hyperparameter

Return type

str

get_hyperparameter_names() List[str]

Return a list with all names of hyperparameter, which are contained in the configuration space object.

Returns

List of hyperparameter names

Return type

list(str)

get_hyperparameters() List[ConfigSpace.hyperparameters.Hyperparameter]

Return a list with all the hyperparameter, which are contained in the configuration space object.

Returns

A list with all hyperparameters stored in the configuration space object

Return type

list(Hyperparameters)

get_hyperparameters_dict() Dict[str, ConfigSpace.hyperparameters.Hyperparameter]

Return an OrderedDict with all the (name, Hyperparameter) contained in the configuration space object.

Returns

An OrderedDict of names and hyperparameters

Return type

OrderedDict(str, Hyperparameters)

get_idx_by_hyperparameter_name(name: unicode) int

Return the id of a hyperparameter by its name.

Parameters

name (str) – Name of a hyperparameter

Returns

Id of the hyperparameter with name name

Return type

int

get_parent_conditions_of(name: Union[str, ConfigSpace.hyperparameters.Hyperparameter]) List[ConfigSpace.conditions.AbstractCondition]

Return a list with conditions of all parents of a given hyperparameter.

Parameters

name (str, Hyperparameters) – Can either be the name of a hyperparameter or the hyperparameter object

Returns

List with all conditions on parent hyperparameters

Return type

List[Conditions]

get_parents_of(name: Union[str, ConfigSpace.hyperparameters.Hyperparameter]) List[ConfigSpace.hyperparameters.Hyperparameter]

Return the parent hyperparameters of a given hyperparameter.

Parameters

name (str, Hyperparameters) – Can either be the name of a hyperparameter or the hyperparameter object

Returns

List with all parent hyperparameters

Return type

list[Conditions]

keys() a set-like object providing a view on D's keys
sample_configuration(size: int = 1)

Sample size configurations from the configuration space object.

Parameters

size (int, optional) – Number of configurations to sample. Default to 1

Returns

List[Configuration]: A single configuration if size 1 else a list of Configurations

Return type
seed(seed: int) None

Set the random seed to a number.

Parameters

seed (int) – The random seed

## Configuration¶

class ConfigSpace.configuration_space.Configuration(configuration_space: ConfigSpace.configuration_space.ConfigurationSpace, values: Union[None, Dict[str, Union[str, float, int]]] = None, vector: Union[None, numpy.ndarray] = None, allow_inactive_with_values: bool = False, origin: Any = None, config_id: Optional[int] = None)

Class for a single configuration.

The Configuration object holds for all active hyperparameters a value. While the ConfigurationSpace stores the definitions for the hyperparameters (value ranges, constraints,…), a Configuration object is more an instance of it. Parameters of a Configuration object can be accessed and modified similar to python dictionaries (c.f. Guide).

Parameters
• configuration_space (ConfigurationSpace) –

• values (dict, optional) – A dictionary with pairs (hyperparameter_name, value), where value is a legal value of the hyperparameter in the above configuration_space

• vector (np.ndarray, optional) – A numpy array for efficient representation. Either values or vector has to be given

• allow_inactive_with_values (bool, optional) – Whether an Exception will be raised if a value for an inactive hyperparameter is given. Default is to raise an Exception. Default to False

• origin (Any, optional) – Store information about the origin of this configuration. Default to None

• config_id (int, optional) – Integer configuration ID which can be used by a program using the ConfigSpace package.

get(item: unicode, default: Union[None, Any] = None) Union[None, Any]

Return for a given hyperparameter name item the value of this hyperparameter. default if the hyperparameter name doesn’t exist.

Parameters
• item (str) – Name of the desired hyperparameter

• default (None, Any) –

Returns

Value of the hyperparameter

Return type

Any, None

get_array() numpy.ndarray

Return the internal vector representation of the Configuration. All continuous values are scaled between zero and one.

Returns

The vector representation of the configuration

Return type

numpy.ndarray

get_dictionary() Dict[str, Union[str, float, int]]

Return a representation of the Configuration in dictionary form.

Returns

Configuration as dictionary

Return type

dict

is_valid_configuration() None

Check if the object is a valid Configuration. Raise an error if configuration is not valid.

keys() List[str]

Cache the keys to speed up the process of retrieving the keys.

Returns

list of keys

Return type

list(str)

## Hyperparameters¶

ConfigSpace contains integer, float, categorical, as well as ordinal hyperparameters. Integer and float hyperparameter can be sampled from a uniform or normal distribution. Example usages are shown in the quickstart.

### 3.1 Integer hyperparameters¶

class ConfigSpace.hyperparameters.UniformIntegerHyperparameter

An integer hyperparameter.

Its values are sampled from a uniform distribution with bounds lower and upper.

Example

>>> import ConfigSpace as CS
>>> import ConfigSpace.hyperparameters as CSH
>>> cs = CS.ConfigurationSpace(seed=1)
>>> uniform_integer_hp = CSH.UniformIntegerHyperparameter(name='uni_int', lower=10,
...                                                       upper=100, log=False)
uni_int, Type: UniformInteger, Range: [10, 100], Default: 55

Parameters
• name (str) – Name of the hyperparameter with which it can be accessed

• lower (int) – Lower bound of a range of values from which the hyperparameter will be sampled

• upper (int) – upper bound

• default_value (int, optional) – Sets the default value of a hyperparameter to a given value

• q (int, optional) – Quantization factor

• log (bool, optional) – If True, the values of the hyperparameter will be sampled on a logarithmic scale. Defaults to False

• meta (Dict, optional) – Field for holding meta data provided by the user. Not used by the configuration space.

class ConfigSpace.hyperparameters.NormalIntegerHyperparameter

An integer hyperparameter.

Its values are sampled from a normal distribution $$\mathcal{N}(\mu, \sigma^2)$$.

Example

>>> import ConfigSpace as CS
>>> import ConfigSpace.hyperparameters as CSH
>>> cs = CS.ConfigurationSpace(seed=1)
>>> normal_int_hp = CSH.NormalIntegerHyperparameter(name='normal_int', mu=0,
...                                                 sigma=1, log=False)
normal_int, Type: NormalInteger, Mu: 0 Sigma: 1, Default: 0

Parameters
• name (str) – Name of the hyperparameter with which it can be accessed

• mu (int) – Mean of the distribution, from which hyperparameter is sampled

• sigma (int, float) – Standard deviation of the distribution, from which hyperparameter is sampled

• default_value (int, optional) – Sets the default value of a hyperparameter to a given value

• q (int, optional) – Quantization factor

• log (bool, optional) – If True, the values of the hyperparameter will be sampled on a logarithmic scale. Defaults to False

• lower (int, float, optional) – Lower bound of a range of values from which the hyperparameter will be sampled

• upper (int, float, optional) – Upper bound of a range of values from which the hyperparameter will be sampled

• meta (Dict, optional) – Field for holding meta data provided by the user. Not used by the configuration space.

### 3.2 Float hyperparameters¶

class ConfigSpace.hyperparameters.UniformFloatHyperparameter

A float hyperparameter.

Its values are sampled from a uniform distribution with values from lower to upper.

Example

>>> import ConfigSpace as CS
>>> import ConfigSpace.hyperparameters as CSH
>>> cs = CS.ConfigurationSpace(seed=1)
>>> uniform_float_hp = CSH.UniformFloatHyperparameter('uni_float', lower=10,
...                                                   upper=100, log = False)
uni_float, Type: UniformFloat, Range: [10.0, 100.0], Default: 55.0

Parameters
• name (str) – Name of the hyperparameter, with which it can be accessed

• lower (int, float) – Lower bound of a range of values from which the hyperparameter will be sampled

• upper (int, float) – Upper bound

• default_value (int, float, optional) – Sets the default value of a hyperparameter to a given value

• q (int, float, optional) – Quantization factor

• log (bool, optional) – If True, the values of the hyperparameter will be sampled on a logarithmic scale. Default to False

• meta (Dict, optional) – Field for holding meta data provided by the user. Not used by the configuration space.

class ConfigSpace.hyperparameters.NormalFloatHyperparameter

A float hyperparameter.

Its values are sampled from a normal distribution $$\mathcal{N}(\mu, \sigma^2)$$.

Example

>>> import ConfigSpace as CS
>>> import ConfigSpace.hyperparameters as CSH
>>> cs = CS.ConfigurationSpace(seed=1)
>>> normal_float_hp = CSH.NormalFloatHyperparameter('normal_float', mu=0,
...                                                 sigma=1, log=False)
normal_float, Type: NormalFloat, Mu: 0.0 Sigma: 1.0, Default: 0.0

Parameters
• name (str) – Name of the hyperparameter, with which it can be accessed

• mu (int, float) – Mean of the distribution

• sigma (int, float) – Standard deviation of the distribution

• default_value (int, float, optional) – Sets the default value of a hyperparameter to a given value

• q (int, float, optional) – Quantization factor

• log (bool, optional) – If True, the values of the hyperparameter will be sampled on a logarithmic scale. Default to False

• lower (int, float, optional) – Lower bound of a range of values from which the hyperparameter will be sampled

• upper (int, float, optional) – Upper bound of a range of values from which the hyperparameter will be sampled

• meta (Dict, optional) – Field for holding meta data provided by the user. Not used by the configuration space.

### 3.3 Categorical hyperparameters¶

class ConfigSpace.hyperparameters.CategoricalHyperparameter

A categorical hyperparameter.

Its values are sampled from a set of values.

None is a forbidden value, please use a string constant instead and parse it in your own code, see here <https://github.com/automl/ConfigSpace/issues/159>_ for further details.

Example

>>> import ConfigSpace as CS
>>> import ConfigSpace.hyperparameters as CSH
>>> cs = CS.ConfigurationSpace(seed=1)
>>> cat_hp = CSH.CategoricalHyperparameter('cat_hp', choices=['red', 'green', 'blue'])
cat_hp, Type: Categorical, Choices: {red, green, blue}, Default: red

Parameters
• name (str) – Name of the hyperparameter, with which it can be accessed

• choices (list or tuple with str, float, int) – Collection of values to sample hyperparameter from

• default_value (int, float, str, optional) – Sets the default value of the hyperparameter to a given value

• meta (Dict, optional) – Field for holding meta data provided by the user. Not used by the configuration space.

• weights ((list[float], optional)) – List of weights for the choices to be used (after normalization) as probabilities during sampling, no negative values allowed

### 3.4 OrdinalHyperparameters¶

class ConfigSpace.hyperparameters.OrdinalHyperparameter

An ordinal hyperparameter.

Its values are sampled form a sequence of values. The sequence of values from a ordinal hyperparameter is ordered.

None is a forbidden value, please use a string constant instead and parse it in your own code, see here <https://github.com/automl/ConfigSpace/issues/159>_ for further details.

Example

>>> import ConfigSpace as CS
>>> import ConfigSpace.hyperparameters as CSH
>>> cs = CS.ConfigurationSpace(seed=1)
>>> ord_hp = CSH.OrdinalHyperparameter('ordinal_hp', sequence=['10', '20', '30'])
ordinal_hp, Type: Ordinal, Sequence: {10, 20, 30}, Default: 10

Parameters
• name (str) – Name of the hyperparameter, with which it can be accessed.

• sequence (list or tuple with (str, float, int)) – ordered collection of values to sample hyperparameter from.

• default_value (int, float, str, optional) – Sets the default value of a hyperparameter to a given value.

• meta (Dict, optional) – Field for holding meta data provided by the user. Not used by the configuration space.

### 3.5 Constant¶

class ConfigSpace.hyperparameters.Constant

Representing a constant hyperparameter in the configuration space.

By sampling from the configuration space each time only a single, constant value will be drawn from this hyperparameter.

Parameters
• name (str) – Name of the hyperparameter, with which it can be accessed

• value (str, int, float) – value to sample hyperparameter from

• meta (Dict, optional) – Field for holding meta data provided by the user. Not used by the configuration space.

## Conditions¶

ConfigSpace can realize equal, not equal, less than, greater than and in conditions. Conditions can be combined by using the conjunctions and and or. To see how to use conditions, please take a look at the user guide.

### 4.1 EqualsCondition¶

class ConfigSpace.conditions.EqualsCondition

Hyperparameter child is conditional on the parent hyperparameter being equal to value.

Example

>>> import ConfigSpace as CS
>>> import ConfigSpace.hyperparameters as CSH
>>> cs = CS.ConfigurationSpace()
>>> a = CSH.CategoricalHyperparameter('a', choices=[1, 2, 3])
>>> b = CSH.UniformFloatHyperparameter('b', lower=1., upper=8., log=False)
[a, Type: Categorical, Choices: {1, 2, 3}, Default: 1, b, Type: ...]


make b an active hyperparameter if a has the value 1

>>> cond = CS.EqualsCondition(b, a, 1)
b | a == 1

Parameters
• child (Hyperparameters) – This hyperparameter will be sampled in the configspace if the equal condition is satisfied

• parent (Hyperparameters) – The hyperparameter, which has to satisfy the equal condition

• value (str, float, int) – Value, which the parent is compared to

### 4.2 NotEqualsCondition¶

class ConfigSpace.conditions.NotEqualsCondition

Hyperparameter child is conditional on the parent hyperparameter being not equal to value.

Example

>>> import ConfigSpace as CS
>>> import ConfigSpace.hyperparameters as CSH
>>> cs = CS.ConfigurationSpace()
>>> a = CSH.CategoricalHyperparameter('a', choices=[1, 2, 3])
>>> b = CSH.UniformFloatHyperparameter('b', lower=1., upper=8., log=False)
[a, Type: Categorical, Choices: {1, 2, 3}, Default: 1, b, Type: ...]


make b an active hyperparameter if a has not the value 1

>>> cond = CS.NotEqualsCondition(b, a, 1)
b | a != 1

Parameters
• child (Hyperparameters) – This hyperparameter will be sampled in the configspace if the not-equals condition is satisfied

• parent (Hyperparameters) – The hyperparameter, which has to satisfy the not equal condition

• value (str, float, int) – Value, which the parent is compared to

### 4.3 LessThanCondition¶

class ConfigSpace.conditions.LessThanCondition

Hyperparameter child is conditional on the parent hyperparameter being less than value.

Example

>>> import ConfigSpace as CS
>>> import ConfigSpace.hyperparameters as CSH
>>> cs = CS.ConfigurationSpace()
>>> a = CSH.UniformFloatHyperparameter('a', lower=0., upper=10.)
>>> b = CSH.UniformFloatHyperparameter('b', lower=1., upper=8., log=False)
[a, Type: UniformFloat, Range: [0.0, 10.0], Default: 5.0, b, Type: ...]


make b an active hyperparameter if a is less than 5

>>> cond = CS.LessThanCondition(b, a, 5.)
b | a < 5.0

Parameters
• child (Hyperparameters) – This hyperparameter will be sampled in the configspace, if the LessThanCondition is satisfied

• parent (Hyperparameters) – The hyperparameter, which has to satisfy the LessThanCondition

• value (str, float, int) – Value, which the parent is compared to

### 4.4 GreaterThanCondition¶

class ConfigSpace.conditions.GreaterThanCondition

Hyperparameter child is conditional on the parent hyperparameter being greater than value.

Example

>>> import ConfigSpace as CS
>>> import ConfigSpace.hyperparameters as CSH
>>> cs = CS.ConfigurationSpace(seed=1)
>>> a = CSH.UniformFloatHyperparameter('a', lower=0., upper=10.)
>>> b = CSH.UniformFloatHyperparameter('b', lower=1., upper=8., log=False)
[a, Type: UniformFloat, Range: [0.0, 10.0], Default: 5.0, b, Type: ...]


make b an active hyperparameter if a is greater than 5

>>> cond = CS.GreaterThanCondition(b, a, 5.)
b | a > 5.0

Parameters
• child (Hyperparameters) – This hyperparameter will be sampled in the configspace, if the GreaterThanCondition is satisfied

• parent (Hyperparameters) – The hyperparameter, which has to satisfy the GreaterThanCondition

• value (str, float, int) – Value, which the parent is compared to

### 4.5 InCondition¶

class ConfigSpace.conditions.InCondition

Hyperparameter child is conditional on the parent hyperparameter being in a set of values.

Example

>>> import ConfigSpace as CS
>>> import ConfigSpace.hyperparameters as CSH
>>> cs = CS.ConfigurationSpace(seed=1)
>>> a = CSH.UniformIntegerHyperparameter('a', lower=0, upper=10)
>>> b = CSH.UniformFloatHyperparameter('b', lower=1., upper=8., log=False)
[a, Type: UniformInteger, Range: [0, 10], Default: 5, b, Type: ...]


make b an active hyperparameter if a is in the set [1, 2, 3, 4]

>>> cond = CS.InCondition(b, a, [1, 2, 3, 4])
b | a in {1, 2, 3, 4}

Parameters
• child (Hyperparameters) – This hyperparameter will be sampled in the configspace, if the InCondition is satisfied

• parent (Hyperparameters) – The hyperparameter, which has to satisfy the InCondition

• values (list(str, float, int)) – Collection of values, which the parent is compared to

### 4.6 AndConjunction¶

class ConfigSpace.conditions.AndConjunction

By using the AndConjunction, constraints can easily be connected.

Example

The following example shows how two constraints with an AndConjunction can be combined.

>>> import ConfigSpace as CS
>>> import ConfigSpace.hyperparameters as CSH
>>> cs = CS.ConfigurationSpace(seed=1)
>>> a = CSH.UniformIntegerHyperparameter('a', lower=5, upper=15)
>>> b = CSH.UniformIntegerHyperparameter('b', lower=0, upper=10)
>>> c = CSH.UniformFloatHyperparameter('c', lower=0., upper=1.)
[a, Type: UniformInteger, Range: [5, 15], Default: 10, b, Type: ...]

>>> less_cond = CS.LessThanCondition(c, a, 10)
>>> greater_cond = CS.GreaterThanCondition(c, b, 5)
(c | a < 10 && c | b > 5)

Parameters

*args (Conditions) – conditions, which will be combined with an AndConjunction

### 4.7 OrConjunction¶

class ConfigSpace.conditions.OrConjunction

Similar to the AndConjunction, constraints can be combined by using the OrConjunction.

Example

>>> import ConfigSpace as CS
>>> import ConfigSpace.hyperparameters as CSH
>>> cs = CS.ConfigurationSpace(seed=1)
>>> a = CSH.UniformIntegerHyperparameter('a', lower=5, upper=15)
>>> b = CSH.UniformIntegerHyperparameter('b', lower=0, upper=10)
>>> c = CSH.UniformFloatHyperparameter('c', lower=0., upper=1.)
[a, Type: UniformInteger, Range: [5, 15], Default: 10, b, Type: ...]

>>> less_cond = CS.LessThanCondition(c, a, 10)
>>> greater_cond = CS.GreaterThanCondition(c, b, 5)
(c | a < 10 || c | b > 5)

Parameters

*args (Conditions) – conditions, which will be combined with an OrConjunction

## Forbidden Clauses¶

ConfigSpace contains forbidden equal and forbidden in clauses. The ForbiddenEqualsClause and the ForbiddenInClause can forbid values to be sampled from a configuration space if a certain condition is met. The ForbiddenAndConjunction can be used to combine ForbiddenEqualsClauses and the ForbiddenInClauses.

For a further example, please take a look in the user guide.

### 5.1 ForbiddenEqualsClause¶

class ConfigSpace.ForbiddenEqualsClause(hyperparameter, value)

A ForbiddenEqualsClause

It forbids a value from the value range of a hyperparameter to be equal to value.

Example

>>> cs = CS.ConfigurationSpace()
>>> a = CSH.CategoricalHyperparameter('a', [1,2,3])
[a, Type: Categorical, Choices: {1, 2, 3}, Default: 1]


It forbids the value 2 for the hyperparameter a

>>> forbidden_clause_a = CS.ForbiddenEqualsClause(a, 2)
Forbidden: a == 2

Parameters
• hyperparameter (Hyperparameters) – Methods on which a restriction will be made

• value (Any) – forbidden value

### 5.2 ForbiddenInClause¶

class ConfigSpace.ForbiddenInClause(hyperparameter, values)

A ForbiddenInClause.

It forbids a value from the value range of a hyperparameter to be in a collection of values.

Note

The forbidden values have to be a subset of the hyperparameter’s values.

Example

>>> cs = CS.ConfigurationSpace(seed=1)
>>> a = CSH.CategoricalHyperparameter('a', [1,2,3])
[a, Type: Categorical, Choices: {1, 2, 3}, Default: 1]


It forbids the values 2, 3, 4 for the hyperparameter a

>>> forbidden_clause_a = CS.ForbiddenInClause(a, [2, 3])
Forbidden: a in {2, 3}

Parameters
• hyperparameter ((Hyperparameters, dict)) – Hyperparameter on which a restriction will be made

• values (Any) – Collection of forbidden values

### 5.3 ForbiddenAndConjunction¶

class ConfigSpace.ForbiddenAndConjunction(*args)

A ForbiddenAndConjunction.

The ForbiddenAndConjunction combines forbidden-clauses, which allows to build powerful constraints.

Example

>>> cs = CS.ConfigurationSpace(seed=1)
>>> a = CSH.CategoricalHyperparameter('a', [1,2,3])
>>> b = CSH.CategoricalHyperparameter('b', [2,5,6])
[a, Type: Categorical, Choices: {1, 2, 3}, Default: 1, b, Type: ...]

>>> forbidden_clause_a = CS.ForbiddenEqualsClause(a, 2)
>>> forbidden_clause_b = CS.ForbiddenInClause(b, [2])
>>> forbidden_clause = CS.ForbiddenAndConjunction(forbidden_clause_a, forbidden_clause_b)
(Forbidden: a == 2 && Forbidden: b in {2})

Parameters

*args (list(Forbidden Clauses)) – forbidden clauses, which should be combined

## Serialization¶

ConfigSpace offers json, pcs and pcs_new writers/readers. These classes can serialize and deserialize configuration spaces. Serializing configuration spaces is useful to share configuration spaces across experiments, or use them in other tools, for example, to analyze hyperparameter importance with CAVE.

### 6.1 Serialization to JSON¶

Create a configuration space definition from a json string.

Example

>>> from ConfigSpace.read_and_write import json
>>> with open('configspace.json', 'r') as f:

Parameters

jason_string (str) – A json string representing a configuration space definition

Returns

The deserialized ConfigurationSpace object

Return type

ConfigurationSpace

Create a string representation of a ConfigurationSpace in json format. This string can be written to file.

Example

>>> from ConfigSpace import ConfigurationSpace
>>> import ConfigSpace.hyperparameters as CSH
>>> cs = ConfigurationSpace()
a, Type: Categorical, Choices: {1, 2, 3}, Default: 1

>>> with open('configspace.json', 'w') as f:
...      f.write(json.write(cs))
305

Parameters
• configuration_space (ConfigurationSpace) – a configuration space, which should be written to file.

• indent (int) – number of whitespaces to use as indent

Returns

String representation of the configuration space, which will be written to file

Return type

str

### 6.2 Serialization with pcs-new¶

Pcs is a simple, human-readable file format for the description of an algorithm’s configurable parameters, their possible values, as well as any parameter dependencies.

Pcs is part of the Algorithm Configuration Library. A detailed explanation of the pcs format can be found here. A short summary is also given in the SMAC Documentation. Further examples are provided in the pysmac documentation

Note

The pcs format definition has changed in the year 2016 and is supported by AClib 2.0, as well as SMAC. To write or to read the old version of pcs, please use the pcs module.

Read in a ConfigurationSpace definition from a pcs file.

Example

>>> from ConfigSpace.read_and_write import pcs_new
>>> with open('configspace.pcs_new', 'r') as fh:

Parameters
• pcs_string (str) – ConfigSpace definition in pcs format

• debug (bool) – Provides debug information. Defaults to False.

Returns

The deserialized ConfigurationSpace object

Return type

ConfigurationSpace

Create a string representation of a ConfigurationSpace in pcs_new format. This string can be written to file.

Example

>>> import ConfigSpace as CS
>>> import ConfigSpace.hyperparameters as CSH
>>> cs = CS.ConfigurationSpace()
a, Type: Categorical, Choices: {1, 2, 3}, Default: 1

>>> with open('configspace.pcs_new', 'w') as fh:
...     fh.write(pcs_new.write(cs))
27

Parameters

configuration_space (ConfigurationSpace) – a configuration space

Returns

The string representation of the configuration space

Return type

str

### 6.3 Serialization with pcs¶

Read in a ConfigurationSpace definition from a pcs file.

Example

>>> from ConfigSpace.read_and_write import pcs
>>> with open('configspace.pcs', 'r') as fh:

Parameters
• pcs_string (str) – ConfigSpace definition in pcs format

• debug (bool) – Provides debug information. Defaults to False.

Returns

The deserialized ConfigurationSpace object

Return type

ConfigurationSpace

Create a string representation of a ConfigurationSpace in pcs format. This string can be written to file.

Example

>>> import ConfigSpace as CS
>>> import ConfigSpace.hyperparameters as CSH
>>> cs = CS.ConfigurationSpace()
a, Type: Categorical, Choices: {1, 2, 3}, Default: 1

>>> with open('configspace.pcs', 'w') as fh:
...     fh.write(pcs.write(cs))
15

Parameters

configuration_space (ConfigurationSpace) – a configuration space

Returns

The string representation of the configuration space

Return type

str

## Utils¶

Functions defined in the utils module can be helpful to develop custom tools that create configurations from a given configuration space or modify a given configuration space.

ConfigSpace.util.deactivate_inactive_hyperparameters()

Remove inactive hyperparameters from a given configuration

Parameters
• configuration (dict) – a configuration as a dictionary. Key: name of the hyperparameter. Value: value of this hyperparamter configuration from which inactive hyperparameters will be removed

• configuration_space (ConfigurationSpace) – The defined configuration space. It is necessary to find the inactive hyperparameters by iterating through the conditions of the configuration space.

• vector ((np.ndarray, optional)) – Efficient represantation of a configuration. Either configuration or vector must be specified. If both are specified only configuration will be used.

Returns

A configuration that is equivalent to the given configuration, except that inactivate hyperparameters have been removed.

Return type

Configuration

ConfigSpace.util.fix_types()

Iterate over all hyperparameters in the ConfigSpace and fix the types of the parameter values in configuration.

Parameters
• configuration (dict) – a configuration as a dictionary. Key: name of the hyperparameter. Value: value of this hyperparamter

• configuration_space (ConfigurationSpace) – Configuration space which knows the types for all parameter values

Returns

configuration with fixed types of parameter values

Return type

dict

ConfigSpace.util.generate_grid()

Generates a grid of Configurations for a given ConfigurationSpace. Can be used, for example, for grid search.

Parameters
• configuration_space (ConfigurationSpace) – The Configuration space over which to create a grid of HyperParameter Configuration values. It knows the types for all parameter values.

• num_steps_dict (dict) – A dict containing the number of points to divide the grid side formed by Hyperparameters which are either of type UniformFloatHyperparameter or type UniformIntegerHyperparameter. The keys in the dict should be the names of the corresponding Hyperparameters and the values should be the number of points to divide the grid side formed by the corresponding Hyperparameter in to.

Returns

List containing Configurations. It is a cartesian product of tuples of HyperParameter values. Each tuple lists the possible values taken by the corresponding HyperParameter. Within the cartesian product, in each element, the ordering of HyperParameters is the same for the OrderedDict within the ConfigurationSpace.

Return type

list

ConfigSpace.util.get_one_exchange_neighbourhood()

Return all configurations in a one-exchange neighborhood.

The method is implemented as defined by: Frank Hutter, Holger H. Hoos and Kevin Leyton-Brown Sequential Model-Based Optimization for General Algorithm Configuration In Proceedings of the conference on Learning and Intelligent Optimization(LION 5)

Parameters
Returns

It contains configurations, with values being situated around the given configuration.

Return type

Generator

ConfigSpace.util.get_random_neighbor()

Draw a random neighbor by changing one parameter of a configuration.

• If the parameter is categorical, it changes it to another value.

• If the parameter is ordinal, it changes it to the next higher or lower value.

• If parameter is a float, draw a random sample

If changing a parameter activates new parameters or deactivates previously active parameters, the configuration will be rejected. If more than 10000 configurations were rejected, this function raises a ValueError.

Parameters
• configuration (Configuration) – a configuration for which a random neigbour is calculated

• seed (int) – Used to generate a random state.

Returns

The new neighbor

Return type

Configuration

ConfigSpace.util.impute_inactive_values()

Impute inactive parameters.

Iterate through the hyperparameters of a Configuration and set the values of the inactive hyperparamters to their default values if the choosen strategy is ‘default’. Otherwise strategy contains a float number. Set the hyperparameters’ value to this number.

Parameters
• configuration (Configuration) – For this configuration inactive values will be imputed.

• strategy ((str, float, optional)) – The imputation strategy. Defaults to ‘default’ If ‘default’, replace inactive parameters by their default. If float, replace inactive parameters by the given float value, which should be able to be splitted apart by a tree-based model.

Returns

A new configuration with the imputed values. In this new configuration inactive values are included.

Return type

Configuration