protomotions.agents.utils.metering module

Performance timing and metric averaging utilities for profiling training.

This module provides utilities for measuring and reporting time spent in different parts of the training loop, as well as accumulating and averaging tensor metrics.

Key Classes:

• Timer: Individual timer for a named operation

• TimeReport: Manager for multiple timers with reporting

• TensorAverageMeter: Accumulates and averages tensor values

• TensorAverageMeterDict: Dictionary of TensorAverageMeters

class protomotions.agents.utils.metering.Timer(name)

Bases: object

Individual timer for measuring elapsed time.

Tracks total time and number of activations for a named operation.

Parameters:

name – Identifier for this timer.

time_total

Cumulative time in seconds.

num_ons

Number of times timer was activated.

__init__(name)

on()

off()

report()

clear()

class protomotions.agents.utils.metering.TimeReport

Bases: object

Manager for multiple timers with reporting capabilities.

Maintains a collection of named timers and provides methods for starting, stopping, and reporting timing statistics.

Example

>>> time_report = TimeReport()
>>> time_report.add_timer("data_collection")
>>> time_report.start_timer("data_collection")
>>> # ... do work ...
>>> time_report.end_timer("data_collection")
>>> time_report.report()

__init__()

add_timer(name)

start_timer(name)

end_timer(name)

report(name=None)

clear_timer(name=None)

pop_timer(name=None)

class protomotions.agents.utils.metering.TensorAverageMeter(dtype=<Mock object>, device=None)

Bases: object

Accumulates and averages tensor values.

Collects tensor values and computes their mean. Supports memory optimization by storing tensors in lower precision or on CPU.

Parameters:

• dtype – Data type for storing tensors (default: torch.float16 to save memory).

• device – Device to store tensors on (default: None keeps original device, use ‘cpu’ to save GPU memory).

Example

>>> meter = TensorAverageMeter()
>>> meter.add(torch.tensor([1.0, 2.0, 3.0]))
>>> meter.add(torch.tensor([4.0, 5.0, 6.0]))
>>> print(meter.mean())  # 3.5

__init__(dtype=<Mock object>, device=None)

Parameters:

• dtype – Data type for storing tensors. Use torch.float16 to save memory since these tensors don’t require gradients.

• device – Device to store tensors on. If None, keeps on original device. Use ‘cpu’ to save GPU memory by moving tensors to CPU.

add(x)

mean()

clear()

mean_and_clear()

class protomotions.agents.utils.metering.TensorAverageMeterDict(dtype=<Mock object>, device=None)

Bases: object

Dictionary of TensorAverageMeters for managing multiple metrics.

Maintains a collection of TensorAverageMeters, automatically creating new meters as needed when keys are accessed. Useful for tracking multiple training metrics (losses, rewards, etc.).

Parameters:

• dtype – Data type for storing tensors in child TensorAverageMeters.

• device – Device to store tensors on.

Example

>>> meter_dict = TensorAverageMeterDict()
>>> meter_dict.add({"loss": torch.tensor(0.5), "reward": torch.tensor(10.0)})
>>> meter_dict.add({"loss": torch.tensor(0.3), "reward": torch.tensor(15.0)})
>>> print(meter_dict.mean())  # {"loss": 0.4, "reward": 12.5}

__init__(dtype=<Mock object>, device=None)

Parameters:

• dtype – Data type for storing tensors in child TensorAverageMeters. Use torch.float16 to save memory since these tensors don’t require gradients.

• device – Device to store tensors on. If None, keeps on original device. Use ‘cpu’ to save GPU memory by moving tensors to CPU.

add(data_dict)

mean()

clear()

mean_and_clear()