Population Utils¶

Helpers for aggregating population-level metrics.

scalar_fitness() is the fitness reduction shared by the selection strategies (TournamentSelection and MultiFrequencySelection). Multi-agent algorithms evaluated with sum_scores=False record one fitness value per sub-agent, while ranking a population requires a total order, so those rows are collapsed to their mean across sub-agents.

agilerl.utils.population_utils.scalar_fitness(fitness: float | ndarray[tuple[int, ...], dtype[_ScalarType_co]] | dict[str, float]) → float¶

Reduce a possibly vector-valued fitness to a single scalar for ranking.

When sum_scores=False, multi-agent algorithms record one fitness value per sub-agent. Selection strategies need a total ordering over the population, so such rows are collapsed to their mean across sub-agents.

Parameters:: fitness (float | numpy.typing.NDArray | dict[str, float]) – A recorded fitness: a scalar, a per-sub-agent sequence, or a per-sub-agent mapping.
Returns:: The scalar fitness used for ranking.
Return type:: float

Example:

>>> scalar_fitness({"agent_0": 2.0, "agent_1": 4.0})
3.0

agilerl.utils.population_utils.get_nested_mean(metrics: list[dict[str, float]]) → dict[str, float]¶

Transpose a list of dicts and compute the mean per key.

Works for both plain scalar keys ("loss") and flattened multi-agent keys ("loss/a0", "loss/a1").

Parameters:: metrics (list[dict[str, float]]) – List of dictionaries containing scalar metric snapshots.
Returns:: Dictionary mapping each key to the mean across all dicts.
Return type:: dict[str, float]

Example:

>>> metrics = [{"a": 1.0, "b": 2.0}, {"a": 3.0, "b": 4.0}]
>>> get_nested_mean(metrics)
{"a": 2.0, "b": 3.0}

agilerl.utils.population_utils.get_values_for_key(snapshots: list[dict[str, float]], key: str) → list[float]¶

Get the values for a key from a list of metric snapshots.

Parameters:

snapshots (list[dict[str, float]]) – List of metric snapshots.
key (str) – The key to get the values for.

Returns:

List of values for the key.

Return type:

list[float]

Example:

>>> snapshots = [{"a": 1.0, "b": 2.0}, {"a": 3.0, "b": 4.0}]
>>> get_values_for_key(snapshots, "a")
[1.0, 3.0]