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, *, source=None, catalog=None, data_root=None, interpolation='linear', use_default=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, *, source=None, catalog=None, data_root=None)[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, candidates)[source]#

Bases: ValueError

A name or source matches several scientific datasets.

Variables:

candidates (list of MaterialPage) – Matching pages in canonical order, including descriptions and provenance.

Parameters:

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, book, page)[source]#

Bases: object

Canonical upstream identity: shelf, book, and page.

Parameters:
  • shelf (str)

  • book (str)

  • page (str)

book: str#
property key: str#

Return the canonical identifier as a string.

page: str#
shelf: str#
class MaterialPage(id, name, data_path=None, source_url=None, description=None, metadata=None, data_root=None)[source]#

Bases: object

A catalog page and its associated optical-data file.

Parameters:
  • id (MaterialId)

  • name (str)

  • data_path (str | None)

  • source_url (str | None)

  • description (str | None)

  • metadata (dict | None)

  • data_root (Path | None)

property available: bool#

Whether this page’s data file is available in the local cache.

data_path: str | None = None#
data_root: Path | None = None#
description: str | None = None#
id: MaterialId#
load(*, interpolation='linear')[source]#

Load this page as the appropriate PyOptik material object.

Parameters:

interpolation ({"linear", "pchip"}, optional) – Tabulated-data interpolation method. Formula materials ignore this option.

Returns:

Material model selected from the local YAML data type.

Return type:

SellmeierMaterial or TabulatedMaterial

Raises:
  • FileNotFoundError – If the page has not been downloaded locally.

  • ValueError – If the file contains no supported optical dataset.

property local_path: Path | None#

Return the local cached path, if a data path is known.

metadata: dict | None = None#
name: str#
provenance()[source]#

Return the canonical identity and source information for this page.

Returns:

Serializable identity, cache-path, availability, and source fields.

Return type:

dict

property reference: str | None#

Return the local source reference, when the page has been cached.

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

Bases: object

Browse and download materials using the upstream hierarchy.

Parameters:
  • catalog_file (Path | str | None)

  • data_root (Path | str | None)

books(shelf=None)[source]#

Return sorted book identifiers, optionally within one shelf.

Parameters:

shelf (str, optional) – Restrict the result to this shelf.

Returns:

Unique book identifiers.

Return type:

list of str

download(shelf=None, book=None, *, force=False, continue_on_error=False, progress=None, workers=1)[source]#

Download matching pages into a resumable hierarchical cache.

Parameters:
  • shelf (str, optional) – Optional hierarchy filters.

  • book (str, optional) – Optional hierarchy filters.

  • force (bool, optional) – Re-download files even when a local copy already exists.

  • continue_on_error (bool, optional) – Record failures and continue with remaining pages. If false, the first download error is raised.

  • progress (callable, optional) – Callback receiving (completed, total, page, status) after each page. Status is one of "downloaded", "cached", "skipped", "snapshot", or "error".

  • workers (int, optional) – Number of concurrent page downloads. Keep this bounded to respect the upstream service.

Returns:

Pages selected by the filters.

Return type:

list of MaterialPage

download_all(*, force=False, continue_on_error=True, progress=None, workers=1)[source]#

Download every page in the catalog.

Parameters:
  • force (bool, optional) – Re-download all files instead of using local copies.

  • continue_on_error (bool, optional) – Continue after failed pages and record failures in the manifest.

  • progress (callable, optional) – Callback receiving (completed, total, page, status).

  • workers (int, optional) – Number of concurrent page downloads.

Returns:

All catalog pages.

Return type:

list of MaterialPage

classmethod from_snapshot(data_root=None, url='https://github.com/polyanskiy/refractiveindex.info-database/archive/refs/heads/main.zip', force=False, progress=None)[source]#

Download and extract the complete upstream database snapshot.

Parameters:
  • data_root (pathlib.Path or str, optional) – Root directory where the upstream database contents are extracted.

  • url (str, optional) – URL of a ZIP archive containing the upstream database.

  • force (bool, optional) – Download the archive even when a catalog is already present.

  • progress (callable, optional) – Callback receiving (downloaded_bytes, total_bytes) while the archive is downloaded.

Returns:

Catalog backed by the extracted snapshot.

Return type:

MaterialCatalog

classmethod from_upstream(data_root=None, url='https://raw.githubusercontent.com/polyanskiy/refractiveindex.info-database/main/database/catalog-nk.yml')[source]#

Download and load the current upstream catalog index.

Parameters:
  • data_root (pathlib.Path or str, optional) – Directory used for the catalog index and downloaded pages.

  • url (str, optional) – Catalog YAML URL.

Returns:

Catalog indexed from the downloaded upstream YAML file.

Return type:

MaterialCatalog

get(identifier, book=None, page=None)[source]#

Get a page by MaterialId, canonical path, or components.

Parameters:
  • identifier (MaterialId or str) – Canonical identifier, or shelf when book and page are set.

  • book (str, optional) – Remaining canonical hierarchy components.

  • page (str, optional) – Remaining canonical hierarchy components.

Returns:

The selected catalog page.

Return type:

MaterialPage

Raises:

KeyError – If the identifier is unknown or incomplete.

load_catalog(catalog_file)[source]#

Load an upstream catalog-nk.yml file.

Parameters:

catalog_file (Path | str)

Return type:

None

property manifest_path: Path#

Return the path of the resumable download manifest.

pages(shelf=None, book=None)[source]#

Return pages filtered by shelf and/or book.

Parameters:
  • shelf (str, optional) – Canonical hierarchy filters.

  • book (str, optional) – Canonical hierarchy filters.

Returns:

Matching pages in canonical identifier order.

Return type:

list of MaterialPage

search(query=None, *, shelf=None, book=None, source=None, reference=None, available=None)[source]#

Search catalog pages by text and provenance-aware filters.

Text matching is case-insensitive and covers canonical IDs, page names, catalog descriptions, and source URLs. reference filters the local YAML REFERENCES field, so it requires cached pages. Set available=True to restrict results to local pages. Each result exposes MaterialPage.provenance() for a source record.

Parameters:
  • query (str, optional) – Case-insensitive text query.

  • shelf (str, optional) – Canonical hierarchy filters.

  • book (str, optional) – Canonical hierarchy filters.

  • source (str, optional) – Case-insensitive source-URL filter.

  • reference (str, optional) – Case-insensitive local YAML reference filter.

  • available (bool, optional) – Restrict results by cache availability.

Returns:

Matching pages in canonical identifier order.

Return type:

list of MaterialPage

shelves()[source]#

Return sorted upstream shelf identifiers.

Returns:

Unique shelf identifiers represented in the catalog.

Return type:

list of str

verify_integrity()[source]#

Verify checksums recorded in the local download manifest.

Pages without a recorded checksum are omitted. The returned mapping is keyed by canonical material identity, allowing callers to identify and re-download only altered or incomplete cached files.

Returns:

Whether every manifest-recorded page matches its SHA-256 digest.

Return type:

dict of MaterialId to bool

download_snapshot(data_root=None, *, force=False, progress=None)[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, file_path=None)[source]#

Bases: BaseMaterial

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

Variables:
  • filename (str) – The name of the YAML file containing material properties.

  • coefficients (numpy.ndarray) – The Sellmeier coefficients used for calculating the refractive index.

  • wavelength_range (Optional[Tuple[float, float]]) – The allowable wavelength range for the material in micrometers.

  • reference (Optional[str]) – Reference information for the material data.

  • formula_type (int) – The formula type to use for refractive index calculation.

Parameters:

filename (str)

classmethod from_coefficients(name, coefficients, *, formula_type=1, wavelength_range=None, reference=None, conditions=None, comments=None)[source]#

Construct a formula material without an intermediate YAML file.

wavelength_range may be a unit-bearing two-element quantity or a pair interpreted as micrometres.

Parameters:
  • name (str)

  • formula_type (int)

  • reference (str | None)

  • comments (str | None)

to_yaml(path)[source]#

Export this material as a validated, reloadable YAML document.

compute_refractive_index(wavelength, out_of_range='warn', *, validation='warn', allow_negative_index=False, allow_gain=False)[source]#

Computes the refractive index n(u03bb) using the appropriate RefractiveIndex.INFO dispersion formula (types 1 through 9).

Parameters:
  • wavelength (Length | float) – The wavelength u03bb in meters, can be a single float or a numpy array.

  • out_of_range ({"warn", "raise", "clip"}, optional) – Policy for wavelengths outside the source validity range.

  • validation ({"ignore", "warn", "raise"}, optional) – Optical-constant validation policy (default “warn”). Nonfinite results always raise. Checks apply to the evaluated samples only.

  • allow_negative_index (bool, optional) – Permit zero or negative real index without a validation diagnostic.

  • allow_gain (bool, optional) – Permit negative extinction coefficients (gain) without a diagnostic.

Returns:

The refractive index n(u03bb) for the given wavelength or array of wavelengths.

Return type:

RefractiveIndex

Raises:

ValueError – If the wavelength is outside the specified range or if an unsupported formula type is encountered.

plot(axes=None, samples=100)[source]#

Plots the refractive index as a function of wavelength over a specified range.

Parameters:
  • axes (matplotlib.axes.Axes, optional) – Axes on which to draw the dispersion curve. A compact, styled figure is created when omitted.

  • samples (int) – The number of samples to use for the wavelength range.

Returns:

The supplied axes are modified in place.

Return type:

None

Raises:

ValueError – If the wavelength is not a 1D array or list of float values.

print()[source]#

Provides a formal string representation of the Material object, including key attributes.

Returns:

Formal representation of the Material object.

Return type:

str

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, file_path=None, interpolation='linear')[source]#

Bases: BaseMaterial

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

Variables:
  • filename (str) – The name of the YAML file containing material properties.

  • wavelength (numpy.ndarray) – Array of wavelengths in micrometers for which the refractive index and absorption values are tabulated.

  • n_values (numpy.ndarray) – Array of tabulated refractive index values (n) corresponding to the wavelengths.

  • k_values (numpy.ndarray) – Array of tabulated absorption values (k) corresponding to the wavelengths.

  • reference (Optional[str]) – Reference information for the material data.

Parameters:
  • filename (str)

  • interpolation (str)

classmethod from_arrays(name, wavelength, *, n=None, k=None, interpolation='linear', reference=None, conditions=None, comments=None)[source]#

Construct a tabulated material from wavelength, n, and k arrays.

classmethod from_csv(path, *, name=None, wavelength_unit=<Unit('micrometer')>, wavelength_column='wavelength', n_column='n', k_column='k', missing_k=None, **kwargs)[source]#

Construct a material from a header-based CSV file.

Missing columns are allowed; missing cells in present columns raise ValueError. Set missing_k to a finite replacement (for example 0.0) to fill empty extinction cells explicitly. Missing n is never inferred.

to_arrays(*, validation='warn', allow_negative_index=False, allow_gain=False)[source]#

Return independent wavelength, n, and k arrays on a common grid.

Wavelengths carry micrometre units. The grid is the sorted union of both component grids within their shared range, including its bounds. Missing n defaults to 1 and missing k to 0, as during evaluation. Validation options are forwarded to compute_refractive_index. Linear interpolation is exactly preserved inside this range. For pchip, the returned values are samples, not cubic coefficients.

to_yaml(path)[source]#

Export this material as a validated, reloadable YAML document.

compute_refractive_index(wavelength, out_of_range='warn', *, validation='warn', allow_negative_index=False, allow_gain=False)[source]#

Interpolates the refractive index (n) and absorption (k) values for the given wavelength(s).

Parameters:
  • wavelength (Length | float) – Wavelength(s) in micrometers for which to interpolate n and k.

  • out_of_range ({"warn", "raise", "clip"}, optional) – Policy for wavelengths outside the tabulated range.

  • validation ({"ignore", "warn", "raise"}, optional) – Optical-constant validation policy (default “warn”). Nonfinite results always raise. Checks apply to the evaluated samples only.

  • allow_negative_index (bool, optional) – Permit zero or negative real index without a validation diagnostic.

  • allow_gain (bool, optional) – Permit negative extinction coefficients (gain) without a diagnostic.

Returns:

Complex refractive index values (n + i*k). A scalar input returns a scalar complex value; array-like input returns an array.

Return type:

complex or numpy.ndarray

Raises:

ValueError – If the wavelength is outside the tabulated range.

plot(axes=None, samples=100)[source]#

Plots the tabulated refractive index (n) and absorption (k) as a function of wavelength.

Parameters:
  • axes (matplotlib.axes.Axes, optional) – Axes on which to draw the curves. A compact, styled figure is created when omitted.

  • samples (int) – The number of samples to use for the wavelength range.

Returns:

The supplied axes and its absorption twin are modified in place.

Return type:

None

Raises:

ValueError – If the wavelength is not a 1D array or list of float values.

print()[source]#

Provides a formal string representation of the TabulatedMaterial object, including key attributes.

Returns:

Formal representation of the TabulatedMaterial object.

Return type:

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.

property provenance: dict#

Return source and validity metadata for this material.

Returns:

Material name, source file, reference, conditions, validity range, and catalog identity when the material was loaded from a catalog.

Return type:

dict

refractive_index(wavelength, **kwargs)[source]#

Return the complex refractive index n + i k.

Parameters:
  • wavelength (Length) – Vacuum wavelength.

  • **kwargs – Forwarded to compute_refractive_index().

Returns:

Complex refractive index.

Return type:

complex or numpy.ndarray

nk(wavelength, **kwargs)[source]#

Return the complex refractive index n + i k.

Parameters:
  • wavelength (Length) – Vacuum wavelength, as a scalar or array with units.

  • **kwargs – Forwarded to compute_refractive_index(), including out_of_range.

Returns:

Complex refractive index. Alias of refractive_index().

Return type:

complex or numpy.ndarray

n(wavelength, **kwargs)[source]#

Return the real refractive index.

Parameters:
  • wavelength (Length) – Vacuum wavelength.

  • **kwargs – Forwarded to compute_refractive_index().

Returns:

Real part of the complex refractive index.

Return type:

float or numpy.ndarray

k(wavelength, **kwargs)[source]#

Return the extinction coefficient.

Parameters:
  • wavelength (Length) – Vacuum wavelength.

  • **kwargs – Forwarded to compute_refractive_index().

Returns:

Imaginary part of the complex refractive index.

Return type:

float or numpy.ndarray

relative_permittivity(wavelength, **kwargs)[source]#

Return relative complex permittivity, (n + i k)².

Parameters:
  • wavelength (Length) – Vacuum wavelength.

  • **kwargs – Forwarded to compute_refractive_index().

Returns:

Relative complex permittivity.

Return type:

complex or numpy.ndarray

absorption_coefficient(wavelength, **kwargs)[source]#

Return the intensity absorption coefficient, α = 4πk / λ.

Parameters:
  • wavelength (Length) – Vacuum wavelength.

  • **kwargs – Forwarded to k().

Returns:

Absorption coefficient with inverse-length units.

Return type:

AnyUnit

ensure_units()[source]#

Decorator ensuring the wavelength argument carries ureg.

Parameters:

func (Callable) – Function that expects a wavelength Quantity.

Returns:

Wrapped version of func that accepts numerical wavelengths and converts them to metre-based Quantity objects.

Return type:

Callable

compute_group_index(wavelength, delta=<Quantity(1, 'nanometer')>)[source]#

Calculate the group refractive index n_g(λ). The group index is defined as n_g(λ) = n(λ) - λ * dn/dλ, where n(λ) is the refractive index and dn/dλ is the derivative of the refractive index with respect to wavelength.

Parameters:
  • wavelength (ureg.Quantity) – Wavelength at which to compute the group index, in metres.

  • delta (ureg.Quantity, optional) – Small change in wavelength for numerical differentiation, default is 1 nanometer.

Returns:

  • ureg.Quantity – Group refractive index at the specified wavelength, in dimensionless ureg.

  • ——-

  • ureg.Quantity – Group refractive index at the specified wavelength, in dimensionless ureg.

Return type:

Length

compute_group_velocity(wavelength)[source]#

Calculate the group velocity v_g(λ) = c / n_g(λ), where c is the speed of light in vacuum and n_g(λ) is the group index.

Parameters:

wavelength (Length) – Wavelength at which to compute the group velocity, in metres.

Returns:

Group velocity at the specified wavelength, in metres per second.

Return type:

AnyUnit

compute_group_delay(wavelength, length=<Quantity(1, 'meter')>)[source]#

Calculate the group delay for a given propagation length.

Parameters:
  • wavelength (Length) – Wavelength at which to compute the group delay, in metres.

  • length (Length, optional) – Propagation length (default is 1 metre).

Returns:

Group delay for the specified wavelength and length.

Return type:

Time

compute_group_delay_wavelength_slope(wavelength, length=<Quantity(1, 'meter')>, delta=<Quantity(1, 'nanometer')>)[source]#

Calculate the wavelength slope dτ_g/dλ for a given length.

This is a wavelength-space derivative, not conventional GDD.

Parameters:
  • wavelength (Length) – Central wavelength for the computation, in metres.

  • length (Length, optional) – Propagation length (default is 1 metre).

  • delta (Length, optional) – Wavelength step used for the numerical differentiation (default is 1 nanometre).

Returns:

Wavelength derivative of group delay evaluated at wavelength.

Return type:

AnyUnit

compute_group_delay_dispersion(wavelength, length=<Quantity(1, 'meter')>, delta_angular_frequency=<Quantity(6.28318531e+12, '1 / second')>)[source]#

Calculate conventional GDD, dτ_g/dω = d²β/dω² × length.

The derivative is evaluated with a centred finite difference in angular frequency and has time-squared units (commonly fs²). Use compute_group_delay_wavelength_slope() for dτ_g/dλ.

Parameters:
  • wavelength (Length) – Central vacuum wavelength.

  • length (Length, optional) – Propagation length.

  • delta_angular_frequency (ureg.Quantity, optional) – Positive centred angular-frequency increment. The default is 2π × 1 THz.

Returns:

Conventional group-delay dispersion with time-squared units.

Return type:

AnyUnit

Raises:
  • TypeError – If delta_angular_frequency does not carry units.

  • ValueError – If delta_angular_frequency is not positive.

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=None, conditions=<factory>, comments=None)[source]#

Bases: object

Source metadata shared by formula and tabulated datasets.

Parameters:
  • reference (str | None)

  • conditions (Mapping[str, Any])

  • comments (str | None)

comments: str | None = None#
conditions: Mapping[str, Any]#
reference: str | None = None#
class FormulaDataset(formula_type, coefficients, wavelength_range=None)[source]#

Bases: object

A validated RefractiveIndex.INFO formula dataset.

Parameters:
  • formula_type (int)

  • coefficients (tuple[float, ...])

  • wavelength_range (tuple[float, float] | None)

coefficients: tuple[float, ...]#
formula_type: int#
wavelength_range: tuple[float, float] | None = None#
class TabulatedDataset(kind, wavelength_um, values)[source]#

Bases: object

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

Parameters:
  • kind (str)

  • wavelength_um (tuple[float, ...])

  • values (tuple[tuple[float, ...], ...])

kind: str#
values: tuple[tuple[float, ...], ...]#
wavelength_um: tuple[float, ...]#
class MaterialDocument(datasets, metadata=<factory>)[source]#

Bases: object

A parsed optical-material document and its provenance metadata.

Parameters:
datasets: tuple[FormulaDataset | TabulatedDataset, ...]#
property formula_datasets: tuple[FormulaDataset, ...]#

Return formula datasets in source order.

metadata: MaterialMetadata#
property tabulated_datasets: tuple[TabulatedDataset, ...]#

Return tabulated datasets in source order.

to_mapping()[source]#

Return a RefractiveIndex.INFO-compatible YAML mapping.

Return type:

dict[str, Any]

to_yaml(path)[source]#

Serialize this document to path and return the resulting path.

Parameters:

path (str | Path)

Return type:

Path

parse_material(source)[source]#

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

Parameters:

source (str | Path | Mapping[str, Any])

Return type:

MaterialDocument

Interface and thin-film optics#

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

Bases: object

Amplitude coefficients and power fractions at one interface.

Parameters:
  • reflection_amplitude (Any)

  • transmission_amplitude (Any)

  • reflectance (Any)

  • transmittance (Any)

  • absorptance (Any)

  • transmitted_angle (Any)

absorptance: Any#
reflectance: Any#
reflection_amplitude: Any#
transmission_amplitude: Any#
transmittance: Any#
transmitted_angle: Any#
class ThinFilmLayer(material, thickness)[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.

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

Bases: object

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

Parameters:
  • reflection_amplitude (Any)

  • transmission_amplitude (Any)

  • reflectance (Any)

  • transmittance (Any)

  • absorptance (Any)

absorptance: Any#
reflectance: Any#
reflection_amplitude: Any#
transmission_amplitude: Any#
transmittance: Any#
fresnel_coefficients(incident_index, transmitted_index, angle=0.0, *, polarization='s', wavelength=None)[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.

Return type:

FresnelResult

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, *, incident_index=1.0, substrate_index=1.0, angle=0.0, polarization='s')[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.

Parameters:
  • layers (Iterable[ThinFilmLayer | tuple[Any, Any]])

  • polarization (str)

Return type:

ThinFilmResult

Enumerations#

class MaterialType(value)[source]#

Bases: Enum

Enumeration of material data representations.

SELLMEIER = 'sellmeier'#
TABULATED = 'tabulated'#