PyOptik 3.0.0__tar.gz → 3.0.5__tar.gz

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

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

pyoptik-3.0.5/CHANGELOG.md

@@ -0,0 +1,47 @@
+# 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λ`.
+- 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.
+
+### 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.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyOptik
-Version: 3.0.0
+Version: 3.0.5
 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
@@ -192,6 +191,12 @@ 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.
+
 Validity ranges
 ~~~~~~~~~~~~~~~
 
@@ -228,7 +233,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 +307,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 +403,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.5}/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.5'
+__version_tuple__ = version_tuple = (3, 0, 5)
 
-__commit_id__ = commit_id = 'g8275e8e4b'
+__commit_id__ = commit_id = 'g3091905a0'

{pyoptik-3.0.0 → pyoptik-3.0.5}/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,30 @@ 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."""
+    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
+            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
 
@@ -97,9 +151,19 @@ class MaterialPage:
                 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)
+                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):
-                return TabulatedMaterial(self.name, file_path=self.local_path)
+                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(
@@ -146,7 +210,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 +365,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 +416,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 +435,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 +557,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.5}/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.5}/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.
 
@@ -228,13 +335,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 +358,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