PyOptik 3.0.5__tar.gz → 3.1.0__tar.gz

{pyoptik-3.0.5 → pyoptik-3.1.0}/.github/workflows/deploy_PyPi.yml

@@ -2,18 +2,14 @@ name: Deploy to PyPi
 
 on:
   push:
-    branches: [ "master" ]
-    tags:
-      - '*'
-  pull_request:
-    branches: [ "master" ]
+    tags: [ "v*" ]
 
 permissions:
-    contents: write
+  contents: read
 
 jobs:
   pure_package:
-    uses: MartinPdeS/MPSActions/.github/workflows/publish_pure_package_to_PyPi.yml@master
+    uses: MartinPdeS/MPSActions/.github/workflows/publish_pure_package_to_PyPi.yml@v5
     with:
       python-version: "3.11"
     secrets:

{pyoptik-3.0.5 → pyoptik-3.1.0}/.github/workflows/deploy_anaconda.yml

@@ -2,20 +2,20 @@ name: Deploy Conda Packages
 
 on:
   push:
-    branches: [ "master" ]
-    tags: '*'
-  pull_request:
-    branches: [ "master" ]
+    tags: [ "v*" ]
 
 permissions:
-    contents: write
+  contents: read
 
 jobs:
   linux:
-    uses: MartinPdeS/MPSActions/.github/workflows/publish_compiled_package_to_anaconda.yml@master
+    uses: MartinPdeS/MPSActions/.github/workflows/publish_compiled_package_to_anaconda.yml@v5
     with:
       python_versions: '["3.13"]'
       apt_package: ""
       os_list: '["ubuntu-latest"]'
+      package_name: pyoptik
+      recipe_path: conda.recipe
+      test_import: PyOptik
     secrets:
       ANACONDA_API_TOKEN: ${{ secrets.ANACONDA_API_TOKEN }}

{pyoptik-3.0.5 → pyoptik-3.1.0}/.github/workflows/deploy_coverage.yml

@@ -17,9 +17,10 @@ permissions:
 
 jobs:
   ManyLinux_x86_64:
-    uses: MartinPdeS/MPSActions/.github/workflows/publish_coverage.yml@master
+    uses: MartinPdeS/MPSActions/.github/workflows/publish_coverage.yml@v5
     with:
       python-version: "3.11"
       apt-package: xvfb
+      coverage-package: PyOptik
     secrets:
       _GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

{pyoptik-3.0.5 → pyoptik-3.1.0}/.github/workflows/deploy_documentation.yml

@@ -16,8 +16,8 @@ permissions:
 
 jobs:
   ManyLinux_x86_64:
-    uses: MartinPdeS/MPSActions/.github/workflows/publish_documentation.yml@master
+    uses: MartinPdeS/MPSActions/.github/workflows/publish_documentation.yml@v5
     with:
       python-version: "3.11"
       package-name: "PyOptik"
-      apt-package: xvfb jq
+      apt-package: xvfb jq

pyoptik-3.1.0/.github/workflows/quality.yml

@@ -0,0 +1,18 @@
+name: Static quality checks
+on:
+  push:
+    branches: ["master"]
+  pull_request:
+    branches: ["master"]
+permissions:
+  contents: read
+jobs:
+  flake8:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
+        with:
+          python-version: "3.11"
+      - run: python -m pip install "flake8==7.1.1"
+      - run: python -m flake8 PyOptik tests

{pyoptik-3.0.5 → pyoptik-3.1.0}/.github/workflows/tests.yml

@@ -15,8 +15,8 @@ jobs:
         python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
         with:
           python-version: ${{ matrix.python-version }}
           cache: pip

{pyoptik-3.0.5 → pyoptik-3.1.0}/.gitignore

@@ -4,10 +4,14 @@
 
 # Except ...
 !.github
+!conda.recipe
+!conda.recipe/meta.yaml
 !PyOptik
 !development
 !docs
 !tests
+!tools
+!tools/*.py
 !.flake8
 !.gitignore
 !.pre-commit-config.yaml
@@ -21,6 +25,7 @@
 !pytest.ini
 !.coveragerc
 !CHANGELOG.md
+!CONTRIBUTING.md
 
 # But ignore docs/build inside docs and code
 docs/build/

{pyoptik-3.0.5 → pyoptik-3.1.0}/CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.1.0] - 2026-09-16
+
 ### Added
 
 - Support for all nine RefractiveIndex.INFO dispersion formula types.
@@ -25,6 +27,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Numerical regression, unit-equivalence, catalog-search, and cache-integrity
   test coverage.
 - A new PyOptik prism logo and documentation favicon.
+- Typed, validated material documents for formula and tabulated optical data.
+- User-defined material construction from arrays, CSV files, and formula
+  coefficients, with atomic RefractiveIndex.INFO-compatible YAML export.
+- An optional Textual terminal browser for searching the local material
+  catalog and inspecting provenance.
+- Fresnel reflection and transmission calculations for s and p polarization,
+  including Brewster and critical-angle helpers.
+- Coherent transfer-matrix calculations for isotropic multilayer thin films,
+  supporting constant complex indices and wavelength-dependent PyOptik
+  material models.
+- Numerical reference tests for interfaces, total internal reflection,
+  antireflection coatings, absorbing films, custom material round trips, and
+  malformed input paths.
 
 ### Changed
 
@@ -32,6 +47,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   GDD, `dτ_g/dω`, with time-squared units.
 - Material plots use a consistent built-in Matplotlib layout and typography.
 - Public catalog and group-delay APIs use expanded NumPy-style docstrings.
+- Material YAML loading and export share one typed parser and validation layer.
+- Wavelength validity endpoints tolerate floating-point round-off introduced
+  by unit conversions.
 
 ### Fixed
 
@@ -44,4 +62,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   plotting helpers.
 - Retired logo assets.
 
-[Unreleased]: https://github.com/MartinPdeS/PyOptik/compare/v3.0.0...HEAD
+[Unreleased]: https://github.com/MartinPdeS/PyOptik/compare/v3.1.0...HEAD
+[3.1.0]: https://github.com/MartinPdeS/PyOptik/compare/v3.0.5...v3.1.0

pyoptik-3.1.0/CONTRIBUTING.md

@@ -0,0 +1,10 @@
+# Contributing to PyOptik
+
+Contributions should preserve PyOptik's offline material-catalogue workflow.
+Add tests for behaviour changes, document data provenance and physical units,
+and avoid committing generated assets, caches, or `PyOptik/_version.py`.
+
+Use `make quality`, `make test`, and `make docs` as appropriate before a pull
+request. Semantic release commands (`make release patch`, `minor`, or `major`)
+create and push the release commit and exact tag; `make tag VERSION=vX.Y.Z`
+creates a local-only tag.

{pyoptik-3.0.5 → pyoptik-3.1.0}/Makefile

@@ -3,10 +3,13 @@ BUILD_DIR ?= build
 DIST_DIR ?= dist
 DOCS_DIR ?= docs
 DOCS_BUILD_DIR ?= $(DOCS_DIR)/build
+RELEASE_KIND := $(filter major minor patch,$(MAKECMDGOALS))
 
 .PHONY: help quality test docs build install uninstall quick rebuild editable \
 	 setup download-all clean
 
+.PHONY: release tag major minor patch
+
 help:
 	@echo "PyOptik development targets:"
 	@echo "  make quality       Run static checks"
@@ -20,6 +23,7 @@ help:
 	@echo "  make quick         Run quality checks, tests, and build"
 	@echo "  make rebuild       Clean, then run the quick workflow"
 	@echo "  make clean         Remove generated build and test artifacts"
+	@echo "  make release patch Create and push the next patch release"
 
 quality:
 	$(PYTHON) -m flake8 PyOptik tests
@@ -55,6 +59,16 @@ setup:
 download-all:
 	$(PYTHON) -m PyOptik download-all $(ARGS)
 
+tag:
+	$(PYTHON) tools/release_tag.py "$(VERSION)"
+
+release:
+	@test "$(words $(RELEASE_KIND))" -eq 1 || { echo "usage: make release [patch|minor|major]" >&2; exit 2; }
+	@set -eu; tag="$$($(PYTHON) tools/next_release_version.py $(RELEASE_KIND))"; $(PYTHON) tools/release_tag.py "$$tag"; git push origin HEAD "refs/tags/$$tag"
+
+major minor patch:
+	@:
+
 clean:
 	rm -rf $(BUILD_DIR) $(DIST_DIR) $(DOCS_BUILD_DIR) \
 		.pytest_cache htmlcov .coverage

{pyoptik-3.0.5 → pyoptik-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyOptik
-Version: 3.0.5
+Version: 3.1.0
 Summary: A package for refractive index values.
 Author-email: Martin Poinsinet de Sivry-Houle <martin.poinsinet.de.sivry@gmail.com>
 License: MIT License
@@ -55,6 +55,8 @@ Requires-Dist: sphinx-rtd-theme==2.0.0; extra == "documentation"
 Requires-Dist: pydata-sphinx-theme==0.14.1; extra == "documentation"
 Provides-Extra: dev
 Requires-Dist: flake8==7.1.1; extra == "dev"
+Provides-Extra: ui
+Requires-Dist: textual>=1.0; extra == "ui"
 Dynamic: license-file
 
 |logo|
@@ -101,6 +103,7 @@ Features
 * Tabulated complex refractive index data, ``n + i k``.
 * Unit-aware wavelength calculations through ``TypedUnit`` and Pint.
 * Group index, group velocity, group delay, and group-delay dispersion.
+* Fresnel interfaces and coherent multilayer thin-film calculations.
 * NumPy-compatible scalar and array evaluation.
 * Plotting helpers for dispersion and absorption data.
 * Hierarchical catalog access using upstream ``shelf / book / page`` identity.
@@ -197,6 +200,35 @@ Use ``material.n(wavelength)``, ``material.k(wavelength)``,
 See the documentation's physical-conventions page for the vacuum-wavelength,
 ``n + i k``, GDD, interpolation, and extrapolation conventions.
 
+User-defined materials
+~~~~~~~~~~~~~~~~~~~~~~
+
+Create tabulated materials directly from measured arrays or a CSV file, then
+export them in the same validated YAML format used by the catalog:
+
+.. code-block:: python
+
+   from TypedUnit import ureg
+   from PyOptik import TabulatedMaterial
+
+   sample = TabulatedMaterial.from_arrays(
+       "sample",
+       [400, 500, 600] * ureg.nanometer,
+       n=[1.40, 1.45, 1.50],
+       k=[0.01, 0.02, 0.04],
+       reference="Laboratory measurement",
+   )
+   sample.to_yaml("sample.yml")
+
+   # CSV headers default to: wavelength,n,k
+   imported = TabulatedMaterial.from_csv(
+       "sample.csv",
+       wavelength_unit=ureg.nanometer,
+   )
+
+Formula materials can be authored in the same way with
+``SellmeierMaterial.from_coefficients(...)`` and exported with ``to_yaml()``.
+
 Validity ranges
 ~~~~~~~~~~~~~~~
 
@@ -241,6 +273,55 @@ These methods accept scalar or array wavelengths and return unit-aware values.
 ``dτ_g/dω`` (typically expressed in fs²); use
 ``compute_group_delay_wavelength_slope`` for ``dτ_g/dλ``.
 
+Interfaces and thin films
+-------------------------
+
+Calculate s- or p-polarized Fresnel coefficients at a single interface:
+
+.. code-block:: python
+
+   from TypedUnit import ureg
+   from PyOptik import fresnel_coefficients, brewster_angle, critical_angle
+
+   interface = fresnel_coefficients(
+       1.0,
+       1.5,
+       angle=45 * ureg.degree,
+       polarization="p",
+   )
+   print(interface.reflectance, interface.transmittance)
+
+   print(brewster_angle(1.0, 1.5).to(ureg.degree))
+   print(critical_angle(1.5, 1.0).to(ureg.degree))
+
+For coherent multilayers, supply constant indices or PyOptik material models.
+Each thickness should carry units:
+
+.. code-block:: python
+
+   import numpy
+   from PyOptik import ThinFilmLayer, thin_film_stack
+
+   wavelength = 600 * ureg.nanometer
+   substrate_index = 1.5
+   coating_index = numpy.sqrt(substrate_index)
+   coating = ThinFilmLayer(
+       coating_index,
+       wavelength / (4 * coating_index),
+   )
+   spectrum = thin_film_stack(
+       [500, 550, 600, 650, 700] * ureg.nanometer,
+       [coating],
+       incident_index=1.0,
+       substrate_index=substrate_index,
+       polarization="s",
+   )
+
+The returned results contain complex amplitude coefficients and the power
+fractions ``reflectance``, ``transmittance``, and ``absorptance``. The model is
+coherent and isotropic; it does not model roughness, anisotropy, or incoherent
+thick substrates.
+
 Plotting
 --------
 
@@ -325,6 +406,18 @@ The command-line interface provides the canonical catalog workflow:
 After installation, the equivalent console command is ``pyoptik
 download-all --data-root ./refractiveindex-data``.
 
+An optional terminal interface provides live search and a provenance pane for
+browsing the downloaded database:
+
+.. code-block:: bash
+
+   python -m pip install "PyOptik[ui]"
+   pyoptik setup
+   pyoptik browse
+
+Use the arrow keys or mouse to select a page, ``/`` to focus search, and ``q``
+to quit. Pass ``--data-root`` when browsing a non-default snapshot location.
+
 For a beginner-friendly first-time setup, use:
 
 .. code-block:: bash

{pyoptik-3.0.5 → pyoptik-3.1.0}/PyOptik/__init__.py

@@ -14,6 +14,16 @@ from .catalog import MaterialCatalog, MaterialId, MaterialPage, download_snapsho
 
 from .material import TabulatedMaterial
 from .material import SellmeierMaterial
+from .material import FormulaDataset, MaterialDocument, MaterialMetadata, TabulatedDataset, parse_material
+from .thin_film import (
+    FresnelResult,
+    ThinFilmLayer,
+    ThinFilmResult,
+    brewster_angle,
+    critical_angle,
+    fresnel_coefficients,
+    thin_film_stack,
+)
 from .material import base_class
 
 

{pyoptik-3.0.5 → pyoptik-3.1.0}/PyOptik/__main__.py

@@ -22,7 +22,7 @@ def main() -> None:
         "command",
         nargs="?",
         default="setup",
-        choices=("setup", "download-all"),
+        choices=("setup", "download-all", "browse"),
         help="Canonical catalog command (default: setup)",
     )
     parser.add_argument(
@@ -70,6 +70,16 @@ def main() -> None:
         format="%(asctime)s %(levelname)s %(name)s: %(message)s",
     )
 
+    if args.command == "browse":
+        if args.force or args.fail_fast or args.source != "snapshot" or args.workers != 8 or args.no_progress:
+            parser.error("download options cannot be used with browse")
+        from PyOptik.tui import run_browser
+        try:
+            run_browser(args.data_root)
+        except (FileNotFoundError, RuntimeError) as error:
+            parser.error(str(error))
+        return
+
     if args.command == "setup" and args.source != "snapshot":
         parser.error("setup always uses the upstream snapshot; use download-all for page mode")
     source = "snapshot" if args.command == "setup" else args.source

{pyoptik-3.0.5 → pyoptik-3.1.0}/PyOptik/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '3.0.5'
-__version_tuple__ = version_tuple = (3, 0, 5)
+__version__ = version = '3.1.0'
+__version_tuple__ = version_tuple = (3, 1, 0)
 
-__commit_id__ = commit_id = 'g3091905a0'
+__commit_id__ = commit_id = 'g705a5ec86'

{pyoptik-3.0.5 → pyoptik-3.1.0}/PyOptik/catalog.py

@@ -145,17 +145,16 @@ class MaterialPage:
         """
         from PyOptik.material.sellmeier_class import SellmeierMaterial
         from PyOptik.material.tabulated_class import TabulatedMaterial
+        from PyOptik.material.dataset import parse_material
 
         if self.local_path is not None and self.local_path.exists():
-            with self.local_path.open("r") as stream:
-                document = yaml.safe_load(stream) or {}
-            entries = document.get("DATA", [])
-            if any("formula" in str(entry.get("type", "")) for entry in entries):
+            document = parse_material(self.local_path)
+            if document.formula_datasets:
                 material = SellmeierMaterial(self.name, file_path=self.local_path)
                 material.catalog_id = self.id.key
                 material.source_url = self.source_url
                 return material
-            if any("tabulated" in str(entry.get("type", "")) for entry in entries):
+            if document.tabulated_datasets:
                 material = TabulatedMaterial(
                     self.name,
                     file_path=self.local_path,

{pyoptik-3.0.5 → pyoptik-3.1.0}/PyOptik/material/__init__.py

@@ -1,3 +1,4 @@
 from .base_class import BaseMaterial
 from .sellmeier_class import SellmeierMaterial
 from .tabulated_class import TabulatedMaterial
+from .dataset import FormulaDataset, MaterialDocument, MaterialMetadata, TabulatedDataset, parse_material

{pyoptik-3.0.5 → pyoptik-3.1.0}/PyOptik/material/base_class.py

@@ -195,8 +195,13 @@ class BaseMaterial(object):
             raise ValueError("out_of_range must be 'warn', 'raise', or 'clip'.")
         if self.wavelength_bound is not None:
             min_value, max_value = self.wavelength_bound
+            values = wavelength.to(ureg.meter).magnitude
+            lower = min_value.to(ureg.meter).magnitude
+            upper = max_value.to(ureg.meter).magnitude
+            below = (values < lower) & ~numpy.isclose(values, lower, rtol=1e-12, atol=0.0)
+            above = (values > upper) & ~numpy.isclose(values, upper, rtol=1e-12, atol=0.0)
 
-            if numpy.any((wavelength < min_value) | (wavelength > max_value)):
+            if numpy.any(below | above):
                 message = (
                     f"Wavelength range goes from {wavelength.min().to_compact()} to {wavelength.max().to_compact()} "
                     f"which is outside the allowable range of {min_value.to_compact()} to {max_value.to_compact()} µm. "

pyoptik-3.1.0/PyOptik/material/dataset.py

@@ -0,0 +1,204 @@
+"""Typed, validated representations of PyOptik material datasets."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+import numpy
+import yaml
+
+
+@dataclass(frozen=True)
+class MaterialMetadata:
+    """Source metadata shared by formula and tabulated datasets."""
+
+    reference: str | None = None
+    conditions: Mapping[str, Any] = field(default_factory=dict)
+    comments: str | None = None
+
+
+@dataclass(frozen=True)
+class FormulaDataset:
+    """A validated RefractiveIndex.INFO formula dataset."""
+
+    formula_type: int
+    coefficients: tuple[float, ...]
+    wavelength_range: tuple[float, float] | None = None
+
+    def __post_init__(self) -> None:
+        """Validate formula identity, coefficients, and optional bounds."""
+        if self.formula_type not in range(1, 10):
+            raise ValueError(f"Unsupported formula type: {self.formula_type}")
+        if not self.coefficients or not numpy.all(numpy.isfinite(self.coefficients)):
+            raise ValueError("formula coefficients must be a non-empty finite sequence")
+        _validate_range(self.wavelength_range)
+
+
+@dataclass(frozen=True)
+class TabulatedDataset:
+    """One validated table of ``n``, ``k``, or combined ``nk`` values."""
+
+    kind: str
+    wavelength_um: tuple[float, ...]
+    values: tuple[tuple[float, ...], ...]
+
+    def __post_init__(self) -> None:
+        """Validate shape, finiteness, and wavelength ordering."""
+        if self.kind not in {"n", "k", "nk"}:
+            raise ValueError("tabulated kind must be 'n', 'k', or 'nk'")
+        expected = 2 if self.kind == "nk" else 1
+        if len(self.wavelength_um) < 2 or len(self.values) != len(self.wavelength_um):
+            raise ValueError(f"tabulated {self.kind} data must contain at least two rows")
+        if any(len(row) != expected for row in self.values):
+            raise ValueError(f"tabulated {self.kind} rows require {expected + 1} columns")
+        wavelength = numpy.asarray(self.wavelength_um, dtype=float)
+        data = numpy.asarray(self.values, dtype=float)
+        if not numpy.all(numpy.isfinite(wavelength)) or not numpy.all(numpy.isfinite(data)):
+            raise ValueError("tabulated data must be finite")
+        if numpy.any(numpy.diff(wavelength) <= 0):
+            raise ValueError("tabulated wavelengths must be strictly increasing")
+
+
+Dataset = FormulaDataset | TabulatedDataset
+
+
+@dataclass(frozen=True)
+class MaterialDocument:
+    """A parsed optical-material document and its provenance metadata."""
+
+    datasets: tuple[Dataset, ...]
+    metadata: MaterialMetadata = field(default_factory=MaterialMetadata)
+
+    def __post_init__(self) -> None:
+        """Require at least one supported dataset."""
+        if not self.datasets:
+            raise ValueError("material document contains no supported dataset")
+
+    @property
+    def formula_datasets(self) -> tuple[FormulaDataset, ...]:
+        """Return formula datasets in source order."""
+        return tuple(item for item in self.datasets if isinstance(item, FormulaDataset))
+
+    @property
+    def tabulated_datasets(self) -> tuple[TabulatedDataset, ...]:
+        """Return tabulated datasets in source order."""
+        return tuple(item for item in self.datasets if isinstance(item, TabulatedDataset))
+
+    def to_mapping(self) -> dict[str, Any]:
+        """Return a RefractiveIndex.INFO-compatible YAML mapping."""
+        document: dict[str, Any] = {}
+        if self.metadata.reference is not None:
+            document["REFERENCES"] = self.metadata.reference
+        if self.metadata.comments is not None:
+            document["COMMENTS"] = self.metadata.comments
+        if self.metadata.conditions:
+            document["CONDITIONS"] = dict(self.metadata.conditions)
+        entries = []
+        for dataset in self.datasets:
+            if isinstance(dataset, FormulaDataset):
+                entry: dict[str, Any] = {
+                    "type": f"formula {dataset.formula_type}",
+                    "coefficients": " ".join(_format_number(value) for value in dataset.coefficients),
+                }
+                if dataset.wavelength_range is not None:
+                    entry["wavelength_range"] = " ".join(
+                        _format_number(value) for value in dataset.wavelength_range
+                    )
+            else:
+                rows = []
+                for wavelength, values in zip(dataset.wavelength_um, dataset.values):
+                    rows.append(" ".join(_format_number(value) for value in (wavelength, *values)))
+                entry = {"type": f"tabulated {dataset.kind}", "data": "\n".join(rows) + "\n"}
+            entries.append(entry)
+        document["DATA"] = entries
+        return document
+
+    def to_yaml(self, path: str | Path) -> Path:
+        """Serialize this document to ``path`` and return the resulting path."""
+        destination = Path(path)
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        temporary = destination.with_suffix(destination.suffix + ".tmp")
+        with temporary.open("w", encoding="utf-8") as stream:
+            yaml.safe_dump(self.to_mapping(), stream, sort_keys=False, allow_unicode=True)
+        temporary.replace(destination)
+        return destination
+
+
+def parse_material(source: str | Path | Mapping[str, Any]) -> MaterialDocument:
+    """Parse and validate a material YAML path or already-loaded mapping."""
+    if isinstance(source, Mapping):
+        raw = dict(source)
+        label = "material mapping"
+    else:
+        path = Path(source)
+        label = str(path)
+        try:
+            with path.open("r", encoding="utf-8") as stream:
+                raw = yaml.safe_load(stream)
+        except (OSError, yaml.YAMLError) as error:
+            raise ValueError(f"Unable to read material YAML {label}: {error}") from error
+    if not isinstance(raw, dict):
+        raise ValueError(f"Invalid material YAML in {label}: expected a mapping")
+    entries = raw.get("DATA")
+    if not isinstance(entries, list):
+        raise ValueError(f"Invalid material YAML in {label}: DATA must be a list")
+    datasets: list[Dataset] = []
+    try:
+        for entry in entries:
+            if not isinstance(entry, dict):
+                raise ValueError("DATA entries must be mappings")
+            tokens = str(entry.get("type", "")).lower().split()
+            if len(tokens) != 2:
+                continue
+            if tokens[0] == "formula":
+                wavelength_range = (
+                    _numbers(entry["wavelength_range"])
+                    if "wavelength_range" in entry else ()
+                )
+                datasets.append(FormulaDataset(
+                    formula_type=int(tokens[1]),
+                    coefficients=_numbers(entry["coefficients"]),
+                    wavelength_range=tuple(wavelength_range) if wavelength_range else None,
+                ))
+            elif tokens[0] == "tabulated" and tokens[1] in {"n", "k", "nk"}:
+                rows = tuple(_numbers(line) for line in str(entry["data"]).strip().splitlines())
+                datasets.append(TabulatedDataset(
+                    kind=tokens[1],
+                    wavelength_um=tuple(row[0] for row in rows),
+                    values=tuple(tuple(row[1:]) for row in rows),
+                ))
+    except (KeyError, TypeError, ValueError) as error:
+        raise ValueError(f"Invalid material dataset in {label}: {error}") from error
+    try:
+        metadata = MaterialMetadata(
+            reference=str(raw["REFERENCES"]) if raw.get("REFERENCES") is not None else None,
+            conditions=dict(raw.get("CONDITIONS") or {}),
+            comments=str(raw["COMMENTS"]) if raw.get("COMMENTS") is not None else None,
+        )
+    except (TypeError, ValueError) as error:
+        raise ValueError(f"Invalid material metadata in {label}: {error}") from error
+    try:
+        return MaterialDocument(tuple(datasets), metadata)
+    except ValueError as error:
+        raise ValueError(f"Invalid material dataset in {label}: {error}") from error
+
+
+def _numbers(value: str | Sequence[float]) -> tuple[float, ...]:
+    """Convert whitespace-delimited text or a sequence to floats."""
+    values = value.split() if isinstance(value, str) else value
+    return tuple(float(item) for item in values)
+
+
+def _validate_range(value: tuple[float, float] | None) -> None:
+    """Validate an optional increasing two-value wavelength interval."""
+    if value is None:
+        return
+    if len(value) != 2 or not numpy.all(numpy.isfinite(value)) or value[0] >= value[1]:
+        raise ValueError("wavelength_range must contain two increasing finite values")
+
+
+def _format_number(value: float) -> str:
+    """Format a float precisely enough for lossless YAML round trips."""
+    return format(float(value), ".17g")