PyOptik 3.0.5__tar.gz → 3.2.0__tar.gz

{pyoptik-3.0.5 → pyoptik-3.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.0/CHANGELOG.md

@@ -0,0 +1,84 @@
+# 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.2.0] - 2026-09-16
+
+### Added
+
+- Task-oriented getting-started and material-catalog guides.
+- Executable gallery examples for measured-material import and YAML round
+  trips, Fresnel polarization and Brewster angle, quarter-wave antireflection
+  coatings, dielectric Bragg mirrors, and catalog provenance workflows.
+- Direct README links to the principal guides, examples, and API reference.
+
+### Changed
+
+- Documentation navigation now groups content into Start here, User guide,
+  Learn by example, and Reference sections.
+- The documentation landing page, page titles, API hierarchy, and gallery
+  descriptions now use clearer task-oriented language.
+
+## [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.2.0...HEAD
+[3.2.0]: https://github.com/MartinPdeS/PyOptik/compare/v3.1.0...v3.2.0
+[3.1.0]: https://github.com/MartinPdeS/PyOptik/compare/v3.0.5...v3.1.0

pyoptik-3.2.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.2.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.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyOptik
-Version: 3.0.5
+Version: 3.2.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|
@@ -94,6 +96,24 @@ catalog interface for the hierarchical `RefractiveIndex.INFO
 The library is designed for optical design, photonics simulations,
 electromagnetic modeling, and experimental data analysis.
 
+Documentation
+-------------
+
+The full documentation is organized by task:
+
+* `Getting started <https://martinpdes.github.io/PyOptik/getting_started.html>`_
+  for installation and a first unit-aware calculation.
+* `Materials and catalog <https://martinpdes.github.io/PyOptik/materials_and_catalog.html>`_
+  for model selection, search, provenance, and cache integrity.
+* `Custom materials <https://martinpdes.github.io/PyOptik/custom_materials.html>`_
+  for arrays, CSV import, coefficients, validation, and YAML export.
+* `Interfaces and thin films <https://martinpdes.github.io/PyOptik/thin_films.html>`_
+  for Fresnel coefficients and coherent multilayer design.
+* `Example gallery <https://martinpdes.github.io/PyOptik/examples.html>`_
+  for complete, executable workflows.
+* `API reference <https://martinpdes.github.io/PyOptik/code.html>`_ for public
+  classes and functions.
+
 Features
 --------
 
@@ -101,6 +121,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 +218,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 +291,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
 --------
 
@@ -262,6 +361,20 @@ Matplotlib backend before importing plotting code:
    import matplotlib
    matplotlib.use("Agg")
 
+Worked examples
+---------------
+
+The documentation gallery includes downloadable Python scripts and notebooks
+for:
+
+* Sellmeier and tabulated material dispersion;
+* group index and group velocity;
+* importing, interpolating, exporting, and reloading measured optical data;
+* s- and p-polarized Fresnel reflectance and Brewster angle;
+* quarter-wave antireflection coatings;
+* multilayer dielectric Bragg mirrors; and
+* catalog search, canonical source selection, and provenance capture.
+
 Hierarchical material catalog
 -----------------------------
 
@@ -325,6 +438,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.2.0/PyOptik/__init__.py

@@ -0,0 +1,32 @@
+try:
+    from ._version import version as __version__  # noqa: F401
+
+except ImportError:
+    __version__ = "0.0.0"
+
+import logging
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+
+from .material_type import MaterialType  # noqa: E402
+from .catalog import MaterialCatalog, MaterialId, MaterialPage, download_snapshot  # noqa: E402
+
+from .material import TabulatedMaterial  # noqa: E402
+from .material import SellmeierMaterial  # noqa: E402
+from .material import (  # noqa: E402
+    FormulaDataset, MaterialDocument, MaterialMetadata, TabulatedDataset, parse_material,
+)
+from .thin_film import (  # noqa: E402
+    FresnelResult,
+    ThinFilmLayer,
+    ThinFilmResult,
+    brewster_angle,
+    critical_angle,
+    fresnel_coefficients,
+    thin_film_stack,
+)
+from .material import base_class  # noqa: E402
+
+
+TIMEOUT = 10  # Default timeout for requests in seconds

{pyoptik-3.0.5 → pyoptik-3.2.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.2.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.2.0'
+__version_tuple__ = version_tuple = (3, 2, 0)
 
-__commit_id__ = commit_id = 'g3091905a0'
+__commit_id__ = commit_id = 'g7c8410160'

{pyoptik-3.0.5 → pyoptik-3.2.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.2.0}/PyOptik/directories.py

@@ -54,6 +54,7 @@ user_data_path = _default_user_data_path()
 user_sellmeier_data_path = user_data_path / "sellmeier"
 user_tabulated_data_path = user_data_path / "tabulated"
 
+
 def material_paths(material_type):
     """Return the user data directory for a material type.
 

{pyoptik-3.0.5 → pyoptik-3.2.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.2.0}/PyOptik/material/base_class.py

@@ -10,6 +10,7 @@ from TypedUnit import Length, AnyUnit, Time, ureg, validate_units
 
 logger = logging.getLogger(__name__)
 
+
 class BaseMaterial(object):
     """Common interface for refractive-index material models.
 
@@ -195,8 +196,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. "