Units Module

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

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

to_dB

The conversion to decibels is done using:

\[\text{X}_{\text{dB}} = \text{factor} \cdot \log_{10}(x)\]

The result will have units of dB(input_unit), e.g. dBW, dBK, dBHz, etc. For dimensionless input, the result will have unit dB.

to_linear

The conversion from decibels to a linear (dimensionless) ratio is done using:

\[x = 10^{\frac{\text{X}_{\text{dB}}}{\text{factor}}}\]

where:

• \(\text{X}_{\text{dB}}\) is the value in decibels

• \(\text{factor}\) is 10 for power quantities, 20 for field quantities

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)

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.

Parameters:

func (callable) – The function to wrap.

Returns:

The wrapped function with unit enforcement.

Return type:

callable

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.to_dB(x, *, factor=10.0)

Convert dimensionless quantity to decibels.

Note that for referenced logarithmic units, conversions should be done using the .to(unit) method. :type x: Quantity :param x: value to be converted :type x: Dimensionless :type factor: float :param factor: 10 for power quantities, 20 for field quantities :type factor: float, optional

Return type:

Decibels

spacelink.core.units.to_linear(x, *, factor=10.0)

Convert decibels to a linear (dimensionless) ratio.

Parameters:

• x (Decibels) – A quantity in decibels

• factor (float, optional) – 10 for power quantities, 20 for field quantities

Return type:

Dimensionless

spacelink.core.units.return_loss_to_vswr(return_loss)

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

Parameters:

return_loss (Quantity) – Return loss in decibels (>= 0). Use float(‘inf’) for a perfect match

Returns:

VSWR (>= 1)

Return type:

Dimensionless

Raises:

ValueError – If return_loss is negative

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