Antenna Patterns#

We refer the user to the section “Far Field of a Transmitting Antenna” for various useful definitions and background on antenna modeling. An AntennaPattern can be single- or dual-polarized and might have for each polarization direction a possibly different pattern. One can think of a dual-polarized pattern as two colocated linearly polarized antennas.

Mathematically, an antenna pattern is defined as a function \(f:(\theta,\varphi)\mapsto (C_\theta(\theta, \varphi), C_\varphi(\theta, \varphi))\) that maps a pair of zenith and azimuth angles to zenith and azimuth pattern values.

class sionna.rt.AntennaPattern[source]#

Abstract class for antenna patterns

Any instance of this class must implement the patterns property which returns a list of one or two antenna patterns for single- or dual-polarized antennas, respectively.

Methods

compute_gain(polarization_direction: int = 0, num_samples: int = 1000, verbose: bool = True) → Tuple[drjit.cuda.ad.Float, drjit.cuda.ad.Float, drjit.cuda.ad.Float][source]#

Computes directivity, gain, and radiation efficiency of the antenna pattern of one of the polarization directions

Given a function \(f:(\theta,\varphi)\mapsto (C_\theta(\theta, \varphi), C_\varphi(\theta, \varphi))\) describing an antenna pattern (14), this function computes the directivity \(D\), gain \(G\), and radiation efficiency \(\eta_\text{rad}=G/D\) (see (12)).

Parameters:

  • polarization_direction (int) – Polarization direction (0 | 1)

  • num_samples (int) – Number of discretization steps for numerical integration

  • verbose (bool) – If True, the results are pretty printed.

Returns:

Directivity \(D\), gain \(G\), and radiation efficiency \(\eta_\text{rad}=G/D\)

Example#

from sionna.rt import PlanarArray
array = PlanarArray(num_rows=1, num_cols=1, pattern="tr38901", polarization="V")
d, g, eta = array.antenna_pattern.compute_gain();

Directivity [dB]: 9.825768560205825
Gain [dB]: 7.99998570013805
Efficiency [%]: 65.67826867103577
show(polarization_direction: int = 0) → Tuple[matplotlib.figure.Figure, matplotlib.figure.Figure, matplotlib.figure.Figure][source]#

Visualizes the antenna gain of the antenna pattern of one of the polarization directions

This function visualizes the directional antenna gain with the help of three figures showing the vertical and horizontal cuts as well as a three-dimensional visualization.

Parameters:

polarization_direction (int) – Polarization direction (0 | 1)

Returns:

Vertical cut, horizontal cut, and 3D visualization of the antenna gain

Example#

from sionna.rt import PlanarArray
array = PlanarArray(num_rows=1, num_cols=1, pattern="dipole", polarization="V")
array.antenna_pattern.show()
../../_images/pattern_vertical.png
../../_images/pattern_horizontal.png
../../_images/pattern_3d.png

Attributes

property patterns#

List of antenna patterns for one or two polarization directions. The pattern of a specific polarization direction can be also accessed by indexing the antenna pattern instance.

Type:

List [Callable [[mitsuba.Float, mitsuba.Float], Tuple [mitsuba.Complex2f, mitsuba.Complex2f]]]

class sionna.rt.PolarizedAntennaPattern(*, v_pattern: Callable[[drjit.cuda.ad.Float, drjit.cuda.ad.Float], drjit.cuda.ad.Complex2f], polarization: str, polarization_model: str = 'tr38901_2')[source]#

Transforms a vertically polarized antenna pattern function into an arbitray single- or dual-polarized antenna pattern based on a polarization and polarization model

Parameters:

Methods

compute_gain(polarization_direction: int = 0, num_samples: int = 1000, verbose: bool = True) → Tuple[drjit.cuda.ad.Float, drjit.cuda.ad.Float, drjit.cuda.ad.Float]#

Computes directivity, gain, and radiation efficiency of the antenna pattern of one of the polarization directions

Given a function \(f:(\theta,\varphi)\mapsto (C_\theta(\theta, \varphi), C_\varphi(\theta, \varphi))\) describing an antenna pattern (14), this function computes the directivity \(D\), gain \(G\), and radiation efficiency \(\eta_\text{rad}=G/D\) (see (12)).

Parameters:

  • polarization_direction (int) – Polarization direction (0 | 1)

  • num_samples (int) – Number of discretization steps for numerical integration

  • verbose (bool) – If True, the results are pretty printed.

Returns:

Directivity \(D\), gain \(G\), and radiation efficiency \(\eta_\text{rad}=G/D\)

Example#

from sionna.rt import PlanarArray
array = PlanarArray(num_rows=1, num_cols=1, pattern="tr38901", polarization="V")
d, g, eta = array.antenna_pattern.compute_gain();

Directivity [dB]: 9.825768560205825
Gain [dB]: 7.99998570013805
Efficiency [%]: 65.67826867103577
show(polarization_direction: int = 0) → Tuple[matplotlib.figure.Figure, matplotlib.figure.Figure, matplotlib.figure.Figure]#

Visualizes the antenna gain of the antenna pattern of one of the polarization directions

This function visualizes the directional antenna gain with the help of three figures showing the vertical and horizontal cuts as well as a three-dimensional visualization.

Parameters:

polarization_direction (int) – Polarization direction (0 | 1)

Returns:

Vertical cut, horizontal cut, and 3D visualization of the antenna gain

Example#

from sionna.rt import PlanarArray
array = PlanarArray(num_rows=1, num_cols=1, pattern="dipole", polarization="V")
array.antenna_pattern.show()
../../_images/pattern_vertical.png
../../_images/pattern_horizontal.png
../../_images/pattern_3d.png

Attributes

property patterns#

List of antenna patterns for one or two polarization directions. The pattern of a specific polarization direction can be also accessed by indexing the antenna pattern instance.

Type:

List [Callable [[mitsuba.Float, mitsuba.Float], Tuple [mitsuba.Complex2f, mitsuba.Complex2f]]]

Vertically Polarized Antenna Pattern Functions#

sionna.rt.antenna_pattern.v_iso_pattern(theta: drjit.cuda.ad.Float, phi: drjit.cuda.ad.Float) → drjit.cuda.ad.Complex2f[source]#

Vertically polarized isotropic antenna pattern function

Parameters:
sionna.rt.antenna_pattern.v_dipole_pattern(theta: drjit.cuda.ad.Float, phi: drjit.cuda.ad.Float) → drjit.cuda.ad.Complex2f[source]#

Vertically polarized short dipole antenna pattern function from (Eq. 4-26a) [Balanis97]

Parameters:
sionna.rt.antenna_pattern.v_hw_dipole_pattern(theta: drjit.cuda.ad.Float, phi: drjit.cuda.ad.Float) → drjit.cuda.ad.Complex2f[source]#

Vertically polarized half-wavelength dipole antenna pattern function from (Eq. 4-84) [Balanis97]

Parameters:
sionna.rt.antenna_pattern.v_tr38901_pattern(theta: drjit.cuda.ad.Float, phi: drjit.cuda.ad.Float) → drjit.cuda.ad.Complex2f[source]#

Vertically polarized antenna pattern function from 3GPP TR 38.901 (Table 7.3-1) [TR38901_RT]

Parameters:

Polarization Models#

sionna.rt.antenna_pattern.polarization_model_tr38901_1(c_theta_tilde: drjit.cuda.ad.Complex2f, theta: drjit.cuda.ad.Float, phi: drjit.cuda.ad.Float, slant_angle: drjit.cuda.ad.Float) → Tuple[drjit.cuda.ad.Complex2f, drjit.cuda.ad.Complex2f][source]#

Model-1 for polarized antennas from 3GPP TR 38.901 [TR38901_RT]

Transforms a vertically polarized antenna pattern \(\tilde{C}_\theta(\theta, \varphi)\) into a linearly polarized pattern whose direction is specified by a slant angle \(\zeta\). For example, \(\zeta=0\) and \(\zeta=\pi/2\) correspond to vertical and horizontal polarization, respectively, and \(\zeta=\pm \pi/4\) to a pair of cross polarized antenna elements.

The transformed antenna pattern is given by (7.3-3) [TR38901_RT]:

\[\begin{split}\begin{aligned} \begin{bmatrix} C_\theta(\theta, \varphi) \\ C_\varphi(\theta, \varphi) \end{bmatrix} &= \begin{bmatrix} \cos(\psi) \\ \sin(\psi) \end{bmatrix} \tilde{C}_\theta(\theta, \varphi)\\ \cos(\psi) &= \frac{\cos(\zeta)\sin(\theta)+\sin(\zeta)\sin(\varphi)\cos(\theta)}{\sqrt{1-\left(\cos(\zeta)\cos(\theta)-\sin(\zeta)\sin(\varphi)\sin(\theta)\right)^2}} \\ \sin(\psi) &= \frac{\sin(\zeta)\cos(\varphi)}{\sqrt{1-\left(\cos(\zeta)\cos(\theta)-\sin(\zeta)\sin(\varphi)\sin(\theta)\right)^2}} \end{aligned}\end{split}\]
Parameters:
Returns:

Zenith (\(C_\theta\)) and azimuth (\(C_\phi\)) pattern

sionna.rt.antenna_pattern.polarization_model_tr38901_2(c_theta_tilde: drjit.cuda.ad.Complex2f, theta: drjit.cuda.ad.Float, phi: drjit.cuda.ad.Float, slant_angle: drjit.cuda.ad.Float) → Tuple[drjit.cuda.ad.Complex2f, drjit.cuda.ad.Complex2f][source]#

Model-2 for polarized antennas from 3GPP TR 38.901 [TR38901_RT]

Transforms a vertically polarized antenna pattern \(\tilde{C}_\theta(\theta, \varphi)\) into a linearly polarized pattern whose direction is specified by a slant angle \(\zeta\). For example, \(\zeta=0\) and \(\zeta=\pi/2\) correspond to vertical and horizontal polarization, respectively, and \(\zeta=\pm \pi/4\) to a pair of cross polarized antenna elements.

The transformed antenna pattern is given by (7.3-4/5) [TR38901_RT]:

\[\begin{split}\begin{aligned} \begin{bmatrix} C_\theta(\theta, \varphi) \\ C_\varphi(\theta, \varphi) \end{bmatrix} &= \begin{bmatrix} \cos(\zeta) \\ \sin(\zeta) \end{bmatrix} \tilde{C}_\theta(\theta, \varphi) \end{aligned}\end{split}\]
Parameters:
Returns:

Zenith (\(C_\theta\)) and azimuth (\(C_\phi\)) pattern

Utility Functions#

sionna.rt.antenna_pattern.antenna_pattern_to_world_implicit(pattern: Callable[[drjit.cuda.ad.Float, drjit.cuda.ad.Float], Tuple[drjit.cuda.ad.Complex2f, drjit.cuda.ad.Complex2f]], to_world: drjit.cuda.ad.Matrix3f, k_world: mitsuba.Vector3f, direction: str) → mitsuba.Vector4f[source]#

Evaluates an antenna pattern for a given direction and returns it in the world implicit basis

For a given direction in the world frame, this function first obtains the local zenith and azimuth angles \(\theta\) and \(\phi\) of the antenna. Then, the antenna pattern is evaluated to obtain the complex-valued zenith and azimuth patterns \(C_\theta\) and \(C_\phi\), respectively. Both are then transformed into the real-valued vectors

\[ \begin{align}\begin{aligned}\begin{split}\mathbf{f}_\text{real} = \begin{bmatrix} \Re\{C_\theta(\theta,\phi)\} \\ \Re\{C_\phi(\theta,\phi)\} \end{bmatrix}\end{split}\\\begin{split}\mathbf{f}_\text{imag} = \begin{bmatrix} \Im\{C_\theta(\theta,\phi)\} \\ \Im\{C_\phi(\theta,\phi)\} \end{bmatrix}.\end{split}\end{aligned}\end{align} \]

The final output is obtained by applying a to-world rotation matrix \(\mathbf{W}\) to both vectors before they are stacked:

\[\begin{split}\mathbf{v}_\text{out} = \begin{bmatrix} \mathbf{W} \mathbf{f}_\text{real}\\ \mathbf{W} \mathbf{f}_\text{imag} \end{bmatrix}.\end{split}\]

The parameter direction indicates the direction of propagation of the transverse wave with respect to the antenna, i.e., away from the antenna (direction = “out”) or towards the antenna (direction = “in”). If the wave propagates towards the antenna, then the evaluated antenna pattern is rotated to be represented in the world frame.

Parameters:
Returns:

Antenna pattern in the world implicit basis as a real-valued vector

sionna.rt.antenna_pattern.complex2real_antenna_pattern(c_theta: drjit.cuda.ad.Complex2f, c_phi: drjit.cuda.ad.Complex2f) → Tuple[mitsuba.Vector2f, mitsuba.Vector2f][source]#

Converts a complex-valued antenna pattern to a real-valued representation

Parameters:
Returns:

Tuple of the real and imaginary parts of the zenith and azimuth antenna patterns

sionna.rt.register_antenna_pattern(name: str, pattern_factory: Callable[[...], sionna.rt.antenna_pattern.AntennaPattern])[source]#

Registers a new factory method for an antenna pattern

Parameters:
sionna.rt.register_polarization(name: str, slant_angles: List[float])[source]#

Registers a new polarization

A polarization is defined as a list of one or two slant angles that will be applied to a vertically polarized antenna pattern function to create the desired polarization directions.

Parameters:

  • name (str) – Name of the polarization

  • slant_angles (List[float]) – List of one or two slant angles

sionna.rt.register_polarization_model(name: str, model: Callable[[drjit.cuda.ad.Complex2f, drjit.cuda.ad.Float, drjit.cuda.ad.Float, drjit.cuda.ad.Float], Tuple[drjit.cuda.ad.Complex2f, drjit.cuda.ad.Complex2f]])[source]#

Registers a new polarization model

A polarization model uses a slant angle to transform a vertically polarized antenna pattern into an arbitrarily rotated linearly polarized antenna pattern

Parameters: