Tuning parameter spaces

Parameter-space objects used by the experimental tuning implementation. The private helpers are retained only for existing source-level bookmarks and are not public imports.

Experimental API

This surface can change incompatibly in a minor release. See the stability policy.

Tuning and racing · Tuning guide

Hyperparameter space definitions for VAMOS tuning.

All parameter types use name as the first argument: - Real(name, low, high, log=False, role="operator_rate") - Int(name, low, high, log=False, role="population") - Categorical(name, choices, role="operator") - Boolean(name, role="adaptive")

All types support: - sample(rng) - draw a random value - to_unit(value) - map to [0, 1] space for optimization - from_unit(value) - map from [0, 1] space back to parameter value

Parameter roles (used by structured tuning workflows): - "structural": algorithm paradigm choices (decomposition, reference points) - "operator": discrete operator family choices (crossover type, mutation type) - "operator_rate": continuous operator parameters (eta, probabilities, sigma) - "population": resource allocation (pop_size, offspring_ratio, archive_size) - "adaptive": meta-parameters (immigration, adaptive operator selection)

Boolean dataclass

Boolean hyperparameter (True/False).

Categorical dataclass

Categorical hyperparameter with discrete choices.

from_unit(value)

Map from [0, 1] space to a choice.

to_unit(value)

Map value to [0, 1] space based on choice index.

Condition dataclass

Simple condition: a parameter is considered active only when expr evaluates to True given the current config.

Expressions are parsed safely (no function calls/attribute access).

ConditionalBlock dataclass

A block of parameters that are active only when a parent parameter has a specific value.

Int dataclass

Integer hyperparameter in [low, high] (inclusive).

from_unit(value)

Map from [0, 1] space to parameter value.

to_unit(value)

Map value to [0, 1] space.

ParamSpace dataclass

Defines a hyperparameter space with named parameters.

Example: space = ParamSpace(params={ "lr": Real("lr", 0.001, 0.1, log=True), "epochs": Int("epochs", 10, 100), })

is_active(param_name, config)

Check if param is active given config and conditions.

sample(rng=None)

Sample a configuration from the space.

validate(config)

Validate that all active params are present and within bounds.

Real dataclass

Real-valued hyperparameter in [low, high].

from_unit(value)

Map from [0, 1] space to parameter value.

to_unit(value)

Map value to [0, 1] space.

_MissingKeyError

Bases: Exception

Raised when a condition references a cfg key that is absent (inactive parent).

_safe_eval_condition(expr, cfg)

Evaluate a condition expression against cfg using a restricted AST (no calls/attrs).

If the expression references a cfg key that is missing (because its parent parameter is inactive), the condition evaluates to False.