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_condition(condition: ConditionComponent) ConditionComponent

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_conditions(conditions: List[ConditionComponent]) List[ConditionComponent]

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: Hyperparameter = None) ConfigurationSpace

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_forbidden_clause(clause: AbstractForbiddenComponent) AbstractForbiddenComponent

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_forbidden_clauses(clauses: List[AbstractForbiddenComponent]) List[AbstractForbiddenComponent]

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_hyperparameter(hyperparameter: Hyperparameter) Hyperparameter

Add a hyperparameter to the configuration space.

Parameters:

hyperparameter (Hyperparameters) – The hyperparameter to add

Returns:

The added hyperparameter

Return type:

Hyperparameters

add_hyperparameters(hyperparameters: List[Hyperparameter]) List[Hyperparameter]

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: Configuration) None

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

Parameters:

configuration (Configuration) – Configuration to check

check_configuration_vector_representation(vector: 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: 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:

set(Configuration)

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, Hyperparameter]) List[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, Hyperparameter]) List[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[AbstractCondition]

Return a list with all conditions from the configuration space.

Returns:

Conditions of the configuration space

Return type:

list(Conditions)

get_default_configuration() Configuration

Return a configuration containing hyperparameters with default values.

Returns:

Configuration with the set default values

Return type:

Configuration

get_forbiddens() List[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) 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[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, 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, Hyperparameter]) List[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, Hyperparameter]) List[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
remove_hyperparameter_priors() ConfigurationSpace

Produces a new ConfigurationSpace where all priors on parameters are removed. Non-uniform hyperpararmeters are replaced with uniform ones, and CategoricalHyperparameters with weights have their weights removed.

Returns:

The resulting configuration space, without priors on the hyperparameters

Return type:

ConfigurationSpace

sample_configuration(size: int = 1) Union[Configuration, List[Configuration]]

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:

Configuration,

seed(seed: int) None

Set the random seed to a number.

Parameters:

seed (int) – The random seed

static substitute_hyperparameters_in_conditions(conditions, new_configspace) List[ConditionComponent]

Takes a set of conditions and generates a new set of conditions with the same structure, where each hyperparameter is replaced with its namesake in new_configspace. As such, the set of conditions remain unchanged, but the included hyperparameters are changed to match those types that exist in new_configspace.

Parameters:

new_configspace (ConfigurationSpace) – A ConfigurationSpace containing hyperparameters with the same names as those in the conditions.

Returns:

The list of conditions, adjusted to fit the new ConfigurationSpace

Return type:

List[ConditionComponent]

static substitute_hyperparameters_in_forbiddens(forbiddens, new_configspace) List[ConditionComponent]

Takes a set of forbidden clauses and generates a new set of forbidden clauses with the same structure, where each hyperparameter is replaced with its namesake in new_configspace. As such, the set of forbidden clauses remain unchanged, but the included hyperparameters are changed to match those types that exist in new_configspace.

Parameters:

new_configspace (ConfigurationSpace) – A ConfigurationSpace containing hyperparameters with the same names as those in the forbidden clauses.

Returns:

The list of forbidden clauses, adjusted to fit the new ConfigurationSpace

Return type:

List[AbstractForbiddenComponent]

Configuration

class ConfigSpace.configuration_space.Configuration(configuration_space: ConfigurationSpace, values: Union[None, Dict[str, Union[str, float, int]]] = None, vector: Union[None, 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() 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

A uniformly distributed 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)
>>> cs.add_hyperparameter(uniform_integer_hp)
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

A normally distributed 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)
>>> cs.add_hyperparameter(normal_int_hp)
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 uniformly distributed 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)
>>> cs.add_hyperparameter(uniform_float_hp)
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 normally distributed 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)
>>> cs.add_hyperparameter(normal_float_hp)
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'])
>>> cs.add_hyperparameter(cat_hp)
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'])
>>> cs.add_hyperparameter(ord_hp)
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)
>>> cs.add_hyperparameters([a, b])
[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)
>>> cs.add_condition(cond)
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)
>>> cs.add_hyperparameters([a, b])
[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)
>>> cs.add_condition(cond)
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)
>>> cs.add_hyperparameters([a, b])
[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.)
>>> cs.add_condition(cond)
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)
>>> cs.add_hyperparameters([a, b])
[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.)
>>> cs.add_condition(cond)
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)
>>> cs.add_hyperparameters([a, b])
[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])
>>> cs.add_condition(cond)
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.)
>>> cs.add_hyperparameters([a, b, c])
[a, Type: UniformInteger, Range: [5, 15], Default: 10, b, Type: ...]
>>> less_cond = CS.LessThanCondition(c, a, 10)
>>> greater_cond = CS.GreaterThanCondition(c, b, 5)
>>> cs.add_condition(CS.AndConjunction(less_cond, greater_cond))
(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.)
>>> cs.add_hyperparameters([a, b, c])
[a, Type: UniformInteger, Range: [5, 15], Default: 10, b, Type: ...]
>>> less_cond = CS.LessThanCondition(c, a, 10)
>>> greater_cond = CS.GreaterThanCondition(c, b, 5)
>>> cs.add_condition(CS.OrConjunction(less_cond, greater_cond))
(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])
>>> cs.add_hyperparameters([a])
[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)
>>> cs.add_forbidden_clause(forbidden_clause_a)
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])
>>> cs.add_hyperparameters([a])
[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])
>>> cs.add_forbidden_clause(forbidden_clause_a)
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])
>>> cs.add_hyperparameters([a, b])
[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)
>>> cs.add_forbidden_clause(forbidden_clause)
(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

ConfigSpace.read_and_write.json.read(jason_string)[source]

Create a configuration space definition from a json string.

Example

>>> from ConfigSpace.read_and_write import json
>>> with open('configspace.json', 'r') as f:
...     jason_string = f.read()
...     config = json.read(jason_string)
Parameters:

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

Returns:

The deserialized ConfigurationSpace object

Return type:

ConfigurationSpace

ConfigSpace.read_and_write.json.write(configuration_space, indent=2)[source]

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

Example:

..code:: python

from ConfigSpace import ConfigurationSpace import ConfigSpace.hyperparameters as CSH from ConfigSpace.read_and_write import json cs = ConfigurationSpace() cs.add_hyperparameter(CSH.CategoricalHyperparameter(‘a’, choices=[1, 2, 3]))

with open(‘configspace.json’, ‘w’) as f:

f.write(json.write(cs))

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 (new format)

PCS (parameter configuration space) 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. There exist an old and a new version.

The new PCS format is part of the Algorithm Configuration Library 2.0. A detailed description of the new format can be found in the ACLIB 2.0 docs, in the SMACv2 docs and further examples are provided in the pysmac docs

Note

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

ConfigSpace.read_and_write.pcs_new.read(pcs_string, debug=False)[source]

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:
...     deserialized_conf = pcs_new.read(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

ConfigSpace.read_and_write.pcs_new.write(configuration_space)[source]

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
>>> from ConfigSpace.read_and_write import pcs_new
>>> cs = CS.ConfigurationSpace()
>>> cs.add_hyperparameter(CSH.CategoricalHyperparameter('a', choices=[1, 2, 3]))
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 (old format)

The old PCS format is part of the Algorithm Configuration Library.

A detailed explanation of the old PCS format can be found here.

ConfigSpace.read_and_write.pcs.read(pcs_string, debug=False)[source]

Read in a ConfigurationSpace definition from a pcs file.

Example

>>> from ConfigSpace.read_and_write import pcs
>>> with open('configspace.pcs', 'r') as fh:
...     deserialized_conf = pcs.read(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

ConfigSpace.read_and_write.pcs.write(configuration_space)[source]

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
>>> from ConfigSpace.read_and_write import pcs
>>> cs = CS.ConfigurationSpace()
>>> cs.add_hyperparameter(CSH.CategoricalHyperparameter('a', choices=[1, 2, 3]))
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:
  • configuration (Configuration) – for this Configuration object num_neighbors neighbors are computed

  • seed (int) – Sets the random seed to a fixed value

  • num_neighbors ((int, optional)) – number of configurations, which are sampled from the neighbourhood of the input configuration

  • stdev ((float, optional)) – The standard deviation is used to determine the neigbours of UniformFloatHyperparameter and UniformIntegerHyperparameter.

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