Skip to content

math#

Unit conversions and small numeric helpers for analysis scripts.

Covers the everyday conversions (temperature, frequency, duration, angles) and a few interpolation/range utilities, so scripts can mix instrument units without hand-rolling the arithmetic.

celsius_to_temperature #

celsius_to_temperature(celsius: float) -> Temperature

Wrap a Celsius number in a unit-aware Temperature value.

Use when an instrument call expects a Temperature rather than a bare number.

Parameters:

Name Type Description Default
celsius float

Temperature in degrees Celsius.

 required

Returns:

Type Description
Temperature

A Temperature carrying the value and its unit.

clamp #

clamp(
    value: float, min_val: float, max_val: float
) -> float

Restrict a value to a range, returning the nearest allowed value.

Returns min_val if value is below the range, max_val if above, and value unchanged if already inside it.

Parameters:

Name Type Description Default
value float

The value to constrain.

 required
min_val float

Lower bound of the allowed range.

 required
max_val float

Upper bound of the allowed range.

 required

Returns:

Type Description
float

value clamped to [min_val, max_val].

convert_duration #

convert_duration(
    value: float,
    from_unit: Literal["ns", "us", "ms", "s", "min", "h"],
    to_unit: Literal["ns", "us", "ms", "s", "min", "h"],
) -> float

Convert a duration between time units (ns, us, ms, s, min, h).

Parameters:

Name Type Description Default
value float

The duration to convert.

 required
from_unit Literal['ns', 'us', 'ms', 's', 'min', 'h']

Unit of value — one of ns, us, ms, s, min, h.

 required
to_unit Literal['ns', 'us', 'ms', 's', 'min', 'h']

Unit to convert to (same choices as from_unit).

 required

Returns:

Type Description
float

The duration expressed in to_unit.

convert_frequency #

convert_frequency(
    value: float,
    from_unit: Literal[
        "hz",
        "Hz",
        "HZ",
        "khz",
        "KHz",
        "KHZ",
        "mhz",
        "MHz",
        "MHZ",
        "ghz",
        "GHz",
        "GHZ",
    ],
    to_unit: Literal[
        "hz",
        "Hz",
        "HZ",
        "khz",
        "KHz",
        "KHZ",
        "mhz",
        "MHz",
        "MHZ",
        "ghz",
        "GHz",
        "GHZ",
    ],
) -> float

Convert a frequency between Hz, kHz, MHz, and GHz.

Parameters:

Name Type Description Default
value float

The frequency to convert.

 required
from_unit Literal['hz', 'Hz', 'HZ', 'khz', 'KHz', 'KHZ', 'mhz', 'MHz', 'MHZ', 'ghz', 'GHz', 'GHZ']

Unit of value (case-insensitive: hz, khz, mhz, ghz).

 required
to_unit Literal['hz', 'Hz', 'HZ', 'khz', 'KHz', 'KHZ', 'mhz', 'MHz', 'MHZ', 'ghz', 'GHz', 'GHZ']

Unit to convert to (same choices as from_unit).

 required

Returns:

Type Description
float

The frequency expressed in to_unit.

convert_temperature #

convert_temperature(
    value: float,
    from_unit: Literal["C", "K", "F"],
    to_unit: Literal["C", "K", "F"],
) -> float

Convert a temperature between Celsius, Kelvin, and Fahrenheit.

Parameters:

Name Type Description Default
value float

The temperature to convert.

 required
from_unit Literal['C', 'K', 'F']

Unit of value — "C", "K", or "F".

 required
to_unit Literal['C', 'K', 'F']

Unit to convert to — "C", "K", or "F".

 required

Returns:

Type Description
float

The temperature expressed in to_unit.

degrees_to_radians #

degrees_to_radians(degrees: float) -> float

Convert an angle from degrees to radians (\(\text{rad} = \deg \times \pi/180\)).

Parameters:

Name Type Description Default
degrees float

Angle in degrees.

 required

Returns:

Type Description
float

The angle in radians.

duration_to_nanos #

duration_to_nanos(duration: Duration) -> float

Read a unit-aware Duration back as plain nanoseconds.

Parameters:

Name Type Description Default
duration Duration

A unit-aware Duration.

 required

Returns:

Type Description
float

The value in nanoseconds.

frequency_to_hz #

frequency_to_hz(frequency: Frequency) -> float

Read a unit-aware Frequency back as plain hertz.

Parameters:

Name Type Description Default
frequency Frequency

A unit-aware Frequency.

 required

Returns:

Type Description
float

The value in Hz.

hz_to_frequency #

hz_to_frequency(hz: float) -> Frequency

Wrap a hertz number in a unit-aware Frequency value.

Parameters:

Name Type Description Default
hz float

Frequency in hertz.

 required

Returns:

Type Description
Frequency

A Frequency carrying the value and its unit.

lerp #

lerp(
    x: float, x1: float, y1: float, x2: float, y2: float
) -> float

Linearly interpolate a \(y\) value at x given two known points.

Draws a straight line through \((x_1, y_1)\) and \((x_2, y_2)\) and reads off its height at x:

\[y = y_1 + (x - x_1)\,\frac{y_2 - y_1}{x_2 - x_1}\]

Parameters:

Name Type Description Default
x float

Position to evaluate at.

 required
x1 float

X of the first known point.

 required
y1 float

Y of the first known point.

 required
x2 float

X of the second known point.

 required
y2 float

Y of the second known point.

 required

Returns:

Type Description
float

The interpolated (or extrapolated) \(y\) value at x.

Raises:

Type Description
ValueError

If the two points share an x (x1 == x2).

map_range #

map_range(
    value: float,
    from_min: float,
    from_max: float,
    to_min: float,
    to_max: float,
) -> float

Rescale a value from one range onto another, linearly.

Maps from_min→to_min and from_max→to_max and interpolates in between (and extrapolates outside). Handy for converting between, say, a data range and pixel or axis coordinates.

Parameters:

Name Type Description Default
value float

The value to rescale.

 required
from_min float

Start of the source range.

 required
from_max float

End of the source range.

 required
to_min float

Start of the target range.

 required
to_max float

End of the target range.

 required

Returns:

Type Description
float

value rescaled into the target range.

Raises:

Type Description
ValueError

If the source range is empty (from_min == from_max).

ns_to_duration #

ns_to_duration(ns: int) -> Duration

Wrap a nanosecond count in a unit-aware Duration value.

Parameters:

Name Type Description Default
ns int

Duration in nanoseconds.

 required

Returns:

Type Description
Duration

A Duration carrying the value and its unit.

radians_to_degrees #

radians_to_degrees(radians: float) -> float

Convert an angle from radians to degrees (\(\deg = \text{rad} \times 180/\pi\)).

Parameters:

Name Type Description Default
radians float

Angle in radians.

 required

Returns:

Type Description
float

The angle in degrees.

temperature_to_celsius #

temperature_to_celsius(temperature: Temperature) -> float

Read a Temperature value back as plain degrees Celsius.

Parameters:

Name Type Description Default
temperature Temperature

A unit-aware Temperature.

 required

Returns:

Type Description
float

The value in degrees Celsius.