robometric_frame.efficiency.base

Base class for efficiency metrics with start/stop interface.

This module provides an abstract base class for efficiency metrics that track resource usage over time intervals using a start/stop pattern.

Classes

EfficiencyMetric([percentiles])

Abstract base class for efficiency metrics with start/stop interface.

class robometric_frame.efficiency.base.EfficiencyMetric(percentiles=None, **kwargs)

Abstract base class for efficiency metrics with start/stop interface.

This base class provides common functionality for metrics that track resource usage (time, memory, etc.) over intervals. It implements: - start()/stop() interface for interval-based measurements - Percentile computation support - Common state management

Subclasses must implement: - _on_start(): Called when measurement starts - _on_stop(): Called when measurement stops, should return measured value - _get_measurement_unit(): Returns the unit suffix for computed statistics

Parameters:

• percentiles (Optional[list[float]]) – List of percentile values to compute (e.g., [0.5, 0.95, 0.99]). Default: [0.5, 0.95, 0.99] for median, 95th, and 99th percentiles.

• **kwargs (Any) – Additional keyword arguments passed to the base Metric class.

full_state_update: bool = False

is_differentiable: bool = False

higher_is_better: bool = False

total_value: Tensor

min_value: Tensor

max_value: Tensor

count: Tensor

values: list[Tensor]

__init__(percentiles=None, **kwargs)

Initialize the efficiency metric.

start()

Start a measurement interval.

This method begins tracking. Call stop() to end the interval and record the measurement.

Raises:

RuntimeError – If start() is called while already tracking.

Return type:

None

Example

>>> metric.start()
>>> # ... perform operations ...
>>> metric.stop()

stop()

Stop tracking and record the measurement.

This method ends the tracking interval and records the measured value.

Raises:

RuntimeError – If stop() is called without a preceding start().

Return type:

None

Example

>>> metric.start()
>>> # ... perform operations ...
>>> metric.stop()

update(value)

Update metric state with measurements.

Parameters:

value (Tensor) –

Measurement values. Can be: - Scalar tensor: Single measurement - 1D tensor: Batch of measurements

All values must be non-negative.

Raises:

ValueError – If value contains negative values.

Return type:

None

Example

>>> metric.update(torch.tensor(0.1))  # Single measurement
>>> metric.update(torch.tensor([0.11, 0.12]))  # Batch

compute()

Compute statistics including percentiles.

Returns:

• ‘mean{unit}’: Mean value

• ’min{unit}’: Minimum value

• ’max{unit}’: Maximum value

• ’total{unit}’: Total accumulated value

• ’count’: Number of measurements

• ’p{X}{unit}’: Xth percentile (e.g., ‘p50’ for median)

Return type:

Dictionary containing

Raises:

RuntimeError – If no measurements have been recorded.

reset()

Reset the metric state.

This method resets all metric states to their default values and clears any internal tracking state.

Return type:

None

training: bool