HPO Specifications

A training manifest selects its evolution regime through the single selection_strategy block, a discriminated union keyed on strategy: tournament (the default) validates the block as TournamentSelectionSpec, and multi_frequency validates it as MultiFrequencySelectionSpec. The two regimes are therefore mutually exclusive by construction, and a block that omits strategy is treated as tournament selection so existing configs are unchanged.

The block was previously named tournament_selection; that spelling is still accepted as an alias, so manifests written against earlier versions keep validating. Serialized output still uses tournament_selection.

Both regimes take their population size from the mandatory training.pop_size field.

In Python, the trainers and from_trainer_specs() take this block through a single selection_strategy argument. The former spellings (tournament on the trainers and tournament_selection on from_trainer_specs) are still accepted with a DeprecationWarning.

class agilerl.models.hpo.MutationProbabilities(*, no_mut: Annotated[float, Ge(ge=0.0), Le(le=1.0)] = 0.4, arch_mut: Annotated[float, Ge(ge=0.0), Le(le=1.0)] = 0.2, new_layer: Annotated[float, Ge(ge=0.0), Le(le=1.0)] = 0.2, params_mut: Annotated[float, Ge(ge=0.0), Le(le=1.0)] = 0.2, act_mut: Annotated[float, Ge(ge=0.0), Le(le=1.0)] = 0.0, rl_hp_mut: Annotated[float, Ge(ge=0.0), Le(le=1.0)] = 0.2)

Mutation probability distribution.

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agilerl.models.hpo.MutationSpec(*, name: str | None = None, probabilities: ~agilerl.arena.models.hpo.MutationProbabilities = <factory>, rl_hp_selection: dict[str, ~agilerl.arena.models.hpo.RLHyperparameter] = <factory>, mutation_sd: ~typing.Annotated[float, ~annotated_types.Ge(ge=0.0)] = 0.1, rand_seed: ~typing.Annotated[int, ~annotated_types.Ge(ge=0)] = 42, network: ~agilerl.arena.models.hpo.NetworkMutationRanges | None = None, dormant_threshold: ~typing.Annotated[float, ~annotated_types.Ge(ge=0.0)] = 0.01)

The manifest’s mutation section.

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agilerl.models.hpo.TournamentSelectionSpec(*, strategy: Literal['tournament'] = 'tournament', name: str | None = None, tournament_size: Annotated[int, Ge(ge=1)] = 2, elitism: bool = True)

Tournament branch of the selection_strategy section.

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agilerl.models.hpo.MultiFrequencySelectionSpec(*, strategy: Literal['multi_frequency'] = 'multi_frequency', name: str | None = None, n_subpopulations: Annotated[int, Ge(ge=2)] = 2, n_winners: Annotated[int | None, Ge(ge=1)] = None, n_survivors: Annotated[int | None, Ge(ge=0)] = None, n_open_for_migration: Annotated[int | None, Ge(ge=1)] = None, n_losers: Annotated[int | None, Ge(ge=1)] = None, evolution_frequency_ratios: list[int] | None = None)

MF-PBT branch of the selection_strategy section.

The total population size is configured in the manifest’s training block, not on this spec. This spec only validates the population-size-independent constraints; resolve_brackets() fills in the rest.

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

resolve_brackets(population_size: int) → Self

Fill in the bracket sizes this spec left unset, for population_size.

Parameters:

population_size (int) – Total population size from the training section.

Returns:

This spec, with every bracket size resolved.

Return type:

Self

Raises:

ValueError – If the resulting layout violates an MF-PBT invariant.