PyOptik 3.0.0__tar.gz → 3.0.4__tar.gz

{pyoptik-3.0.0 → pyoptik-3.0.4}/.gitignore

@@ -20,6 +20,7 @@
 !Makefile
 !pytest.ini
 !.coveragerc
+!CHANGELOG.md
 
 # But ignore docs/build inside docs and code
 docs/build/

pyoptik-3.0.4/CHANGELOG.md

@@ -0,0 +1,42 @@
+# 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]
+
+### 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λ`.
+- Numerical regression, unit-equivalence, catalog-search, and cache-integrity
+  test coverage.
+- A new PyOptik prism logo and documentation favicon.
+
+### 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.
+
+### 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.0.0...HEAD

{pyoptik-3.0.0 → pyoptik-3.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyOptik
-Version: 3.0.0
+Version: 3.0.4
 Summary: A package for refractive index values.
 Author-email: Martin Poinsinet de Sivry-Houle <martin.poinsinet.de.sivry@gmail.com>
 License: MIT License
@@ -40,7 +40,6 @@ Requires-Dist: numpy
 Requires-Dist: matplotlib~=3.8
 Requires-Dist: requests~=2.31
 Requires-Dist: pyyaml~=6.0
-Requires-Dist: MPSPlots
 Requires-Dist: tabulate~=0.9
 Requires-Dist: TypedUnit
 Provides-Extra: testing
@@ -228,7 +227,13 @@ Every material model provides group-related quantities:
    )
    group_delay_dispersion = silica.compute_group_delay_dispersion(wavelength)
 
+   # The wavelength-space slope is available separately.
+   group_delay_wavelength_slope = silica.compute_group_delay_wavelength_slope(wavelength)
+
 These methods accept scalar or array wavelengths and return unit-aware values.
+``compute_group_delay_dispersion`` is the conventional frequency-domain GDD,
+``dτ_g/dω`` (typically expressed in fs²); use
+``compute_group_delay_wavelength_slope`` for ``dτ_g/dλ``.
 
 Plotting
 --------
@@ -296,6 +301,10 @@ Access a page by its canonical identifier and load its material model:
    page = catalog.get("specs/SCHOTT-optical/N-BK7")
    bk7 = page.load()
 
+   # Search by ID, descriptive name, or source URL; retain only cached pages.
+   for page in catalog.search("BK7", shelf="specs", available=True):
+       print(page.provenance())
+
 Material data is cached in a user data directory. Set
 ``PYOPTIK_DATA_DIR`` to choose a different location.
 
@@ -388,7 +397,7 @@ material page for its original scientific or manufacturer reference.
    :alt: Supported Python versions
    :target: https://pypi.org/project/pyoptik/
 
-.. |logo| image:: https://github.com/MartinPdeS/PyOptik/raw/master/docs/images/logo.png
+.. |logo| image:: https://github.com/MartinPdeS/PyOptik/raw/master/docs/images/logo.svg
    :alt: PyOptik logo
 
 .. |docs| image:: https://github.com/martinpdes/pyoptik/actions/workflows/deploy_documentation.yml/badge.svg

{pyoptik-3.0.0 → pyoptik-3.0.4}/PyOptik/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '3.0.0'
-__version_tuple__ = version_tuple = (3, 0, 0)
+__version__ = version = '3.0.4'
+__version_tuple__ = version_tuple = (3, 0, 4)
 
-__commit_id__ = commit_id = 'g8275e8e4b'
+__commit_id__ = commit_id = 'gcad6d74ee'

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

@@ -67,6 +67,41 @@ class MaterialPage:
     metadata: Optional[dict] = None
     data_root: Optional[Path] = None
 
+    @property
+    def available(self) -> bool:
+        """Whether this page's data file is available in the local cache."""
+        return self.local_path is not None and self.local_path.exists()
+
+    @property
+    def reference(self) -> Optional[str]:
+        """Return the local source reference, when the page has been cached."""
+        if not self.available:
+            return None
+        try:
+            with self.local_path.open("r") as stream:
+                reference = (yaml.safe_load(stream) or {}).get("REFERENCES")
+                return str(reference) if reference is not None else None
+        except (OSError, yaml.YAMLError):
+            return None
+
+    def provenance(self) -> dict:
+        """Return the canonical identity and source information for this page.
+
+        Returns
+        -------
+        dict
+            Serializable identity, cache-path, availability, and source fields.
+        """
+        return {
+            "id": self.id.key,
+            "name": self.name,
+            "description": self.description,
+            "reference": self.reference,
+            "source_url": self.source_url,
+            "local_path": str(self.local_path) if self.local_path else None,
+            "available": self.available,
+        }
+
     @property
     def local_path(self) -> Optional[Path]:
         """Return the local cached path, if a data path is known."""
@@ -84,11 +119,24 @@ class MaterialPage:
         The representation intentionally omits YAML metadata and source URLs,
         which may be large or distracting when inspecting a catalog.
         """
-        state = "available" if self.local_path is not None and self.local_path.exists() else "missing"
+        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):
-        """Load this page as the appropriate PyOptik material object."""
+        """Load this page as the appropriate PyOptik material object.
+
+        Returns
+        -------
+        SellmeierMaterial or TabulatedMaterial
+            Material model selected from the local YAML data type.
+
+        Raises
+        ------
+        FileNotFoundError
+            If the page has not been downloaded locally.
+        ValueError
+            If the file contains no supported optical dataset.
+        """
         from PyOptik.material.sellmeier_class import SellmeierMaterial
         from PyOptik.material.tabulated_class import TabulatedMaterial
 
@@ -146,7 +194,20 @@ class MaterialCatalog:
 
     @classmethod
     def from_upstream(cls, data_root: Optional[Path | str] = None, url: str = UPSTREAM_CATALOG_URL):
-        """Download and load the current upstream catalog index."""
+        """Download and load the current upstream catalog index.
+
+        Parameters
+        ----------
+        data_root : pathlib.Path or str, optional
+            Directory used for the catalog index and downloaded pages.
+        url : str, optional
+            Catalog YAML URL.
+
+        Returns
+        -------
+        MaterialCatalog
+            Catalog indexed from the downloaded upstream YAML file.
+        """
         root = Path(data_root or (user_data_path / "rii")).expanduser()
         catalog_file = root / "catalog-nk.yml"
         download_yml_file(
@@ -288,6 +349,16 @@ class MaterialCatalog:
             "mode": "snapshot",
             "updated_at": datetime.now(timezone.utc).isoformat(),
         }
+        for material_page in catalog.pages():
+            if material_page.local_path is None or not material_page.local_path.exists():
+                continue
+            manifest["pages"][material_page.id.key] = {
+                "source_url": material_page.source_url,
+                "local_path": str(material_page.local_path.relative_to(root)),
+                "status": "snapshot",
+                "sha256": catalog._sha256(material_page.local_path),
+                "updated_at": datetime.now(timezone.utc).isoformat(),
+            }
         catalog._write_manifest(manifest)
         logger.info("Extracted upstream snapshot with %s catalog pages", len(catalog.pages()))
         return catalog
@@ -329,7 +400,18 @@ class MaterialCatalog:
         logger.info("Loaded %s material pages from %s", len(self._pages), catalog_file)
 
     def pages(self, shelf: Optional[str] = None, book: Optional[str] = None) -> list[MaterialPage]:
-        """Return pages filtered by shelf and/or book."""
+        """Return pages filtered by shelf and/or book.
+
+        Parameters
+        ----------
+        shelf, book : str, optional
+            Canonical hierarchy filters.
+
+        Returns
+        -------
+        list of MaterialPage
+            Matching pages in canonical identifier order.
+        """
         return sorted(
             (page for page in self._pages.values()
              if (shelf is None or page.id.shelf == shelf)
@@ -337,6 +419,66 @@ class MaterialCatalog:
             key=lambda page: page.id.key,
         )
 
+    def search(
+        self,
+        query: Optional[str] = None,
+        *,
+        shelf: Optional[str] = None,
+        book: Optional[str] = None,
+        source: Optional[str] = None,
+        reference: Optional[str] = None,
+        available: Optional[bool] = None,
+    ) -> list[MaterialPage]:
+        """Search catalog pages by text and provenance-aware filters.
+
+        Text matching is case-insensitive and covers canonical IDs, page names,
+        catalog descriptions, and source URLs. ``reference`` filters the
+        local YAML ``REFERENCES`` field, so it requires cached pages. Set
+        ``available=True`` to restrict results to local pages. Each result
+        exposes :meth:`MaterialPage.provenance` for a source record.
+
+        Parameters
+        ----------
+        query : str, optional
+            Case-insensitive text query.
+        shelf, book : str, optional
+            Canonical hierarchy filters.
+        source : str, optional
+            Case-insensitive source-URL filter.
+        reference : str, optional
+            Case-insensitive local YAML reference filter.
+        available : bool, optional
+            Restrict results by cache availability.
+
+        Returns
+        -------
+        list of MaterialPage
+            Matching pages in canonical identifier order.
+        """
+        terms = (query or "").casefold()
+        source_term = source.casefold() if source else None
+        reference_term = reference.casefold() if reference else None
+        matched = []
+        for material_page in self.pages(shelf=shelf, book=book):
+            haystack = " ".join(
+                value for value in (
+                    material_page.id.key,
+                    material_page.name,
+                    material_page.description,
+                    material_page.source_url,
+                ) if value
+            ).casefold()
+            if terms and terms not in haystack:
+                continue
+            if source_term and source_term not in (material_page.source_url or "").casefold():
+                continue
+            if reference_term and reference_term not in (material_page.reference or "").casefold():
+                continue
+            if available is not None and material_page.available is not available:
+                continue
+            matched.append(material_page)
+        return matched
+
     def shelves(self) -> list[str]:
         """Return sorted upstream shelf identifiers.
 
@@ -399,8 +541,52 @@ class MaterialCatalog:
                 digest.update(block)
         return digest.hexdigest()
 
+    def verify_integrity(self) -> dict[MaterialId, bool]:
+        """Verify checksums recorded in the local download manifest.
+
+        Pages without a recorded checksum are omitted. The returned mapping is
+        keyed by canonical material identity, allowing callers to identify and
+        re-download only altered or incomplete cached files.
+
+        Returns
+        -------
+        dict of MaterialId to bool
+            Whether every manifest-recorded page matches its SHA-256 digest.
+        """
+        checked = {}
+        for key, record in self._read_manifest().get("pages", {}).items():
+            expected = record.get("sha256")
+            relative_path = record.get("local_path")
+            if not expected or not relative_path:
+                continue
+            path = self.data_root / relative_path
+            parts = key.split("/")
+            if len(parts) < 3:
+                continue
+            identifier = MaterialId(parts[0], "/".join(parts[1:-1]), parts[-1])
+            checked[identifier] = path.is_file() and self._sha256(path) == expected
+        return checked
+
     def get(self, identifier: MaterialId | str, book: Optional[str] = None, page: Optional[str] = None) -> MaterialPage:
-        """Get a page by ``MaterialId``, canonical path, or components."""
+        """Get a page by ``MaterialId``, canonical path, or components.
+
+        Parameters
+        ----------
+        identifier : MaterialId or str
+            Canonical identifier, or shelf when ``book`` and ``page`` are set.
+        book, page : str, optional
+            Remaining canonical hierarchy components.
+
+        Returns
+        -------
+        MaterialPage
+            The selected catalog page.
+
+        Raises
+        ------
+        KeyError
+            If the identifier is unknown or incomplete.
+        """
         if isinstance(identifier, MaterialId):
             key = identifier
         elif book is not None and page is not None:

{pyoptik-3.0.0 → pyoptik-3.0.4}/PyOptik/directories.py

@@ -31,7 +31,7 @@ doc_path = project_path.joinpath('docs')
 
 doc_css_path = doc_path.joinpath('source/_static/default.css')
 
-logo_path = doc_path.joinpath('images/logo.png')
+logo_path = doc_path.joinpath('images/logo.svg')
 
 examples_path = root_path.joinpath('examples')
 

{pyoptik-3.0.0 → pyoptik-3.0.4}/PyOptik/material/base_class.py

@@ -228,13 +228,15 @@ class BaseMaterial(object):
         return length / vg
 
     @validate_units
-    def compute_group_delay_dispersion(
+    def compute_group_delay_wavelength_slope(
         self,
         wavelength: Length,
         length: Length = 1 * ureg.meter,
         delta: Length = 1 * ureg.nanometer,
     ) -> AnyUnit:
-        """Calculate ``d\u03c4_g/d\u03bb`` for a given propagation length.
+        """Calculate the wavelength slope ``dτ_g/dλ`` for a given length.
+
+        This is a wavelength-space derivative, not conventional GDD.
 
         Parameters
         ----------
@@ -249,8 +251,57 @@ class BaseMaterial(object):
         Returns
         -------
         AnyUnit
-            Group delay dispersion evaluated at ``wavelength``.
+            Wavelength derivative of group delay evaluated at ``wavelength``.
         """
         gd_plus = self.compute_group_delay(wavelength + delta / 2, length)
         gd_minus = self.compute_group_delay(wavelength - delta / 2, length)
         return (gd_plus - gd_minus) / delta
+
+    @validate_units
+    def compute_group_delay_dispersion(
+        self,
+        wavelength: Length,
+        length: Length = 1 * ureg.meter,
+        delta_angular_frequency: AnyUnit = 2 * numpy.pi * 1e12 / ureg.second,
+    ) -> AnyUnit:
+        """Calculate conventional GDD, ``dτ_g/dω = d²β/dω² × length``.
+
+        The derivative is evaluated with a centred finite difference in
+        angular frequency and has time-squared units (commonly fs²). Use
+        :meth:`compute_group_delay_wavelength_slope` for ``dτ_g/dλ``.
+
+        Parameters
+        ----------
+        wavelength : Length
+            Central vacuum wavelength.
+        length : Length, optional
+            Propagation length.
+        delta_angular_frequency : ureg.Quantity, optional
+            Positive centred angular-frequency increment. The default is
+            ``2π × 1 THz``.
+
+        Returns
+        -------
+        AnyUnit
+            Conventional group-delay dispersion with time-squared units.
+
+        Raises
+        ------
+        TypeError
+            If ``delta_angular_frequency`` does not carry units.
+        ValueError
+            If ``delta_angular_frequency`` is not positive.
+        """
+        if not isinstance(delta_angular_frequency, ureg.Quantity):
+            raise TypeError("delta_angular_frequency must carry units.")
+        if delta_angular_frequency.magnitude <= 0:
+            raise ValueError("delta_angular_frequency must be positive.")
+        speed_of_light = 299792458 * ureg.meter / ureg.second
+        frequency_unit = 1 / ureg.second
+        omega = (2 * numpy.pi * speed_of_light / wavelength).to(frequency_unit)
+        delta = delta_angular_frequency.to(frequency_unit)
+        wavelength_plus = 2 * numpy.pi * speed_of_light / (omega + delta / 2)
+        wavelength_minus = 2 * numpy.pi * speed_of_light / (omega - delta / 2)
+        delay_plus = self.compute_group_delay(wavelength_plus, length)
+        delay_minus = self.compute_group_delay(wavelength_minus, length)
+        return (delay_plus - delay_minus) / delta

{pyoptik-3.0.0 → pyoptik-3.0.4}/PyOptik/material/sellmeier_class.py

@@ -3,9 +3,8 @@
 
 import yaml
 import numpy
-import itertools
 import logging
-from MPSPlots import helper
+from matplotlib import pyplot as plt
 from TypedUnit import Length, RefractiveIndex, validate_units, ureg
 
 from PyOptik.directories import material_paths
@@ -83,14 +82,11 @@ class SellmeierMaterial(BaseMaterial):
             coefficients = list(map(float, data["coefficients"].split()))
         except (KeyError, IndexError, AttributeError, TypeError, ValueError) as error:
             raise ValueError(f"Invalid Sellmeier data in YAML file {file_path}") from error
-        if self.formula_type not in {1, 2, 5, 6}:
+        if self.formula_type not in set(range(1, 10)):
             raise ValueError(f"Unsupported formula type: {self.formula_type}")
         if not coefficients or not numpy.all(numpy.isfinite(coefficients)):
             raise ValueError(f"Sellmeier coefficients must be finite in {file_path}")
 
-        # Extract coefficients and ensure the list has exactly 7 coefficients by padding with zeros if necessary
-        if len(coefficients) < 7:
-            coefficients.extend([0.0] * (7 - len(coefficients)))
         self.coefficients = numpy.array(coefficients)
 
         # Extract wavelength range
@@ -141,47 +137,83 @@ class SellmeierMaterial(BaseMaterial):
         if out_of_range == "clip":
             wavelength = self._clip_wavelength(wavelength)
 
-        # Compute the refractive index based on the formula type
-        zipped_coefficients = itertools.zip_longest(*[iter(self.coefficients[1:])] * 2)
+        # Formula definitions follow the RefractiveIndex.INFO database
+        # documentation. Wavelengths are expressed in micrometres here.
+        wavelength_um = wavelength.to(ureg.micrometer).magnitude
+        coefficients = self.coefficients
+        padded = numpy.pad(coefficients, (0, 10))
 
         match self.formula_type:
             case 1:  # Formula 1 computation (standard Sellmeier)
-                n_squared = 1.0
-                for (B, C) in zipped_coefficients:
-                    n_squared += (B * wavelength.to(ureg.micrometer).magnitude**2) / (wavelength.to(ureg.micrometer).magnitude**2 - C**2)
-
+                n_squared = 1.0 + padded[0]
+                for B, C in zip(coefficients[1::2], coefficients[2::2]):
+                    n_squared += B * wavelength_um**2 / (wavelength_um**2 - C**2)
                 n = numpy.sqrt(n_squared)
 
             case 2:  # Formula 2 computation (extended Sellmeier)
-                n_squared = 1 + self.coefficients[0]
-                for (B, C) in zipped_coefficients:
-                    n_squared += (B * wavelength.to(ureg.micrometer).magnitude**2) / (wavelength.to(ureg.micrometer).magnitude**2 - C)
+                n_squared = 1 + padded[0]
+                for B, C in zip(coefficients[1::2], coefficients[2::2]):
+                    n_squared += B * wavelength_um**2 / (wavelength_um**2 - C)
+                n = numpy.sqrt(n_squared)
+
+            case 3:  # Polynomial
+                n_squared = padded[0]
+                for B, exponent in zip(coefficients[1::2], coefficients[2::2]):
+                    n_squared += B * wavelength_um**exponent
+                n = numpy.sqrt(n_squared)
+
+            case 4:  # RefractiveIndex.INFO
+                n_squared = padded[0]
+                for index in range(1, min(8, len(coefficients)), 4):
+                    B, exponent, C, power = padded[index:index + 4]
+                    n_squared += B * wavelength_um**exponent / (wavelength_um**2 - C**power)
+                for B, exponent in zip(coefficients[9::2], coefficients[10::2]):
+                    n_squared += B * wavelength_um**exponent
                 n = numpy.sqrt(n_squared)
 
             case 5:  # Formula 5 computation (extended Sellmeier)
-                n = 1 + self.coefficients[0]
-                for (B, C) in zipped_coefficients:
-                    n += B * wavelength.to(ureg.micrometer).magnitude**C
+                n = padded[0]
+                for B, exponent in zip(coefficients[1::2], coefficients[2::2]):
+                    n += B * wavelength_um**exponent
 
             case 6:
-                n = 1 + self.coefficients[0]
-                for (B, C) in zipped_coefficients:
-                    n = B / (C - wavelength.to(ureg.micrometer).magnitude**-2)
+                n = 1 + padded[0]
+                for B, C in zip(coefficients[1::2], coefficients[2::2]):
+                    n += B / (C - wavelength_um**-2)
+
+            case 7:  # Herzberger
+                n = padded[0] + padded[1] / (wavelength_um**2 - 0.028)
+                n += padded[2] / (wavelength_um**2 - 0.028)**2
+                for index, coefficient in enumerate(coefficients[3:], start=3):
+                    n += coefficient * wavelength_um**(2 * (index - 2))
+
+            case 8:  # Retro
+                temporary = padded[0] + padded[1] * wavelength_um**2 / (wavelength_um**2 - padded[2])
+                temporary += padded[3] * wavelength_um**2
+                n = numpy.sqrt((2 * temporary + 1) / (1 - temporary))
+
+            case 9:  # Exotic
+                n = numpy.sqrt(
+                    padded[0]
+                    + padded[1] / (wavelength_um**2 - padded[2])
+                    + padded[3] * (wavelength_um - padded[4])
+                    / ((wavelength_um - padded[4])**2 + padded[5])
+                )
 
             case _:
                 raise ValueError(f"Unsupported formula type: {self.formula_type}")
 
         return n[0] if return_as_scalar else n
 
-    @helper.pre_plot(nrows=1, ncols=1)
-    def plot(self, axes, samples: int = 100) -> None:
+    def plot(self, axes=None, samples: int = 100) -> None:
         """
         Plots the refractive index as a function of wavelength over a specified range.
 
         Parameters
         ----------
-        axes : matplotlib.axes.Axes
-            Axes on which to draw the dispersion curve.
+        axes : matplotlib.axes.Axes, optional
+            Axes on which to draw the dispersion curve. A compact, styled
+            figure is created when omitted.
         samples : int
             The number of samples to use for the wavelength range.
 
@@ -195,6 +227,11 @@ class SellmeierMaterial(BaseMaterial):
         ValueError
             If the wavelength is not a 1D array or list of float values.
         """
+        if axes is None:
+            figure, axes = plt.subplots(figsize=(7, 4.5), layout="constrained")
+        else:
+            figure = axes.figure
+        figure.set_size_inches(7, 4.5, forward=True)
         wavelength = numpy.linspace(
             self.wavelength_bound[0].magnitude,
             self.wavelength_bound[1].magnitude,
@@ -207,10 +244,16 @@ class SellmeierMaterial(BaseMaterial):
         axes.set(
             ylabel='Refractive Index',
             xlabel=r'Wavelength [$\mu$m]',
-            title=f"Refractive Index vs. Wavelength: [{self.filename}]"
+            title=f"Refractive index: {self.filename}",
         )
-        axes.plot(wavelength.to(ureg.micrometer).magnitude, refractive_index.real, linewidth=2, label='Real Part')
+        axes.set_title(axes.get_title(), fontsize=14, pad=12)
+        axes.set_xlabel(axes.get_xlabel(), fontsize=11)
+        axes.set_ylabel(axes.get_ylabel(), fontsize=11)
+        axes.tick_params(labelsize=10)
+        axes.grid(alpha=0.25, linewidth=0.7)
+        axes.plot(wavelength.to(ureg.micrometer).magnitude, refractive_index.real, linewidth=2, label='n')
         axes.legend()
+        return None
 
     def print(self) -> str:
         """