fdtdx.Material

fdtdx.Material#

class fdtdx.Material(*, permittivity=(1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0), permeability=(1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0), electric_conductivity=(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0), magnetic_conductivity=(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0), dispersion=None)[source]#

Bases: TreeClass

Represents an electromagnetic material with specific electrical and magnetic properties.

This class stores the fundamental electromagnetic properties of a material for use in electromagnetic simulations. Supports both isotropic and anisotropic materials.

Note

All material properties are stored internally as 9-tuples (xx, xy, xz, yx, yy, yz, zx, zy, zz components). Scalar inputs are automatically broadcast to all diagonal components.

Quick Reference#

Attributes

Methods

Attributes#

Material.dispersion: DispersionModel | None#

Optional dispersion model. When set, permittivity represents the high-frequency permittivity \(\varepsilon_\infty\); the full \(\varepsilon(\omega)\) is \(\varepsilon_\infty + \chi(\omega)\) from the dispersion model. Defaults to None (non-dispersive).

Material.electric_conductivity: tuple[float, float, float, float, float, float, float, float, float]#

The electrical conductivity of the material in siemens per meter (S/m), which describes how easily electric current can flow through it. Higher values indicate materials that conduct electricity more easily. For isotropic materials, provide a scalar float. For diagonally anisotropic materials, provide a tuple of 3 floats (σx, σy, σz). For fully anisotropic materials, provide either:

  • A tuple of 9 floats (σxx, σxy, σxz, σyx, σyy, σyz, σzx, σzy, σzz), or

  • A nested tuple ((σxx, σxy, σxz), (σyx, σyy, σyz), (σzx, σzy, σzz))

Stored internally as a 9-tuple. Defaults to (0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0).

Material.has_isotropic_dispersion#

Check whether the material’s dispersion (if any) is isotropic.

Returns:

True if the material is non-dispersive or every pole of its dispersion model applies the same parameters to all three axes.

Return type:

bool

Material.is_all_diagonally_anisotropic#

Check if all material properties are diagonally anisotropic (no off-diagonal components).

Returns:

True if material is diagonally anisotropic

Return type:

bool

Material.is_all_isotropic#

Check if all material properties are isotropic (all components equal and no off-diagonal components).

Returns:

True if material is isotropic, False if anisotropic

Return type:

bool

Material.is_diagonally_anisotropic_electric_conductivity#

Check if material has diagonally anisotropic electric conductivity (no off-diagonal components).

Returns:

True if material has diagonally anisotropic electric conductivity

Return type:

bool

Material.is_diagonally_anisotropic_magnetic_conductivity#

Check if material has diagonally anisotropic magnetic conductivity (no off-diagonal components).

Returns:

True if material has diagonally anisotropic magnetic conductivity

Return type:

bool

Material.is_diagonally_anisotropic_permeability#

Check if material has diagonally anisotropic permeability (no off-diagonal components).

Returns:

True if material has diagonally anisotropic permeability

Return type:

bool

Material.is_diagonally_anisotropic_permittivity#

Check if material has diagonally anisotropic permittivity (no off-diagonal components).

Returns:

True if material has diagonally anisotropic permittivity

Return type:

bool

Material.is_dispersive#

Check if the material has a non-trivial dispersion model.

Returns:

True if a DispersionModel with at least one pole is attached.

Return type:

bool

Material.is_electrically_conductive#

Check if material is electrically conductive (conductivity != 0.0 for any component).

Returns:

True if material is electrically conductive

Return type:

bool

Material.is_isotropic_electric_conductivity#

Check if material has isotropic electric conductivity (all components equal and no off-diagonal components).

Returns:

True if material has isotropic electric conductivity

Return type:

bool

Material.is_isotropic_magnetic_conductivity#

Check if material has isotropic magnetic conductivity (all components equal and no off-diagonal components).

Returns:

True if material has isotropic magnetic conductivity

Return type:

bool

Material.is_isotropic_permeability#

Check if material has isotropic permeability (all components equal and no off-diagonal components).

Returns:

True if material has isotropic permeability

Return type:

bool

Material.is_isotropic_permittivity#

Check if material has isotropic permittivity (all components equal and no off-diagonal components).

Returns:

True if material has isotropic permittivity

Return type:

bool

Material.is_magnetic#

Check if material has magnetic properties (permeability != 1.0 for any component).

Returns:

True if material is magnetic

Return type:

bool

Material.is_magnetically_conductive#

Check if material has magnetic conductivity (magnetic loss != 0.0 for any component).

Returns:

True if material has magnetic conductivity

Return type:

bool

Material.magnetic_conductivity: tuple[float, float, float, float, float, float, float, float, float]#

The magnetic conductivity, or magnetic loss of the material. This is an artificial parameter for numerical applications and does not represent an actual physical unit, even though often described in Ohm/m. The naming can be misleading, because it does not actually describe a conductivity, but rather an “equivalent magnetic loss parameter”. For isotropic materials, provide a scalar float. For diagonally anisotropic materials, provide a tuple of 3 floats (σx, σy, σz). For fully anisotropic materials, provide either:

  • A tuple of 9 floats (σxx, σxy, σxz, σyx, σyy, σyz, σzx, σzy, σzz), or

  • A nested tuple ((σxx, σxy, σxz), (σyx, σyy, σyz), (σzx, σzy, σzz))

Stored internally as a 9-tuple. Defaults to (0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0).

Material.permeability: tuple[float, float, float, float, float, float, float, float, float]#

The relative permeability of the material, which describes how the magnetic field is affected by the material. Higher values indicate greater magnetic response to an applied magnetic field. For isotropic materials, provide a scalar float. For diagonally anisotropic materials, provide a tuple of 3 floats (μx, μy, μz). For fully anisotropic materials, provide either:

  • A tuple of 9 floats (μxx, μxy, μxz, μyx, μyy, μyz, μzx, μzy, μzz), or

  • A nested tuple ((μxx, μxy, μxz), (μyx, μyy, μyz), (μzx, μzy, μzz))

Stored internally as a 9-tuple. Defaults to (1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0).

Material.permittivity: tuple[float, float, float, float, float, float, float, float, float]#

The relative permittivity (dielectric constant) of the material, which describes how the electric field is affected by the material. Higher values indicate greater electric polarization in response to an applied electric field. For isotropic materials, provide a scalar float. For diagonally anisotropic materials, provide a tuple of 3 floats (εx, εy, εz). For fully anisotropic materials, provide either:

  • A tuple of 9 floats (εxx, εxy, εxz, εyx, εyy, εyz, εzx, εzy, εzz), or

  • A nested tuple ((εxx, εxy, εxz), (εyx, εyy, εyz), (εzx, εzy, εzz))

Stored internally as a 9-tuple. Defaults to (1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0).

Methods#

Material.aset(attr_name, val, create_new_ok=False)#

Sets an attribute of this class. In contrast to the classical .at[].set(), this method updates the class attribute directly and does not only operate on jax pytree leaf nodes. Instead, replaces the full attribute with the new value.

The attribute can either be the attribute name of this class, or for nested classes it can also be the attribute name of a class, which itself is an attribute of this class. The syntax for this operation could look like this: “a->b->[0]->[‘name’]”. Here, the current class has an attribute a, which has an attribute b, which is a list, which we index at index 0, which is an element of type dictionary, which we index using the dictionary key ‘name’.

Note that dictionary keys cannot contain square brackets or single quotes (even if they are escaped).

Parameters:

  • attr_name (str) – Name of attribute to set

  • val (Any) – Value to set the attribute to

  • create_new_ok (bool, optional) – If false (default), throw an error if the attribute does not exist. If true, creates a new attribute if the attribute name does not exist yet.

Returns:

Updated instance with new attribute value

Return type:

Self

classmethod Material.from_complex_permittivity(permittivity, *, reference=None, wavelength=None, frequency=None, permeability=1.0)[source]#

Build a non-dispersive lossy material from a complex permittivity.

The imaginary part of the permittivity is converted to an equivalent electric conductivity \(\sigma = \omega_0 \varepsilon_0 \varepsilon''\) at the reference angular frequency \(\omega_0 = 2\pi f_0\). Likewise, a complex permeability maps its imaginary part to a magnetic conductivity \(\sigma_m = \omega_0 \mu_0 \mu''\).

Sign convention: \(e^{-i\omega t}\), so a positive imaginary part denotes loss (\(\varepsilon = \varepsilon' + i\varepsilon''\)), matching the dispersion model used elsewhere in FDTDX.

Warning

This reproduces the requested complex permittivity exactly only at the reference frequency. A constant conductivity yields \(\varepsilon''(\omega) = \sigma / (\varepsilon_0 \omega)\), which falls off as \(1/\omega\) away from \(\omega_0\) — the causal behaviour of a conductor, not a frequency-flat loss. For a material whose \(\varepsilon(\omega)\) must be matched across a band, use a dispersion model instead. The reference frequency is consumed only to pick \(\sigma\); it is not stored on the material and need not match any source.

Parameters:

  • permittivity (complex | float | tuple) – Complex relative permittivity \(\varepsilon' + i\varepsilon''\). Scalar (isotropic) or a flat 3-tuple (diagonally anisotropic).

  • reference (WaveCharacter | None) – Reference wave characteristic. Provide exactly one of reference, wavelength, or frequency.

  • wavelength (float | None) – Free-space reference wavelength (m).

  • frequency (float | None) – Reference frequency (Hz).

  • permeability (complex | float | tuple) – Optional complex relative permeability \(\mu' + i\mu''\). Defaults to 1.0 (non-magnetic, lossless).

Returns:

Material with real permittivity/permeability and the derived electric/magnetic conductivities.

Return type:

Material

classmethod Material.from_loss_tangent(permittivity, loss_tangent, *, reference=None, wavelength=None, frequency=None, permeability=1.0)[source]#

Build a non-dispersive lossy material from a real permittivity and loss tangent.

The loss tangent \(\tan\delta = \varepsilon''/\varepsilon'\) defines the imaginary part \(\varepsilon'' = \varepsilon' \tan\delta\), which maps to an equivalent electric conductivity \(\sigma = \omega_0 \varepsilon_0 \varepsilon' \tan\delta\) at the reference frequency (see from_complex_permittivity()).

Warning

The loss is matched exactly only at the reference frequency (see from_complex_permittivity()).

Parameters:

  • permittivity (float | tuple) – Real relative permittivity \(\varepsilon'\). Scalar (isotropic) or a flat 3-tuple (diagonally anisotropic).

  • loss_tangent (float | tuple) – Loss tangent \(\tan\delta\). Scalar, or a flat 3-tuple matching permittivity.

  • reference (WaveCharacter | None) – Reference wave characteristic. Provide exactly one of reference, wavelength, or frequency.

  • wavelength (float | None) – Free-space reference wavelength (m).

  • frequency (float | None) – Reference frequency (Hz).

  • permeability (complex | float | tuple) – Optional complex relative permeability. Defaults to 1.0.

Returns:

The equivalent lossy material.

Return type:

Material

classmethod Material.from_refractive_index(refractive_index, *, reference=None, wavelength=None, frequency=None)[source]#

Build a non-dispersive lossy material from a complex refractive index.

The complex refractive index \(\tilde{n} = n + i\kappa\) maps to the relative permittivity \(\varepsilon = \tilde{n}^2 = (n^2 - \kappa^2) + i\,2 n \kappa\), whose imaginary part becomes an equivalent electric conductivity at the reference frequency (see from_complex_permittivity()). Assumes a non-magnetic medium (\(\mu_r = 1\)); for magnetic materials specify \(\varepsilon\) and \(\mu\) directly via from_complex_permittivity().

Sign convention: \(e^{-i\omega t}\), so a positive extinction coefficient \(\kappa\) denotes loss.

Warning

The loss is matched exactly only at the reference frequency (see from_complex_permittivity()).

Parameters:

  • refractive_index (complex | float | tuple) – Complex refractive index \(n + i\kappa\). Scalar (isotropic) or a flat 3-tuple (diagonally anisotropic).

  • reference (WaveCharacter | None) – Reference wave characteristic. Provide exactly one of reference, wavelength, or frequency.

  • wavelength (float | None) – Free-space reference wavelength (m).

  • frequency (float | None) – Reference frequency (Hz).

Returns:

The equivalent lossy material.

Return type:

Material

Material.get_class_fields()#
Return type:

list[TreeClassField]

Material.get_public_fields()#
Return type:

list[TreeClassField]

If you find any errors in the documentation, please report them in the Github Issues!