materials.material_spec

MaterialSpec and MatchPolicy for the Optiland materials system.

Provides the canonical type-safe spec for surface material assignment and a three-value enum controlling fuzzy-match behavior.

Kramer Harrison, 2025

Classes

MatchPolicy(*values)	Controls how Material resolves ambiguous name matches.
MaterialSpec(name[, catalog, reference, ...])	Canonical, type-safe specification for a surface material.

class MatchPolicy(*values)

Controls how Material resolves ambiguous name matches.

Variables:

• BEST – Silent best-match; no warning emitted.

• WARN – Warn when fuzzy match is used (edit distance > 0). Default.

• STRICT – Raise ValueError on any non-exact or ambiguous match.

BEST = 'best'

STRICT = 'strict'

WARN = 'warn'

class MaterialSpec(name: str, catalog: str | None = None, reference: str | None = None, match_policy: MatchPolicy = MatchPolicy.WARN, min_wavelength: float | None = None, max_wavelength: float | None = None)

Canonical, type-safe specification for a surface material.

Instances are frozen (hashable) and safe to cache. Pass to MaterialFactory.create() or call .to_material() directly.

Parameters:

• name – Glass or material name (e.g. "N-BK7").

• catalog – Manufacturer catalog to restrict lookup to (e.g. "schott").

• reference – Citation string (passed through to Material).

• match_policy – Controls fuzzy-match warnings/errors.

• min_wavelength – Minimum wavelength filter in microns.

• max_wavelength – Maximum wavelength filter in microns.

catalog: str | None = None

classmethod from_dict(data: dict) → MaterialSpec

Deserialize a MaterialSpec from a plain dictionary.

Parameters:

data – Dictionary with at least a "name" key.

Returns:

MaterialSpec instance.

match_policy: MatchPolicy = 'warn'

max_wavelength: float | None = None

min_wavelength: float | None = None

name: str

reference: str | None = None

to_dict() → dict

Serialize this spec to a plain dictionary.

to_material() → Material

Resolve this spec to a concrete Material instance.