PyOptik 3.0.4__tar.gz → 3.0.5__tar.gz

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

@@ -17,6 +17,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyOptik
-Version: 3.0.4
+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
@@ -191,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
 ~~~~~~~~~~~~~~~
 

{pyoptik-3.0.4 → 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.4'
-__version_tuple__ = version_tuple = (3, 0, 4)
+__version__ = version = '3.0.5'
+__version_tuple__ = version_tuple = (3, 0, 5)
 
-__commit_id__ = commit_id = 'gcad6d74ee'
+__commit_id__ = commit_id = 'g3091905a0'

{pyoptik-3.0.4 → pyoptik-3.0.5}/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
@@ -145,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(

{pyoptik-3.0.4 → 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.
 

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

@@ -50,6 +50,8 @@ class SellmeierMaterial(BaseMaterial):
         self.coefficients = None
         self.wavelength_bound = None
         self.reference = None
+        self.conditions = None
+        self.comments = None
         self.formula_type = None
 
         self._load_coefficients()
@@ -101,14 +103,17 @@ class SellmeierMaterial(BaseMaterial):
         else:
             self.wavelength_bound = None
 
-        # # Extract reference
+        # Preserve upstream provenance and experimental conditions.
         self.reference = parsed_yaml.get('REFERENCES', None)
+        self.conditions = parsed_yaml.get('CONDITIONS', {})
+        self.comments = parsed_yaml.get('COMMENTS', None)
         logger.debug("Validated Sellmeier material '%s' with formula %s", self.filename, self.formula_type)
 
     @validate_units
     def compute_refractive_index(self, wavelength: Length | float, out_of_range: str = "warn") -> RefractiveIndex:
         r"""
-        Computes the refractive index n(\u03bb) using the appropriate formula (either Formula 1, 2, 5, or 6).
+        Computes the refractive index n(\u03bb) using the appropriate
+        RefractiveIndex.INFO dispersion formula (types 1 through 9).
 
         Parameters
         ----------

{pyoptik-3.0.4 → pyoptik-3.0.5}/PyOptik/material/tabulated_class.py

@@ -32,7 +32,7 @@ class TabulatedMaterial(BaseMaterial):
         Reference information for the material data.
     """
 
-    def __init__(self, filename: str, file_path=None):
+    def __init__(self, filename: str, file_path=None, interpolation: str = "linear"):
         """
         Initializes the TabulatedMaterial with a filename.
 
@@ -43,9 +43,15 @@ class TabulatedMaterial(BaseMaterial):
         file_path : pathlib.Path, optional
             Explicit YAML path for hierarchy-preserving catalog pages. When
             omitted, the user material directory is searched.
+        interpolation : {"linear", "pchip"}, optional
+            Interpolation method. ``"linear"`` is the default;
+            ``"pchip"`` provides monotonic piecewise-cubic interpolation.
         """
         self.filename = filename
         self.file_path = file_path
+        if interpolation not in {"linear", "pchip"}:
+            raise ValueError("interpolation must be 'linear' or 'pchip'.")
+        self.interpolation = interpolation
 
         # Initialize attributes
         self.wavelength_bound = None
@@ -53,6 +59,10 @@ class TabulatedMaterial(BaseMaterial):
         self.n_values = None
         self.k_values = None
         self.reference = None
+        self.conditions = None
+        self.comments = None
+        self._n_wavelength = None
+        self._k_wavelength = None
 
         # Load tabulated data from the YAML file
         self._load_tabulated_data()
@@ -86,24 +96,41 @@ class TabulatedMaterial(BaseMaterial):
         logger.debug("Loaded tabulated data from %s", file_path)
 
         try:
-            # Extract data points
-            data_points = parsed_yaml['DATA'][0]['data'].strip().split('\n')
-            data = numpy.array([[float(value) for value in point.split()] for point in data_points])
-            if data.ndim != 2 or data.shape[1] != 3 or len(data) < 2:
-                raise ValueError("tabulated data must contain at least two rows of wavelength, n, k")
-            if not numpy.all(numpy.isfinite(data)) or numpy.any(numpy.diff(data[:, 0]) <= 0):
-                raise ValueError("tabulated wavelengths must be finite and strictly increasing")
-
-            self.wavelength = data[:, 0] * ureg.micrometer
-            self.n_values = data[:, 1]
-            self.k_values = data[:, 2]
-        except (KeyError, IndexError, ValueError):
+            for entry in parsed_yaml['DATA']:
+                kind = str(entry.get('type', '')).lower().split()
+                if len(kind) != 2 or kind[0] != 'tabulated' or kind[1] not in {'n', 'k', 'nk'}:
+                    continue
+                data = numpy.array(
+                    [[float(value) for value in row.split()] for row in entry['data'].strip().splitlines()]
+                )
+                expected_columns = 3 if kind[1] == 'nk' else 2
+                if data.ndim != 2 or data.shape[1] != expected_columns or len(data) < 2:
+                    raise ValueError(f"tabulated {kind[1]} data must contain at least two valid rows")
+                if not numpy.all(numpy.isfinite(data)) or numpy.any(numpy.diff(data[:, 0]) <= 0):
+                    raise ValueError("tabulated wavelengths must be finite and strictly increasing")
+                wavelengths = data[:, 0] * ureg.micrometer
+                if kind[1] in {'n', 'nk'}:
+                    self._n_wavelength = wavelengths
+                    self.n_values = data[:, 1]
+                if kind[1] == 'k':
+                    self._k_wavelength = wavelengths
+                    self.k_values = data[:, 1]
+                elif kind[1] == 'nk':
+                    self._k_wavelength = wavelengths
+                    self.k_values = data[:, 2]
+            if self.n_values is None and self.k_values is None:
+                raise ValueError("no supported tabulated n, k, or nk dataset found")
+            self.wavelength = self._n_wavelength if self._n_wavelength is not None else self._k_wavelength
+        except (KeyError, IndexError, TypeError, ValueError) as error:
             raise ValueError(f"Invalid or missing data in YAML file {file_path}")
 
-        self.wavelength_bound = [self.wavelength.min().magnitude, self.wavelength.max().magnitude] * ureg.micrometer
+        ranges = [values for values in (self._n_wavelength, self._k_wavelength) if values is not None]
+        self.wavelength_bound = [min(values.min().magnitude for values in ranges), max(values.max().magnitude for values in ranges)] * ureg.micrometer
 
         # Extract reference
         self.reference = parsed_yaml.get('REFERENCES', None)
+        self.conditions = parsed_yaml.get('CONDITIONS', {})
+        self.comments = parsed_yaml.get('COMMENTS', None)
         logger.debug("Validated tabulated material '%s' with %s points", self.filename, len(self.wavelength))
 
     @validate_units
@@ -145,13 +172,47 @@ class TabulatedMaterial(BaseMaterial):
             # behavior explicit for future range implementations.
             pass
 
-        n_interp = numpy.interp(wavelength.to(ureg.meter).magnitude, self.wavelength.to(ureg.meter).magnitude, self.n_values)
-        k_interp = numpy.interp(wavelength.to(ureg.meter).magnitude, self.wavelength.to(ureg.meter).magnitude, self.k_values)
+        values = wavelength.to(ureg.meter).magnitude
+        n_interp = self._interpolate(values, self._n_wavelength, self.n_values, default=1.0)
+        k_interp = self._interpolate(values, self._k_wavelength, self.k_values, default=0.0)
 
         index = n_interp + 1j * k_interp
 
         return index[0] if return_as_scalar else index
 
+    def _interpolate(self, values, wavelengths, data, default: float):
+        """Interpolate one optical-constant component with endpoint extrapolation."""
+        if wavelengths is None or data is None:
+            return numpy.full(values.shape, default, dtype=float)
+        x = wavelengths.to(ureg.meter).magnitude
+        if self.interpolation == "linear":
+            result = numpy.interp(values, x, data)
+            left = values < x[0]
+            right = values > x[-1]
+            result[left] = data[0] + (values[left] - x[0]) * (data[1] - data[0]) / (x[1] - x[0])
+            result[right] = data[-1] + (values[right] - x[-1]) * (data[-1] - data[-2]) / (x[-1] - x[-2])
+            return result
+        return self._pchip(values, x, data)
+
+    @staticmethod
+    def _pchip(values, x, y):
+        """Evaluate monotonic cubic Hermite interpolation with linear extrapolation."""
+        h = numpy.diff(x)
+        delta = numpy.diff(y) / h
+        slopes = numpy.empty_like(y, dtype=float)
+        slopes[0], slopes[-1] = delta[0], delta[-1]
+        for index in range(1, len(y) - 1):
+            if delta[index - 1] * delta[index] <= 0:
+                slopes[index] = 0.0
+            else:
+                w1, w2 = 2 * h[index] + h[index - 1], h[index] + 2 * h[index - 1]
+                slopes[index] = (w1 + w2) / (w1 / delta[index - 1] + w2 / delta[index])
+        intervals = numpy.clip(numpy.searchsorted(x, values, side='right') - 1, 0, len(x) - 2)
+        step = h[intervals]
+        t = (values - x[intervals]) / step
+        result = ((2*t**3 - 3*t**2 + 1) * y[intervals] + (t**3 - 2*t**2 + t) * step * slopes[intervals] + (-2*t**3 + 3*t**2) * y[intervals + 1] + (t**3 - t**2) * step * slopes[intervals + 1])
+        return result
+
     def plot(self, axes=None, samples: int = 100) -> None:
         """
         Plots the tabulated refractive index (n) and absorption (k) as a function of wavelength.

{pyoptik-3.0.4 → pyoptik-3.0.5}/PyOptik.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyOptik
-Version: 3.0.4
+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
@@ -191,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
 ~~~~~~~~~~~~~~~
 

{pyoptik-3.0.4 → pyoptik-3.0.5}/PyOptik.egg-info/SOURCES.txt

@@ -52,6 +52,7 @@ docs/images/example_bk7.png
 docs/images/logo.svg
 docs/source/code.rst
 docs/source/conf.py
+docs/source/conventions.rst
 docs/source/examples.rst
 docs/source/index.rst
 docs/source/references.rst

{pyoptik-3.0.4 → pyoptik-3.0.5}/PyOptik.egg-info/scm_file_list.json

@@ -47,6 +47,7 @@
     "docs/source/_static/thumbnail.png",
     "docs/source/code.rst",
     "docs/source/conf.py",
+    "docs/source/conventions.rst",
     "docs/source/examples.rst",
     "docs/source/index.rst",
     "docs/source/references.rst",

pyoptik-3.0.5/PyOptik.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "3.0.5",
+  "distance": 0,
+  "node": "g3091905a0f08639e9897ebe92c762e837617f0bf",
+  "dirty": true,
+  "branch": "HEAD",
+  "node_date": "2026-08-22"
+}

{pyoptik-3.0.4 → pyoptik-3.0.5}/README.rst

@@ -132,6 +132,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
 ~~~~~~~~~~~~~~~
 

pyoptik-3.0.5/docs/source/conventions.rst

@@ -0,0 +1,49 @@
+Physical conventions and data provenance
+========================================
+
+Wavelength and optical constants
+--------------------------------
+
+PyOptik accepts vacuum wavelength quantities. Always attach units—for example
+``1550 * ureg.nanometer``—to avoid ambiguity. Bare numeric inputs are retained
+for compatibility and interpreted as metres.
+
+The complex refractive index uses the convention ``N = n + i k``: ``n`` is the
+real refractive index and ``k`` is the non-negative extinction coefficient.
+The convenience methods ``material.n(wavelength)``, ``material.k(wavelength)``,
+``material.relative_permittivity(wavelength)``, and
+``material.absorption_coefficient(wavelength)`` expose common derived values.
+The relative permittivity is ``N²`` and the intensity absorption coefficient is
+``α = 4πk / λ``.
+
+Dispersion and group delay
+--------------------------
+
+``compute_group_delay_dispersion`` returns conventional frequency-domain GDD,
+``dτ_g/dω = d²β/dω² × length``. Its units are time squared (typically fs²).
+``compute_group_delay_wavelength_slope`` is deliberately separate because it
+returns ``dτ_g/dλ``, a wavelength-space derivative with different units.
+
+Interpolation and validity ranges
+---------------------------------
+
+Tabulated materials use linear interpolation by default. Pass
+``interpolation="pchip"`` to ``MaterialPage.load`` or ``TabulatedMaterial`` for
+monotonic piecewise-cubic interpolation without overshoot. Both methods use
+linear endpoint extrapolation when ``out_of_range="warn"``; set
+``out_of_range="raise"`` for strict validity enforcement, or
+``out_of_range="clip"`` to evaluate at the nearest source boundary.
+
+Provenance and conditions
+-------------------------
+
+Every loaded material provides ``material.provenance``. It contains the source
+reference, upstream catalog ID and URL when available, source path, stated
+wavelength range, and the upstream YAML ``CONDITIONS`` and ``COMMENTS`` fields.
+Use it when recording simulation inputs or preparing results for publication.
+
+.. code-block:: python
+
+   page = catalog.get("specs/SCHOTT-optical/N-BK7")
+   material = page.load()
+   print(material.provenance)

{pyoptik-3.0.4 → pyoptik-3.0.5}/docs/source/index.rst

@@ -8,5 +8,6 @@
     :maxdepth: 2
 
     code.rst
+    conventions.rst
     examples.rst
     references.rst

{pyoptik-3.0.4 → pyoptik-3.0.5}/tests/test_material_models.py

@@ -65,6 +65,30 @@ def test_canonical_tabulated_material_and_group_properties(tmp_path):
     index = material.compute_refractive_index(wavelengths)
     assert index.shape == wavelengths.shape
     assert np.all(np.isfinite(material.compute_group_index(wavelengths).magnitude))
+    wavelength = 0.8 * ureg.micrometer
+    assert material.n(wavelength) == pytest.approx(material.compute_refractive_index(wavelength).real)
+    assert material.k(wavelength) == pytest.approx(material.compute_refractive_index(wavelength).imag)
+    assert material.relative_permittivity(wavelength) == pytest.approx(material.compute_refractive_index(wavelength) ** 2)
+    assert material.absorption_coefficient(wavelength).to(1 / ureg.meter).magnitude > 0
+
+
+def test_tabulated_n_and_k_blocks_support_pchip_and_provenance(tmp_path):
+    data_file = tmp_path / "split.yml"
+    data_file.write_text(
+        "REFERENCES: Example et al. 2026\n"
+        "CONDITIONS:\n  temperature: 293 K\n"
+        "DATA:\n"
+        "  - type: tabulated n\n    data: |\n      0.4 1.4\n      0.8 1.6\n      1.2 1.8\n"
+        "  - type: tabulated k\n    data: |\n      0.4 0.01\n      0.8 0.02\n      1.2 0.03\n"
+    )
+    from PyOptik.material import TabulatedMaterial
+
+    material = TabulatedMaterial("split", file_path=data_file, interpolation="pchip")
+    index = material.refractive_index(0.6 * ureg.micrometer)
+    assert index.real == pytest.approx(1.5)
+    assert index.imag == pytest.approx(0.015)
+    assert material.provenance["reference"] == "Example et al. 2026"
+    assert material.provenance["conditions"]["temperature"] == "293 K"
 
 
 def test_formula_six_accumulates_all_gas_terms(tmp_path):

pyoptik-3.0.4/PyOptik.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "3.0.4",
-  "distance": 0,
-  "node": "gcad6d74eeab6e3a6c39281193f6233dc6ed15aa3",
-  "dirty": true,
-  "branch": "HEAD",
-  "node_date": "2026-08-21"
-}