Radio Materials

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

The base classRadioMaterialBase provides an interfacefor implementing arbitrary radio materials and can be used to implementedcustom materials, as detailed in theDeveloper Guide.

TheRadioMaterial class implements the model described in thePrimer on Electromagnetics, and supports specular and diffusereflection as well as refraction. The details of this model are provided thereafter.

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

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

Radio materials provided with Sionna

The classRadioMaterial implements the model described in thePrimer on Electromagnetics. Following this model, a radio material consists of thereal-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 radiowave. 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 ofthe reflected and refracted fields (see(35)). For example, a wallis modeled in Sionna RT as a planar surface whose radio material describes thedesired thickness.

Additionally, aRadioMaterial 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 theLambertianPattern orDirectivePattern. The meaning ofthese parameters is explained inScattering.

Sionna provides theITU models of several materials whose propertiesare automatically updated according to the configuredfrequency.

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

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[ITU_R_2040_3]).Note that the relative permittivity\(\varepsilon_r\) andconductivity\(\sigma\) of all materials are updated automatically whenthe frequency is set through the scene’s propertyfrequency.Moreover, by default, the scattering coefficient,\(S\), of these materials is set to0, leading to no diffuse reflection.

classsionna.rt.RadioMaterialBase(props)[source]

Base class to implement a radio material

This is an abstract class that cannot be instantiated, and serves asinterface 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

propertycolor

Get/set the the RGB (red, green, blue) color for theradio 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]

eval(ctx,si,wo,active=True)[source]

Evaluates the radio material

This function evaluates the Jones matrix of the radio material for the scattereddirectionwo and for the interaction type stored insi.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 thesh_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 ofsi.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 ofsi.dn_dv)

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

• si.prim_index stores the interaction type to evaluate

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

• wo (mitsuba.Vector3f) – Direction of propagation of the scattered wave in the world frame

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

Return type:

mitsuba.Spectrum

Returns:

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

propertyname

(read-only) Name of the radio material

Type:

str

pdf(ctx,si,wo,active=True)[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 scattereddirectionwo and for the interaction type stored insi.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 thesh_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 ofsi.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 ofsi.dn_dv)

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

• si.prim_index stores the interaction type to evaluate

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

• wo (mitsuba.Vector3f) – Direction of propagation of the scattered wave in the world frame

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

Return type:

drjit.cuda.ad.Float

Returns:

Probability density value

sample(ctx,si,sample1,sample2,active=True)[source]

Samples the radio material

This function samples an interaction type (e.g., specular reflection,diffuse reflection or refraction) and direction of propagation for thescattered ray, and returns the corresponding radio material sample and Jones matrix.The returned radio material sample stores the sampled type of interaction and sampled directionof 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)>0diffuse_reflection_enabled=(ctx.component&InteractionType.DIFFUSE)>0transmission_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 thesh_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 ofsi.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 ofsi.dn_dv)

• si.dp_du stores the solid angle of the ray tube (first component ofsi.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

Return type:

typing.Tuple[mitsuba.BSDFSample3f,mitsuba.Spectrum]

Returns:

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

propertyscene

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

Type:

Scene

to_string()[source]

Returns object description

Return type:

str

traverse(callback)[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

classsionna.rt.RadioMaterial(name=None,thickness=0.1,relative_permittivity=1.0,conductivity=0.0,scattering_coefficient=0.0,xpd_coefficient=0.0,scattering_pattern='lambertian',frequency_update_callback=None,color=None,props=None,**kwargs)[source]

Class implementing the radio material model described in thePrimer on Electromagnetics

This class implementsRadioMaterialBase.

A radio material is defined by its relative permittivity\(\varepsilon_r\) and conductivity\(\sigma\) (see(9)), itsthickness\(d\) (see(36)),as well as optional parameters related to diffuse reflection (seeScattering), such as thescattering coefficient\(S\), cross-polarization discriminationcoefficient\(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 thepermeability\(\mu\) of the material is assumed to be equalto the permeability of vacuum i.e.,\(\mu_r=1.0\).

Reflection and refraction coefficients are computed assuming that theintersected surface models a slab with the specifiedthickness(see(35)). The computed coefficients therefore account forthe multiple internal reflections inside the slab, meaning that thisclass should be used when objects like walls are modeled as single flatsurfaces. The figure below illustrates this model, where\(E_i\) is theincident electric field,\(E_r\) is the reflected field and\(E_t\) isthe 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\).

For frequency-dependent materials, it is possible tospecify a callback functionfrequency_update_callback that computesthe material properties\((\varepsilon_r, \sigma)\) from thefrequency. If a callback function is specified, the material propertiescannot be set and the values specified at instantiation are ignored.

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

Parameters:

• name (typing.Optional[str]) – Unique name of the material. Ignored ifprops is provided.

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

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

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

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

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

• scattering_pattern (str) – Name of a registered scattering pattern fordiffuse reflections(“lambertian” | “backscattering” | “directive”).Only relevant ifscattering_coefficient is not equal to zero. Ignored ifprops is provided.

• frequency_update_callback (typing.Optional[typing.Callable[[drjit.cuda.ad.Float],typing.Tuple[drjit.cuda.ad.Float,drjit.cuda.ad.Float]]]) – 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 toNone, then material properties are constant and equal to the value set at instantiation or using the corresponding setters.

• color (typing.Optional[typing.Tuple[float,float,float]]) – 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 toNone, then a random color is used.

• props (typing.Optional[mitsuba.Properties]) – Mitsuba container storing the material properties, and usedwhen loading a scene to initialize the radio material.

Keyword Arguments:

**kwargs (Any) – Depending on the chosen scattering antenna pattern, other keyword argumentsmust be provided.See theDeveloper Guide formore details.

propertyconductivity

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

Type:

mi.Float

frequency_update()[source]

Updates the material parameters according to the set frequency

propertyfrequency_update_callback

Get/set the frequency update callback

Type:

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

propertyrelative_permittivity

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

Type:

mi.Float

propertyscattering_coefficient

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

Type:

mi.Float

propertyscattering_pattern

Get/set the scattering pattern

Type:

ScatteringPattern

propertythickness

Get/set the material thickness [m]

Type:

mi.Float

propertyxpd_coefficient

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

Type:

mi.Float

classsionna.rt.ITURadioMaterial(name=None,itu_type=None,thickness=None,scattering_coefficient=0.0,xpd_coefficient=0.0,scattering_pattern=None,color=None,props=None,**kwargs)[source]

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

This class inherits fromRadioMaterial.

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

\[\begin{split}\begin{align} \varepsilon_r &= a f_{\text{GHz}}^b\\ \sigma &= c f_{\text{GHz}}^d\end{align}\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\) andconductivity\(\sigma\) of all materials are updated automatically whenthe frequency is set through the scene’s propertyfrequency.

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

Parameters:

• name (typing.Optional[str]) – Unique name of the material. Ignored ifprops is provided.

• itu_type (typing.Optional[str]) – Type the ITU material. The available materials are listed inthe corresponding table. Ignored ifprops is provided.

• thickness (typing.Union[float,drjit.cuda.ad.Float,None]) – Thickness of the material [m]. Ignored ifprops is provided.

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

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

• scattering_pattern (typing.Optional[typing.Callable[[mitsuba.Vector3f,mitsuba.Vector3f,...],drjit.cuda.ad.Float]]) – Scattering pattern to use for diffuse reflection. Only relevant ifscattering_coefficient is not equal to zero. Ignored ifprops is provided. Defaults tolambertian_pattern().

• color (typing.Optional[typing.Tuple[float,float,float]]) – 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 toNone, then a random color is used.

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

propertyitu_type

Get the ITU type

Type:

str

to_string()[source]

Returns a string describing the object

Return type:

str