Antenna Patterns
We refer the user to the section “Far Field of a Transmitting Antenna” for various usefuldefinitions and background on antenna modeling. AnAntennaPattern can be single- ordual-polarized and might have for each polarization direction a possiblydifferent pattern. One can think of a dual-polarized pattern as two colocatedlinearly 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.
- classsionna.rt.AntennaPattern[source]
Abstract class for antenna patterns
Any instance of this class must implement the
patternsproperty which returns a list of one or two antenna patternsfor single- or dual-polarized antennas, respectively.- compute_gain(polarization_direction=0,num_samples=1000,verbose=True)[source]
Computes directivity, gain, and radiation efficiency of the antennapattern 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 thedirectivity\(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 stepsfor numerical integrationverbose (
bool) – IfTrue, 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
fromsionna.rtimportPlanarArrayarray=PlanarArray(num_rows=1,num_cols=1,pattern="tr38901",polarization="V")d,g,eta=array.antenna_pattern.compute_gain();
Directivity[dB]:9.825768560205825Gain[dB]:7.99998570013805Efficiency[%]:65.67826867103577
- propertypatterns
List of antenna patterns for one or two polarization directions.The pattern of a specific polarization direction can be also accessed byindexing the antenna pattern instance.
- Type:
List[Callable[[mitsuba.Float,mitsuba.Float],Tuple[mitsuba.Complex2f,mitsuba.Complex2f]]]
- show(polarization_direction=0)[source]
Visualizes the antenna gain of the antenna pattern of oneof the polarization directions
This function visualizes the directional antenna gain with the helpof three figures showing the vertical and horizontal cuts as well as athree-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 ofthe antenna gain
Example
fromsionna.rtimportPlanarArrayarray=PlanarArray(num_rows=1,num_cols=1,pattern="dipole",polarization="V")array.antenna_pattern.show()
- classsionna.rt.PolarizedAntennaPattern(*,v_pattern,polarization,polarization_model='tr38901_2')[source]
Transforms avertically polarized antenna pattern functioninto an arbitray single- or dual-polarized antenna patternbased 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 functionpolarization (
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 antennapattern 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 thedirectivity\(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 stepsfor numerical integrationverbose (
bool) – IfTrue, 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
fromsionna.rtimportPlanarArrayarray=PlanarArray(num_rows=1,num_cols=1,pattern="tr38901",polarization="V")d,g,eta=array.antenna_pattern.compute_gain();
Directivity[dB]:9.825768560205825Gain[dB]:7.99998570013805Efficiency[%]:65.67826867103577
- propertypatterns
List of antenna patterns for one or two polarization directions.The pattern of a specific polarization direction can be also accessed byindexing 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 oneof the polarization directions
This function visualizes the directional antenna gain with the helpof three figures showing the vertical and horizontal cuts as well as athree-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 ofthe antenna gain
Example
fromsionna.rtimportPlanarArrayarray=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)[source]
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)[source]
Vertically polarized short dipole antenna pattern functionfrom (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)[source]
Vertically polarized half-wavelength dipole antenna pattern functionfrom (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
Polarization Models
- sionna.rt.antenna_pattern.polarization_model_tr38901_1(c_theta_tilde,theta,phi,slant_angle)[source]
Model-1 for polarized antennas from 3GPP TR 38.901[TR38901]
Transforms a vertically polarized antenna pattern\(\tilde{C}_\theta(\theta, \varphi)\)into a linearly polarized pattern whose directionis specified by a slant angle\(\zeta\). For example,\(\zeta=0\) and\(\zeta=\pi/2\) correspondto vertical and horizontal polarization, respectively,and\(\zeta=\pm \pi/4\) to a pair of cross polarizedantenna elements.
The transformed antenna pattern is given by (7.3-3)[TR38901]:
\[\begin{split}\begin{align} \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{align}\end{split}\]- Parameters:
c_theta_tilde (
drjit.cuda.ad.Complex2f) – Vertically polarized zenith pattern\(\tilde{C}_\theta(\theta, \varphi)\)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_\phi\)) pattern
- sionna.rt.antenna_pattern.polarization_model_tr38901_2(c_theta_tilde,theta,phi,slant_angle)[source]
Model-2 for polarized antennas from 3GPP TR 38.901[TR38901]
Transforms a vertically polarized antenna pattern\(\tilde{C}_\theta(\theta, \varphi)\)into a linearly polarized pattern whose directionis specified by a slant angle\(\zeta\). For example,\(\zeta=0\) and\(\zeta=\pi/2\) correspondto vertical and horizontal polarization, respectively,and\(\zeta=\pm \pi/4\) to a pair of cross polarizedantenna elements.
The transformed antenna pattern is given by (7.3-4/5)[TR38901]:
\[\begin{split}\begin{align} \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{align}\end{split}\]- Parameters:
c_theta_tilde (
drjit.cuda.ad.Complex2f) – Vertically polarized zenith pattern\(\tilde{C}_\theta(\theta, \varphi)\)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_\phi\)) pattern
Utility Functions
- sionna.rt.antenna_pattern.antenna_pattern_to_world_implicit(pattern,to_world,k_world,direction)[source]
Evaluates an antenna pattern for a given direction andreturns it in the world implicit basis
For a given direction in the world frame, this function first obtainsthe local zenith and azimuth angles\(\theta\) and\(\phi\) of the antenna. Then, the antenna patternis evaluated to obtain the complex-valued zenith and azimuth patterns\(C_\theta\) and\(C_\phi\), respectively. Both are thentransformed 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 rotationmatrix\(\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 parameterdirection indicates the direction of propagation of thetransverse wave with respect to the antenna, i.e., away from the antenna(direction = “out”) or towards the antenna (direction = “in”). If thewave propagates towards the antenna, then the evaluated antenna patternis 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 patternto_world (
drjit.cuda.ad.Matrix3f) – To-world rotation matrixk_world (
mitsuba.Vector3f) – Direction in which to evaluate the antenna pattern inthe world framedirection (
str) – Direction of propagation with respectto the antenna (“in” | “out”)
- Return type:
mitsuba.Vector4f- Returns:
Antenna pattern in the world implicit basis as areal-valued vector
- sionna.rt.antenna_pattern.complex2real_antenna_pattern(c_theta,c_phi)[source]
Converts a complex-valued antenna pattern toa real-valued representation
- Parameters:
c_theta (
drjit.cuda.ad.Complex2f) – Zenith antenna patternc_phi (
drjit.cuda.ad.Complex2f) – Azimuth antenna pattern
- Return type:
typing.Tuple[mitsuba.Vector2f,mitsuba.Vector2f]- Returns:
Tuple of the real and imaginaryparts of the zenith and azimuth antenna patterns
- sionna.rt.register_antenna_pattern(name,pattern_factory)[source]
Registers a new factory method for an antenna pattern
- Parameters:
name (
str) – Name of the factory methodpattern_factory (
typing.Callable[...,sionna.rt.antenna_pattern.AntennaPattern]) – A factory method returning an instance ofAntennaPattern
- sionna.rt.register_polarization(name,slant_angles)[source]
Registers a new polarization
A polarization is defined as a list of one or two slant anglesthat will be applied to a vertically polarized antenna patternfunction to create the desired polarization directions.
- Parameters:
name (
str) – Name of the polarizationslant_angles (
typing.List[float]) – List of one or two slant angles
- sionna.rt.register_polarization_model(name,model)[source]
Registers a new polarization model
A polarization model uses a slant angle to transforma vertically polarized antenna pattern into an arbitrarilyrotated linearly polarized antenna pattern
- Parameters:
name (
str) – Name of the polarization modelmodel (
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: