simplebench.si_units module🔗

Utility functions for handling SI units

simplebench.si_units.si_scale(unit: str, base_unit: str) → float[source]🔗

Get the SI scale factor for a unit given the base unit.

This method will return the scale factor for the given unit relative to the base unit for SI prefixes ranging from tera (T) to pico (p).

Example: si_scale('ns', 's') returns 1e-9

Parameters:

  • unit (str) – The unit to get the scale factor for.

  • base_unit (str) – The base unit

Returns:

The scale factor for the given unit.

Return type:

float

Raises:

  • SimpleBenchValueError – If the SI unit is not recognized, if base_unit is an empty string, or if the unit does not end with the base_unit.

  • SimpleBenchTypeError – If the unit or base_unit args are not type str.

simplebench.si_units.si_scale_for_largest(
numbers: Sequence[int | float],
base_unit: str,
) → tuple[str, float][source]🔗

Get the scale factor and SI unit for the largest in a sequence of numbers.

The scale factor is the factor that should be applied to the numbers to convert them to the desired unit. The SI unit is the unit that corresponds to the scale factor.

It gives the SI prefix unit and scale for the largest absolute value in the sequence. If all numbers are zero, it returns the base unit and a scale factor of 1.0.

Parameters:

  • numbers (Sequence[float | int]) – A sequence of numbers to scale.

  • base_unit (str) – The base unit to use for scaling.

Returns:

A tuple containing the scaled unit and the scaling factor.

Return type:

tuple[str, float]

simplebench.si_units.si_scale_for_smallest(
numbers: Sequence[int | float],
base_unit: str,
) → tuple[str, float][source]🔗

Get the scale factor and SI unit for the smallest in a sequence of numbers.

The scale factor is the factor that should be applied to the numbers to convert them to the desired unit. The SI unit is the unit that corresponds to the scale factor.

It gives the SI prefix unit and scale for the smallest non-zero absolute value in the sequence. If all numbers are zero, it returns the base unit and a scale factor of 1.0.

Parameters:

  • numbers (Sequence[float | int]) – A sequence of numbers to scale.

  • base_unit (str) – The base unit to use for scaling.

Returns:

A tuple containing the scaled unit and the scaling factor.

Return type:

tuple[str, float]

simplebench.si_units.si_scale_to_unit(
base_unit: str,
current_unit: str,
target_unit: str,
) → float[source]🔗

Get the scale factor to convert a current SI unit to a target SI unit based on their SI prefixes.

Example:

scale_by: float = si_scale_to_unit(base_unit='s', current_unit='s', target_unit='ns')
Parameters:

  • base_unit (str) – The base unit to use for scaling.

  • current_unit (str) – The current unit of the number.

  • target_unit (str) – The target unit to scale the number to.

Returns:

The scaling factor to convert the current unit to the target unit.

Return type:

float

Raises:

  • SimpleBenchValueError – If the SI prefix units are not recognized; if base_unit, current_unit, or target_unit is an empty string; or if the units are not compatible (i.e., do not share the same base unit (i.e. ‘seconds’ vs ‘meters’)).

  • SimpleBenchTypeError – If the unit, base_unit, current_unit, or target_unit args are not type str.

simplebench.si_units.si_unit_base(unit: str) → str[source]🔗

Guess the base unit from an SI unit.

This assumes that the SI unit is a valid SI unit with an optional SI prefix. If the unit is a single character, it is returned as-is on the assumption that it is already the base unit.

We only check for a single-character SI prefix at the start of the unit from the range of supported SI prefixes (from tera (T) to pico (p)).

This CAN result in false positives if the base unit starts with a character that is also a valid SI prefix. (potential false positives: ‘m’ (meter), ‘M’ (mole), ‘P’ (peta), ‘T’ (tesla), ‘G’ (gauss), ‘k’ (katal), ‘n’ (newton), ‘p’ (pascal)). However, these units are uncommon in benchmarking and the benefit of simplicity outweighs the risk of false positives.

We could do a more complex check by looking for known SI base units, but this would require maintaining a list of known base units and would still not be exhaustive.

If no valid SI prefix is found, the unit is assumed to already be the base unit.

Example

si_unit_base('ns') returns 's'

Parameters:

unit (str) – The SI unit to get the base unit from.

Returns:

The base unit.

Return type:

str

Raises: