Population

The Population container manages a collection of evolutionary agents. It collects per-agent metrics into a PopulationMetrics snapshot each evolution step and formats them into MetricsReport objects consumed by loggers.

Metrics Snapshots

class agilerl.population.PopulationMetrics(fitnesses: list[float | int] | list[dict[str, float]], scores: list[float | int] | list[dict[str, float]], steps: list[int], steps_per_second: list[float], mutations: list[str | None], indices: list[int], additional_metrics: list[dict[str, float]], hyperparameters: list[dict[str, float]], nonscalar_additional_metrics: list[dict[str, ~numpy.ndarray[tuple[int, ...], ~numpy.dtype[~numpy._typing._array_like._ScalarType_co]] | None]] = <factory>, subpopulations: list[int | None] = <factory>)

Immutable snapshot of per-agent population metrics.

Stores raw per-agent data and exposes computed properties for population-level aggregates.

to_dict() → dict[str, float | int | str]

Return a flat, JSON-friendly dict for logging backends.

Returns:

Dictionary of metrics suitable for wandb/CSV logging.

Return type:

dict[str, float | int | str]

class agilerl.population.MetricsReport(metrics: PopulationMetrics)

Formats population metrics into a tabular report.

Constructed by Population.report_metrics() and consumed by Logger implementations.

Parameters:

metrics (PopulationMetrics) – Aggregated population metrics snapshot.

eval_rows() → list[ScalarMetricRow | NestedMetricRow]

Return the evaluation metric rows.

Returns:

List of evaluation metric rows.

Return type:

list[ScalarMetricRow | NestedMetricRow]

render() → str

Render a MetricsReport snapshot of collected training metrics into a Rich-formatted table string.

Returns:

The report rendered by Rich as ANSI-styled text.

Return type:

str

property show_mean_column: bool

Whether to display a population mean column.

to_dict() → dict[str, float | int | str]

Return a JSON-friendly dict for logging backends.

Returns:

Dictionary of metrics suitable for wandb/CSV logging.

Return type:

dict[str, float | int | str]

to_nonscalar_dict() → dict[str, ndarray[tuple[int, ...], dtype[_ScalarType_co]]]

Return per-agent non-scalar metrics for TensorBoard-style backends.

Returns:

Dictionary mapping train/agent_{idx}/{name} to arrays.

Return type:

dict[str, npt.NDArray]

train_rows() → list[ScalarMetricRow | NestedMetricRow]

Return the training metric rows.

Returns:

List of training metric rows.

Return type:

list[ScalarMetricRow | NestedMetricRow]

Population Container

class agilerl.population.Population(agents: list[AgentT], min_evo_steps: int = 100, accelerator: Accelerator | None = None, loggers: list[Logger] | None = None)

Population wrapper for evolutionary agent management.

Owns the logger pipeline and provides a single report_metrics() entry-point that gathers per-agent data, builds a MetricsReport, and dispatches it to all configured loggers.

Parameters:

• agents (list[AgentT]) – Initial population of RL agents.

• min_evo_steps (int) – Minimum evolutionary steps before allowing early stopping.

• accelerator (Accelerator | None) – HuggingFace Accelerator for distributed training.

• loggers (list[Logger] | None) – List of loggers to use.

property agents: list[AgentT]

Current population of agents.

all_below(max_steps: int) → bool

Check if every agent’s step count is below max_steps.

Parameters:

max_steps (int) – The maximum number of steps to check.

Returns:

True if every agent’s step count is below max_steps, False otherwise.

Return type:

bool

clear_agent_metrics() → None

Clear scores and additional metric accumulators for all agents.

finish() → None

Release resources held by all loggers.

increment_evo_step() → None

Increment the population-level evo-step counter.

is_nested_scores() → bool

Check if the scores are nested per-sub-agent i.e. a nested list.

Returns:

True if the scores are nested per-sub-agent, False otherwise.

Return type:

bool

property last_scalar_fitnesses: list[float]

Most recent fitnesses as scalars (single-agent / summed loops).

property local_step: int

Local step counter for the population.

report_metrics(clear: bool = True) → MetricsReport

Gather, format, and log population metrics.

Parameters:

clear (bool) – Whether to clear the metrics after reporting.

Returns:

The metrics report.

Return type:

MetricsReport

should_stop(target: float | None) → bool

Check if all agents consistently exceed the target fitness and the minimum number of evo-steps has been reached.

Consistency is judged on the mean of each agent’s last 10 recorded fitness values.

Parameters:

target (float | None) – The target fitness to check.

Returns:

True if all agents consistently exceed the target fitness, False otherwise.

Return type:

bool

property size: int

Number of agents in the population.

update(agents: list[AgentT]) → None

Replace the population (e.g. after tournament selection + mutation).