Skip to content

Materials and the n/k database

RefractiveIndex: Sellmeier, tabulated nk sources and the built-in materials.db. Docstrings are the source of truth, rendered with mkdocstrings (numpydoc style).

photonics_helper.materials

Refractive index data with spline interpolation and Sellmeier models.

NK_MATERIALS module-attribute 

NK_MATERIALS: tuple[str, ...] = ('AgGaS2', 'AgGaSe2', 'Al2O3', 'AlGaAs', 'AlN', 'As2S3', 'As2Se3', 'BaF2', 'BaTiO3', 'CaF2', 'CdS', 'CdTe', 'Diamond', 'F2', 'Ga2O3', 'GaAs', 'GaN', 'Ge', 'GeAsSe', 'GeO2', 'InGaAs', 'InP', 'KBr', 'KTP', 'LBO', 'LiNbO3', 'LiTaO3', 'MgF2', 'N-BK7', 'N-F2', 'N-SF11', 'PMMA', 'Si', 'Si3N4', 'Si3N4-Ligentec', 'SiC_4H', 'Silica', 'YAG', 'YLF', 'YVO4', 'ZBLAN', 'Zerodur', 'ZnO', 'ZnSe')

NKMaterial module-attribute 

NKMaterial = Literal['AgGaS2', 'AgGaSe2', 'Al2O3', 'AlGaAs', 'AlN', 'As2S3', 'As2Se3', 'BaF2', 'BaTiO3', 'CaF2', 'CdS', 'CdTe', 'Diamond', 'F2', 'Ga2O3', 'GaAs', 'GaN', 'Ge', 'GeAsSe', 'GeO2', 'InGaAs', 'InP', 'KBr', 'KTP', 'LBO', 'LiNbO3', 'LiTaO3', 'MgF2', 'N-BK7', 'N-F2', 'N-SF11', 'PMMA', 'Si', 'Si3N4', 'Si3N4-Ligentec', 'SiC_4H', 'Silica', 'YAG', 'YLF', 'YVO4', 'ZBLAN', 'Zerodur', 'ZnO', 'ZnSe']

RefractiveIndex

Wavelength-dependent complex refractive index (n + ik).

Stores tabulated n and k values and interpolates via cubic splines.

Attributes:

Name Type Description
n real part of refractive index.
k imaginary part (extinction coefficient).
wl wavelength array (um).

n instance-attribute 

n: NDArray

k instance-attribute 

k: NDArray

wl instance-attribute 

wl: WavelengthArray

nk cached property 

nk: NDArray

from_complex classmethod 

from_complex(nk: ArrayLike, wl: WavelengthArray) -> Self

Construct from a complex refractive index array.

n_func 

n_func(wavelength: float) -> float

Interpolated real refractive index n at wavelength (μm).

k_func 

k_func(wavelength: float) -> float

Interpolated extinction coefficient k at wavelength (μm).

nk_func 

nk_func(wavelength: float) -> complex

Interpolated complex refractive index n+ik at wavelength (μm).

dn_dlambda 

dn_dlambda(wavelength: float) -> float

Derivative dn/dλ at a scalar wavelength (μm). Returns value in μm⁻¹.

group_index 

group_index(wavelength: float) -> float

Group index n_g = n - λ·(dn/dλ) at a scalar wavelength (μm). Dimensionless.

group_index_array 

group_index_array() -> NDArray

Group index n_g across the full wavelength grid. Dimensionless.

group_velocity 

group_velocity(wavelength: float) -> float

Group velocity v_g = c / n_g at a scalar wavelength (μm). Returns m/s.

Warns if n_g approaches zero (division-by-zero guard).

group_velocity_array 

group_velocity_array() -> NDArray

Group velocity v_g across the full wavelength grid. Returns m/s.

plot 

plot(include_k: bool = True)

Plot n (and optionally k) versus wavelength.

from_sellmeier classmethod 

from_sellmeier(A0: float, A: list[float], B: list[float], wl_from_to_in_um: tuple[float, float], n_points=200) -> Self

Construct from a Sellmeier equation: n² = A₀ + Σ Aᵢλ²/(λ² - Bᵢ).

Note: B entries must be squared resonance wavelengths (Bᵢ = λ_res²) in μm², matching the convention in materials.db.

from_alt_sellmeier classmethod 

from_alt_sellmeier(A0: float, A: list[float], B: list[float], wl_from_to_in_um: tuple[float, float], n_points=200) -> Self

Construct from an alternative Sellmeier form: n² = A₀ + Σ Aᵢ/(λ² - Bᵢ²).

Note: unlike :meth:from_sellmeier, B entries here are the unsquared resonance wavelengths in μm (they are squared internally).

from_material_database classmethod 

from_material_database(material: str, n_points: int = 200, axis: str | None = None, db: MaterialsDatabase | None = None) -> Self

Build a RefractiveIndex from materials.db.

Resolution order:

  1. If material is given as a material–author key (contains -), load the matching tabulated n/k spectrum from nk_data. A missing key raises ValueError (no silent Sellmeier fallback), so callers are steered to the dataset browser.
  2. Otherwise (no author requested) fall back to Sellmeier dispersion, preserving the original behavior.

Parameters:

Name Type Description Default
material canonical material name, or a ``material-author`` key.
required
n_points number of samples when interpolating a Sellmeier equation.
200
axis str | None — for birefringent crystals (e.g. LiNbO₃) the

Sellmeier-table sub-row to load: "extraordinary" (or "e") and "ordinary" (or "o") select <material>_er / <material>_or rows (raises ValueError when the sub-row is not seeded). The no-axis canonical row of an axis-bearing material is the extraordinary index by convention (d33-active for x-cut LiNbO₃ χ⁽²⁾ work).

 None
db optional existing ``RamanDatabase`` instance to reuse (mainly for

tests and for callers that already hold a handle).

 None

Raises:

Type Description
ValueError

With an actionable message when the material is unknown, the axis is unknown or unavailable, or the database is missing/empty/corrupt.

propagation_loss 

propagation_loss() -> NDArray

Compute propagation loss (dB/m) from the extinction coefficient k.

Uses intensity attenuation α(λ) = 4πk(λ)/λ, then converts to dB/m: loss = 10·log₁₀(e)·α ≈ 4.343·α

MaterialDataset

One dataset available for a material.

A material may have several: tabulated n/k spectra (one per literature source) and/or a Sellmeier equation.

material instance-attribute 

material: str

kind instance-attribute 

kind: Literal['tabulated', 'sellmeier']

axis class-attribute instance-attribute 

axis: Literal['extraordinary', 'ordinary'] | None = None

source class-attribute instance-attribute 

source: str | None = None

source_key class-attribute instance-attribute 

source_key: str | None = None

wl_min_um class-attribute instance-attribute 

wl_min_um: float | None = None

wl_max_um class-attribute instance-attribute 

wl_max_um: float | None = None

n_points class-attribute instance-attribute 

n_points: int | None = None

doi class-attribute instance-attribute 

doi: str | None = None

citation class-attribute instance-attribute 

citation: str | None = None

license class-attribute instance-attribute 

license: str | None = None

wavelength_range_um property 

wavelength_range_um: tuple[float, float] | None

(min, max) wavelength in µm, or None when unknown.

validate_nk_dataset 

validate_nk_dataset(entry: Any) -> list[str]

Validate a tabulated n/k dataset record.

This is the single shared gate used both by the collector (nk_datasets/collect.py) and by the database seeder (seed_db.py) so that invalid datasets are rejected in exactly one place.

The validator inspects a manifest-style dataset record::

{
    "material": "Si",
    "source": "si-aspnes",
    "citation": "...",
    "wavelengths": [...],   # um, strictly increasing
    "n": [...],
    "k": [...],
}

and returns a list of human-readable error strings. An empty list means the dataset is valid and may be seeded.

material_catalog 

material_catalog(name: str | None = None) -> list[MaterialDataset]

List every dataset available in the bundled material database.

Covers both tabulated n/k spectra and Sellmeier equations, so it is the single place to discover what material data the library ships.

Parameters:

Name Type Description Default
name optional case-insensitive substring filter on the material name

("sil" matches Silica; "sin" matches Si3N4). None returns everything.

 None

Returns:

Type Description
list[MaterialDataset]

One entry per tabulated dataset and per Sellmeier equation, sorted by material name then kind. Each entry carries the wavelength range, the source/citation, a DOI when the citation provides one, and the licence.

Examples:

>>> [d.material for d in material_catalog("Silica")]
['Silica', 'Silica']  # a Sellmeier equation and (if seeded) spectra

print_material_catalog 

print_material_catalog(name: str | None = None) -> None

Print :func:material_catalog as a rich table.

Parameters:

Name Type Description Default
name optional case-insensitive substring filter on the material name.
None

Examples:

>>> print_material_catalog("sil")