PyOptik 3.0.4__tar.gz → 3.1.0__tar.gz

{pyoptik-3.0.4 → 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.4 → 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.4 → 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.4 → 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.4 → 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.4 → 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.1.0/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to PyOptik are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [3.1.0] - 2026-09-16
+
+### Added
+
+- Support for all nine RefractiveIndex.INFO dispersion formula types.
+- `MaterialCatalog.search()` with hierarchy, source, reference, and local
+  availability filters.
+- `MaterialPage.provenance()` for serializable material-source records.
+- `MaterialCatalog.verify_integrity()` for SHA-256 verification of cached
+  material data.
+- `compute_group_delay_wavelength_slope()` for the explicit wavelength-space
+  derivative, `dτ_g/dλ`.
+- Convenience APIs for real index, extinction coefficient, relative
+  permittivity, and absorption coefficient.
+- Split tabulated ``n`` and ``k`` YAML support and opt-in monotonic PCHIP
+  interpolation.
+- A physical conventions and provenance documentation guide.
+- 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
+
+- `compute_group_delay_dispersion()` now returns conventional frequency-domain
+  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
+
+- Formula type 6 now accumulates every gas-dispersion term instead of
+  overwriting earlier terms.
+
+### Removed
+
+- The `MPSPlots` runtime dependency and its use in examples and material
+  plotting helpers.
+- Retired logo assets.
+
+[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.4 → 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.4 → pyoptik-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyOptik
-Version: 3.0.4
+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.
@@ -191,6 +194,41 @@ Tabulated materials interpolate complex optical constants:
 The real part is the refractive index ``n`` and the imaginary part is the
 extinction coefficient ``k``.
 
+Use ``material.n(wavelength)``, ``material.k(wavelength)``,
+``material.relative_permittivity(wavelength)``, and
+``material.absorption_coefficient(wavelength)`` for common derived properties.
+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
 ~~~~~~~~~~~~~~~
 
@@ -235,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
 --------
 
@@ -319,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.4 → 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.4 → 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.4 → 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.4'
-__version_tuple__ = version_tuple = (3, 0, 4)
+__version__ = version = '3.1.0'
+__version_tuple__ = version_tuple = (3, 1, 0)
 
-__commit_id__ = commit_id = 'gcad6d74ee'
+__commit_id__ = commit_id = 'g705a5ec86'

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

@@ -122,9 +122,15 @@ class MaterialPage:
         state = "available" if self.available else "missing"
         return f"MaterialPage(id={self.id.key!r}, name={self.name!r}, data={state!r})"
 
-    def load(self):
+    def load(self, *, interpolation: str = "linear"):
         """Load this page as the appropriate PyOptik material object.
 
+        Parameters
+        ----------
+        interpolation : {"linear", "pchip"}, optional
+            Tabulated-data interpolation method. Formula materials ignore this
+            option.
+
         Returns
         -------
         SellmeierMaterial or TabulatedMaterial
@@ -139,15 +145,24 @@ 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):
-                return SellmeierMaterial(self.name, file_path=self.local_path)
-            if any("tabulated" in str(entry.get("type", "")) for entry in entries):
-                return TabulatedMaterial(self.name, file_path=self.local_path)
+            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 document.tabulated_datasets:
+                material = TabulatedMaterial(
+                    self.name,
+                    file_path=self.local_path,
+                    interpolation=interpolation,
+                )
+                material.catalog_id = self.id.key
+                material.source_url = self.source_url
+                return material
             raise ValueError(f"No supported optical dataset found in {self.local_path}")
 
         raise FileNotFoundError(

{pyoptik-3.0.4 → 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.4 → pyoptik-3.1.0}/PyOptik/material/base_class.py

@@ -17,6 +17,113 @@ class BaseMaterial(object):
     unit handling, validity-range checks, and group-delay calculations.
     """
 
+    @property
+    def provenance(self) -> dict:
+        """Return source and validity metadata for this material.
+
+        Returns
+        -------
+        dict
+            Material name, source file, reference, conditions, validity range,
+            and catalog identity when the material was loaded from a catalog.
+        """
+        return {
+            "name": self.filename,
+            "file_path": str(getattr(self, "file_path", "")) or None,
+            "reference": getattr(self, "reference", None),
+            "conditions": getattr(self, "conditions", None),
+            "comments": getattr(self, "comments", None),
+            "wavelength_range": getattr(self, "wavelength_bound", None),
+            "catalog_id": getattr(self, "catalog_id", None),
+            "source_url": getattr(self, "source_url", None),
+        }
+
+    def refractive_index(self, wavelength: Length, **kwargs):
+        """Return the complex refractive index ``n + i k``.
+
+        Parameters
+        ----------
+        wavelength : Length
+            Vacuum wavelength.
+        **kwargs
+            Forwarded to :meth:`compute_refractive_index`.
+
+        Returns
+        -------
+        complex or numpy.ndarray
+            Complex refractive index.
+        """
+        return self.compute_refractive_index(wavelength, **kwargs)
+
+    def n(self, wavelength: Length, **kwargs):
+        """Return the real refractive index.
+
+        Parameters
+        ----------
+        wavelength : Length
+            Vacuum wavelength.
+        **kwargs
+            Forwarded to :meth:`compute_refractive_index`.
+
+        Returns
+        -------
+        float or numpy.ndarray
+            Real part of the complex refractive index.
+        """
+        return self.compute_refractive_index(wavelength, **kwargs).real
+
+    def k(self, wavelength: Length, **kwargs):
+        """Return the extinction coefficient.
+
+        Parameters
+        ----------
+        wavelength : Length
+            Vacuum wavelength.
+        **kwargs
+            Forwarded to :meth:`compute_refractive_index`.
+
+        Returns
+        -------
+        float or numpy.ndarray
+            Imaginary part of the complex refractive index.
+        """
+        return self.compute_refractive_index(wavelength, **kwargs).imag
+
+    def relative_permittivity(self, wavelength: Length, **kwargs):
+        """Return relative complex permittivity, ``(n + i k)²``.
+
+        Parameters
+        ----------
+        wavelength : Length
+            Vacuum wavelength.
+        **kwargs
+            Forwarded to :meth:`compute_refractive_index`.
+
+        Returns
+        -------
+        complex or numpy.ndarray
+            Relative complex permittivity.
+        """
+        return self.compute_refractive_index(wavelength, **kwargs) ** 2
+
+    @validate_units
+    def absorption_coefficient(self, wavelength: Length, **kwargs) -> AnyUnit:
+        """Return the intensity absorption coefficient, ``α = 4πk / λ``.
+
+        Parameters
+        ----------
+        wavelength : Length
+            Vacuum wavelength.
+        **kwargs
+            Forwarded to :meth:`k`.
+
+        Returns
+        -------
+        AnyUnit
+            Absorption coefficient with inverse-length units.
+        """
+        return 4 * numpy.pi * self.k(wavelength, **kwargs) / wavelength
+
     def __eq__(self, other) -> bool:
         """Compare materials by concrete type and filename.
 
@@ -88,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. "