Radio Materials#

A radio material defines how an object scatters incident radio waves. It implements all necessary components to simulate the interaction between radio waves and objects composed of specific materials.

The base class RadioMaterialBase provides an interface for implementing arbitrary radio materials and can be used to implemented custom materials, as detailed in the Developer Guide.

The RadioMaterial class implements the model described in the Primer on Electromagnetics, and supports specular and diffuse reflection as well as refraction. The details of this model are provided thereafter.

Similarly to scene objects (SceneObject), all radio materials are uniquely identified by their name. For example, specifying that a scene object named “wall” is made of the material named “itu-brick” is done as follows:

obj = scene.get("wall") # obj is a SceneObject
obj.radio_material = "itu-brick" # "wall" is made of "itu-brick"

Radio materials provided with Sionna

The class RadioMaterial implements the model described in the Primer on Electromagnetics. Following this model, a radio material consists of the real-valued relative permittivity \(\varepsilon_r\), the conductivity \(\sigma\), and the relative permeability \(\mu_r\). For more details, see (7), (8), (9). These quantities can possibly depend on the frequency of the incident radio wave. Note that this model only allows non-magnetic materials with \(\mu_r=1\).

A radio material has also a thickness \(d\) associated with it which impacts the computation of the reflected and refracted fields (see (35)). For example, a wall is modeled in Sionna RT as a planar surface whose radio material describes the desired thickness.

Additionally, a RadioMaterial can have an effective roughness (ER) associated with it, leading to diffuse reflections (see, e.g., [Degli-Esposti11]). The ER model requires a scattering coefficient \(S\in[0,1]\) (39), a cross-polarization discrimination coefficient \(K_x\) (41), as well as a scattering pattern \(f_\text{s}(\hat{\mathbf{k}}_\text{i}, \hat{\mathbf{k}}_\text{s})\) (42)–(44), such as the LambertianPattern or DirectivePattern. The meaning of these parameters is explained in Scattering.

Sionna provides the ITU models of several materials whose properties are automatically updated according to the configured frequency.

Through the ITURadioMaterial class, Sionna provides the models of all of the materials defined in the ITU-R P.2040-3 recommendation [ITURP20403]. These models are based on curve fitting to measurement results and assume non-ionized and non-magnetic materials (\(\mu_r = 1\)). Frequency dependence is modeled by

\[\begin{split}\begin{aligned} \varepsilon_r &= a f_{\text{GHz}}^b\\ \sigma &= c f_{\text{GHz}}^d \end{aligned}\end{split}\]

where \(f_{\text{GHz}}\) is the frequency in GHz, and the constants \(a\), \(b\), \(c\), and \(d\) characterize the material. The table below provides their values which are used in Sionna (from [ITURP20403]). Note that the relative permittivity \(\varepsilon_r\) and conductivity \(\sigma\) of all materials are updated automatically when the frequency is set through the scene’s property frequency. Moreover, by default, the scattering coefficient, \(S\), of these materials is set to 0, leading to no diffuse reflection.

Material type

Real part of relative permittivity

Conductivity [S/m]

Frequency range (GHz)

a

b

c

d

vacuum

1

0

0

0

0.001 – 100

concrete

5.24

0

0.0462

0.7822

1 – 100

brick

3.91

0

0.0238

0.16

1 – 40

plasterboard

2.73

0

0.0085

0.9395

1 – 100

wood

1.99

0

0.0047

1.0718

0.001 – 100

glass

6.31

0

0.0036

1.3394

0.1 – 100

5.79

0

0.0004

1.658

220 – 450

ceiling_board

1.48

0

0.0011

1.0750

1 – 100

1.52

0

0.0029

1.029

220 – 450

chipboard

2.58

0

0.0217

0.7800

1 – 100

plywood

2.71

0

0.33

0

1 – 40

marble

7.074

0

0.0055

0.9262

1 – 60

floorboard

3.66

0

0.0044

1.3515

50 – 100

metal

1

0

\(10^7\)

0

1 – 100

very_dry_ground

3

0

0.00015

2.52

1 – 10

medium_dry_ground

15

-0.1

0.035

1.63

1 – 10

wet_ground

30

-0.4

0.15

1.30

1 – 10
class sionna.rt.RadioMaterialBase(props: mitsuba.Properties)[source]#

Base class to implement a radio material

This is an abstract class that cannot be instantiated, and serves as interface for defining radio materials.

A radio material defines how an object scatters incident radio waves.

Parameters:

props (mitsuba.Properties) – Property container storing the parameters required to build the material

Methods

eval(ctx: mitsuba.BSDFContext, si: mitsuba.SurfaceInteraction3f, wo: mitsuba.Vector3f, active: bool | drjit.cuda.ad.Bool = True) → mitsuba.Spectrum[source]#

Evaluates the radio material

This function evaluates the Jones matrix of the radio material for the scattered direction wo and for the interaction type stored in si.prim_index.

The following assumptions are made on the inputs:

  • si.wi is the direction of propagation of the incident wave in the world frame

  • si.sh_frame is the frame such that the sh_frame.n is the normal to the intersected surface in the world coordinate system

  • si.dn_du stores the real part of the S and P components of the incident electric field represented in the implicit world frame (first and second components of si.dn_du)

  • si.dn_dv stores the imaginary part of the S and P components of the incident electric field represented in the implicit world frame (first and second components of si.dn_dv)

  • si.dp_du stores the solid angle of the ray tube (first component of si.dn_du)

  • si.prim_index stores the interaction type to evaluate

Parameters:
Returns:

Jones matrix as a \(4 \times 4\) real-valued matrix

pdf(ctx: mitsuba.BSDFContext, si: mitsuba.SurfaceInteraction3f, wo: mitsuba.Vector3f, active: bool | drjit.cuda.ad.Bool = True) → drjit.cuda.ad.Float[source]#

Evaluates the probability of the sampled interaction type and direction of scattered ray

This function evaluates the probability density of the radio material for the scattered direction wo and for the interaction type stored in si.prim_index.

The following assumptions are made on the inputs:

  • si.wi is the direction of propagation of the incident wave in the world frame

  • si.sh_frame is the frame such that the sh_frame.n is the normal to the intersected surface in the world coordinate system

  • si.dn_du stores the real part of the S and P components of the incident electric field represented in the implicit world frame (first and second components of si.dn_du)

  • si.dn_dv stores the imaginary part of the S and P components of the incident electric field represented in the implicit world frame (first and second components of si.dn_dv)

  • si.dp_du stores the solid angle of the ray tube (first component of si.dn_du)

  • si.prim_index stores the interaction type to evaluate

Parameters:
Returns:

Probability density value

sample(ctx: mitsuba.BSDFContext, si: mitsuba.SurfaceInteraction3f, sample1: drjit.cuda.ad.Float, sample2: mitsuba.Point2f, active: bool | drjit.cuda.ad.Bool = True) → Tuple[mitsuba.BSDFSample3f, mitsuba.Spectrum][source]#

Samples the radio material

This function samples an interaction type (e.g., specular reflection, diffuse reflection or refraction) and direction of propagation for the scattered ray, and returns the corresponding radio material sample and Jones matrix. The returned radio material sample stores the sampled type of interaction and sampled direction of propagation of the scattered ray.

The following assumptions are made on the inputs:

  • ctx.component is a binary mask that specifies the types of interaction enabled. Booleans can be obtained from this mask as follows:

specular_reflection_enabled = (ctx.component & InteractionType.SPECULAR) > 0
diffuse_reflection_enabled = (ctx.component & InteractionType.DIFFUSE) > 0
transmission_enabled = (ctx.component & InteractionType.TRANSMISSION) > 0

  • si.wi is the direction of propagation of the incident wave in the world frame

  • si.sh_frame is the frame such that the sh_frame.n is the normal to the intersected surface in the world coordinate system

  • si.dn_du stores the real part of the S and P components of the incident electric field represented in the implicit world frame (first and second components of si.dn_du)

  • si.dn_dv stores the imaginary part of the S and P components of the incident electric field represented in the implicit world frame (first and second components of si.dn_dv)

  • si.dp_du stores the solid angle of the ray tube (first component of si.dn_du)

The outputs are set as follows:

  • bs.wo is the direction of propagation of the sampled scattered ray in the world frame

  • jones_mat is the Jones matrix describing the transformation incurred to the incident wave in the implicit world frame

Parameters:

  • ctx (mitsuba.BSDFContext) – A context data structure used to specify which interaction types are enabled

  • si (mitsuba.SurfaceInteraction3f) – Surface interaction data structure describing the underlying surface position

  • sample1 (drjit.cuda.ad.Float) – A uniformly distributed sample on \([0,1]\) used to sample the type of interaction

  • sample2 (mitsuba.Point2f) – A uniformly distributed sample on \([0,1]^2\) used to sample the direction of the reflected wave in the case of diffuse reflection

  • active (bool | drjit.cuda.ad.Bool) – Mask to specify active rays

Returns:

Radio material sample and Jones matrix as a \(4 \times 4\) real-valued matrix

to_string() → str[source]#

Returns object description

traverse(callback: mitsuba.TraversalCallback)[source]#

Traverse the attributes and objects of this instance

Implementing this function is required for Mitsuba to traverse a scene graph, including materials, and determine the differentiable parameters.

Parameters:

callback (mitsuba.TraversalCallback) – Object used to traverse the scene graph

Attributes

property color#

Get/set the the RGB (red, green, blue) color for the radio material as displayed in the previewer and renderer. Each RGB component must have a value within the range \(\in [0,1]\).

Type:

Tuple[float, float, float]

property name#

(read-only) Name of the radio material

Type:

str

property scene#

Get/set the scene used by the radio material. Note that the scene can only be set once.

Type:

Scene

class sionna.rt.RadioMaterial(name: str | None = None, thickness: float | drjit.cuda.ad.Float = 0.1, relative_permittivity: float | drjit.cuda.ad.Float = 1.0, conductivity: float | drjit.cuda.ad.Float = 0.0, scattering_coefficient: float | drjit.cuda.ad.Float = 0.0, xpd_coefficient: float | drjit.cuda.ad.Float = 0.0, scattering_pattern: str = 'lambertian', frequency_update_callback: Callable[[drjit.cuda.ad.Float], Tuple[drjit.cuda.ad.Float, drjit.cuda.ad.Float]] | None = None, color: Tuple[float, float, float] | None = None, props: mitsuba.Properties | None = None, **kwargs)[source]#

Class implementing the radio material model described in the Primer on Electromagnetics

This class implements RadioMaterialBase.

A radio material is defined by its relative permittivity \(\varepsilon_r\) and conductivity \(\sigma\) (see (9)), its thickness \(d\) (see (36)), as well as optional parameters related to diffuse reflection (see Scattering), such as the scattering coefficient \(S\), cross-polarization discrimination coefficient \(K_x\), and scattering pattern \(f_\text{s}(\hat{\mathbf{k}}_\text{i}, \hat{\mathbf{k}}_\text{s})\).

We assume non-ionized and non-magnetic materials, and therefore the permeability \(\mu\) of the material is assumed to be equal to the permeability of vacuum i.e., \(\mu_r=1.0\).

Reflection and refraction coefficients are computed assuming that the intersected surface models a slab with the specified thickness (see (35)). The computed coefficients therefore account for the multiple internal reflections inside the slab, meaning that this class should be used when objects like walls are modeled as single flat surfaces. The figure below illustrates this model, where \(E_i\) is the incident electric field, \(E_r\) is the reflected field and \(E_t\) is the transmitted field. The Jones matrices, \(\mathbf{R}(d)\) and \(\mathbf{T}(d)\), represent the effects of reflection and transmission, respectively, and depend on the slab thickness, \(d\).

../../_images/transmission_model.png

For frequency-dependent materials, it is possible to specify a callback function frequency_update_callback that computes the material properties \((\varepsilon_r, \sigma)\) from the frequency. If a callback function is specified, the material properties cannot be set and the values specified at instantiation are ignored.

In addition to the following inputs, additional keyword arguments can be provided that will be passed to the scattering pattern as keyword arguments.

Parameters:

  • name (str | None) – Unique name of the material. Ignored if props is provided.

  • thickness (float | drjit.cuda.ad.Float) – Thickness of the material [m]. Ignored if props is provided.

  • relative_permittivity (float | drjit.cuda.ad.Float) – Relative permittivity of the material. Must be larger or equal to 1. Ignored if frequency_update_callback or props is provided.

  • conductivity (float | drjit.cuda.ad.Float) – Conductivity of the material [S/m]. Must be non-negative. Ignored if frequency_update_callback or props is provided.

  • scattering_coefficient (float | drjit.cuda.ad.Float) – Scattering coefficient \(S\in[0,1]\) as defined in (39). Ignored if props is provided.

  • xpd_coefficient (float | drjit.cuda.ad.Float) – Cross-polarization discrimination coefficient \(K_x\in[0,1]\) as defined in (41). Only relevant if scattering_coefficient is not equal to zero. Ignored if props is provided.

  • scattering_pattern (str) – Name of a registered scattering pattern for diffuse reflections (“lambertian” | “backscattering” | “directive”). Only relevant if scattering_coefficient is not equal to zero. Ignored if props is provided.

  • frequency_update_callback (Callable[[drjit.cuda.ad.Float], Tuple[drjit.cuda.ad.Float, drjit.cuda.ad.Float]] | None) – Callable used to update the material parameters when the frequency is set. This callable must take as input the frequency [Hz] and must return the material properties as a tuple: (relative_permittivity, conductivity). If set to None, then material properties are constant and equal to the value set at instantiation or using the corresponding setters.

  • color (Tuple[float, float, float] | None) – RGB (red, green, blue) color for the radio material as displayed in the previewer and renderer. Each RGB component must have a value within the range \([0,1]\). If set to None, then a random color is used.

  • props (mitsuba.Properties | None) – Mitsuba container storing the material properties, and used when loading a scene to initialize the radio material.

Keyword Arguments#

**kwargs: Any

Depending on the chosen scattering antenna pattern, other keyword arguments must be provided. See the Developer Guide for more details.

frequency_update()[source]#

Updates the material parameters according to the set frequency

property conductivity#

Get/set the conductivity \(\sigma\) [S/m] (9)

Type:

mi.Float

property frequency_update_callback#

Get/set the frequency update callback

Type:

Callable [[mi.Float], [mi.Float, mi.Float]]

property relative_permittivity#

Get/set the relative permittivity \(\varepsilon_r\) (9)

Type:

mi.Float

property scattering_coefficient#

Get/set the scattering coefficient \(S\in[0,1]\) (39)

Type:

mi.Float

property scattering_pattern#

Get/set the scattering pattern

Type:

ScatteringPattern

property thickness#

Get/set the material thickness [m]

Type:

mi.Float

property xpd_coefficient#

Get/set the cross-polarization discrimination coefficient \(K_x\in[0,1]\) (41)

Type:

mi.Float

class sionna.rt.ITURadioMaterial(name: str | None = None, itu_type: str | None = None, thickness: float | drjit.cuda.ad.Float | None = None, scattering_coefficient: float | drjit.cuda.ad.Float = 0.0, xpd_coefficient: float | drjit.cuda.ad.Float = 0.0, scattering_pattern: Callable[[mitsuba.Vector3f, mitsuba.Vector3f, ...], drjit.cuda.ad.Float] | None = None, color: Tuple[float, float, float] | None = None, props: mitsuba.Properties | None = None, **kwargs)[source]#

Class implementing the materials defined in the ITU-R P.2040-3 recommendation [ITURP20403]

This class inherits from RadioMaterial.

The models from the ITU-R P.2040-3 recommendation are based on curve fitting to measurement results and assume non-ionized and non-magnetic materials (\(\mu_r = 1\)). Frequency dependence is modeled by

\[\begin{split}\begin{aligned} \varepsilon_r &= a f_{\text{GHz}}^b\\ \sigma &= c f_{\text{GHz}}^d \end{aligned}\end{split}\]

where \(f_{\text{GHz}}\) is the frequency in GHz, and the constants \(a\), \(b\), \(c\), and \(d\) characterize the material.

Note that the relative permittivity \(\varepsilon_r\) and conductivity \(\sigma\) of all materials are updated automatically when the frequency is set through the scene’s property frequency.

In addition to the following inputs, additional keyword arguments can be provided that will be passed to the scattering pattern as keyword arguments.

Parameters:

  • name (str | None) – Unique name of the material. Ignored if props is provided.

  • itu_type (str | None) – Type the ITU material. The available materials are listed in the corresponding table. Ignored if props is provided.

  • thickness (float | drjit.cuda.ad.Float | None) – Thickness of the material [m]. Ignored if props is provided.

  • scattering_coefficient (float | drjit.cuda.ad.Float) – Scattering coefficient \(S\in[0,1]\) as defined in (39). Ignored if props is provided.

  • xpd_coefficient (float | drjit.cuda.ad.Float) – Cross-polarization discrimination coefficient \(K_x\in[0,1]\) as defined in (41). Only relevant if scattering_coefficient is not equal to zero. Ignored if props is provided.

  • scattering_pattern (Callable[[mitsuba.Vector3f, mitsuba.Vector3f, ...], drjit.cuda.ad.Float] | None) – Scattering pattern to use for diffuse reflection. Only relevant if scattering_coefficient is not equal to zero. Ignored if props is provided. Defaults to lambertian_pattern().

  • color (Tuple[float, float, float] | None) – RGB (red, green, blue) color for the radio material as displayed in the previewer and renderer. Each RGB component must have a value within the range \([0,1]\). If set to None, then a random color is used.

  • props (mitsuba.Properties | None) – Mitsuba container storing the material properties, and used when loading a scene to initialize the radio material.

Methods

to_string() → str[source]#

Returns a string describing the object

Attributes

property itu_type#

Get the ITU type

Type:

str

Scattering Patterns#

class sionna.rt.ScatteringPattern[source]#

Abstract class implementing a scattering pattern

Methods

abstractmethod __call__(ki_local: mitsuba.Vector3f, ko_local: mitsuba.Vector3f) → drjit.cuda.ad.Float[source]#
Parameters:

  • ki_local (mitsuba.Vector3f) – Direction of propagation of the incident wave in local frame

  • ko_local (mitsuba.Vector3f) – Direction of propagation of the scattered wave in local frame

Returns:

Scattering pattern value

show(k_i_local: mitsuba.Vector3f = (0.7071, 0.0, -0.7071), show_directions: bool = False) → tuple[matplotlib.figure.Figure, matplotlib.figure.Figure][source]#

Visualizes the scattering pattern

It is assumed that the surface normal points toward the positive z-axis.

Parameters:

  • k_i_local (mitsuba.Vector3f) – Incoming direction

  • show_directions (bool) – Show incoming and specular reflection directions

Returns:

3D visualization of the scattering pattern

Returns:

Visualization of the incident plane cut through the scattering pattern

class sionna.rt.LambertianPattern[source]#

Lambertian scattering model from [Degli-Esposti07] as given in (42)

Example#

>>> LambertianPattern().show()
../../_images/lambertian_pattern_3d.png
../../_images/lambertian_pattern_cut.png
__call__(ki_local: mitsuba.Vector3f, ko_local: mitsuba.Vector3f) → drjit.cuda.ad.Float[source]#
Parameters:

  • ki_local (mitsuba.Vector3f) – Direction of propagation of the incident wave in local frame

  • ko_local (mitsuba.Vector3f) – Direction of propagation of the scattered wave in local frame

Returns:

Scattering pattern value

show(k_i_local: mitsuba.Vector3f = (0.7071, 0.0, -0.7071), show_directions: bool = False) → tuple[matplotlib.figure.Figure, matplotlib.figure.Figure]#

Visualizes the scattering pattern

It is assumed that the surface normal points toward the positive z-axis.

Parameters:

  • k_i_local (mitsuba.Vector3f) – Incoming direction

  • show_directions (bool) – Show incoming and specular reflection directions

Returns:

3D visualization of the scattering pattern

Returns:

Visualization of the incident plane cut through the scattering pattern

class sionna.rt.DirectivePattern(alpha_r: int = 1)[source]#

Directive scattering model from [Degli-Esposti07] as given in (43)

Parameters:

alpha_r (int) – Parameter related to the width of the scattering lobe in the direction of the specular reflection

Example#

>>> from sionna.rt import DirectivePattern
>>> DirectivePattern(alpha_r=10).show()
../../_images/directive_pattern_3d.png
../../_images/directive_pattern_cut.png
__call__(ki_local: mitsuba.Vector3f, ko_local: mitsuba.Vector3f) → drjit.cuda.ad.Float#
Parameters:

  • ki_local (mitsuba.Vector3f) – Direction of propagation of the incident wave in local frame

  • ko_local (mitsuba.Vector3f) – Direction of propagation of the scattered wave in local frame

Returns:

Scattering pattern value

show(k_i_local: mitsuba.Vector3f = (0.7071, 0.0, -0.7071), show_directions: bool = False) → tuple[matplotlib.figure.Figure, matplotlib.figure.Figure]#

Visualizes the scattering pattern

It is assumed that the surface normal points toward the positive z-axis.

Parameters:

  • k_i_local (mitsuba.Vector3f) – Incoming direction

  • show_directions (bool) – Show incoming and specular reflection directions

Returns:

3D visualization of the scattering pattern

Returns:

Visualization of the incident plane cut through the scattering pattern

property alpha_r#

Get/set \(\alpha_\text{R}\)

Type:

int

class sionna.rt.BackscatteringPattern(alpha_r: int = 1, alpha_i: int = 1, lambda_: drjit.cuda.ad.Float = 1.0)[source]#

Backscattering model from [Degli-Esposti07] as given in (44)

Parameters:

  • alpha_r (int) – Parameter related to the width of the scattering lobe in the direction of the specular reflection

  • alpha_i (int) – Parameter related to the width of the scattering lobe in the incoming direction

  • lambda – Parameter determining the percentage of the diffusely reflected energy in the lobe around the specular reflection

  • lambda_ (drjit.cuda.ad.Float)

Example#

>>> from sionna.rt import BackscatteringPattern
>>> BackscatteringPattern(alpha_r=20, alpha_i=30, lambda_=0.7).show()
../../_images/backscattering_pattern_3d.png
../../_images/backscattering_pattern_cut.png
__call__(ki_local: mitsuba.Vector3f, ko_local: mitsuba.Vector3f) → drjit.cuda.ad.Float[source]#
Parameters:

  • ki_local (mitsuba.Vector3f) – Direction of propagation of the incident wave in local frame

  • ko_local (mitsuba.Vector3f) – Direction of propagation of the scattered wave in local frame

Returns:

Scattering pattern value

show(k_i_local: mitsuba.Vector3f = (0.7071, 0.0, -0.7071), show_directions: bool = False) → tuple[matplotlib.figure.Figure, matplotlib.figure.Figure]#

Visualizes the scattering pattern

It is assumed that the surface normal points toward the positive z-axis.

Parameters:

  • k_i_local (mitsuba.Vector3f) – Incoming direction

  • show_directions (bool) – Show incoming and specular reflection directions

Returns:

3D visualization of the scattering pattern

Returns:

Visualization of the incident plane cut through the scattering pattern

property alpha_i#

Get/set \(\alpha_\text{I}\)

Type:

int

property alpha_r#

Get/set \(\alpha_\text{R}\)

Type:

int

property lambda_#

Get/set \(\Lambda\)

Type:

mi.float

sionna.rt.register_scattering_pattern(name: str, scattering_pattern_factory: Callable[[...], sionna.rt.radio_materials.scattering_pattern.ScatteringPattern])[source]#

Registers a new factory method for a scattering pattern

Parameters: