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. Reading it back as TrainingManifest.tournament_selection (core or Arena) also still works, with a DeprecationWarning; it returns None when the configured strategy is not tournament selection.

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

In Python, the trainers and TrainingManifest.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.

Parameters:

  • no_mut (float) – Probability of no mutation.

  • arch_mut (float) – Probability of architecture mutation.

  • new_layer (float) – Probability of new layer mutation.

  • params_mut (float) – Probability of parameters mutation.

  • act_mut (float) – Probability of activation mutation.

  • rl_hp_mut (float) – Probability of RL hyperparameter mutation.

model_config: ClassVar[ConfigDict] = {}

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

class agilerl.models.hpo.MutationSpec(*, probabilities: ~agilerl.models.hpo.MutationProbabilities = <factory>, rl_hp_selection: dict[str, ~agilerl.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)

Pydantic model for Mutations object.

Parameters:

  • probabilities (MutationProbabilities) – Probability distribution for the mutations.

  • rl_hp_selection (dict[str, RLHyperparameter]) – RL hyperparameters to mutate.

  • mutation_sd (float) – Standard deviation of the mutation.

  • rand_seed (int) – Random seed for repeatability.

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', tournament_size: Annotated[int, Ge(ge=1)] = 2, elitism: bool = True)

Pydantic model for TournamentSelection object.

Parameters:

  • strategy (Literal["tournament"]) – Discriminator selecting this (tournament) branch of the manifest’s selection_strategy union. Fixed to “tournament”.

  • tournament_size (int) – Size of the tournament.

  • elitism (bool) – Whether elitism is enabled.

model_config: ClassVar[ConfigDict] = {}

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', 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)

Pydantic model for the MultiFrequencySelection object.

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.

Parameters:

  • strategy (Literal["multi_frequency"]) – Discriminator selecting this (MF-PBT) branch of the manifest’s selection_strategy union. Fixed to “multi_frequency”.

  • n_subpopulations (int) – Number of subpopulations (>= 2, since MF-PBT migration draws from other subpopulations).

  • n_winners (int | None) – Agents in the winners bracket (>= 1; default round(0.25 * population_size // n_subpopulations)).

  • n_survivors (int | None) – Agents in the survivors bracket (>= 0; default 0).

  • n_open_for_migration (int | None) – Agents in the open-for-migration bracket (>= 1; default round(0.25 * population_size // n_subpopulations)).

  • n_losers (int | None) – Agents in the losers bracket (>= 1; default the remainder population_size // n_subpopulations - n_winners - n_survivors - n_open_for_migration).

  • evolution_frequency_ratios (list[int] | None) – Per-subpopulation evolution-frequency ratios (strictly increasing integers, each >= 1; one per subpopulation; default [1, 5, 10, …]).

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

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