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.

Every parameter is drawn in declaration order, so the random stream does not depend on which parameters end up active. A parameter is kept when its conditions hold for the parents already kept, so descendants of an inactive parameter are left out.

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.