differt.em.TracedFields

class TracedFields(fields, delay, frequency, mask, confidence_threshold=0.5)

Bases: Module

A convenient wrapper class around received electromagnetic fields, propagation delays, and masks.

This class represents the EM fields computed for a set of paths (e.g., as produced by TracedPaths).

Attributes

confidence_threshold	A threshold used to decide whether a given path is valid or not.
masked_delay	The array of masked propagation delays, with batched dimensions flattened into one.
masked_fields	The array of masked fields, with batched dimensions flattened into one.
num_valid_paths	The number of paths kept by mask.
shape	The batch shape of the fields.
fields	The complex received electric fields (or channel gains) for each path.
delay	The propagation delay (in seconds) for each path.
frequency	The operating frequency (in Hz).
mask	A mask to indicate which paths are valid and contribute to the received field.

Methods

cir()	Return the Channel Impulse Response (CIR) as (delay, fields) pairs.
from_paths(paths, mesh[, frequency, solver])	Compute the received electromagnetic fields for each path and return a TracedFields instance.
masked()	Return a flattened version of this object that only keeps valid paths.
power([coherent, axis, z_0])	Compute the received power from the received fields (in dBW).
reduce(fun[, axis])	Apply a function on all fields and accumulate the result into a scalar value (or an array if axis is provided).
reshape(*batch)	Return a new fields instance with reshaped batch dimensions to match a given shape.
squeeze([axis])	Return a new fields instance by squeezing one or more axes of batch dimensions.

Detailed documentation

cir()

Return the Channel Impulse Response (CIR) as (delay, fields) pairs.

Return type:

tuple[Float[Array, "*batch"], Complex[Array, "*batch"]]

Returns:

A tuple of (delay, fields) where delay and fields have the same shape.

confidence_threshold: Float[ArrayLike, ""] = 0.5

A threshold used to decide whether a given path is valid or not.

A path is considered valid if its confidence is greater than or equal to this threshold. Unused if mask is of type bool.

delay: Float[Array, "*batch"]

The propagation delay (in seconds) for each path.

fields: Complex[Array, "*batch"]

The complex received electric fields (or channel gains) for each path.

frequency: Float[Array, "*#batch"]

The operating frequency (in Hz).

classmethod from_paths(paths, mesh, frequency=None, *, solver='geometric', **solver_kwargs)

Compute the received electromagnetic fields for each path and return a TracedFields instance.

Parameters:

• paths (TracedPaths) – The traced paths.

• mesh (Mesh) – The triangle mesh of the scene.

• frequency (Float[ArrayLike, "*#batch"] | None) –

  The operating frequency (or frequencies) in Hz.

  May be omitted (left to None) when solver’s tx_polarization is an AbstractAntenna instance, in which case its own frequency is used instead.

• solver (AbstractFieldSolver | Literal['geometric']) –

  The field solver configuration or string shortcut.

  Defaults to GeometricFieldSolver.

• **solver_kwargs (Any) – Parameters passed to the solver configuration when it is instantiated from a string shortcut (e.g., tx_polarization, rx_polarization, radio_materials, tx_wavefront_radii).

Return type:

Self

Returns:

A TracedFields instance wrapping the computed fields, propagation delays, operating frequency, and validity mask.

mask: Bool[Array, "*batch"] | Float[Array, "*batch"]

A mask to indicate which paths are valid and contribute to the received field.

The mask is kept separately to fields so that we can keep information about batch *batch dimensions, which would not be possible if we were to directly store valid paths.

If mask contains floating-point values, then they are interpreted as confidence values between 0 and 1, where values greater than or equal to confidence_threshold are considered valid.

masked()

Return a flattened version of this object that only keeps valid paths.

The returned object has all batch dimensions flattened into one, keeping only the paths where mask is True (or where mask is greater than or equal to confidence_threshold).

Return type:

Self

Returns:

A new fields instance with flattened batch dimensions and only valid paths.

property masked_delay: Float[Array, 'num_valid_paths']

The array of masked propagation delays, with batched dimensions flattened into one.

property masked_fields: Complex[Array, 'num_valid_paths']

The array of masked fields, with batched dimensions flattened into one.

property num_valid_paths: Int[Array, '']

The number of paths kept by mask.

The output value can be traced by JAX.

power(coherent=True, axis=None, z_0=z_0)

Compute the received power from the received fields (in dBW).

Parameters:

• coherent (bool) – Whether to sum coherently (vector sum of fields before power) or non-coherently (power sum of individual fields). Only active if axis is not None.

• axis (int | None) – The axis along which to sum the fields. If None, no sum is performed.

• z_0 (Float[ArrayLike, ""] | float) – The reference impedance.

Return type:

Float[Array, "..."]

Returns:

The received power in dBW.

reduce(fun, axis=None)

Apply a function on all fields and accumulate the result into a scalar value (or an array if axis is provided).

Parameters:

• fun (Callable[[Complex[Array, "*batch"]], Num[Array, "*batch"]]) – Function to apply on fields.

• axis (int | Sequence[int] | None) – See jax.numpy.sum for allowed values.

Return type:

Num[Array, ""] | Num[Array, "*reduced_batch"]

Returns:

The sum of the results, with contributions from invalid paths that are set to zero.

reshape(*batch)

Return a new fields instance with reshaped batch dimensions to match a given shape.

Parameters:

batch (int) – New batch shape.

Return type:

Self

Returns:

A new fields instance with specified batch dimensions.

property shape: tuple[int, ...]

The batch shape of the fields.

squeeze(axis=None)

Return a new fields instance by squeezing one or more axes of batch dimensions.

Parameters:

axis (int | Sequence[int] | None) – See jax.numpy.squeeze for allowed values.

Return type:

Self

Returns:

A new fields instance with squeezed batch dimensions.

Raises:

ValueError – If one of the provided axes is out-of-bounds, or if trying to squeeze a 0-dimensional batch.