API reference#

This page documents the public classes and functions. For task-oriented introductions, begin with Getting started or Example gallery.

Public API#

Below, you will find detailed, automatically generated documentation for significant classes and functions in the PyOptik library. These descriptions are intended to help you understand how each class and function fits into the overall framework, and how to utilize them effectively in your projects.

Material discovery#

Call material(name, source=...) after from PyOptik import material. The equivalent load_material function documents the full call signature.

load_material(name: str, *, source: str | None = None, catalog: MaterialCatalog | None = None, data_root: Path | str | None = None, interpolation: str = 'linear', use_default: bool = True)[source]#

Load a material by name with documented defaults and source overrides.

This is also available as from PyOptik import material; material(...). Common names use documented canonical defaults unless source is supplied or use_default is False. Other ambiguous queries raise an error listing sources and canonical IDs. Ordering and cache availability never select a dataset.

Parameters:

  • name (str) – Common name, chemical formula, glass name, or canonical page ID.

  • source (str, optional) – Exact page ID or source-description text. Use the exact ID when a source publishes several datasets or measurement conditions.

  • catalog (MaterialCatalog, optional) – Existing catalog for custom data or offline operation.

  • data_root (pathlib.Path or str, optional) – Snapshot directory. Cannot be combined with catalog.

  • interpolation ({"linear", "pchip"}, optional) – Interpolation for tabulated data; ignored for formula models.

  • use_default (bool, optional) – Use the documented source for a known family alias (default True). Set False to require a source whenever several datasets match.

Returns:

Loaded model, retaining canonical ID and scientific provenance.

Return type:

SellmeierMaterial or TabulatedMaterial

Raises:

  • AmbiguousMaterialError – More than one dataset matches and no documented default applies, or use_default is False. Inspect candidates or use find_materials.

  • ValueError – Empty name or source, or conflicting catalog/data_root arguments.

  • TypeError – Name or source is not a string, or use_default is not a bool.

  • KeyError – No material or source matches; includes spelling suggestions when possible.

  • FileNotFoundError – The chosen page has no local data. Run pyoptik setup to repair the cache.

Notes

Defaults are main/SiO2/Malitson for silica, main/Au/Johnson for gold, main/Ag/Johnson for silver, and main/H2O/Hale for water. BK7 and N-BK7 refer explicitly to specs/SCHOTT-optical/N-BK7. Loaded models expose catalog_id and provenance. A missing default never falls back to another dataset. See the materials-and-catalog guide for the full source table.

Examples

>>> from PyOptik import material
>>> gold = material("gold", source="Johnson")  
>>> gold.catalog_id  
'main/Au/Johnson'
find_materials(name: str, *, source: str | None = None, catalog: MaterialCatalog | None = None, data_root: Path | str | None = None) → list[MaterialPage][source]#

Find material datasets by common name, formula, or canonical identity.

Parameters:

  • name (str) – Common name (gold, fused silica, water), formula (Au, SiO2), glass name (BK7, N-BK7), or canonical shelf/book/page ID. BK7 is an explicit alias for SCHOTT N-BK7. Other aliases select families; find_materials always returns all sources.

  • source (str, optional) – Page ID, canonical ID, or source-description text. Exact page IDs take precedence over partial matches.

  • catalog (MaterialCatalog, optional) – Existing catalog, including custom or offline catalogs.

  • data_root (pathlib.Path or str, optional) – Snapshot location. Cannot be combined with catalog.

Returns:

Candidates in canonical order, or an empty list if none match.

Return type:

list of MaterialPage

Notes

Names and source descriptions ignore case, accents, spaces, and punctuation for exact matching. General text search uses the catalog’s case-insensitive substring search. The first lookup downloads the snapshot if no local index exists. An existing index is read locally without a network request.

exception AmbiguousMaterialError(name: str, candidates: list[MaterialPage])[source]#

Bases: ValueError

A name or source matches several scientific datasets.

candidates#

Matching pages in canonical order, including descriptions and provenance.

Type:

list of MaterialPage

Catalog#

PyOptik preserves the upstream shelf / book / page organization used by RefractiveIndex.INFO. The catalog API is useful when source provenance matters or when downloading a complete material collection.

class MaterialId(shelf: str, book: str, page: str)[source]#

Bases: object

Canonical upstream identity: shelf, book, and page.

class MaterialPage(id: MaterialId, name: str, data_path: str | None = None, source_url: str | None = None, description: str | None = None, metadata: dict | None = None, data_root: Path | None = None)[source]#

Bases: object

A catalog page and its associated optical-data file.

class MaterialCatalog(catalog_file: Path | str | None = None, data_root: Path | str | None = None)[source]#

Bases: object

Browse and download materials using the upstream hierarchy.

download_snapshot(data_root: Path | str | None = None, *, force: bool = False, progress=None) → MaterialCatalog[source]#

Download and activate the complete upstream material snapshot.

Parameters:

  • data_root (pathlib.Path or str, optional) – Directory where the snapshot should be stored.

  • force (bool, optional) – Refresh an existing snapshot.

  • progress (callable, optional) – Callback receiving (downloaded_bytes, total_bytes).

Returns:

Catalog backed by the downloaded snapshot.

Return type:

MaterialCatalog

Examples

>>> from PyOptik import download_snapshot
>>> catalog = download_snapshot()
>>> silver = catalog.get("main/Ag/Johnson").load()

Material models#

Sellmeier material#

The SellmeierMaterial class extends the Material base class to handle materials defined by the Sellmeier equation. It allows for precise modeling of refractive indices using parameters from the Sellmeier formula, which is essential for optical design and simulation.

class SellmeierMaterial(filename: str, file_path=None)[source]#

Bases: BaseMaterial

Class representing a material with Sellmeier coefficients for refractive index computation.

filename#

The name of the YAML file containing material properties.

Type:

str

coefficients#

The Sellmeier coefficients used for calculating the refractive index.

Type:

numpy.ndarray

wavelength_range#

The allowable wavelength range for the material in micrometers.

Type:

Optional[Tuple[float, float]]

reference#

Reference information for the material data.

Type:

Optional[str]

formula_type#

The formula type to use for refractive index calculation.

Type:

int

Tabulated material#

The TabulatedMaterial class extends the Material base class to handle materials characterized by tabulated refractive index and absorption values. This class is particularly useful when working with empirical data from experiments or literature.

class TabulatedMaterial(filename: str, file_path=None, interpolation: str = 'linear')[source]#

Bases: BaseMaterial

Class representing a material with tabulated refractive index (n) and absorption (k) values.

filename#

The name of the YAML file containing material properties.

Type:

str

wavelength#

Array of wavelengths in micrometers for which the refractive index and absorption values are tabulated.

Type:

numpy.ndarray

n_values#

Array of tabulated refractive index values (n) corresponding to the wavelengths.

Type:

numpy.ndarray

k_values#

Array of tabulated absorption values (k) corresponding to the wavelengths.

Type:

numpy.ndarray

reference#

Reference information for the material data.

Type:

Optional[str]

Base material#

class BaseMaterial[source]#

Bases: object

Common interface for refractive-index material models.

Subclasses provide compute_refractive_index(); this class supplies unit handling, validity-range checks, and group-delay calculations.

Typed material documents#

These immutable data objects provide the validated representation shared by catalog loading, user-defined material construction, and YAML export.

class MaterialMetadata(reference: str | None = None, conditions: ~typing.Mapping[str, ~typing.Any] = <factory>, comments: str | None = None)[source]#

Bases: object

Source metadata shared by formula and tabulated datasets.

class FormulaDataset(formula_type: int, coefficients: tuple[float, ...], wavelength_range: tuple[float, float] | None = None)[source]#

Bases: object

A validated RefractiveIndex.INFO formula dataset.

class TabulatedDataset(kind: str, wavelength_um: tuple[float, ...], values: tuple[tuple[float, ...], ...])[source]#

Bases: object

One validated table of n, k, or combined nk values.

class MaterialDocument(datasets: tuple[~PyOptik.material.dataset.FormulaDataset | ~PyOptik.material.dataset.TabulatedDataset, ...], metadata: ~PyOptik.material.dataset.MaterialMetadata = <factory>)[source]#

Bases: object

A parsed optical-material document and its provenance metadata.

parse_material(source: str | Path | Mapping[str, Any]) → MaterialDocument[source]#

Parse and validate a material YAML path or already-loaded mapping.

Interface and thin-film optics#

class FresnelResult(reflection_amplitude: Any, transmission_amplitude: Any, reflectance: Any, transmittance: Any, absorptance: Any, transmitted_angle: Any)[source]#

Bases: object

Amplitude coefficients and power fractions at one interface.

class ThinFilmLayer(material: Any, thickness: Any)[source]#

Bases: object

One homogeneous layer in a coherent optical stack.

Parameters:

  • material (complex or BaseMaterial) – Constant complex refractive index or a PyOptik material model.

  • thickness (Length) – Physical layer thickness. Bare numbers are interpreted as metres.

class ThinFilmResult(reflection_amplitude: Any, transmission_amplitude: Any, reflectance: Any, transmittance: Any, absorptance: Any)[source]#

Bases: object

Coherent reflection, transmission, and absorption of a layer stack.

fresnel_coefficients(incident_index, transmitted_index, angle=0.0, *, polarization: str = 's', wavelength=None) → FresnelResult[source]#

Calculate Fresnel amplitude coefficients and power fractions.

Parameters:

  • incident_index (complex or BaseMaterial) – Refractive indices or material models on either side of the interface.

  • transmitted_index (complex or BaseMaterial) – Refractive indices or material models on either side of the interface.

  • angle (float or angle quantity, optional) – Incidence angle. Bare values are radians.

  • polarization ({"s", "p"}, optional) – Electric-field polarization.

  • wavelength (Length, optional) – Required when either index is a wavelength-dependent material model.

brewster_angle(incident_index, transmitted_index, *, wavelength=None)[source]#

Return the p-polarized Brewster angle for two lossless media.

critical_angle(incident_index, transmitted_index, *, wavelength=None)[source]#

Return the total-internal-reflection critical angle.

Raises:

ValueError – If the media are absorbing or the incident index is not larger than the transmitted index.

thin_film_stack(wavelength, layers: Iterable[ThinFilmLayer | tuple[Any, Any]], *, incident_index=1.0, substrate_index=1.0, angle=0.0, polarization: str = 's') → ThinFilmResult[source]#

Evaluate a coherent isotropic multilayer using characteristic matrices.

Wavelength may be scalar or one-dimensional. Layers may be ThinFilmLayer objects or (material, thickness) tuples. All layers are treated as optically coherent; surface roughness, incoherent substrates, anisotropy, and magnetic media are outside this model.

Enumerations#

class MaterialType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: Enum

Enumeration of material data representations.