materials.registry

MaterialRegistry — global singleton for material lookup.

Owns the complete lookup table for both built-in and user-registered materials. Wraps the existing catalog_nk.csv load and adds user catalog state.

The hot path (built-in CSV lookup) adds zero overhead compared to PR1: the built-in DataFrame is lazy-loaded once per process and cached, exactly as before.

Kramer Harrison, 2025

Classes

MaterialRegistry()

Global singleton owning all material lookup state (built-in + user).
class MaterialRegistry[source]

Global singleton owning all material lookup state (built-in + user).

Access via MaterialRegistry.instance(). All methods are safe to call from any thread after the first instance() call completes.

On the first call to instance() the registry checks for ~/.optiland/catalogs/. Each subdirectory there is ingested via load_catalog() as a best-effort operation; failures emit OptilandMaterialWarning and are skipped, never raising.

:param None — instantiate via instance().:

property built_in_df: pandas.DataFrame

Lazy-loaded, cached built-in catalog DataFrame.

classmethod instance() → MaterialRegistry[source]

Return the process-wide singleton, creating it on first call.

list_catalogs(group: str | None = None) → list[str][source]

Return sorted unique catalog names, optionally filtered by group.

Parameters:

group – If given, restrict results to this group (e.g. 'glass', 'main', 'organic', 'other', '3d').

list_groups() → list[str][source]

Return sorted unique group names (built-in + user-registered).

list_materials(catalog: str | None = None) → list[str][source]

Return sorted material names, optionally filtered to one catalog.

Parameters:

catalog – If given, restrict results to this catalog name.

Returns:

Sorted list of material filename_no_ext values.

load_catalog(directory: str | Path) → None[source]

Load all YAML files found in directory.

If a catalog.csv index exists (same schema as the built-in catalog_nk.csv), it is used directly. Otherwise each .yml file is registered via register_file().

Parameters:

directory – Path to a directory of refractiveindex.info YAML files.

register(name: str, catalog: str, data: dict) → None[source]

Register a material programmatically.

The data dict must follow the refractiveindex.info YAML schema. If a built-in or previously-registered entry with the same (name, catalog) key exists, it is shadowed and a warning is emitted.

Parameters:

  • name – Material name (used for lookup).

  • catalog – Catalog name (e.g. "internal").

  • data – refractiveindex.info YAML payload as a Python dict.

register_file(path: str | Path) → None[source]

Load a single refractiveindex.info-format YAML file.

The catalog name is inferred from the parent directory name. The material name is the filename stem (without extension).

Parameters:

path – Path to a refractiveindex.info YAML file.

resolve(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) → str[source]

Return the absolute path to the resolved YAML data file.

Parameters:

  • name – Material name to search for.

  • catalog – Manufacturer catalog to restrict lookup to.

  • reference – Citation string for further disambiguation.

  • match_policy – Controls fuzzy-match warnings/errors.

  • min_wavelength – Minimum wavelength filter (µm).

  • max_wavelength – Maximum wavelength filter (µm).

Returns:

Absolute path to the resolved YAML data file.

Raises:

ValueError – If no match found, or if match_policy='strict' and the match is not exact / is ambiguous.