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 ,\phi )\mapsto (C_{\theta }(\theta ,\phi ),C_{\phi }(\theta ,\phi ))$ that maps a pair of zenith and azimuth angles to zenith and azimuth pattern values.

class sionna.rt.AntennaPattern

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.

compute_gain(polarization_direction=0, num_samples=1000, verbose=True)

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

Given a function $f:(\theta ,\phi )\mapsto (C_{\theta }(\theta ,\phi ),C_{\phi }(\theta ,\phi ))$ 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.

Return type:

typing.Tuple[drjit.cuda.ad.Float, drjit.cuda.ad.Float, drjit.cuda.ad.Float]

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

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]]]

show(polarization_direction=0)

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)

Return type:

typing.Tuple[matplotlib.figure.Figure, matplotlib.figure.Figure, matplotlib.figure.Figure]

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()

class sionna.rt.PolarizedAntennaPattern(*, v_pattern, polarization, polarization_model='tr38901_2')

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

Parameters:

• v_pattern (typing.Callable[[drjit.cuda.ad.Float, drjit.cuda.ad.Float], drjit.cuda.ad.Complex2f]) – Vertically polarized antenna pattern function

• polarization (str) – Name of registered polarization (“V” | “H” | “VH” | “cross”)

• polarization_model (str) – Name of registered polarization model (“tr38901_1” | “tr38901_2”)

compute_gain(polarization_direction=0, num_samples=1000, verbose=True)

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

Given a function $f:(\theta ,\phi )\mapsto (C_{\theta }(\theta ,\phi ),C_{\phi }(\theta ,\phi ))$ 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.

Return type:

typing.Tuple[drjit.cuda.ad.Float, drjit.cuda.ad.Float, drjit.cuda.ad.Float]

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

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]]]

show(polarization_direction=0)

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)

Return type:

typing.Tuple[matplotlib.figure.Figure, matplotlib.figure.Figure, matplotlib.figure.Figure]

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()

Vertically Polarized Antenna Pattern Functions

sionna.rt.antenna_pattern.v_iso_pattern(theta, phi)

Vertically polarized isotropic antenna pattern function

Parameters:

• theta (drjit.cuda.ad.Float) – Elevation angle [rad]

• phi (drjit.cuda.ad.Float) – Elevation angle [rad]

Return type:

drjit.cuda.ad.Complex2f

sionna.rt.antenna_pattern.v_dipole_pattern(theta, phi)

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

Parameters:

• theta (drjit.cuda.ad.Float) – Elevation angle [rad]

• phi (drjit.cuda.ad.Float) – Elevation angle [rad]

Return type:

drjit.cuda.ad.Complex2f

sionna.rt.antenna_pattern.v_hw_dipole_pattern(theta, phi)

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

Parameters:

• theta (drjit.cuda.ad.Float) – Elevation angle [rad]

• phi (drjit.cuda.ad.Float) – Elevation angle [rad]

Return type:

drjit.cuda.ad.Complex2f

sionna.rt.antenna_pattern.v_tr38901_pattern(theta, phi)

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

Parameters:

• theta (drjit.cuda.ad.Float) – Elevation angle [rad]

• phi (drjit.cuda.ad.Float) – Elevation angle [rad]

Return type:

drjit.cuda.ad.Complex2f

Polarization Models

sionna.rt.antenna_pattern.polarization_model_tr38901_1(c_theta_tilde, theta, phi, slant_angle)

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

Transforms a vertically polarized antenna pattern ${\tilde{C}}_{\theta }(\theta ,\phi )$ 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]:

$$\begin{array}{r}\begin{array}{rl}\left[\begin{array}{c}{C}_{\theta }(\theta ,\phi )\\ C_{\phi }(\theta ,\phi )\end{array}\right]& =\left[\begin{array}{c}\cos (\psi )\\ \sin (\psi )\end{array}\right]{\tilde{C}}_{\theta }(\theta ,\phi )\\ \cos (\psi )& =\frac{\cos (\zeta )\sin (\theta )+\sin (\zeta )\sin (\phi )\cos (\theta )}{\sqrt{1-{(\cos (\zeta )\cos (\theta )-\sin (\zeta )\sin (\phi )\sin (\theta ))}^2}}\\ \sin (\psi )& =\frac{\sin (\zeta )\cos (\phi )}{\sqrt{1-{(\cos (\zeta )\cos (\theta )-\sin (\zeta )\sin (\phi )\sin (\theta ))}^2}}\end{array}\end{array}$$

Parameters:

• c_theta_tilde (drjit.cuda.ad.Complex2f) – Vertically polarized zenith pattern ${\tilde{C}}_{\theta }(\theta ,\phi )$

• theta (drjit.cuda.ad.Float) – Zenith angles [rad]

• phi (drjit.cuda.ad.Float) – Azimuth angles [rad]

• slant_angle (drjit.cuda.ad.Float) – Slant angle of the linear polarization [rad]. A slant angle of zero means vertical polarization.

Return type:

typing.Tuple[drjit.cuda.ad.Complex2f, drjit.cuda.ad.Complex2f]

Returns:

Zenith ($C_{\theta }$) and azimuth ($C_{\varphi }$) pattern

sionna.rt.antenna_pattern.polarization_model_tr38901_2(c_theta_tilde, theta, phi, slant_angle)

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

Transforms a vertically polarized antenna pattern ${\tilde{C}}_{\theta }(\theta ,\phi )$ 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]:

$$\begin{array}{r}\begin{array}{rl}\left[\begin{array}{c}{C}_{\theta }(\theta ,\phi )\\ C_{\phi }(\theta ,\phi )\end{array}\right]& =\left[\begin{array}{c}\cos (\zeta )\\ \sin (\zeta )\end{array}\right]{\tilde{C}}_{\theta }(\theta ,\phi )\end{array}\end{array}$$

Parameters:

• c_theta_tilde (drjit.cuda.ad.Complex2f) – Vertically polarized zenith pattern ${\tilde{C}}_{\theta }(\theta ,\phi )$

• theta (drjit.cuda.ad.Float) – Zenith angles [rad]

• phi (drjit.cuda.ad.Float) – Azimuth angles [-pi, pi) [rad]

• slant_angle (drjit.cuda.ad.Float) – Slant angle of the linear polarization [rad]. A slant angle of zero means vertical polarization.

Return type:

typing.Tuple[drjit.cuda.ad.Complex2f, drjit.cuda.ad.Complex2f]

Returns:

Zenith ($C_{\theta }$) and azimuth ($C_{\varphi }$) pattern

Utility Functions

sionna.rt.antenna_pattern.antenna_pattern_to_world_implicit(pattern, to_world, k_world, direction)

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 $\varphi$ of the antenna. Then, the antenna pattern is evaluated to obtain the complex-valued zenith and azimuth patterns $C_{\theta }$ and $C_{\varphi }$, respectively. Both are then transformed into the real-valued vectors

$$\begin{array}{r}\begin{array}{c}\begin{array}{c}{\mathbf{f}}_{\text{real}}=\left[\begin{array}{c}\mathrm{\Re }\{C_{\theta }(\theta ,\varphi )\}\\ \mathrm{\Re }\{C_{\varphi }(\theta ,\varphi )\}\end{array}\right]\end{array}\\ \begin{array}{c}{\mathbf{f}}_{\text{imag}}=\left[\begin{array}{c}\mathrm{\Im }\{C_{\theta }(\theta ,\varphi )\}\\ \mathrm{\Im }\{C_{\varphi }(\theta ,\varphi )\}\end{array}\right].\end{array}\end{array}\end{array}$$

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

$$\begin{array}{r}{\mathbf{v}}_{\text{out}}=\left[\begin{array}{c}\mathbf{W}{\mathbf{f}}_{\text{real}}\\ \mathbf{W}{\mathbf{f}}_{\text{imag}}\end{array}\right].\end{array}$$

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:

• pattern (typing.Callable[[drjit.cuda.ad.Float, drjit.cuda.ad.Float], typing.Tuple[drjit.cuda.ad.Complex2f, drjit.cuda.ad.Complex2f]]) – Antenna pattern

• to_world (drjit.cuda.ad.Matrix3f) – To-world rotation matrix

• k_world (mitsuba.Vector3f) – Direction in which to evaluate the antenna pattern in the world frame

• direction (str) – Direction of propagation with respect to the antenna (“in” | “out”)

Return type:

mitsuba.Vector4f

Returns:

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

sionna.rt.antenna_pattern.complex2real_antenna_pattern(c_theta, c_phi)

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

Parameters:

• c_theta (drjit.cuda.ad.Complex2f) – Zenith antenna pattern

• c_phi (drjit.cuda.ad.Complex2f) – Azimuth antenna pattern

Return type:

typing.Tuple[mitsuba.Vector2f, mitsuba.Vector2f]

Returns:

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

sionna.rt.register_antenna_pattern(name, pattern_factory)

Registers a new factory method for an antenna pattern

Parameters:

• name (str) – Name of the factory method

• pattern_factory (typing.Callable[..., sionna.rt.antenna_pattern.AntennaPattern]) – A factory method returning an instance of AntennaPattern

sionna.rt.register_polarization(name, slant_angles)

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 (typing.List[float]) – List of one or two slant angles

sionna.rt.register_polarization_model(name, model)

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:

• name (str) – Name of the polarization model

• model (typing.Callable[[drjit.cuda.ad.Complex2f, drjit.cuda.ad.Float, drjit.cuda.ad.Float, drjit.cuda.ad.Float], typing.Tuple[drjit.cuda.ad.Complex2f, drjit.cuda.ad.Complex2f]]) – Polarization model

References:

[Balanis97] (1,2)

A. Balanis, “Antenna Theory: Analysis and Design,” 2nd Edition, John Wiley & Sons, 1997.

[TR38901] (1,2,3,4,5)

3GPP TR 38.901, “Study on channel model for frequencies from 0.5 to 100 GHz”, Release 18.0