simplebench.iteration module🔗

Iteration class

class simplebench.iteration.Iteration(
*,
n: int | float = 1,
rounds: int = 1,
unit: str = 'ns',
scale: float = 1e-09,
elapsed: float = 0.0,
memory: int = 0,
peak_memory: int = 0,
)[source]🔗

Bases: object

Container for the results of a single benchmark iteration.

An iteration represents a single run of a benchmarked action (a run may consist of multiple rounds and a full benchmark consists of multiple iterations).

It holds the elapsed time, n weight, unit, scale, memory usage, and peak memory usage for that iteration.

Elapsed time is the total time taken for the iteration in the specified unit (e.g., nanoseconds) and scale (e.g., 1e-9 to convert nanoseconds to seconds) divided by the number of rounds as measured in the unit and scale specified. It is the average time per round for the iteration.

So if an iteration with a unit of ‘ns’ and a scale of 1e-9 had an elapsed time of 5000000 (5 million nanoseconds) and 20 rounds, then the elapsed time would be equivalent to an average of (5000000 * 1e-9) / 20 = 0.00025 seconds per round.

The n-weight represents the O(n) type complexity of the action being benchmarked. For example, if the action processes a list of size n, then the n-weight would be n.

This allows data analysis tools to better understand the performance characteristics of the action being benchmarked when the benchmark data is exported, although it is not used directly in any calculations by SimpleBench itself currently.

Variables:

  • n (int | float) – The complexity n-weight for the iteration. (read only)

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

  • unit (str) – The unit of measurement for the elapsed time. It gets its default value from DEFAULT_INTERVAL_UNIT. (read only)

  • scale (float) – The scale factor for the elapsed time. It gets its default value from DEFAULT_INTERVAL_SCALE. (read only)

  • elapsed (float) – The elapsed time for the iteration. (read only)

  • ops_per_second (float) – The number of operations per second. (read only)

  • per_round_elapsed (float) – The mean time for a single round scaled to the base unit. (read only)

  • memory (int) – The memory usage in bytes. (defaults to 0) (read only)

  • peak_memory (int) – The peak memory usage in bytes. (read only)

Initialize an Iteration instance.

Parameters:

  • n (int | float) – The complexity n-weight for the iteration. Must be a positive integer.

  • rounds (int) – The number of rounds in the iteration. Must be a positive integer.

  • unit (str) – The unit of measurement for the elapsed time. It gets its default value from DEFAULT_INTERVAL_UNIT.

  • scale (float) – The scale factor for the elapsed time. It gets its default value from simplebench.defaults.DEFAULT_INTERVAL_SCALE.

  • elapsed (float) – The elapsed time for the iteration. Must be a non-negative float.

  • memory (int) – The memory usage in bytes. Must be an integer.

  • peak_memory (int) – The peak memory usage in bytes. Must be an integer.

Raises:
property elapsed: float🔗

The total elapsed time for the iteration in the specified unit.

iteration_section(
section: Section,
) → int | float[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 memory: int🔗

The memory usage in bytes. This is the difference between the allocated memory before and after the action.

The edge case of no memory allocated results in a returned value of 0

property n: float🔗

The ‘n’ complexity weight of the iteration for O() analysis.

property ops_per_second: float🔗

The number of operations per second.

This is calculated as the inverse of the elapsed time.

The edge cases of 0 elapsed time results in a returned value of 0.0 This would otherwise be an impossible value and so flags a measurement error.

property peak_memory: int🔗

The peak memory usage in bytes.

This is the maximum memory allocated during the action.

property per_round_elapsed: float🔗

The mean time for a single round scaled to the base unit. If elapsed is 0, returns 0.0

The per round computation is the elapsed time divided by the number of rounds in the iteration.

The scaling to the base unit is done using the scale factor. This has the effect of converting the elapsed time into the base unit. For example, if the scale factor is 1e-9 then elapsed time in nanoseconds will be converted to seconds.

Returns:

The mean time for a single round scaled to the base unit.

Return type:

float

property rounds: int🔗

The number of rounds in the iteration

property scale: float🔗

The scale factor for the elapsed time.

property unit: str🔗

The unit of measurement for the elapsed time.