Metadata-Version: 2.5
Name: designspace
Version: 0.1.0
Summary: Declarative design spaces with a polars-like expression API
Project-URL: Homepage, https://librelunch.github.io/designspace/
Project-URL: Repository, https://github.com/librelunch/designspace
Project-URL: Changelog, https://github.com/librelunch/designspace/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/librelunch/designspace/issues
Author-email: Jonathan Wurth <jonathan.wurth@uni-a.de>
License-Expression: MIT
License-File: LICENSE
Keywords: configuration,declarative,design-space,hyperparameters,optimization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: numpy>=1.26
Requires-Dist: rfc8785==0.1.4
Provides-Extra: polars
Requires-Dist: polars>=1.0; extra == 'polars'
Description-Content-Type: text/markdown

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/_static/readme-header-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="docs/_static/readme-header-light.svg">
  <img alt="designspace. Declarative design spaces. Search strategy not included." src="docs/_static/readme-header-light.svg">
</picture>

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

```pycon
>>> 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

```console
pip install designspace
```

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

```console
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](https://devenv.sh):

```console
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](./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](./LICENSE).
