Materials and catalog#

Material models#

PyOptik exposes one calculation interface for two source representations:

SellmeierMaterial: Evaluates RefractiveIndex.INFO formula types 1 through 9. Formula datasets are compact and provide smooth dispersion within their stated range.
TabulatedMaterial: Interpolates measured real index n, extinction coefficient k, or combined nk tables. Linear interpolation is the default; monotonic PCHIP is available with interpolation="pchip".

Both support scalar and array wavelengths, provenance, validity policies, derived optical quantities, and plotting.

Find a material by name#

The material(...) shortcut accepts common names, chemical formulas, and canonical IDs. Use it with familiar terms while retaining dataset provenance:

from PyOptik import material, find_materials
from TypedUnit import ureg

glass = material("BK7")
gold = material("gold")
silica = material("SiO2")
water = material("water")
print(gold.nk(633 * ureg.nm))
print(gold.provenance)

Supported family aliases include gold/Au, silver/Ag, silicon/Si, silica/fused silica/SiO2, and water/H2O. Case, accents, spaces, and punctuation are normalized for alias and exact source matching. BK7 and N-BK7 explicitly refer to specs/SCHOTT-optical/N-BK7; this is a naming convention, not a claim that every BK7-type glass is identical. Common names use these fixed source choices. They are convenience defaults, not a ranking of measurement quality:

Documented default datasets#
Names	Canonical dataset	Source
silica, fused silica, SiO2	`main/SiO2/Malitson`	Malitson (1965)
gold, Au	`main/Au/Johnson`	Johnson and Christy (1972)
silver, Ag	`main/Ag/Johnson`	Johnson and Christy (1972)
water, H2O	`main/H2O/Hale`	Hale and Querry (1973)
BK7, N-BK7	`specs/SCHOTT-optical/N-BK7`	SCHOTT

catalog_id and provenance expose the resolved source on every loaded model. For reproducible work, record that identity, the source reference, and the snapshot version/checksum. Pass a canonical ID to pin the page. If a documented default is missing from a custom catalog, the lookup raises an error; it never substitutes another measurement. Silicon/Si has no convenience default and requires a source when its family is ambiguous.

Other queries first match an exact catalog book or page name, then use case-insensitive catalog text search. Spelling suggestions are offered for unknown names; they are never loaded automatically.

Choose a scientific source#

Different measurements of the same material can have different wavelength ranges, temperatures, phases, or fabrication conditions. A supplied source always overrides the convenience default. find_materials always lists all matching datasets, even for a name with a default:

for page in find_materials("Au"):
    print(page.id.key, page.description)

# An exact page ID takes precedence over partial source matches.
gold = material("Au", source="Johnson")
same_gold = material("main/Au/Johnson")

Pass use_default=False to require a source when several datasets match:

from PyOptik import AmbiguousMaterialError

try:
    gold = material("Au", use_default=False)
except AmbiguousMaterialError as error:
    print(error)  # Lists dataset descriptions, canonical IDs, and selection syntax.

Names without a documented default also raise this error when ambiguous. source accepts an exact page ID, canonical ID, or text from the catalog source description. If the text still matches several pages (for example, several temperatures from the same author), the lookup remains ambiguous. Use the complete page ID or canonical path to select a specific measurement. find_materials returns pages without loading models; ambiguity exceptions also expose these pages in their candidates attribute.

An existing local catalog is read without a network request. If no index exists, the first lookup downloads the upstream snapshot. Missing selected page data raises the existing setup error. Specify data_root for a custom cache or catalog for an existing, fully offline catalog:

from PyOptik import MaterialCatalog

catalog = MaterialCatalog.from_snapshot(data_root="./optical-data")
gold = material("Au", source="Johnson", catalog=catalog, interpolation="pchip")

load_material(...) is equivalent to material(...). The existing PyOptik.material package remains importable for code using material classes or submodules.

Catalog organization#

RefractiveIndex.INFO organizes pages as shelf / book / page. PyOptik keeps that complete identity to prevent short-name collisions:

from PyOptik import MaterialCatalog

catalog = MaterialCatalog.from_snapshot()
page = catalog.get("main/Si/Aspnes")
silicon = page.load(interpolation="pchip")

Search and selection#

Search matches canonical IDs, names, descriptions, and source URLs. Filters can narrow results by shelf, book, reference text, or local availability:

matches = catalog.search("BK7", shelf="specs", available=True)
for page in matches:
    print(page.id, page.description)

Use Catalog browser for the same workflow in an interactive terminal.

Provenance and integrity#

Catalog pages and loaded materials retain complementary provenance records:

page_record = page.provenance()
material_record = page.load().provenance
integrity = catalog.verify_integrity()

These records include canonical identity, source URL, local path, scientific reference, experimental conditions, comments, and validity range where available. Set PYOPTIK_DATA_DIR or pass data_root=... for a custom snapshot location.