Utility Functions

Complex-valued tensors

sionna.rt.utils.cpx_abs(x)

Element-wise absolute value of a complex-valued tensor

The tensor is represented as a tuple of two real-valued tensors, corresponding to the real and imaginary part, respectively.

Parameters:

x (typing.Tuple[drjit.cuda.ad.TensorXf, drjit.cuda.ad.TensorXf]) – A tensor

Return type:

drjit.cuda.ad.TensorXf

sionna.rt.utils.cpx_abs_square(x)

Element-wise absolute squared value of a complex-valued tensor

The tensor is represented as a tuple of two real-valued tensors, corresponding to the real and imaginary part, respectively.

Parameters:

x (typing.Tuple[drjit.cuda.ad.TensorXf, drjit.cuda.ad.TensorXf]) – A tensor

Return type:

drjit.cuda.ad.TensorXf

sionna.rt.utils.cpx_add(a, b)

Element-wise addition of two complex-valued tensors

Each tensor is represented as a tuple of two real-valued tensors, corresponding to the real and imaginary part, respectively.

Parameters:

• a (typing.Tuple[drjit.cuda.ad.TensorXf, drjit.cuda.ad.TensorXf]) – First tensor

• b (typing.Tuple[drjit.cuda.ad.TensorXf, drjit.cuda.ad.TensorXf]) – Second tensor

Return type:

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

sionna.rt.utils.cpx_convert(x, out_type)

Converts a complex-valued tensor to any of the supported frameworks

The tensor is represented as a tuple of two real-valued tensors, corresponding to the real and imaginary part, respectively.

Note that the chosen framework must be installed for this function to work.

Parameters:

• x (typing.Tuple[drjit.cuda.ad.TensorXf, drjit.cuda.ad.TensorXf]) – A tensor

• out_type (typing.Literal['numpy', 'jax', 'tf', 'torch']) – Name of the target framework. Currently supported are Numpy (“numpy”), Jax (“jax”), TensorFlow (“tf”), and PyTorch (“torch”).

Return type:

np.array | jax.array | tf.Tensor | torch.tensor

sionna.rt.utils.cpx_div(a, b)

Element-wise division of a complex-valued tensor by another

Each tensor is represented as a tuple of two real-valued tensors, corresponding to the real and imaginary part, respectively.

Parameters:

• a (typing.Tuple[drjit.cuda.ad.TensorXf, drjit.cuda.ad.TensorXf]) – First tensor

• b (typing.Tuple[drjit.cuda.ad.TensorXf, drjit.cuda.ad.TensorXf]) – Second tensor by which the first is divided

Return type:

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

sionna.rt.utils.cpx_exp(x)

Element-wise exponential of a complex-valued tensor

The tensor is represented as a tuple of two real-valued tensors, corresponding to the real and imaginary part, respectively.

Parameters:

x (typing.Tuple[drjit.cuda.ad.TensorXf, drjit.cuda.ad.TensorXf]) – A tensor

Return type:

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

sionna.rt.utils.cpx_mul(a, b)

Element-wise multiplication of two complex-valued tensors

Each tensor is represented as a tuple of two real-valued tensors, corresponding to the real and imaginary part, respectively.

Parameters:

• a (typing.Tuple[drjit.cuda.ad.TensorXf, drjit.cuda.ad.TensorXf]) – First tensor

• b (typing.Tuple[drjit.cuda.ad.TensorXf, drjit.cuda.ad.TensorXf]) – Second tensor

Return type:

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

sionna.rt.utils.cpx_sqrt(x)

Element-wise square root of a complex-valued tensor

The tensor is represented as a tuple of two real-valued tensors, corresponding to the real and imaginary part, respectively.

The following formula is implemented to compute the square roots of complex numbers: https://en.wikipedia.org/wiki/Square_root#Algebraic_formula

Parameters:

x (typing.Tuple[drjit.cuda.ad.TensorXf, drjit.cuda.ad.TensorXf]) – A tensor

Return type:

drjit.cuda.ad.TensorXf

sionna.rt.utils.cpx_sub(a, b)

Element-wise substraction of a complex-valued tensor from another

Each tensor is represented as a tuple of two real-valued tensors, corresponding to the real and imaginary part, respectively.

Parameters:

• a (typing.Tuple[drjit.cuda.ad.TensorXf, drjit.cuda.ad.TensorXf]) – First tensor

• b (typing.Tuple[drjit.cuda.ad.TensorXf, drjit.cuda.ad.TensorXf]) – Second tensor which is substracted from the first

Return type:

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

Electromagnetics

sionna.rt.utils.complex_relative_permittivity(eta_r, sigma, omega)

Computes the complex relative permittivity of a material as defined in (9)

Parameters:

• eta_r (drjit.cuda.ad.Float) – Real component of the relative permittivity

• sigma (drjit.cuda.ad.Float) – Conductivity [S/m]

• omega (drjit.cuda.ad.Float) – Angular frequency [rad/s]

Return type:

drjit.cuda.ad.Complex2f

sionna.rt.utils.fresnel_reflection_coefficients_simplified(cos_theta, eta)

Computes the Fresnel transverse electric and magnetic reflection coefficients assuming an incident wave propagating in vacuum (34)

Parameters:

• cos_theta (drjit.cuda.ad.Float) – Cosine of the angle of incidence

• eta (drjit.cuda.ad.Complex2f) – Complex-valued relative permittivity of the medium upon which the wave is incident

Return type:

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

Returns:

Transverse electric $r_{\perp }$ and magnetic $r_{\parallel }$ Fresnel reflection coefficients

sionna.rt.utils.itu_coefficients_single_layer_slab(cos_theta, eta, d, wavelength)

Computes the single-layer slab Fresnel transverse electric and magnetic reflection and refraction coefficients assuming the incident wave propagates in vacuum using recommendation ITU-R P.2040 [ITU_R_2040_3]

More precisely, this function implements equations (43) and (44) from [ITU_R_2040_3].

Parameters:

• cos_theta (drjit.cuda.ad.Float) – Cosine of the angle of incidence

• eta (drjit.cuda.ad.Complex2f) – Complex-valued relative permittivity of the medium upon which the wave is incident

• d (drjit.cuda.ad.Float) – Thickness of the slab [m]

• wavelength (drjit.cuda.ad.Float) – Wavelength [m]

Return type:

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

Returns:

Transverse electric reflection coefficient $R_{eTE}$, transverse magnetic reflection coefficient $R_{eTM}$, transverse electric refraction coefficient $T_{eTE}$, and transverse magnetic refraction coefficient $T_{eTM}$

Geometry

sionna.rt.utils.phi_hat(phi)

Computes the spherical unit vector $\hat{\mathit{\phi }}(\theta ,\phi )$ as defined in (1)

Parameters:

phi (drjit.cuda.ad.Float) – Azimuth angle $\phi$ [rad]

Return type:

mitsuba.Vector3f

sionna.rt.utils.theta_hat(theta, phi)

Computes the spherical unit vector $\hat{\mathit{\theta }}(\theta ,\phi )$ as defined in (1)

Parameters:

• theta (drjit.cuda.ad.Float) – Zenith angle $\theta$ [rad]

• phi (drjit.cuda.ad.Float) – Azimuth angle $\phi$ [rad]

Return type:

mitsuba.Vector3f

sionna.rt.utils.r_hat(theta, phi)

Computes the spherical unit vetor $\hat{\mathbf{r}}(\theta ,\varphi )$ as defined in (1)

Parameters:

• theta (drjit.cuda.ad.Float) – Zenith angle $\theta$ [rad]

• phi (drjit.cuda.ad.Float) – Azimuth angle $\phi$ [rad]

Return type:

mitsuba.Vector3f

sionna.rt.utils.theta_phi_from_unit_vec(v)

Computes zenith and azimuth angles ($\theta ,\phi$) from unit-norm vectors as described in (2)

Parameters:

v (mitsuba.Vector3f) – Unit vector

Return type:

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

Returns:

Zenith angle $\theta$ [rad] and azimuth angle $\phi$ [rad]

sionna.rt.utils.rotation_matrix(angles)

Computes the rotation matrix as defined in (3)

The closed-form expression in (7.1-4) [TR38901] is used.

Parameters:

angles (mitsuba.Point3f) – Angles for the rotations $(\alpha ,\beta ,\gamma )$ [rad] that define rotations about the axes $(z,y,x)$, respectively

Return type:

drjit.cuda.ad.Matrix3f

Jones calculus

sionna.rt.utils.implicit_basis_vector(k)

Returns a reference frame basis vector for a Jones vector, representing a transverse wave propagating in direction k

The spherical basis vector $\hat{\mathit{\theta }}(\theta ,\phi )$ (1) is used as basis vector, where the zenith and azimuth angles are obtained from the unit vector k.

Parameters:

k (mitsuba.Vector3f) – A unit vector corresponding to the direction of propagation of a transverse wave

Return type:

mitsuba.Vector3f

Returns:

A basis vector orthogonal to k

sionna.rt.utils.jones_matrix_rotator(k, s_current, s_target)

Constructs the 2D change-of-basis matrix to rotate the reference frame of a Jones vector representing a transverse wave propagating in direction k from basis vector s_current to basis vector s_target

Parameters:

• k (mitsuba.Vector3f) – Direction of propagation as a unit vector

• s_current (mitsuba.Vector3f) – Current basis vector as a unit vector

• s_target (mitsuba.Vector3f) – Target basis vector as a unit vector

Return type:

drjit.cuda.ad.Matrix2f

sionna.rt.utils.jones_matrix_rotator_flip_forward(k)

Constructs the 2D change-of-basis matrix that flips the direction of propagation of the reference frame of a Jones vector representing a transverse wave from the basis vector corresponding to k to the one corresponding to -k

This is useful to evaluate the antenna pattern of a receiver, as the pattern needs to be rotated to match the frame in which the incident wave is represented.

Note that the rotation matrix returned by this function is a diagonal matrix:

$$\begin{array}{r}\mathbf{R}=\left[\begin{array}{c}\begin{array}{cc}c& 0\\ 0& -c\end{array}\end{array}\right]\end{array}$$

where:

$$c={{\mathbf{s}}_{\mathbf{c}}}^{\mathsf{\text{T}}}{\mathbf{s}}_{\mathbf{t}}$$

and ${\mathbf{s}}_{\mathbf{c}}$ and ${\mathbf{s}}_{\mathbf{t}}$ are the basis vectors corresponding to k and -k, respectively, and computed using implicit_basis_vector().

Parameters:

k (mitsuba.Vector3f) – Current direction of propagation as a unit vector

Return type:

drjit.cuda.ad.Matrix2f

sionna.rt.utils.to_world_jones_rotator(to_world, k_local)

Constructs the 2D change-of-basis matrix to rotate the reference frame of a Jones vector representing a transverse wave with k_local as direction of propagation from the local implicit frame to the world implicit frame

Parameters:

• to_world (drjit.cuda.ad.Matrix3f) – Change-of-basis matrix from the local to the world frame

• k_local (mitsuba.Vector3f) – Direction of propagation in the local frame as a unit vector

Return type:

drjit.cuda.ad.Matrix2f

sionna.rt.utils.jones_matrix_to_world_implicit(c1, c2, to_world, k_in_local, k_out_local)

Builds the Jones matrix that models a specular reflection or a refraction

c1 and c2 are Fresnel coefficients that depend on the composition of the scatterer. k_in_local and k_out_local are the direction of propagation of the incident and scattered wave, respectively, represented in the local frame of the interaction. Note that in the local frame of the interaction, the z-axis vector corresponds to the normal to the scatterer surface at the interaction point.

The returned matrix operates on the incident wave represented in the implicit world frame. The resulting scattered wave is also represented in the implicit world frame. This is ensured by applying a left and right rotation matrix to the 2x2 diagonal matrix containing the Fresnel coefficients, which operates on the local frame having the transverse electric component as basis vector:

$$\mathbf{J}={\mathbf{R}}_{\mathbf{O}}\mathbf{D}{{\mathbf{R}}_{\mathbf{I}}}^{\mathsf{\text{T}}}$$

where:

$$\begin{array}{r}\mathbf{D}=\left[\begin{array}{c}\begin{array}{cc}\mathtt{\text{c1}}& 0\\ 0& \mathtt{\text{c2}}\end{array}\end{array}\right]\end{array}$$

and ${\mathbf{R}}_{\mathbf{I}}$ (${\mathbf{R}}_{\mathbf{O}}$) is the change-of-basis matrix from the local frame using the transverse electric direction as basis vector to the world implicit frame for the incident (scattered) wave.

This function returns the $4\times 4$ real-valued matrix equivalent to $\mathbf{J}$:

$$\begin{array}{r}\mathbf{M}=\left[\begin{array}{c}\begin{array}{cc}\mathrm{\Re }\{\mathbf{J}\}& -\mathrm{\Im }\{\mathbf{J}\}\\ \mathrm{\Im }\{\mathbf{J}\}& \mathrm{\Re }\{\mathbf{J}\}\end{array}\end{array}\right]\end{array}$$

where $\mathbf{M}$ is the returned matrix and $\mathrm{\Re }\{\mathbf{J}\}$ and $\mathrm{\Im }\{\mathbf{J}\}$ the real and imaginary components of $\mathbf{J}$, respectively.

Parameters:

• c1 (drjit.cuda.ad.Complex2f) – First complex-valued Fresnel coefficient

• c2 (drjit.cuda.ad.Complex2f) – Second complex-valued Fresnel coefficient

• to_world (drjit.cuda.ad.Matrix3f) – Change-of-basis matrix from the local to the world frame

• k_in_local (mitsuba.Vector3f) – Direction of propagation of the incident wave in the local frame as a unit vector

• k_out_local (mitsuba.Vector3f) – Direction of propagation of the scattered wave in the local frame as a unit vector

Return type:

drjit.cuda.ad.Matrix4f

sionna.rt.utils.jones_vec_dot(u, v)

Computes the dot product of two Jones vectors $\mathbf{u}$ and $\mathbf{v}$

A Jones vector is assumed to be represented by a real-valued vector of four dimensions, obtained by concatenating its real and imaginary components. The returned array is complex-valued.

More precisely, the following formula is implemented:

$$\begin{gathered} \begin{array}{r}\begin{array}{c}a={\mathbf{u}}^{\mathsf{\text{H}}}\mathbf{v}\hfill \\ =(\mathrm{\Re }\{\mathbf{u}{\}}^{\mathsf{\text{T}}}\mathrm{\Re }\{\mathbf{v}\} \\ +\mathrm{\Im }\{\mathbf{u}{\}}^{\mathsf{\text{T}}}\mathrm{\Im }\{\mathbf{v}\})\\ +j(\mathrm{\Re }\{\mathbf{u}{)}^{\mathsf{\text{T}}}\mathrm{\Im }\{\mathbf{v}\} \\ -\mathrm{\Im }\{\mathbf{u}{\}}^{\mathsf{\text{T}}}\mathrm{\Re }\{\mathbf{v}\})\end{array}\end{array} \end{gathered}$$

Parameters:

• u (mitsuba.Vector4f) – First input vector

• v (mitsuba.Vector4f) – Second input vector

Return type:

drjit.cuda.ad.Complex2f

Miscellaneous

sionna.rt.utils.complex_sqrt(x)

Computes the square root of a complex number $x$

The following formula is implemented to compute the square roots of complex numbers: https://en.wikipedia.org/wiki/Square_root#Algebraic_formula

Parameters:

x (drjit.cuda.ad.Complex2f) – Complex number

Return type:

drjit.cuda.ad.Complex2f

sionna.rt.utils.dbm_to_watt(x)

Converts dBm to Watt

Implements the following formula:

$$P_W={10}^{\frac{P_{dBm}-30}{10}}$$

Parameters:

x (drjit.cuda.ad.Float) – Power [dBm]

Return type:

drjit.cuda.ad.Float

sionna.rt.utils.isclose(a, b, rtol=1e-05, atol=1e-08)

Returns an array of boolean in which an element is set to True if the corresponding entries in a and b are equal within a tolerance

More precisely, this function returns True for the $i^{th}$ element if:

$$|\mathtt{\text{a}}[i]-\mathtt{\text{b}}[i]|<\mathtt{\text{atol}}+\mathtt{\text{rtol}}\cdot \mathtt{\text{b}}[i]$$

Parameters:

• a (drjit.cuda.ad.Float) – First input array to compare

• b (drjit.cuda.ad.Float) – Second input array to compare

• rtol (drjit.cuda.ad.Float) – Relative error threshold

• atol (drjit.cuda.ad.Float) – Absolute error threshold

Return type:

drjit.cuda.ad.Bool

sionna.rt.utils.log10(x)

Evaluates the base-10 logarithm

Parameters:

x (drjit.cuda.ad.Float) – Input value

Return type:

drjit.cuda.ad.Float

sionna.rt.utils.sigmoid(x)

Evaluates the sigmoid of x

Parameters:

x (drjit.cuda.ad.Float) – Input value

Return type:

drjit.cuda.ad.Float

sionna.rt.utils.sinc(x)

Evaluates the normalized sinc function

The sinc function is defined as $\sin (\pi x)/(\pi x)$ for any $x\ne 0$ and equals $0$ for $x=0$.

Return type:

drjit.cuda.ad.Float

Parameters:

x (Float)

sionna.rt.utils.subcarrier_frequencies(num_subcarriers, subcarrier_spacing)

Compute the baseband frequencies of num_subcarrier subcarriers spaced by subcarrier_spacing, i.e.,

>>> # If num_subcarrier is even:
>>> frequencies = [-num_subcarrier/2, ..., 0, ..., num_subcarrier/2-1] * subcarrier_spacing
>>>
>>> # If num_subcarrier is odd:
>>> frequencies = [-(num_subcarrier-1)/2, ..., 0, ..., (num_subcarrier-1)/2] * subcarrier_spacing

Parameters:

• num_subcarriers (int) – Number of subcarriers

• subcarrier_spacing (float) – Subcarrier spacing [Hz]

Return type:

drjit.cuda.ad.Float

Returns:

Baseband frequencies of subcarriers

sionna.rt.utils.watt_to_dbm(x)

Converts Watt to dBm

Implements the following formula:

$$P_{dBm}=30+10{\log }_{10}(P_W)$$

Parameters:

x (drjit.cuda.ad.Float) – Power [W]

Return type:

drjit.cuda.ad.Float

Ray tracing

sionna.rt.utils.fibonacci_lattice(num_points)

Generates a Fibonacci lattice of size num_points on the unit square $[0,1]\times [0,1]$

Parameters:

num_points (int) – Size of the lattice

Return type:

mitsuba.Point2f

sionna.rt.utils.spawn_ray_from_sources(lattice, samples_per_src, src_positions)

Spawns samples_per_src rays for each source at the positions specified by src_positions, oriented in the directions defined by the lattice

The spawned rays are ordered samples-first.

Parameters:

• lattice (typing.Callable[[int], mitsuba.Point2f]) – Callable that generates the lattice used as directions for the rays

• samples_per_src (int) – Number of rays per source to spawn

• src_positions (mitsuba.Point3f) – Positions of the sources

Return type:

mitsuba.Ray3f

sionna.rt.utils.offset_p(p, d, n)

Adds a small offset to $\mathbf{p}$ along $\mathbf{n}$ such that ${\mathbf{n}}^{\mathsf{\text{T}}}\mathbf{d}>0$

More precisely, this function returns $\mathbf{o}$ such that:

$$\mathbf{o}=\mathbf{p}+ϵ(1+max\{|p_x|,|p_y|,|p_z|\})\mathtt{\text{sign}}(\mathbf{d}\cdot \mathbf{n})\mathbf{n}$$

where $ϵ$ depends on the numerical precision and $\mathbf{p}=(p_x,p_y,p_z)$.

Parameters:

• p (mitsuba.Point3f) – Point to offset

• d (mitsuba.Vector3f) – Direction toward which to offset along n

• n (mitsuba.Vector3f) – Direction along which to offset

Return type:

mitsuba.Point3f

sionna.rt.utils.spawn_ray_towards(p, t, n=None)

Spawns a ray with infinite length from $\mathbf{p}$ toward $\mathbf{t}$

If $\mathbf{n}$ is not None, then a small offset is added to $\mathbf{p}$ along $\mathbf{n}$ in the direction of $\mathbf{t}$.

Parameters:

• p (mitsuba.Point3f) – Origin of the ray

• t (mitsuba.Point3f) – Point towards which to spawn the ray

• n (typing.Optional[mitsuba.Vector3f]) – (Optional) Direction along which to offset $\mathbf{p}$

Return type:

mitsuba.Ray3f

sionna.rt.utils.spawn_ray_to(p, t, n=None)

Spawns a finite ray from $\mathbf{p}$ to $\mathbf{t}$

The length of the ray is set to $\Vert \mathbf{p}-\mathbf{t}\Vert$.

If $\mathbf{n}$ is not None, then a small offset is added to $\mathbf{p}$ along $\mathbf{n}$ in the direction of $\mathbf{t}$.

Parameters:

• p (mitsuba.Point3f) – Origin of the ray

• t (mitsuba.Point3f) – Point towards which to spawn the ray

• n (typing.Optional[mitsuba.Vector3f]) – (Optional) Direction along which to offset $\mathbf{p}$

Return type:

mitsuba.Ray3f

References:

[ITU_R_2040_3]

Recommendation ITU-R P.2040-3, “Effects of building materials and structures on radiowave propagation above about 100 MHz”

[TR38901]

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