designspace 0.1.0

Declarative design spaces with a polars-like expression API.

A design space is the set of configurations a system can take: an algorithm, a model, a process, or a physical assembly. A space is declared once, giving the parameters, their domains, the condition under which each is active, and the combinations that are legal. The resulting Space can then be sampled, validated against, handed to a solver, serialized, or compared with another space by fingerprint.

[!NOTE] This project is research software, and may contain bugs. Please open an issue if you encounter one!

[!IMPORTANT] This project uses AI-assisted development tools. Code contributions generated or modified with the help of AI tools are reviewed and tested by maintainers before release.

Example

>>> import designspace as ds
>>> space = ds.space(
...     ds.param("optimizer").categorical("adam", "sgd"),
...     ds.param("lr").real(1e-4, 1e-1).log_scale(),  # shorthand for .prior(ds.Log())
...     ds.param("momentum").real(0.0, 0.99).when(ds.param("optimizer") == "sgd"),
... )
>>> print(space)
Space: 3 params, 1 conditional, 0 constraints
  optimizer  categorical  {'adam', 'sgd'}
  lr         real         [0.0001, 0.1]  log
  momentum   real         [0.0, 0.99]  when optimizer == 'sgd'
>>> sgd = space.sample_one(seed=0)
>>> sgd["optimizer"], "momentum" in sgd
('sgd', True)
>>> adam = space.sample_one(seed=3)
>>> adam["optimizer"], "momentum" in adam
('adam', False)

momentum is absent from the second configuration rather than present and null. Conditionality is structural, not a mask applied afterwards.

Scope

designspace declares spaces and does not search them. It ships no search operators, no distance functions, no tree generators, and no algebraic normalization of expressions. No value is ever silently clamped: a value outside its domain is an error, never a rounded input.

Install

pip install designspace

Python 3.12 or later. DataFrame output needs the polars extra:

pip install "designspace[polars]"

Documentation

https://librelunch.github.io/designspace

Stability

While the major version is zero, a minor release may change the Python API. The serialized format carries a version of its own, independent of the release version, so a space written to JSON by one release reads back in every later release that keeps that number. CHANGELOG.md says when it changes.

Development

Enter the development environment with devenv:

devenv shell

The commit gates install as git hooks on first entry: a fast subset on commit, the full set before a push. Run them by hand with just gates.

API.md is the normative specification. It states the target rather than the current release, so it also describes surface that is not built yet. The documentation site describes what ships.

License

This project is licensed under the MIT License.