Units Module

The units module provides comprehensive unit handling and conversion utilities for RF system analysis, built on top of the Astropy units system.

Decibel Units

To create a dimensionless quantity in decibels, use the u.dB(1) unit rather than u.dB. For example, 3.01 * u.dB(1). The (1) informs Astropy that the reference level is 1, which allows conversion from decibels to linear scale via .to(u.dimensionless). A bare u.dB has no defined reference level and Astropy will refuse to convert it to u.dimensionless.

For quantities with physical dimensions in decibels, use u.dB(unit). For example, 3.01 * u.dB(u.W). Or use one of the aliases defined in this module for common cases like u.dBW or u.dBm.

Wavelength

The relationship between wavelength and frequency is given by:

\[\lambda = \frac{c}{f}\]

where:

• \(c\) is the speed of light (299,792,458 m/s)

• \(f\) is the frequency in Hz

Return Loss to VSWR

The conversion from return loss in decibels to voltage standing wave ratio (VSWR) is done using:

\[\text{VSWR} = \frac{1 + |\Gamma|}{1 - |\Gamma|}\]

where:

• \(|\Gamma|\) is the magnitude of the reflection coefficient

• \(|\Gamma| = 10^{-\frac{\text{RL}}{20}}\)

• \(\text{RL}\) is the return loss in dB

VSWR to Return Loss

The conversion from voltage standing wave ratio (VSWR) to return loss in decibels is done using:

\[\text{RL} = -20 \log_{10}\left(\frac{\text{VSWR} - 1}{\text{VSWR} + 1}\right)\]

where:

• \(\text{VSWR}\) is the voltage standing wave ratio

• \(\text{RL}\) is the return loss in dB

spacelink.core.units.enforce_units(func_or_class)

Decorator to enforce the units specified in function parameter type annotations.

This decorator enforces some unit consistency rules for function parameters that annotated with one of the Annotated types in this module:

• The argument must be a Quantity object.

• The argument must be provided with a compatible unit. For example, a Frequency argument’s units can be u.Hz, u.MHz, u.GHz, etc. but not u.m, u.K, or any other non-frequency unit.

In addition to the above, the value of any Annotated argument will be converted automatically to the unit specified in for that type. For example, the Angle type will be converted to u.rad, even if the argument is provided with a unit of u.deg. This allows functions to flexibly handle compatible units while keeping tedious unit conversion logic out of the function body.

When applied to a dataclass, this decorator will wrap the __init__ method to enforce units on dataclass field assignments.

Parameters:

func_or_class (callable or class) – The function or dataclass to wrap.

Returns:

The wrapped function or modified dataclass with unit enforcement.

Return type:

callable or class

Raises:

• UnitConversionError – If any argument has incompatible units.

• TypeError – If an Annotated argument is not an Astropy Quantity object.

spacelink.core.units.wavelength(frequency)

Convert frequency to wavelength.

Parameters:

frequency (Quantity) – Frequency quantity (e.g., in Hz)

Returns:

Wavelength in meters

Return type:

Quantity

Raises:

UnitConversionError – If the input quantity has incompatible units

spacelink.core.units.frequency(wavelength)

Convert wavelength to frequency.

Parameters:

wavelength (Quantity) – Wavelength quantity (e.g., in meters)

Returns:

Frequency in hertz

Return type:

Quantity

Raises:

UnitConversionError – If the input quantity has incompatible units

spacelink.core.units.return_loss_to_vswr(return_loss)

Convert a return loss in decibels to voltage standing wave ratio (VSWR).

Parameters:

return_loss (Dimensionless) – Return loss. Must be >= 1 if provided as dimensionless or >= 0 if provided in decibels. Use np.inf for a perfect match.

Returns:

VSWR (>= 1)

Return type:

Dimensionless

Raises:

ValueError – If return_loss is < 0 dB

spacelink.core.units.vswr_to_return_loss(vswr)

Convert voltage standing wave ratio (VSWR) to return loss in decibels.

Parameters:

vswr (Quantity) – VSWR value (>= 1). Use 1 for a perfect match (infinite return loss)

Returns:

Return loss in decibels

Return type:

Quantity

Raises:

ValueError – If vswr is less than 1

spacelink.core.units.safe_negate(quantity)

Safely negate a dB or function unit quantity, preserving the unit. Astropy does not allow direct negation of function units (like dB).

Return type:

Quantity