Skip to content

Utilities

Signal processing and unit conversion utilities.

Miscellaneous helpers: dB/linear conversions, phase wrapping to (−π, π], replacing zeros with the smallest float, and other small signal utilities used across the library.

db2power(db)

Converts power from decibels (dB) to watts.

The conversion is calculated as 10**(db / 10).

Parameters:

Name Type Description Default
db float

Power in decibels (dB).

 required

Returns:

Name Type Description
float float

Power in watts (W).
Source code in src/rad_lab/utilities.py 
26
27
28
29
30
31
32
33
34
35
36
37
def db2power(db: float) -> float:
    """Converts power from decibels (dB) to watts.

    The conversion is calculated as 10**(db / 10).

    Args:
        db (float): Power in decibels (dB).

    Returns:
        float: Power in watts (W).
    """
    return 10 ** (db / 10)

db2volt(db)

Converts a decibel (dB) value to a voltage or amplitude ratio.

The conversion is calculated as 10**(db / 20).

Parameters:

Name Type Description Default
db float

A value in decibels (dB).

 required

Returns:

Name Type Description
float float

The corresponding voltage or amplitude ratio (unitless).
Source code in src/rad_lab/utilities.py 
55
56
57
58
59
60
61
62
63
64
65
66
def db2volt(db: float) -> float:
    """Converts a decibel (dB) value to a voltage or amplitude ratio.

    The conversion is calculated as 10**(db / 20).

    Args:
        db (float): A value in decibels (dB).

    Returns:
        float: The corresponding voltage or amplitude ratio (unitless).
    """
    return 10 ** (db / 20)

phase_negpi_pospi(phase)

Wraps phase angles to the interval [-pi, pi).

Parameters:

Name Type Description Default
phase float or array - like

Phase angle(s) in radians.

 required

Returns:

Type Description
ndarray

numpy.ndarray: Phase angle(s) wrapped to the [-pi, pi) interval.
Source code in src/rad_lab/utilities.py 
69
70
71
72
73
74
75
76
77
78
79
80
81
82
def phase_negpi_pospi(phase: float | np.ndarray) -> np.ndarray:
    """Wraps phase angles to the interval [-pi, pi).

    Args:
        phase (float or array-like): Phase angle(s) in radians.

    Returns:
        numpy.ndarray: Phase angle(s) wrapped to the [-pi, pi) interval.
    """

    phase = np.atleast_1d(np.array(phase))
    phase = phase % (2 * c.PI)
    phase[phase >= c.PI] -= 2 * c.PI
    return phase

phase_zero_twopi(phase)

Wraps phase angles to the interval [0, 2*pi).

Parameters:

Name Type Description Default
phase float or array - like

Phase angle(s) in radians.

 required

Returns:

Type Description
ndarray

numpy.ndarray: Phase angle(s) wrapped to the [0, 2*pi) interval.
Source code in src/rad_lab/utilities.py 
85
86
87
88
89
90
91
92
93
94
95
96
def phase_zero_twopi(phase: float | np.ndarray) -> np.ndarray:
    """Wraps phase angles to the interval [0, 2*pi).

    Args:
        phase (float or array-like): Phase angle(s) in radians.

    Returns:
        numpy.ndarray: Phase angle(s) wrapped to the [0, 2*pi) interval.
    """
    phase = np.array(phase)
    phase = phase % (2 * c.PI)
    return phase

power2db(power)

Converts power from watts to decibels (dB).

The conversion is calculated as 10 * log10(power).

Parameters:

Name Type Description Default
power float

Power in watts (W).

 required

Returns:

Name Type Description
float float

Power in decibels (dB).
Source code in src/rad_lab/utilities.py 
12
13
14
15
16
17
18
19
20
21
22
23
def power2db(power: float) -> float:
    """Converts power from watts to decibels (dB).

    The conversion is calculated as 10 * log10(power).

    Args:
        power (float): Power in watts (W).

    Returns:
        float: Power in decibels (dB).
    """
    return 10 * np.log10(power)

volt2db(voltage)

Converts a voltage or amplitude ratio to decibels (dB).

The conversion is calculated as 20 * log10(voltage). This is typically used for field quantities like voltage or pressure.

Parameters:

Name Type Description Default
voltage float

Voltage or amplitude ratio (unitless).

 required

Returns:

Name Type Description
float float

The corresponding value in decibels (dB).
Source code in src/rad_lab/utilities.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
def volt2db(voltage: float) -> float:
    """Converts a voltage or amplitude ratio to decibels (dB).

    The conversion is calculated as 20 * log10(voltage). This is typically
    used for field quantities like voltage or pressure.

    Args:
        voltage (float): Voltage or amplitude ratio (unitless).

    Returns:
        float: The corresponding value in decibels (dB).
    """
    return 20 * np.log10(voltage)

zero_to_smallest_float(array, value=1e-16)

Replaces all zero elements in a NumPy array with a small float value.

This operation is performed in-place. It is often used to avoid division-by-zero errors or issues with taking logarithms of zero.

Parameters:

Name Type Description Default
array ndarray

The input array to modify.

 required
value float

The small value to substitute for zeros. Defaults to 1e-16.

 1e-16

Returns:

Name Type Description
None None

The array is modified in-place.
Source code in src/rad_lab/utilities.py 
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
def zero_to_smallest_float(array: np.ndarray, value: float = 1e-16) -> None:
    """Replaces all zero elements in a NumPy array with a small float value.

    This operation is performed in-place. It is often used to avoid
    division-by-zero errors or issues with taking logarithms of zero.

    Args:
        array (numpy.ndarray): The input array to modify.
        value (float, optional): The small value to substitute for zeros.
            Defaults to 1e-16.

    Returns:
        None: The array is modified in-place.
    """
    indxs = np.where(array == 0)
    array[indxs] = value