Welcome to ConfigSpace’s documentation!

ConfigSpace is a simple python package to manage configuration spaces for algorithm configuration and hyperparameter optimization tasks. It includes various modules to translate between different text formats for configuration space descriptions.

ConfigSpace is often used in AutoML tools such as SMAC3, BOHB or auto-sklearn. To read more about our group and projects, visit our homepage AutoML.org.

This documentation explains how to use ConfigSpace and demonstrates its features. In the Quickstart, you will see how to set up a ConfigurationSpace and add hyperparameters of different types to it. Besides containing hyperparameters, a ConfigurationSpace can contain constraints such as conditions and forbidden clauses. Those are introduced in the user guide.

Furthermore, in the serialization section, it will be explained how to serialize a ConfigurationSpace for later usage.

Get Started

Create a simple ConfigurationSpace and then sample a Configuration from it!

>>> from ConfigSpace import ConfigurationSpace
>>>
>>> cs = ConfigurationSpace({
...     "myfloat": (0.1, 1.5),                # Uniform Float
...     "myint": (2, 10),                     # Uniform Integer
...     "species": ["mouse", "cat", "dog"],   # Categorical
... })
>>> configs = cs.sample_configuration(2)

Use float, integer or categorical to customize how sampling is done!

>>> from ConfigSpace import ConfigurationSpace, Integer, Float, Categorical, Normal
>>> cs = ConfigurationSpace(
...     name="myspace",
...     seed=1234,
...     space={
...         "a": Float("a", bounds=(0.1, 1.5), distribution=Normal(1, 10), log=True),
...         "b": Integer("b", bounds=(2, 10)),
...         "c": Categorical("c", ["mouse", "cat", "dog"], weights=[2, 1, 1]),
...     },
... )
>>> cs.sample_configuration(2)
[Configuration(values={
  'a': 0.17013149799713567,
  'b': 5,
  'c': 'dog',
})
, Configuration(values={
  'a': 0.5476203000512754,
  'b': 9,
  'c': 'mouse',
})
]

Maximum flexibility with conditionals, see forbidden clauses and conditionals for more info.

>>> from ConfigSpace import Categorical, ConfigurationSpace, EqualsCondition, Float
...
>>> cs = ConfigurationSpace(seed=1234)
...
>>> c = Categorical("c1", items=["a", "b"])
>>> f = Float("f1", bounds=(1.0, 10.0))
...
>>> # A condition where `f` is only active if `c` is equal to `a` when sampled
>>> cond = EqualsCondition(f, c, "a")
...
>>> # Add them explicitly to the configuration space
>>> cs.add_hyperparameters([c, f])
[c1, Type: Categorical, Choices: {a, b}, Default: a, f1, Type: UniformFloat, Range: [1.0, 10.0], Default: 5.5]

>>> cs.add_condition(cond)
f1 | c1 == 'a'

Installation

ConfigSpace requires Python 3.7 or higher.

ConfigSpace can be installed with pip:

pip install ConfigSpace

If installing from source, the ConfigSpace package requires numpy, cython and pyparsing. Additionally, a functioning C compiler is required.

On Ubuntu, the required compiler tools and Python headers can be installed with:

sudo apt-get install build-essential python3 python3-dev

When using Anaconda/Miniconda, the compiler has to be installed with:

conda install gxx_linux-64 gcc_linux-64

Citing the ConfigSpace

@article{
    title   = {BOAH: A Tool Suite for Multi-Fidelity Bayesian Optimization & Analysis of Hyperparameters},
    author  = {M. Lindauer and K. Eggensperger and M. Feurer and A. Biedenkapp and J. Marben and P. Müller and F. Hutter},
    journal = {arXiv:1908.06756 {[cs.LG]}},
    date    = {2019},
}

next

Quickstart