SummaryMetrics

class cubie.outputhandling.summarymetrics.metrics.SummaryMetrics(precision: type[float16] | type[float32] | type[float64] | dtype[float16] | dtype[float32] | dtype[float64])

Bases: object

Registry and dispatcher for summary metrics.

_names

list[str]. Registered metric names.

Type:

list[str]

_buffer_sizes

dict[str, int | Callable]. Buffer size requirements keyed by name.

Type:

dict[str, int | Callable]

_output_sizes

dict[str, int | Callable]. Output size requirements keyed by name.

Type:

dict[str, int | Callable]

_metric_objects

dict[str, SummaryMetric]. Registered metric instances.

_params

dict[str, Any]. Parameters parsed from configuration strings.

Type:

dict[str, Any | None]

Notes

Methods only report information for metrics explicitly requested so the caller can compile device functions tailored to the active configuration.

_apply_combined_metrics(request: list[str]) → list[str]

Substitute individual metrics with combined metrics when beneficial.

Parameters:

request – List of metric names to check for substitution.

Returns:

Modified list with combined metrics substituted where applicable.

Return type:

list[str]

Notes

Checks if subsets of requested metrics match any combined metric patterns and substitutes them with the more efficient combined version. Prioritizes larger combinations (more metrics combined). Preserves the original order of metrics in the request.

_get_size(metric_name: str, size_dict: dict[str, int | Callable]) → int

Calculate size based on parameters if needed.

Parameters:

• metric_name – Name of the metric to look up.

• size_dict – Dictionary containing size specifications for metrics.

Returns:

Calculated size for the metric.

Return type:

int

Warning

UserWarning

Issued when a callable size is provided without a parameter value.

buffer_offsets(output_types_requested: list[str]) → tuple[int, ...]

Get buffer starting offsets for requested summary metrics.

Parameters:

output_types_requested – Metric names to generate offsets for.

Returns:

Buffer starting offsets in the order requested.

Return type:

tuple[int, …]

buffer_sizes(output_types_requested: list[str]) → tuple[int, ...]

Get buffer sizes for requested summary metrics.

Parameters:

output_types_requested – Metric names to generate sizes for.

Returns:

Buffer sizes for the requested metrics.

Return type:

tuple[int, …]

property implemented_metrics: list[str]

Registered summary metric names.

legend(output_types_requested: list[str]) → list[str]

Generate column headings for requested summary metrics.

Parameters:

output_types_requested – Metric names to generate headings for.

Returns:

Column headings for the metrics in order.

Return type:

list[str]

Notes

Metrics with multi-element outputs produce numbered headings such as {name}_1 and {name}_2.

output_offsets(output_types_requested: list[str]) → tuple[int, ...]

Get output array starting offsets for requested summary metrics.

Parameters:

output_types_requested – Metric names to generate offsets for.

Returns:

Output array starting offsets in the order requested.

Return type:

tuple[int, …]

output_offsets_dict(output_types_requested: list[str]) → dict[str, int]

Get output array offsets as a dictionary for requested metrics.

Parameters:

output_types_requested – Metric names to generate offsets for.

Returns:

Mapping of metric names to output offsets.

Return type:

dict[str, int]

output_sizes(output_types_requested: list[str]) → tuple[int, ...]

Get output array sizes for requested summary metrics.

Parameters:

output_types_requested – Metric names to generate sizes for.

Returns:

Output array sizes for the requested metrics.

Return type:

tuple[int, …]

params(output_types_requested: list[str]) → tuple[Any, ...]

Get parameters for requested summary metrics.

Parameters:

output_types_requested – Metric names to get parameters for.

Returns:

Parameter values for the requested metrics.

Return type:

tuple[Any, …]

parse_string_for_params(dirty_request: list[str]) → list[str]

Extract parameters from metric specification strings.

Parameters:

dirty_request – Metric specifications that may contain [param] suffixes.

Returns:

Metrics with any parameter notation removed.

Return type:

list[str]

Notes

Parsed parameter values are cached in self._params keyed by metric name.

precision: type[float16] | type[float32] | type[float64] | dtype[float16] | dtype[float32] | dtype[float64]

preprocess_request(request: list[str]) → list[str]

Parse parameters from metric specifications and validate.

Parameters:

request – List of metric specification strings that may include [parameter] suffixes.

Returns:

Validated metric names after parameter parsing and combined metric substitution.

Return type:

list[str]

Notes

Invalid metric names trigger a warning and are removed from the returned list. Combined metrics are automatically substituted when multiple individual metrics can be computed more efficiently together.

register_metric(metric: SummaryMetric) → None

Register a new summary metric with the system.

Parameters:

metric – SummaryMetric instance to register.

Raises:

ValueError – If a metric with the same name is already registered.

Notes

Registration makes the metric available for summary buffer planning and function dispatch during integration.

save_functions(output_types_requested: list[str]) → tuple[Callable, ...]

Get save functions for requested summary metrics.

Parameters:

output_types_requested – Metric names to get save functions for.

Returns:

CUDA device save functions for the requested metrics.

Return type:

tuple[Callable, …]

summaries_buffer_height(output_types_requested: list[str]) → int

Calculate total buffer size for requested summary metrics.

Parameters:

output_types_requested – Metric names used to determine buffer requirements.

Returns:

Total buffer size needed for the requested metrics.

Return type:

int

summaries_output_height(output_types_requested: list[str]) → int

Calculate total output size for requested summary metrics.

Parameters:

output_types_requested – Metric names used to determine output requirements.

Returns:

Total output size needed for the requested metrics.

Return type:

int

unit_modifications(output_types_requested: list[str]) → list[str]

Generate unit modification strings for requested summary metrics.

Parameters:

output_types_requested – Metric names to generate unit modifications for.

Returns:

Unit modification strings for the metrics in order.

Return type:

list[str]

Notes

Returns one unit modification per output element. For multi-element outputs, the same unit modification is repeated for each element.

update(**kwargs) → None

Update compile settings for all registered metrics.

Parameters:

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

Returns:

Returns None.

Return type:

None

Notes

Propagates updates to all registered metric objects. Each metric invalidates its cache if values change.

update_functions(output_types_requested: list[str]) → tuple[Callable, ...]

Get update functions for requested summary metrics.

Parameters:

output_types_requested – Metric names to get update functions for.

Returns:

CUDA device update functions for the requested metrics.

Return type:

tuple[Callable, …]