Metrics¶

Per-agent metric accumulators used internally by Population to track training progress.

Base Class¶

class agilerl.metrics.BaseMetrics(*, fitness_window: int = 100, nonscalar_window: int = 100000)¶

Base class for per-agent metrics.

Parameters:

fitness_window (int) – Maximum number of fitness values to store.
nonscalar_window (int) – Maximum number of raw samples to keep per non-scalar (histogram) metric.

add_fitness(value: float) → None¶

Add a fitness value to the fitness history.

Parameters:: value (float) – Fitness value to add.

add_scores(scores: list[float]) → None¶

Add scores to the metrics.

Parameters:: scores (list[float]) – List of scores to add.

property additional_metrics: list[str]¶: All registered scalar metric names.

clear() → None¶: Clear scores and all additional metric accumulators.

finalize_training_step(num_steps: int) → None¶

Compute fps from the delta since init_training_step().

Parameters:: num_steps (int) – Number of steps taken during the training step.

abstract get_histogram(name: str, *args: str) → ndarray | None¶: Return accumulated raw values for a histogram metric.

increment_steps(n: int) → None¶

Increment the cumulative environment step count.

Parameters:: n – Number of steps to add.

init_training_step() → None¶: Snapshot state at the start of a training step.

abstract log(name: str, value: float) → None¶: Log a value to the accumulator for a registered metric.

abstract log_histogram(name: str, values: ndarray) → None¶: Extend the accumulator with raw sample values for a histogram metric.

property nonscalar_metrics: list[str]¶: All registered non-scalar metric names.

register(name: str) → None¶

Parameters:: name (str) – Unique metric name (e.g. "loss", "entropy").
Raises:: ValueError – If name is already registered.

register_histogram(name: str) → None¶

Non-scalar metrics store array data (e.g. action distributions) and are only reported by loggers that support them (TensorBoard).

Parameters:: name (str) – Unique metric name (e.g. "action_distribution").
Raises:: ValueError – If name is already registered.

Single-Agent Metrics¶

class agilerl.metrics.AgentMetrics(*, fitness_window: int = 100, nonscalar_window: int = 100000)¶

Tracks training metrics for a single-agent RL algorithm instance.

Parameters:

fitness_window (int) – Maximum number of fitness values to store.
nonscalar_window (int) – Maximum number of raw samples to keep per non-scalar (histogram) metric.

clear() → None¶: Clear scores and all additional metric accumulators.

get_histogram(name: str) → ndarray | None¶

Return the accumulated raw values for a histogram metric.

Parameters:: name (str) – Previously registered non-scalar metric name.
Returns:: Array of all accumulated values, or None if empty.
Return type:: numpy.ndarray | None

get_mean(name: str) → float¶

Return the mean of accumulated values for a registered metric.

Parameters:: name (str) – Previously registered metric name.
Returns:: Mean of accumulated values for the registered metric.
Return type:: float

log(name: str, value: float) → None¶

Append a value to the accumulator for a registered metric.

Parameters:

name (str) – Previously registered metric name.
value (float) – Scalar metric value.

Example: >>> metrics = AgentMetrics() >>> metrics.log(“loss”, 0.1) >>> metrics.log(“loss”, 0.2) >>> metrics.get_mean(“loss”)

log_histogram(name: str, values: ndarray) → None¶

Extend the accumulator with raw sample values for a histogram metric.

Values are accumulated across calls so that get_histogram() returns the full distribution for the entire evo step.

Parameters:

name (str) – Previously registered non-scalar metric name.
values (numpy.ndarray) – Array of raw sample values (e.g. action indices).

Multi-Agent Metrics¶

class agilerl.metrics.MultiAgentMetrics(agent_ids: list[str], *, fitness_window: int = 100, nonscalar_window: int = 100000)¶

Tracks training metrics for multi-agent RL algorithms.

Assumes that we log metrics for each sub-agent separately. For settings where we have homogeneous/grouped agents (e.g. speaker_0, speaker_1, listener_0, listener_1), we assume metrics are logged for the group as a whole.

Parameters:

agent_ids (list[str]) – Sub-agent identifiers from the environment.
fitness_window (int) – Maximum number of fitness values to store.

clear() → None¶: Clear scores and all additional metric accumulators.

get_histogram(name: str, agent_id: str) → ndarray | None¶

Return accumulated raw values for a histogram metric and sub-agent.

Parameters:

name (str) – Previously registered non-scalar metric name.
agent_id (str) – Sub-agent identifier.

Returns:

Array of all accumulated values, or None if empty.

Return type:

numpy.ndarray | None

get_mean(name: str, agent_id: str) → float¶

Return the mean of accumulated values for a registered metric and sub-agent.

Parameters:

name (str) – Previously registered metric name.
agent_id (str) – Sub-agent identifier.

Returns:

Mean of accumulated values for the metric and sub-agent.

Return type:

float

log(name: str, value: float, agent_id: str | None = None) → None¶

Append a value to the accumulator for a registered metric and sub-agent.

Example: >>> metrics = MultiAgentMetrics([“speaker_0”, “speaker_1”, “listener_0”, “listener_1”]) >>> metrics.log(“loss”, 0.1, “speaker_0”) >>> metrics.log(“loss”, 0.2, “speaker_0”) >>> metrics.get_mean(“loss”, “speaker_0”)

Parameters:

name (str) – Previously registered metric name.
value (float) – Scalar metric value.
agent_id (str | None) – Sub-agent identifier.

log_histogram(name: str, values: ndarray, agent_id: str | None = None) → None¶

Extend the accumulator with raw sample values for a histogram metric.

Parameters:

name (str) – Previously registered non-scalar metric name.
values (numpy.ndarray) – Array of raw sample values (e.g. action indices).
agent_id (str | None) – Sub-agent identifier. If omitted, defaults to the first configured sub-agent.