PyOptik 3.2.1__tar.gz → 3.3.0__tar.gz

{pyoptik-3.2.1 → pyoptik-3.3.0}/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.3.0] - 2026-10-01
+
+### Added
+
+- `material(name)` and `load_material(name)` for common-name and chemical-formula
+  lookup, with documented defaults for silica, gold, silver, water, and N-BK7.
+- Explicit source overrides, canonical-ID lookup, and `use_default=False` for
+  workflows that require an explicit choice among competing datasets.
+- `find_materials()` and `AmbiguousMaterialError.candidates` for discovery with
+  dataset descriptions and provenance; missing defaults never select substitutes.
+- `nk()` as a short alias for complex refractive-index evaluation.
+- A gallery example covering lookup, defaults, source overrides, and provenance.
+- Three focused tutorials with plots, scripts, downloadable notebooks, and
+  Google Colab links: silica dispersion, gold optical constants, and coatings.
+
+### Changed
+
+- The README leads with a useful plot and runnable example, with status badges
+  further down the page.
+- Getting-started documentation and material-data tutorials now introduce
+  common-name lookup alongside the canonical catalog API.
+- The existing `PyOptik.material` package remains importable and is callable as
+  a convenience loader, preserving existing class and submodule imports.
+
 ## [3.2.0] - 2026-09-16
 
 ### Added
@@ -79,6 +103,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   plotting helpers.
 - Retired logo assets.
 
-[Unreleased]: https://github.com/MartinPdeS/PyOptik/compare/v3.2.0...HEAD
+[Unreleased]: https://github.com/MartinPdeS/PyOptik/compare/v3.3.0...HEAD
+[3.3.0]: https://github.com/MartinPdeS/PyOptik/compare/v3.2.1...v3.3.0
 [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.1 → pyoptik-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyOptik
-Version: 3.2.1
+Version: 3.3.0
 Summary: A package for refractive index values.
 Author-email: Martin Poinsinet de Sivry-Houle <martin.poinsinet.de.sivry@gmail.com>
 License: MIT License
@@ -61,40 +61,97 @@ Dynamic: license-file
 
 |logo|
 
-.. list-table::
-   :widths: 35 65
-   :header-rows: 1
-
-   * - Badge
-     - Status
-   * - Python versions
-     - |python|
-   * - Documentation
-     - |docs|
-   * - Continuous integration
-     - |ci/cd|
-   * - Test coverage
-     - |coverage|
-   * - PyPI package
-     - |PyPi|
-   * - PyPI downloads
-     - |PyPi_download|
-   * - Anaconda package
-     - |anaconda|
-   * - Anaconda downloads
-     - |anaconda_download|
-
 PyOptik
 =======
 
-**PyOptik** is a Python library for evaluating optical material properties.
-It provides unit-aware refractive-index calculations, dispersion models,
-tabulated optical constants, group-delay properties, plotting helpers, and a
-catalog interface for the hierarchical `RefractiveIndex.INFO
-<https://refractiveindex.info>`_ database.
+**Get wavelength-dependent optical constants and calculate dispersion or
+coating reflectance in Python.** PyOptik combines the RefractiveIndex.INFO
+material catalog with unit-aware calculations for optical materials,
+interfaces, and coherent thin-film stacks.
+
+.. image:: https://raw.githubusercontent.com/MartinPdeS/PyOptik/master/docs/source/_static/tutorials/antireflection_coating.png
+   :alt: Coated glass has a reflection minimum at 550 nm compared with uncoated glass.
+   :width: 700
+
+Make your first plot
+--------------------
+
+Install PyOptik:
+
+.. code-block:: bash
+
+   python -m pip install PyOptik
+
+Compare bare glass with an ideal quarter-wave coating. This example needs
+no material database download:
+
+.. code-block:: python
+
+   import matplotlib.pyplot as plt
+   import numpy as np
+   from TypedUnit import ureg
+   from PyOptik import ThinFilmLayer, thin_film_stack
+
+   wavelengths = np.linspace(350, 900, 600) * ureg.nanometer
+   coating_index = np.sqrt(1.52)
+   coating = ThinFilmLayer(coating_index, 550 * ureg.nanometer / (4 * coating_index))
+   bare = thin_film_stack(wavelengths, [], substrate_index=1.52)
+   coated = thin_film_stack(wavelengths, [coating], substrate_index=1.52)
 
-The library is designed for optical design, photonics simulations,
-electromagnetic modeling, and experimental data analysis.
+   plt.plot(wavelengths.magnitude, 100 * bare.reflectance, label="Bare glass")
+   plt.plot(wavelengths.magnitude, 100 * coated.reflectance, label="Coated glass")
+   plt.xlabel("Vacuum wavelength [nm]")
+   plt.ylabel("Reflectance [%]")
+   plt.legend()
+   plt.show()
+
+The ideal coating suppresses reflection at 550 nm. The
+`full coating tutorial <https://martinpdes.github.io/PyOptik/docs/latest/tutorials/antireflection_coating.html>`_
+explains the physics and assumptions.
+
+Load a material by name
+-----------------------
+
+Use a familiar name or formula. Common names load documented datasets;
+choose another source whenever your experiment needs it. The first lookup
+downloads the material snapshot; later lookups use the local cache:
+
+.. code-block:: python
+
+   from PyOptik import material
+   from TypedUnit import ureg
+
+   bk7 = material("N-BK7")
+   silica = material("SiO2")
+   gold = material("Au")
+
+   print(bk7.n(532 * ureg.nm))
+   print(gold.nk(633 * ureg.nm))
+   print(gold.catalog_id)  # main/Au/Johnson
+   bk7.plot()
+
+Defaults are Malitson for silica, Johnson and Christy for gold and silver,
+Hale and Querry for water, and SCHOTT N-BK7 for ``BK7``/``N-BK7``. Inspect the
+resolved source through ``catalog_id`` and ``provenance``. Override a default
+with ``material("Au", source="Rakic-LD")``, or inspect all candidates with
+``find_materials("gold")``. Use ``use_default=False`` to require a source
+when several datasets match. Other ambiguous names list the candidates
+instead of guessing. See the
+`default-source table <https://martinpdes.github.io/PyOptik/docs/latest/materials_and_catalog.html#find-a-material-by-name>`_
+for canonical IDs; use ``material("main/Au/Johnson")`` to pin a dataset.
+
+Learn through a useful result
+-----------------------------
+
+* `Calculate silica group index and dispersion in Python <https://martinpdes.github.io/PyOptik/docs/latest/tutorials/silica_dispersion.html>`_
+  — compare phase and group index, then calculate GDD through 1 mm of glass.
+* `Plot gold's refractive index and extinction coefficient <https://martinpdes.github.io/PyOptik/docs/latest/tutorials/gold_optical_constants.html>`_
+  — load measured optical constants and plot n and k.
+* `Design an antireflection coating in Python <https://martinpdes.github.io/PyOptik/docs/latest/tutorials/antireflection_coating.html>`_
+  — choose a layer thickness and compare coated and uncoated glass.
+
+Each tutorial includes a plot, a downloadable script and notebook, and an
+**Open in Colab** button.
 
 Documentation
 -------------
@@ -117,6 +174,7 @@ The full documentation is organized by task:
 Features
 --------
 
+* Material lookup by common name with documented defaults and source overrides.
 * Sellmeier and other dispersion-formula models.
 * Tabulated complex refractive index data, ``n + i k``.
 * Unit-aware wavelength calculations through ``TypedUnit`` and Pint.
@@ -488,6 +546,32 @@ Common issues
 * If a material cannot be found, run ``pyoptik setup`` or call
   ``download_snapshot()`` before loading its canonical page.
 
+Project status
+--------------
+
+.. list-table::
+   :widths: 35 65
+   :header-rows: 1
+
+   * - Badge
+     - Status
+   * - Python versions
+     - |python|
+   * - Documentation
+     - |docs|
+   * - Continuous integration
+     - |ci/cd|
+   * - Test coverage
+     - |coverage|
+   * - PyPI package
+     - |PyPi|
+   * - PyPI downloads
+     - |PyPi_download|
+   * - Anaconda package
+     - |anaconda|
+   * - Anaconda downloads
+     - |anaconda_download|
+
 Development and testing
 -----------------------
 

{pyoptik-3.2.1 → pyoptik-3.3.0}/PyOptik/__init__.py

@@ -30,3 +30,5 @@ from .material import base_class  # noqa: E402
 
 
 TIMEOUT = 10  # Default timeout for requests in seconds
+
+from .discovery import AmbiguousMaterialError, find_materials, load_material  # noqa: E402

{pyoptik-3.2.1 → pyoptik-3.3.0}/PyOptik/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '3.2.1'
-__version_tuple__ = version_tuple = (3, 2, 1)
+__version__ = version = '3.3.0'
+__version_tuple__ = version_tuple = (3, 3, 0)
 
-__commit_id__ = commit_id = 'g6f0650682'
+__commit_id__ = commit_id = 'gefc1d294d'

pyoptik-3.3.0/PyOptik/discovery.py

@@ -0,0 +1,277 @@
+"""Human-readable material discovery backed by canonical catalog identities."""
+
+from difflib import get_close_matches
+from pathlib import Path
+import unicodedata
+
+from .catalog import MaterialCatalog, MaterialPage
+
+
+# Aliases identify a material family; documented defaults are applied only
+# by load_material, never by discovery or explicit source selection.
+_BOOK_ALIASES = {
+    "sio2": ("main", "SiO2"),
+    "silica": ("main", "SiO2"),
+    "fusedsilica": ("main", "SiO2"),
+    "au": ("main", "Au"),
+    "gold": ("main", "Au"),
+    "ag": ("main", "Ag"),
+    "silver": ("main", "Ag"),
+    "si": ("main", "Si"),
+    "silicon": ("main", "Si"),
+    "h2o": ("main", "H2O"),
+    "water": ("main", "H2O"),
+}
+_PAGE_ALIASES = {
+    "bk7": "specs/SCHOTT-optical/N-BK7",
+    "nbk7": "specs/SCHOTT-optical/N-BK7",
+}
+
+
+# These source choices are part of the convenience API, not a ranking of
+# measurement quality. Keep canonical IDs explicit and document any changes.
+_DEFAULT_SOURCES = {
+    ("main", "SiO2"): "main/SiO2/Malitson",
+    ("main", "Au"): "main/Au/Johnson",
+    ("main", "Ag"): "main/Ag/Johnson",
+    ("main", "H2O"): "main/H2O/Hale",
+}
+
+
+def _normalize(value: str) -> str:
+    """Normalize case, accents, spacing, and punctuation for exact matching."""
+    value = unicodedata.normalize("NFKD", value).casefold()
+    return "".join(character for character in value if character.isalnum())
+
+
+def _nonempty(value: str, label: str) -> str:
+    """Validate a required non-empty name or source argument."""
+    if not isinstance(value, str):
+        raise TypeError(f"{label} must be a string.")
+    if not _normalize(value):
+        raise ValueError(f"{label} must not be empty.")
+    return value.strip()
+
+
+def _get_catalog(catalog: MaterialCatalog | None, data_root: Path | str | None) -> MaterialCatalog:
+    """Read a local index or obtain the snapshot on the first lookup."""
+    if catalog is not None:
+        if data_root is not None:
+            raise ValueError("Pass either catalog or data_root, not both.")
+        return catalog
+    from .directories import user_data_path
+
+    root = Path(data_root or (user_data_path / "rii")).expanduser()
+    catalog_file = root / "catalog-nk.yml"
+    if catalog_file.is_file():
+        return MaterialCatalog(catalog_file=catalog_file, data_root=root)
+    return MaterialCatalog.from_snapshot(data_root=root)
+
+
+def _candidates(name: str, catalog: MaterialCatalog) -> list[MaterialPage]:
+    """Resolve exact identities and families before falling back to text search."""
+    if "/" in name:
+        return [catalog.get(name)]
+    normalized = _normalize(name)
+    if normalized in _PAGE_ALIASES:
+        return [catalog.get(_PAGE_ALIASES[normalized])]
+    if normalized in _BOOK_ALIASES:
+        shelf, book = _BOOK_ALIASES[normalized]
+        return catalog.pages(shelf=shelf, book=book)
+    pages = catalog.pages()
+    exact_books = [page for page in pages if _normalize(page.id.book) == normalized]
+    if exact_books:
+        return exact_books
+    exact_pages = [page for page in pages if _normalize(page.id.page) == normalized]
+    if exact_pages:
+        return exact_pages
+    return catalog.search(name)
+
+
+def _select_source(pages: list[MaterialPage], source: str) -> list[MaterialPage]:
+    """Prefer an exact page ID to a partial source or description match."""
+    normalized = _normalize(source)
+    exact = [page for page in pages if normalized in (
+        _normalize(page.id.page), _normalize(page.id.key),
+    )]
+    if exact:
+        return exact
+    return [page for page in pages if any(
+        normalized in _normalize(value)
+        for value in (page.id.page, page.description or "")
+    )]
+
+
+class AmbiguousMaterialError(ValueError):
+    """A name or source matches several scientific datasets.
+
+    Attributes
+    ----------
+    candidates : list of MaterialPage
+        Matching pages in canonical order, including descriptions and provenance.
+    """
+
+    def __init__(self, name: str, candidates: list[MaterialPage]):
+        """List candidate identities and show how to select a source explicitly."""
+        self.candidates = candidates
+        lines = [f"Multiple datasets found for {name!r}:"]
+        lines.extend(
+            f"  {number}. {page.id.key}: {page.description or page.name}"
+            for number, page in enumerate(candidates, start=1)
+        )
+        first = candidates[0]
+        lines.extend([
+            "",
+            f"Select a source with material({name!r}, source={first.id.page!r}),",
+            f"or use a canonical ID: material({first.id.key!r}).",
+            "Use find_materials(name) to inspect candidates and provenance.",
+        ])
+        super().__init__("\n".join(lines))
+
+
+def find_materials(
+    name: str,
+    *,
+    source: str | None = None,
+    catalog: MaterialCatalog | None = None,
+    data_root: Path | str | None = None,
+) -> list[MaterialPage]:
+    """Find material datasets by common name, formula, or canonical identity.
+
+    Parameters
+    ----------
+    name : str
+        Common name (gold, fused silica, water), formula (Au, SiO2), glass
+        name (BK7, N-BK7), or canonical shelf/book/page ID. BK7 is an explicit
+        alias for SCHOTT N-BK7. Other aliases select families; find_materials always returns all sources.
+    source : str, optional
+        Page ID, canonical ID, or source-description text. Exact page IDs
+        take precedence over partial matches.
+    catalog : MaterialCatalog, optional
+        Existing catalog, including custom or offline catalogs.
+    data_root : pathlib.Path or str, optional
+        Snapshot location. Cannot be combined with catalog.
+
+    Returns
+    -------
+    list of MaterialPage
+        Candidates in canonical order, or an empty list if none match.
+
+    Notes
+    -----
+    Names and source descriptions ignore case, accents, spaces, and punctuation
+    for exact matching. General text search uses the catalog's case-insensitive
+    substring search. The first lookup downloads the snapshot if no local
+    index exists. An existing index is read locally without a network request.
+    """
+    name = _nonempty(name, "name")
+    if source is not None:
+        source = _nonempty(source, "source")
+    resolved_catalog = _get_catalog(catalog, data_root)
+    try:
+        pages = _candidates(name, resolved_catalog)
+    except KeyError:
+        return []
+    return _select_source(pages, source) if source is not None else pages
+
+
+def load_material(
+    name: str,
+    *,
+    source: str | None = None,
+    catalog: MaterialCatalog | None = None,
+    data_root: Path | str | None = None,
+    interpolation: str = "linear",
+    use_default: bool = True,
+):
+    """Load a material by name with documented defaults and source overrides.
+
+    This is also available as ``from PyOptik import material; material(...)``.
+    Common names use documented canonical defaults unless source is supplied
+    or use_default is False. Other ambiguous queries raise an error listing
+    sources and canonical IDs. Ordering and cache availability never select
+    a dataset.
+
+    Parameters
+    ----------
+    name : str
+        Common name, chemical formula, glass name, or canonical page ID.
+    source : str, optional
+        Exact page ID or source-description text. Use the exact ID when
+        a source publishes several datasets or measurement conditions.
+    catalog : MaterialCatalog, optional
+        Existing catalog for custom data or offline operation.
+    data_root : pathlib.Path or str, optional
+        Snapshot directory. Cannot be combined with catalog.
+    interpolation : {"linear", "pchip"}, optional
+        Interpolation for tabulated data; ignored for formula models.
+    use_default : bool, optional
+        Use the documented source for a known family alias (default True).
+        Set False to require a source whenever several datasets match.
+
+    Returns
+    -------
+    SellmeierMaterial or TabulatedMaterial
+        Loaded model, retaining canonical ID and scientific provenance.
+
+    Raises
+    ------
+    AmbiguousMaterialError
+        More than one dataset matches and no documented default applies, or
+        use_default is False. Inspect candidates or use find_materials.
+    ValueError
+        Empty name or source, or conflicting catalog/data_root arguments.
+    TypeError
+        Name or source is not a string, or use_default is not a bool.
+    KeyError
+        No material or source matches; includes spelling suggestions when possible.
+    FileNotFoundError
+        The chosen page has no local data. Run pyoptik setup to repair the cache.
+
+    Notes
+    -----
+    Defaults are main/SiO2/Malitson for silica, main/Au/Johnson for gold,
+    main/Ag/Johnson for silver, and main/H2O/Hale for water. BK7 and N-BK7
+    refer explicitly to specs/SCHOTT-optical/N-BK7. Loaded models expose
+    catalog_id and provenance. A missing default never falls back to another
+    dataset. See the materials-and-catalog guide for the full source table.
+
+    Examples
+    --------
+    >>> from PyOptik import material
+    >>> gold = material("gold", source="Johnson")  # doctest: +SKIP
+    >>> gold.catalog_id  # doctest: +SKIP
+    'main/Au/Johnson'
+    """
+    name = _nonempty(name, "name")
+    if source is not None:
+        source = _nonempty(source, "source")
+    if not isinstance(use_default, bool):
+        raise TypeError("use_default must be a bool.")
+    resolved_catalog = _get_catalog(catalog, data_root)
+    default = _DEFAULT_SOURCES.get(_BOOK_ALIASES.get(_normalize(name)))
+    if source is None and use_default and default is not None:
+        try:
+            selected = resolved_catalog.get(default)
+        except KeyError as error:
+            raise KeyError(
+                f"Documented default {default!r} for {name!r} is absent from this catalog. "
+                "Use find_materials(name) and select an explicit source."
+            ) from error
+        return selected.load(interpolation=interpolation)
+    pages = find_materials(name, catalog=resolved_catalog)
+    if not pages:
+        known_names = sorted(set(_BOOK_ALIASES) | set(_PAGE_ALIASES) |
+                             {page.id.book for page in resolved_catalog.pages()})
+        suggestions = get_close_matches(_normalize(name), known_names, n=3, cutoff=0.6)
+        hint = f" Did you mean {', '.join(repr(item) for item in suggestions)}?" if suggestions else ""
+        raise KeyError(f"No material found for {name!r}.{hint} Use find_materials(name) to search the catalog.")
+    if source is not None:
+        selected = _select_source(pages, source)
+        if not selected:
+            available = ", ".join(page.id.key for page in pages)
+            raise KeyError(f"No source {source!r} found for {name!r}. Available datasets: {available}")
+        pages = selected
+    if len(pages) > 1:
+        raise AmbiguousMaterialError(name, pages)
+    return pages[0].load(interpolation=interpolation)

pyoptik-3.3.0/PyOptik/material/__init__.py

@@ -0,0 +1,28 @@
+from .base_class import BaseMaterial
+from .sellmeier_class import SellmeierMaterial
+from .tabulated_class import TabulatedMaterial
+from .dataset import FormulaDataset, MaterialDocument, MaterialMetadata, TabulatedDataset, parse_material
+
+# Preserve the existing material package and dotted imports while making the
+# beginner-facing `from PyOptik import material` shortcut callable.
+import sys as _sys
+from types import ModuleType as _ModuleType
+
+
+class _MaterialModule(_ModuleType):
+    """The material package with a convenience loader as its call interface."""
+
+    def __call__(
+        self, name, *, source=None, catalog=None, data_root=None, interpolation="linear",
+        use_default=True,
+    ):
+        """Load a material; see :func:`PyOptik.load_material` for selection rules."""
+        from PyOptik.discovery import load_material
+
+        return load_material(
+            name, source=source, catalog=catalog, data_root=data_root,
+            interpolation=interpolation, use_default=use_default,
+        )
+
+
+_sys.modules[__name__].__class__ = _MaterialModule

{pyoptik-3.2.1 → pyoptik-3.3.0}/PyOptik/material/base_class.py

@@ -56,6 +56,24 @@ class BaseMaterial(object):
         """
         return self.compute_refractive_index(wavelength, **kwargs)
 
+    def nk(self, wavelength: Length, **kwargs):
+        """Return the complex refractive index ``n + i k``.
+
+        Parameters
+        ----------
+        wavelength : Length
+            Vacuum wavelength, as a scalar or array with units.
+        **kwargs
+            Forwarded to :meth:`compute_refractive_index`, including
+            ``out_of_range``.
+
+        Returns
+        -------
+        complex or numpy.ndarray
+            Complex refractive index. Alias of :meth:`refractive_index`.
+        """
+        return self.compute_refractive_index(wavelength, **kwargs)
+
     def n(self, wavelength: Length, **kwargs):
         """Return the real refractive index.