designspace.flatten

designspace.flatten(config: dict[str, Any], space: Space) → dict[str, Any]

Turn a nested configuration into one keyed by path.

Configurations nest: a struct is a dict, a choice with a payload is a single-key dict, while Space.params is flat. This bridges the two, producing keys in the path grammar, which are also the DataFrame column names. ds.unflatten() reverses it.

A choice contributes both its discriminator and its payload’s parameters, so no information is lost.

Parameters:

• config (dict[str, Any]) – A configuration in nested form.

• space (Space) – The space it belongs to, which supplies the structure to walk.

Returns:

The configuration keyed by path.

Return type:

dict[str, Any]

Examples

>>> s = ds.space(
...     ds.param("opt").choice(sgd=ds.space(ds.param("momentum").real(0, 1))),
...     ds.param("lr").real(0, 1),
... )
>>> config = {"opt": {"sgd": {"momentum": 0.5}}, "lr": 0.1}
>>> ds.flatten(config, s)
{'opt': 'sgd', 'opt.sgd.momentum': 0.5, 'lr': 0.1}
>>> ds.unflatten(ds.flatten(config, s), s) == config
True

Raises:

TypeError – When the configuration is already keyed by path. Flattening it again would drop every lift, a list’s entry holding its length rather than a list on the second pass, so this refuses rather than returning a configuration with parameters missing.