Materials API

Material Library

prismo.materials.get_material(name)[source]

Get a material from the global library.

Parameters:: name (str) – Material name.
Returns:: Material object.
Return type:: DispersiveMaterial

Examples

>>> si = get_material('Si')
>>> sio2 = get_material('SiO2')
>>> au = get_material('Gold')

prismo.materials.list_materials()[source]

List all available materials in the global library.

Returns:: List of material names.
Return type:: list

prismo.materials.add_material(name, material)[source]

Add a custom material to the global library.

Parameters:

name (str) – Material name.
material (DispersiveMaterial) – Material object.

Return type:

None

Dispersion Models

DispersiveMaterial (Base Class)

class prismo.materials.dispersion.DispersiveMaterial(epsilon_inf=1.0, name='')[source]

Abstract base class for dispersive materials.

All dispersive material models must implement methods for: - Computing permittivity at a given frequency - Generating ADE update coefficients for FDTD

__init__(epsilon_inf=1.0, name='')[source]

Initialize dispersive material.

Parameters:

epsilon_inf (float) – High-frequency permittivity (ε_∞).
name (str) – Material name for identification.

abstractmethod permittivity(omega)[source]

Calculate complex permittivity at given frequency.

Parameters:: omega (float or array) – Angular frequency (rad/s).
Returns:: Complex relative permittivity ε(ω).
Return type:: complex or array of complex

refractive_index(omega)[source]

Calculate complex refractive index at given frequency.

Parameters:: omega (float or array) – Angular frequency (rad/s).
Returns:: Complex refractive index n(ω) = sqrt(ε(ω)).
Return type:: complex or array of complex

abstractmethod get_ade_coefficients(dt)[source]

Get Auxiliary Differential Equation (ADE) coefficients for FDTD.

Parameters:: dt (float) – Time step (s).
Returns:: Dictionary of ADE coefficients for time-domain updates.
Return type:: dict

LorentzMaterial

class prismo.materials.dispersion.LorentzMaterial(epsilon_inf, poles, name='')[source]

Material with Lorentz dispersion model.

The Lorentz model describes resonant dielectric behavior, suitable for dielectrics with resonances.

Parameters:

epsilon_inf (float) – High-frequency permittivity.
poles (List[LorentzPole]) – List of Lorentz poles.
name (str, optional) – Material name.

__init__(epsilon_inf, poles, name='')[source]

Initialize dispersive material.

Parameters:

epsilon_inf (float) – High-frequency permittivity (ε_∞).
name (str) – Material name for identification.

permittivity(omega)[source]

Calculate complex permittivity using Lorentz model.

Return type:: Union[complex, ndarray]

get_ade_coefficients(dt)[source]

Get ADE coefficients for Lorentz model.

For each Lorentz pole, we solve: d²P/dt² + γ dP/dt + ω₀² P = ε₀ Δε ω₀² E

Using bilinear transform (Trapezoidal rule):

Return type:: dict

DrudeMaterial

class prismo.materials.dispersion.DrudeMaterial(epsilon_inf, omega_p, gamma, name='')[source]

Material with Drude dispersion model (metals, plasmas).

The Drude model describes free carrier behavior, suitable for metals and doped semiconductors.

Parameters:

epsilon_inf (float) – High-frequency permittivity.
omega_p (float) – Plasma frequency (rad/s).
gamma (float) – Collision frequency (rad/s).
name (str, optional) – Material name.

__init__(epsilon_inf, omega_p, gamma, name='')[source]

Initialize dispersive material.

Parameters:

epsilon_inf (float) – High-frequency permittivity (ε_∞).
name (str) – Material name for identification.

permittivity(omega)[source]

Calculate complex permittivity using Drude model.

Return type:: Union[complex, ndarray]

get_ade_coefficients(dt)[source]

Get ADE coefficients for Drude model.

The Drude equation: dJ/dt + γ J = ε₀ ω_p² E

Return type:: dict

DebyeMaterial

class prismo.materials.dispersion.DebyeMaterial(epsilon_inf, epsilon_s, tau, name='')[source]

Material with Debye dispersion model.

The Debye model describes dielectric relaxation, suitable for polar dielectrics.

Parameters:

epsilon_inf (float) – High-frequency permittivity.
epsilon_s (float) – Static permittivity.
tau (float) – Relaxation time (s).
name (str, optional) – Material name.

__init__(epsilon_inf, epsilon_s, tau, name='')[source]

Initialize dispersive material.

Parameters:

epsilon_inf (float) – High-frequency permittivity (ε_∞).
name (str) – Material name for identification.

permittivity(omega)[source]

Calculate complex permittivity using Debye model.

Return type:: Union[complex, ndarray]

get_ade_coefficients(dt)[source]

Get ADE coefficients for Debye model.

Return type:: dict

SellmeierMaterial

class prismo.materials.dispersion.SellmeierMaterial(B_coeffs, C_coeffs, name='')[source]

Material with Sellmeier dispersion formula.

The Sellmeier formula is commonly used for transparent optical materials. n²(λ) = 1 + Σ (B_i λ² / (λ² - C_i))

Parameters:

B_coeffs (List[float]) – B coefficients in Sellmeier formula.
C_coeffs (List[float]) – C coefficients in Sellmeier formula (in μm²).
name (str, optional) – Material name.

__init__(B_coeffs, C_coeffs, name='')[source]

Initialize dispersive material.

Parameters:

epsilon_inf (float) – High-frequency permittivity (ε_∞).
name (str) – Material name for identification.

permittivity(omega)[source]

Calculate permittivity from Sellmeier formula.

Return type:: Union[complex, ndarray]

get_ade_coefficients(dt)[source]

Sellmeier is not directly suitable for time-domain.

Should be fitted to Lorentz poles for FDTD use.

Return type:: dict

Data Classes

LorentzPole

class prismo.materials.dispersion.LorentzPole(omega_0, delta_epsilon, gamma)[source]

Parameters for a single Lorentz pole.

The Lorentz model describes resonant behavior: ε(ω) = ε_∞ + Σ (ω_p² / (ω_0² - ω² - jωΓ))

Parameters:

omega_0 (float) – Resonance frequency (rad/s).
delta_epsilon (float) – Oscillator strength (dimensionless).
gamma (float) – Damping rate (rad/s).

omega_0: float

delta_epsilon: float

gamma: float

__init__(omega_0, delta_epsilon, gamma)

DrudePole

class prismo.materials.dispersion.DrudePole(omega_p, gamma)[source]

Parameters for Drude model (metals, plasmas).

The Drude model describes free carriers: ε(ω) = ε_∞ - (ω_p² / (ω² + jωΓ))

Parameters:

omega_p (float) – Plasma frequency (rad/s).
gamma (float) – Collision frequency (rad/s).

omega_p: float

gamma: float

__init__(omega_p, gamma)

DebyePole

class prismo.materials.dispersion.DebyePole(epsilon_s, tau)[source]

Parameters for Debye model (dielectric relaxation).

The Debye model describes relaxation: ε(ω) = ε_∞ + (ε_s - ε_∞) / (1 + jωτ)

Parameters:

epsilon_s (float) – Static permittivity.
tau (float) – Relaxation time (s).

epsilon_s: float

tau: float

__init__(epsilon_s, tau)

Anisotropic Materials

TensorMaterial

class prismo.materials.tensor.TensorMaterial(epsilon, mu=None, name='', backend=None)[source]

Material with anisotropic tensor properties.

Supports materials with tensor permittivity and/or permeability: D = ε₀ [ε] · E B = μ₀ [μ] · H

where [ε] and [μ] are 3×3 tensors.

Parameters:

epsilon (TensorComponents) – Permittivity tensor components (relative).
mu (TensorComponents, optional) – Permeability tensor components (relative). Default is isotropic μ=1.
name (str, optional) – Material name.
backend (Backend, optional) – Computational backend.

__init__(epsilon, mu=None, name='', backend=None)[source]

apply_to_e_field(E)[source]

Apply permittivity tensor to E field: D = ε₀ [ε] · E

Parameters:: E (Tuple of arrays) – Electric field components (Ex, Ey, Ez).
Returns:: D field components (Dx, Dy, Dz).
Return type:: Tuple of arrays

apply_to_h_field(H)[source]

Apply permeability tensor to H field: B = μ₀ [μ] · H

Parameters:: H (Tuple of arrays) – Magnetic field components (Hx, Hy, Hz).
Returns:: B field components (Bx, By, Bz).
Return type:: Tuple of arrays

get_inverse_epsilon()[source]

Get inverse of permittivity tensor: [ε]^(-1)

Used in E-field updates: E = [ε]^(-1) · D

Returns:: Inverse permittivity tensor.
Return type:: ndarray

get_inverse_mu()[source]

Get inverse of permeability tensor: [μ]^(-1)

Returns:: Inverse permeability tensor.
Return type:: ndarray

TensorComponents

class prismo.materials.tensor.TensorComponents(xx, yy, zz, xy=0.0, xz=0.0, yz=0.0, yx=None, zx=None, zy=None)[source]

Components of a 3x3 material tensor.

For diagonal tensors, only xx, yy, zz are needed. For symmetric tensors, also need xy, xz, yz. For full tensors, all 9 components.

xx, yy, zz

Diagonal components.

Type:: float or array

xy, xz, yz

Off-diagonal components (symmetric).

Type:: float or array, optional

yx, zx, zy

Off-diagonal components (full tensor).

Type:: float or array, optional

xx: Union[float, ndarray]

yy: Union[float, ndarray]

zz: Union[float, ndarray]

xy: Union[float, ndarray] = 0.0

xz: Union[float, ndarray] = 0.0

yz: Union[float, ndarray] = 0.0

yx: Union[float, ndarray, None] = None

zx: Union[float, ndarray, None] = None

zy: Union[float, ndarray, None] = None

is_diagonal()[source]

Check if tensor is diagonal.

Return type:: bool

is_symmetric()[source]

Check if tensor is symmetric.

Return type:: bool

to_full_matrix(backend)[source]

Convert to full 3x3 matrix representation.

Returns:: Tensor as 3x3 matrix or (…, 3, 3) array for spatially varying.
Return type:: ndarray

__init__(xx, yy, zz, xy=0.0, xz=0.0, yz=0.0, yx=None, zx=None, zy=None)

Helper Functions

prismo.materials.tensor.create_uniaxial_material(n_ordinary, n_extraordinary, optic_axis='z', name='')[source]

Create a uniaxial material (e.g., liquid crystal).

Uniaxial materials have different refractive indices parallel and perpendicular to the optic axis.

Parameters:

n_ordinary (float) – Ordinary refractive index (perpendicular to optic axis).
n_extraordinary (float) – Extraordinary refractive index (parallel to optic axis).
optic_axis (str) – Optic axis direction (‘x’, ‘y’, or ‘z’).
name (str) – Material name.

Returns:

Uniaxial material with diagonal tensor.

Return type:

TensorMaterial

prismo.materials.tensor.create_biaxial_material(nx, ny, nz, name='')[source]

Create a biaxial material.

Biaxial materials have three different principal refractive indices.

Parameters:

nx (float) – Refractive indices along x, y, z axes.
ny (float) – Refractive indices along x, y, z axes.
nz (float) – Refractive indices along x, y, z axes.
name (str) – Material name.

Returns:

Biaxial material with diagonal tensor.

Return type:

TensorMaterial

ADE Solver

class prismo.materials.ade.ADESolver(material, dt, grid_shape, backend=None)[source]

Auxiliary Differential Equation solver for dispersive materials.

Implements time-domain updates for dispersive materials by solving auxiliary differential equations alongside the main FDTD equations.

For Lorentz materials:: d²P/dt² + γ dP/dt + ω₀² P = ε₀ Δε ω₀² E
For Drude materials:: dJ/dt + γ J = ε₀ ω_p² E
For Debye materials:: dP/dt + P/τ = ε₀ (ε_s - ε_∞) E/τ

Parameters:

material (DispersiveMaterial) – Dispersive material model.
dt (float) – Time step (s).
grid_shape (tuple) – Shape of the spatial grid.
backend (Backend, optional) – Computational backend.

__init__(material, dt, grid_shape, backend=None)[source]

update_polarization(E_field)[source]

Update auxiliary polarization fields.

Parameters:: E_field (array) – Electric field at current time step.
Return type:: None

get_polarization_current()[source]

Get polarization current for updating D field.

D = ε₀ E + P or equivalently: D = ε₀ ε_∞ E + P_dispersive

Returns:: Polarization current ∂P/∂t or J for Drude.
Return type:: array

get_total_permittivity(E_field)[source]

Get effective permittivity including dispersion.

Returns:: Effective relative permittivity.
Return type:: array

class prismo.materials.ade.ADEManager(grid_shape, dt, backend=None)[source]

Manager for multiple ADE solvers in different regions.

Handles spatial distribution of different materials and their corresponding ADE solvers.

Parameters:

grid_shape (tuple) – Shape of the computational grid.
dt (float) – Time step (s).
backend (Backend, optional) – Computational backend.

__init__(grid_shape, dt, backend=None)[source]

add_material_region(material, region_mask)[source]

Add a dispersive material in a specific spatial region.

Parameters:

material (DispersiveMaterial) – Dispersive material model.
region_mask (array) – Boolean mask indicating where material is present.

Return type:

None

update_all(E_field)[source]

Update all ADE solvers.

Parameters:: E_field (array) – Electric field array.
Return type:: None

get_total_polarization()[source]

Get total polarization from all materials.

Returns:: Total polarization current.
Return type:: array

get_effective_permittivity(E_field)[source]

Get effective permittivity distribution.

Parameters:: E_field (array) – Electric field array.
Returns:: Effective relative permittivity.
Return type:: array