SummaryMetric

class cubie.outputhandling.summarymetrics.metrics.SummaryMetric(buffer_size: int | Callable, output_size: int | Callable, name: str, precision: type[float16] | type[float32] | type[float64] | dtype[float16] | dtype[float32] | dtype[float64], unit_modification: str = '[unit]', sample_summaries_every: float = 0.01)[source]

Bases: CUDAFactory

Abstract base class for summary metrics.

buffer_size

int or Callable. Memory required per metric buffer entry. Parameterised metrics should supply a callable that accepts the metric parameter.

output_size

int or Callable. Memory required for persisted metric results.

name

str. Identifier used in registries and configuration strings.

unit_modification

str. Format string for unit modification in legends.

update_device_func

Callable. Compiled CUDA device update function for the metric.

save_device_func

Callable. Compiled CUDA device save function for the metric.

sample_summaries_every

Time interval between summary metric samples. Defaults to 0.01.

precision

Numerical precision for metric calculations. Defaults to np.float32.

Notes

Subclasses must implement build() to provide CUDA device callbacks with the signatures update(value, buffer, current_index, customisable_variable) and save(buffer, output_array, summarise_every, customisable_variable). Metrics need to be imported only after the global registry has been created so that decoration registers the implementation.

__init__(buffer_size: int | Callable, output_size: int | Callable, name: str, precision: type[float16] | type[float32] | type[float64] | dtype[float16] | dtype[float32] | dtype[float64], unit_modification: str = '[unit]', sample_summaries_every: float = 0.01) → None[source]

Initialise core metadata for a summary metric.

Parameters:

  • buffer_size – int or Callable. Buffer footprint or callable that accepts the metric parameter.

  • output_size – int or Callable. Output footprint or callable that accepts the metric parameter.

  • name – str. Identifier used for registration.

  • unit_modification – str. Format string for unit modification in legends. Use “[unit]” as placeholder. Defaults to “[unit]”.

  • sample_summaries_every – float. Time interval between summary metric samples. Defaults to 0.01.

  • precision – PrecisionDType. Numerical precision for metric calculations. Defaults to np.float32.

abstractmethod build() → MetricFuncCache[source]

Generate CUDA device functions for the metric.

Returns:

Cache containing device update and save functions compiled for CUDA execution.

Return type:

MetricFuncCache

Notes

Implementations must return functions with the signatures update(value, buffer, current_index, customisable_variable) and save(buffer, output_array, summarise_every, customisable_variable). Each callback needs @cuda.jit(..., device=True, inline=True) decoration supporting both single- and double-precision input.

property save_device_func: Callable

CUDA device save function for the metric.

update(**kwargs) → None[source]

Update metric compile settings.

Parameters:

**kwargs – Compile settings to update (e.g., sample_summaries_every=0.02).

Returns:

Returns None.

Return type:

None

Notes

Updates the MetricConfig and invalidates cache if values change. Triggers recompilation on next device_function access.

property update_device_func: Callable

CUDA device update function for the metric.