Antenna Module

The antenna module provides comprehensive antenna modeling capabilities for RF system analysis, including polarization calculations, dish gain computations, and radiation pattern analysis.

Polarization Loss

The polarization loss between two antennas with given axial ratios is calculated using the standard formula for polarization mismatch:

\[\text{PLF} = \frac{1}{2} +\ \frac{1}{2} \frac{4 \gamma_1 \gamma_2 -\ (1-\gamma_1^2)(1-\gamma_2^2)}{(1+\gamma_1^2)(1+\gamma_2^2)}\]

where:

  • \(\gamma_1\) and \(\gamma_2\) are the voltage axial ratios (linear, not dB)

  • PLF is the polarization loss factor (linear)

The polarization loss in dB is then:

\[L_{\text{pol}} = -10 \log_{10}(\text{PLF})\]

For circular polarization, the axial ratio is 0 dB, and for linear polarization, it is >40 dB.

Dish Gain

The gain of a parabolic dish antenna is given by:

\[G = \eta \left(\frac{\pi D}{\lambda}\right)^2\]

where:

  • \(\eta\) is the efficiency factor (typically 0.55 to 0.70)

  • \(D\) is the diameter of the dish

  • \(\lambda\) is the wavelength

Spherical Coordinate System

This module uses the standard spherical coordinate system with the following conventions:

  • \(\theta\) is the polar angle measured from the +z axis with range [0, π] radians.

  • \(\phi\) is the azimuthal angle measured from the +x axis in the xy-plane with range [0, 2π) or [-π, π) radians.

spacelink.core.antenna.polarization_loss(ar1, ar2)[source]

Calculate the polarization loss in dB between two antennas with given axial ratios.

Parameters:

  • ar1 (Decibels) – First antenna axial ratio in dB (amplitude ratio)

  • ar2 (Decibels) – Second antenna axial ratio in dB (amplitude ratio)

Returns:

Polarization loss in dB (positive value)

Return type:

Decibels

spacelink.core.antenna.dish_gain(diameter, frequency, efficiency)[source]

Calculate the gain in dB of a parabolic dish antenna.

Parameters:

  • diameter (Length) – Dish diameter

  • frequency (Frequency) – Frequency

  • efficiency (Dimensionless) – Antenna efficiency (dimensionless)

Returns:

Gain in decibels (dB)

Return type:

Decibels

Raises:

ValueError – If frequency is not positive

class spacelink.core.antenna.Handedness(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Handedness of the polarization ellipse.

The handedness is the direction of rotation of the E-field. The thumb points in the direction of propagation, and the fingers curl in the direction of the E-field rotation. When looking in the direction of propagation, the E-field rotates counter- clockwise for left-hand polarization and clockwise for right-hand polarization.

LEFT = 1
RIGHT = 2
class spacelink.core.antenna.Polarization(tilt_angle, axial_ratio, handedness)[source]

Bases: object

Represents a polarization state.

__init__(tilt_angle, axial_ratio, handedness)[source]

Create a polarization state.

Parameters:

  • tilt_angle (Angle) – Tilt angle of the major axis of the polarization ellipse, measured in the local tangent plane, relative to \(\hat{\theta}\).

  • axial_ratio (Dimensionless) – Ratio of the major to minor axis of the polarization ellipse.

  • handedness (Handedness) – The direction of rotation of the E-field when looking in the direction of propagation.

classmethod lhcp()[source]

Left-hand circular polarization.

Return type:

Self

classmethod rhcp()[source]

Right-hand circular polarization.

Return type:

Self

class spacelink.core.antenna.RadiationPattern(theta, phi, frequency, e_theta, e_phi, rad_efficiency, default_polarization=None, default_frequency=None)[source]

Bases: object

Represents an antenna radiation pattern on a spherical coordinate system.

__init__(theta, phi, frequency, e_theta, e_phi, rad_efficiency, default_polarization=None, default_frequency=None)[source]

Create a radiation pattern from a set of E-field components.

\[\vec{E}(\theta, \phi, f) = E_\theta(\theta, \phi, f)\hat{\theta} + E_\phi(\theta, \phi, f)\hat{\phi}\]
Parameters:

  • theta (Angle) – 1D array of equally spaced polar angles in [0, pi] radians with shape (N,).

  • phi (Angle) – 1D array of equally spaced azimuthal angles with shape (M,). The span must be at most 2π radians.

  • frequency (Frequency | None) – Optional 1D array of strictly increasing frequencies with shape (K,) where K > 1. If None, the pattern is treated as frequency-invariant and 2D over (theta, phi).

  • e_theta (Dimensionless) – Complex array of \(E_{\theta}(\theta, \phi[, f])\) values normalized such that the magnitude squared is equal to directivity. Shape is (N, M) if frequency is None, otherwise (N, M, K).

  • e_phi (Dimensionless) – Complex array of \(E_{\phi}(\theta, \phi[, f])\) values normalized such that the magnitude squared is equal to directivity. Shape is (N, M) if frequency is None, otherwise (N, M, K).

  • rad_efficiency (Dimensionless) – Radiation efficiency \(\eta\) in (0, 1].

  • default_polarization (Polarization | None) – Optional default polarization used when instance methods are called without an explicit polarization.

  • default_frequency (Frequency | None) – Optional default frequency used when instance methods are called without an explicit frequency.

Raises:

  • ValueError – If theta is not in [0, pi], if phi spans more than 2π radians, or if theta/phi/frequency are not strictly increasing, or if inputs are outside allowed ranges.

  • ValueError – If the surface integral of the directivity is greater than 4π.

property default_frequency: Annotated[Quantity, Unit('Hz')] | None

Default frequency used when instance methods are called without an explicit frequency.

For frequency-aware patterns, this must be a scalar frequency within the closed interval defined by the pattern’s frequency grid or None.

For frequency-invariant patterns this is stored but ignored.

classmethod from_circular_e_field(cls, theta, phi, frequency, e_lhcp, e_rhcp, rad_efficiency, default_polarization=None, default_frequency=None)[source]

Create a radiation pattern from a set of LHCP/RHCP E-field components.

\[\vec{E}(\theta, \phi, f) = E_\text{LHCP}(\theta, \phi, f)\hat{\text{LHCP}} + E_\text{RHCP}(\theta, \phi, f)\hat{\text{RHCP}}\]
Parameters:

  • theta (Angle) – 1D array of equally spaced polar angles in [0, pi] radians with shape (N,).

  • phi (Angle) – 1D array of equally spaced azimuthal angles with shape (M,). The span must be at most 2π radians.

  • frequency (Frequency | None) – Optional 1D array of strictly increasing frequencies with shape (K,). If None, the pattern is treated as frequency-invariant and 2D over (theta, phi).

  • e_lhcp (Dimensionless) – Complex array of \(E_{\text{LHCP}}(\theta, \phi[, f])\) values normalized such that the magnitude squared is equal to directivity. Shape is (N, M) if frequency is None, otherwise (N, M, K).

  • e_rhcp (Dimensionless) – Complex array of \(E_{\text{RHCP}}(\theta, \phi[, f])\) values normalized such that the magnitude squared is equal to directivity. Shape is (N, M) if frequency is None, otherwise (N, M, K).

  • rad_efficiency (Dimensionless) – Radiation efficiency \(\eta\) in (0, 1].

  • default_polarization (Polarization | None) – Optional default polarization used when instance methods are called without an explicit polarization.

  • default_frequency (Frequency | None) – Optional default frequency used when instance methods are called without an explicit frequency.

Return type:

Self

classmethod from_circular_gain(cls, theta, phi, frequency, gain_lhcp, gain_rhcp, phase_lhcp, phase_rhcp, rad_efficiency, default_polarization=None, default_frequency=None)[source]

Create a radiation pattern from circular gain and phase.

Parameters:

  • theta (Angle) – 1D array of equally spaced polar angles in [0, pi] radians with shape (N,).

  • phi (Angle) – 1D array of equally spaced azimuthal angles with shape (M,). The span must be at most 2π radians.

  • frequency (Frequency | None) – Optional 1D array of strictly increasing frequencies with shape (K,). If None, the pattern is treated as frequency-invariant and 2D over (theta, phi).

  • gain_lhcp (Dimensionless) – Array of LHCP gain values. Shape is (N, M) if frequency is None, otherwise (N, M, K).

  • gain_rhcp (Dimensionless) – Array of RHCP gain values. Shape is (N, M) if frequency is None, otherwise (N, M, K).

  • phase_lhcp (Angle) – Array of LHCP phase angles. Shape is (N, M) if frequency is None, otherwise (N, M, K).

  • phase_rhcp (Angle) – Array of RHCP phase angles. Shape is (N, M) if frequency is None, otherwise (N, M, K).

  • rad_efficiency (Dimensionless) – Radiation efficiency \(\eta\) in (0, 1].

  • default_polarization (Polarization | None) – Optional default polarization used when instance methods are called without an explicit polarization.

  • default_frequency (Frequency | None) – Optional default frequency used when instance methods are called without an explicit frequency.

Return type:

Self

classmethod from_linear_gain(cls, theta, phi, frequency, gain_theta, gain_phi, phase_theta, phase_phi, rad_efficiency, default_polarization=None, default_frequency=None)[source]

Create a radiation pattern from linear gain and phase.

Parameters:

  • theta (Angle) – 1D array of equally spaced polar angles in [0, pi] radians with shape (N,).

  • phi (Angle) – 1D array of equally spaced azimuthal angles with shape (M,). The span must be at most 2π radians.

  • frequency (Frequency | None) – Optional 1D array of strictly increasing frequencies with shape (K,). If None, the pattern is treated as frequency-invariant and 2D over (theta, phi).

  • gain_theta (Dimensionless) – Array of \(\hat{\theta}\) gain values. Shape is (N, M) if frequency is None, otherwise (N, M, K).

  • gain_phi (Dimensionless) – Array of \(\hat{\phi}\) gain values. Shape is (N, M) if frequency is None, otherwise (N, M, K).

  • phase_theta (Angle) – Array of \(\hat{\theta}\) phase angles. Shape is (N, M) if frequency is None, otherwise (N, M, K).

  • phase_phi (Angle) – Array of \(\hat{\phi}\) phase angles. Shape is (N, M) if frequency is None, otherwise (N, M, K).

  • rad_efficiency (Dimensionless) – Radiation efficiency \(\eta\) in (0, 1].

  • default_polarization (Polarization | None) – Optional default polarization used when instance methods are called without an explicit polarization.

  • default_frequency (Frequency | None) – Optional default frequency used when instance methods are called without an explicit frequency.

Return type:

Self

e_field(theta, phi, *, frequency=None, polarization=None)[source]

Normalized complex E-field in the desired polarization state.

Parameters:

  • theta (Angle) – Polar angles.

  • phi (Angle) – Azimuthal angles.

  • frequency (Frequency | None) – Desired frequency. If None, uses the instance’s default_frequency if set; otherwise raises ValueError. For 2D patterns (constructed without frequency), this argument is ignored.

  • polarization (Polarization | None) – Desired polarization state. If None, uses the instance’s default_polarization if set; otherwise raises ValueError.

Returns:

Complex E-field values. The E-field is normalized such that the magnitude squared is the directivity. Shape is determined by standard Numpy broadcasting rules from the shapes of theta and phi.

Return type:

Dimensionless

directivity(theta, phi, *, frequency=None, polarization=None)[source]

Directivity of the antenna.

Directivity as a function of the E-field in V/m is

\[D(\theta, \phi) = \frac{ 4 \pi r^2 |\vec{E}(r, \theta, \phi)|^2 }{2\eta_0 P_\text{rad}}\]

However, this class uses normalized E-fields since the intent is to represent only the relative power and phase of the E-field as a function of direction. Thus the directivity is simply

\[D(\theta, \phi) = |\vec{E}(\theta, \phi)|^2\]
Parameters:

  • theta (Angle) – Polar angles.

  • phi (Angle) – Azimuthal angles.

  • frequency (Frequency | None) – Desired frequency. If None, uses the instance’s default_frequency if set; otherwise raises ValueError. For 2D patterns (constructed without frequency), this argument is ignored.

  • polarization (Polarization | None) – Desired polarization state. If None, uses the instance’s default_polarization if set; otherwise raises ValueError.

Returns:

Directivity. Shape is determined by standard Numpy broadcasting rules from the shapes of theta and phi.

Return type:

Decibels

gain(theta, phi, *, frequency=None, polarization=None)[source]

Gain of the antenna.

\[G(\theta, \phi) = \eta \cdot D(\theta, \phi)\]

where \(\eta\) is the radiation efficiency.

Parameters:

  • theta (Angle) – Polar angles.

  • phi (Angle) – Azimuthal angles.

  • frequency (Frequency | None) – Desired frequency. If None, uses the instance’s default_frequency if set; otherwise raises ValueError. For 2D patterns (constructed without frequency), this argument is ignored.

  • polarization (Polarization | None) – Desired polarization state. If None, uses the instance’s default_polarization if set; otherwise raises ValueError.

Returns:

Gain. Shape is determined by standard Numpy broadcasting rules from the shapes of theta and phi.

Return type:

Decibels

axial_ratio(theta, phi, *, frequency=None)[source]

Axial ratio of the antenna.

The axial ratio is the ratio of the major to minor axis of the polarization ellipse. An axial ratio of 0 dB corresponds to circular polarization, and an axial ratio of ∞ corresponds to linear polarization. Elliptical polarizations have axial ratios between these two extremes.

Parameters:

  • theta (Angle) – Polar angles.

  • phi (Angle) – Azimuthal angles.

  • frequency (Frequency | None) – Desired frequency. If None, uses the instance’s default_frequency if set; otherwise raises ValueError. For 2D patterns (constructed without frequency), this argument is ignored.

Returns:

Axial ratio. Shape is determined by standard Numpy broadcasting rules from the shapes of theta and phi.

Return type:

Decibels