boxmot.engine.tuning.search_space

YAML config parsing and search-space helpers shared across all backends.

load_yaml_config

load_yaml_config(tracker_name: str) -> dict

Load and validate the tuning metadata from a combined tracker YAML.

expand_yaml_groups

expand_yaml_groups(
    yaml_cfg: dict, *, prefix: str = ""
) -> dict

Expand authored option groups to dotted keys, preserving conditionals.

flatten_yaml_config

flatten_yaml_config(yaml_cfg: dict) -> dict

Flatten a nested YAML config into a single-level dict.

Entries with an activates block have all descendants promoted to the top level. Parent entries are preserved without their activates blocks.

condition_tracker_schema

condition_tracker_schema(
    schema: dict,
    defaults: Mapping[str, Any],
    *,
    geometry: str,
) -> dict

Exclude inactive geometry, metrics, and fixed conditional branches from search.

Keep inactive values as constants so trial records and saved profiles retain the selected runtime configuration. Only fixed parent values are resolved here; a searchable toggle's default does not disable its branch. Authored runtime values set distribution baselines and inactive defaults; a selected default-only case declares its own fixed value.

conditional_yaml_tree

conditional_yaml_tree(
    config: dict,
) -> tuple[dict[str, dict], set[str], dict[str, str]]

Return conditional parent/child metadata from activates blocks.

is_valid_search_param

is_valid_search_param(
    param: str, details: dict, *, warn: bool = True
) -> bool

Validate a YAML search-space entry.

validate_tuning_config

validate_tuning_config(
    tracker_name: str, config: dict
) -> None

Validate that search metadata is complete and targets runtime parameters.

yaml_to_tune_space

yaml_to_tune_space(config: dict, tune: Any) -> dict

Convert a tracker schema into Ray Tune's native conditional search space.

Choice dictionaries contain child distributions only in active branches. Normalize sampled configurations before passing them to the tracker.

default_tune_config

default_tune_config(
    yaml_cfg: dict,
    search_space: dict | None = None,
    *,
    defaults: Mapping[str, Any] | None = None,
    unconditional: bool = False,
) -> dict[str, Any]

Return a flat baseline point for the selected search parameters.

By default, children of inactive parents are excluded (Optuna mode). Set unconditional=True to include all defaults regardless of parent state when the caller needs an unconditional baseline. Defaults are read from the combined tracker YAML; defaults may override them for a selected runtime preset or caller-provided baseline.

to_builtin_value

to_builtin_value(value: Any) -> Any

Convert NumPy scalar values returned by search backends to Python scalars.

unpack_nested_dict

unpack_nested_dict(dct: dict[str, Any]) -> dict[str, Any]

Recursively flatten nested dictionaries produced by conditional search branches.

normalize_trial_config

normalize_trial_config(
    config: dict | None,
) -> dict[str, Any]

Return the flat config shape expected by tracker evaluation and reporting.