simplebench.results module🔗

Container for the results of a single benchmark test.

class simplebench.results.Results(
*,
group: str,
title: str,
description: str,
n: int | float,
rounds: int,
total_elapsed: float,
iterations: Sequence[Iteration],
variation_cols: dict[str, str] | None = None,
variation_marks: dict[str, Any] | None = None,
interval_unit: str = 'ns',
interval_scale: float = 1e-09,
ops_per_interval_unit: str = 'ns',
ops_per_interval_scale: float = 1e-09,
memory_unit: str = 'bytes',
memory_scale: float = 1.0,
ops_per_second: OperationsPerInterval | None = None,
per_round_timings: OperationTimings | None = None,
memory: MemoryUsage | None = None,
peak_memory: PeakMemoryUsage | None = None,
extra_info: dict[str, Any] | None = None,
)[source]🔗

Bases: object

Container for the results of a single benchmark test.

The Results class holds all relevant information about a benchmark test’s execution and its outcomes. It is immutable after creation to ensure data integrity.

Variables:

  • group (str) – The reporting group to which the benchmark case belongs. (read only)

  • title (str) – The name of the benchmark case. (read only)

  • description (str) – A brief description of the benchmark case. (read only)

  • n (int | float) – The n weighting the benchmark assigned to the iteration for purposes of Big O analysis. (read only)

  • rounds (int) – The number of rounds in the benchmark case. (read only)

  • variation_marks (MappingProxyType[str, Any]) – A dictionary of variation marks used to identify the benchmark variation. (read only)

  • variation_cols (MappingProxyType[str, str]) – The columns to use for labelling kwarg variations in the benchmark. (read only)

  • interval_unit (str) – The unit of measurement for the interval (e.g. “ns”). (read only)

  • interval_scale (float) – The scale factor for the interval (e.g. 1e-9 for nanoseconds). (read only)

  • ops_per_interval_unit (str) – The unit of measurement for operations per interval (e.g. “ops/s”). (read only)

  • ops_per_interval_scale (float) – The scale factor for operations per interval (e.g. 1.0 for ops/s). (read only)

  • memory_unit (str) – The unit of measurement for memory usage (e.g. “bytes”). (read only)

  • memory_scale (float) – The scale factor for memory usage (e.g. 1.0 for bytes). (read only)

  • iterations (tuple[Iteration, ...]) – A tuple of Iteration objects representing each iteration of the benchmark. (read only)

  • ops_per_second (OperationsPerInterval) – Statistics for operations per interval. (read only)

  • per_round_timings (OperationTimings) – Statistics for per-round timings. (read only)

  • memory (MemoryUsage) – Statistics for memory usage. (read only)

  • peak_memory (PeakMemoryUsage) – Statistics for peak memory usage. (read only)

  • total_elapsed (float) – The total elapsed time for the benchmark. (read only)

  • extra_info (MappingProxyType[str, Any]) – Additional information about the benchmark run. This is a read-only property that returns a mapping proxy to prevent external mutation. (read only)

Initialize a Results object.

Parameters:

  • group (str) – The reporting group to which the benchmark case belongs.

  • title (str) – The name of the benchmark case.

  • description (str) – A brief description of the benchmark case.

  • n (int | float) – The n weighting assigned to the iteration for purposes of Big O analysis.

  • rounds (int) – The number of rounds in the benchmark case.

  • total_elapsed (float) – The total elapsed time for the benchmark.

  • iterations (list[Iteration]) – The list of Iteration objects representing each iteration of the benchmark.

  • variation_cols (dict[str, str], optional) – The columns to use for labelling kwarg variations in the benchmark. Defaults to None, which results in an empty dictionary.

  • variation_marks (dict[str, Any], optional) – A dictionary of variation marks used to identify the benchmark variation. Defaults to None, which results in an empty dictionary.

  • interval_unit (str, optional) – The unit of measurement for the interval (e.g. “ns”). Defaults to “ns”.

  • interval_scale (float, optional) – The scale factor for the interval (e.g. 1e-9 for nanoseconds). Defaults to 1e-9.

  • ops_per_interval_unit (str, optional) – The unit of measurement for operations per interval (e.g. “ops/s”). Defaults to “ops/s”.

  • ops_per_interval_scale (float, optional) – The scale factor for operations per interval (e.g. 1.0 for ops/s). Defaults to 1.0.

  • memory_unit (str, optional) – The unit of measurement for memory usage (e.g. “bytes”). Defaults to “bytes”.

  • memory_scale (float, optional) – The scale factor for memory usage (e.g. 1.0 for bytes). Defaults to 1.0.

  • ops_per_second (Optional[OperationsPerInterval], optional) – The operations per second for the benchmark. Defaults to a new OperationsPerInterval object initialized from the benchmark’s iterations.

  • per_round_timings (Optional[OperationTimings], optional) – The per-round timings for the benchmark. Defaults to a new OperationTimings object initialized from the benchmark’s iterations.

  • memory (Optional[MemoryUsage], optional) – The memory usage for the benchmark. Defaults to a new MemoryUsage object initialized from the benchmark’s iterations.

  • peak_memory (Optional[PeakMemoryUsage], optional) – The peak memory usage for the benchmark. Defaults to a new PeakMemoryUsage object initialized from the benchmark’s iterations.

  • extra_info (Optional[dict[str, Any]], optional) – Any extra information to include in the benchmark results. Defaults to {}.

Raises:
as_dict(
full_data: bool = False,
) → dict[str, Any][source]🔗

Returns the benchmark results and statistics as a JSON-serializable dictionary.

property description: str🔗

A brief description of the benchmark case.

property extra_info: dict[str, Any]🔗

Additional information about the benchmark run.

property group: str🔗

The reporting group to which the benchmark case belongs.

property interval_scale: float🔗

The scale factor for the interval (e.g. 1e-9 for nanoseconds).

property interval_unit: str🔗

The unit of measurement for the interval (e.g. “ns”).

property iterations: tuple[Iteration, ...]🔗

The tuple of Iteration objects representing each iteration of the benchmark.

property memory: MemoryUsage🔗

Statistics for memory usage.

property memory_scale: float🔗

The scale factor for memory usage (e.g. 1.0 for bytes).

property memory_unit: str🔗

The unit of measurement for memory usage (e.g. “bytes”).

property n: float🔗

The O() complexity analysis size/weighting.

property ops_per_interval_scale: float🔗

The scale factor for operations per interval (e.g. 1.0 for ops/s).

property ops_per_interval_unit: str🔗

The unit of measurement for operations per interval (e.g. “ops/s”).

property ops_per_second: OperationsPerInterval🔗

Statistics for operations per interval.

property peak_memory: PeakMemoryUsage🔗

Statistics for peak memory usage.

property per_round_timings: OperationTimings🔗

Statistics for per-round timings.

results_section(
section: Section,
) → Stats[source]🔗

Returns the requested section of the benchmark results.

Parameters:

section (Section) – The section of the results to return. Must be Section.OPS or Section.TIMING.

Returns:

The requested section of the benchmark results.

Return type:

Stats

property rounds: int🔗

The number of rounds the benchmark ran per iteration.

property title: str🔗

The name of the benchmark case.

property total_elapsed: float🔗

The total elapsed time for the benchmark.

property variation_cols: mappingproxy[str, str]🔗

The columns to use for labelling kwarg variations in the benchmark.

property variation_marks: mappingproxy[str, Any]🔗

A dictionary of variation marks used to identify the benchmark variation.