gratinglab 0.1.13__tar.gz → 0.2.1__tar.gz

{gratinglab-0.1.13/src/gratinglab.egg-info → gratinglab-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gratinglab
-Version: 0.1.13
+Version: 0.2.1
 Summary: Open platform for diffraction grating groove metrology and efficiency analysis
 Author: Jake McCoy, Aditi Gangadharan
 License: BSD-3-Clause
@@ -23,6 +23,7 @@ Requires-Dist: numpy>=1.26
 Requires-Dist: scipy>=1.11
 Requires-Dist: pydantic>=2.6
 Requires-Dist: endstation>=0.2.2
+Requires-Dist: threadpoolctl>=3.1
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
 Requires-Dist: pytest-qt>=4.5; extra == "dev"

{gratinglab-0.1.13 → gratinglab-0.2.1}/pyproject.toml

@@ -52,6 +52,13 @@ dependencies = [
     # so this line adds no transitive weight -- the Qt and matplotlib parts sit
     # behind its own extras, which our `gui` extra asks for by name.
     "endstation>=0.2.2",
+    # The rigorous solvers cap BLAS threads for the length of a solve
+    # (solvers/_execution.py): OpenBLAS's thread-per-core default made RCWA
+    # up to 135x slower on a busy machine, measured in benchmarks/
+    # solver_speed.py. NumPy and SciPy each load their own OpenBLAS, and
+    # this is the one maintained way to reach both. Pure Python, BSD-3, no
+    # dependencies of its own.
+    "threadpoolctl>=3.1",
 ]
 
 [project.optional-dependencies]
@@ -175,12 +182,16 @@ filterwarnings = [
     "ignore:Enum value .Qt..ApplicationAttribute.AA_UseHighDpiPixmaps. is marked as deprecated:DeprecationWarning:matplotlib.backends.backend_qt",
     # CI runs with PYTHONWARNDEFAULTENCODING=1, so any text open() here that
     # leaves the encoding to the platform fails on every OS, not only on
-    # Windows with a non-ASCII file. These three are other projects' calls.
+    # Windows with a non-ASCII file. These four are other projects' calls.
     # numpy's savetxt touches its output with a bare open() whatever encoding
-    # it is given. Inert without the flag.
+    # it is given. threadpoolctl reads /proc/self/maps with a bare open(), so
+    # on Linux only, every rigorous solve (which caps BLAS through it) failed
+    # here: master's CI run 40624677314, both ubuntu jobs. Inert without the
+    # flag.
     "ignore::EncodingWarning:matplotlib.font_manager",
     "ignore::EncodingWarning:numpy.lib._npyio_impl",
     "ignore::EncodingWarning:numpy.lib._datasource",
+    "ignore::EncodingWarning:threadpoolctl",
 ]
 # pytest-qt would otherwise probe every binding it knows. Verified clean under
 # `python -W error -c "import PySide6.QtWidgets"`, so `filterwarnings = error`

{gratinglab-0.1.13 → gratinglab-0.2.1}/src/gratinglab/__init__.py

@@ -22,7 +22,7 @@ from .measured import MeasuredEfficiency, MeasurementProvenance
 from .resolution import ResolvingPower, resolving_power
 from .result import EfficiencyScan, OrderEfficiency, Provenance
 
-__version__ = "0.1.13"
+__version__ = "0.2.1"
 
 __all__ = [
     "Illumination",

{gratinglab-0.1.13 → gratinglab-0.2.1}/src/gratinglab/checks.py

@@ -238,6 +238,9 @@ def check_energy_balance(
 
     Notes
     -----
+    Transmitted orders, when the scan records them, are added to the sum: the
+    power a lossless substrate carries away is accounted for, not lost.
+
     When the scan records an absorbed fraction (``scan.absorption``, from a
     solver that computes one independently), the conserved quantity is the
     sum plus the absorption, and that is what is checked. ``R + A = 1`` is a
@@ -253,6 +256,8 @@ def check_energy_balance(
     reached 3.6.
     """
     total = np.asarray(scan.total, dtype=np.float64)
+    if scan.transmission is not None:
+        total = total + scan.transmission.total
     if scan.absorption is not None:
         total = total + scan.absorption
     return EnergyReport(

{gratinglab-0.1.13 → gratinglab-0.2.1}/src/gratinglab/convergence.py

@@ -201,7 +201,10 @@ def default_ladder(solver) -> tuple[int, ...]:
     """A ladder straddling the solver's own default for its accuracy knob.
 
     The default is read from the signature and is not hardcoded, so a backend
-    that changes its default does not leave this sweeping the wrong range.
+    that changes its default does not leave this sweeping the wrong range. A
+    backend declaring an ``accuracy_ceiling`` has the ladder cut there: a sweep
+    that has not plateaued by the ceiling reports that, instead of failing on
+    a rung the solver refuses.
     """
     knob = _knob_of(solver)
     default = inspect.signature(solver.solve).parameters[knob].default
@@ -211,7 +214,11 @@ def default_ladder(solver) -> tuple[int, ...]:
             f"{knob!r} ({default!r}), so a ladder cannot be inferred -- pass "
             "`values` explicitly"
         )
-    return doubling_ladder(max(1, default // 2**_RUNGS_BELOW_DEFAULT), _DEFAULT_RUNGS)
+    ladder = doubling_ladder(max(1, default // 2**_RUNGS_BELOW_DEFAULT), _DEFAULT_RUNGS)
+    ceiling = solver.capabilities.accuracy_ceiling
+    if ceiling is not None:
+        ladder = tuple(value for value in ladder if value <= ceiling)
+    return ladder
 
 
 def check_convergence(

gratinglab-0.2.1/src/gratinglab/gui/cmethod_options.py

@@ -0,0 +1,123 @@
+"""The C-method's own form: boundary condition, truncation, and their guards.
+
+The third options module, written to the pattern of ``integral_options.py``:
+its own file, its own frozen state and its own ``build_options`` raising
+:class:`~gratinglab.gui.state.FormErrors`, and no toolkit import.
+
+The form has two settings, because the solver has two. ``conductivity`` is
+named and offered as the integral solver offers it, so one geometry reaches
+either method with the same choice: ``"perfect"`` (relative efficiency, no
+material) or ``"tabulated"`` (one interface into the coating, read per
+wavelength, with absolute efficiency, absorption and, into a lossless
+material, the transmitted orders). ``truncation`` is the accuracy knob: ``N``
+harmonics either side of the centre of the propagating orders.
+
+The guards mirror the solver's refusals so an error lands on the field that
+caused it instead of arriving as a ValueError from the worker thread. The
+truncation floor is not re-derived here: it is
+:func:`gratinglab.solvers.cmethod.truncation_floor`, the function the solver
+itself applies, so the form and the solver cannot disagree about it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from ..illumination import Illumination
+from ..problem import Problem
+from ..solvers.cmethod import _MAX_TRUNCATION, truncation_floor
+from .integral_options import _tabulated_index
+from .state import FieldError, FormErrors, _number
+
+__all__ = [
+    "CONDUCTIVITY_MODES",
+    "CONDUCTIVITY_NOTES",
+    "CMethodOptionsState",
+    "build_options",
+]
+
+#: Selectable boundary conditions, the solver's default first.
+CONDUCTIVITY_MODES = ("perfect", "tabulated")
+
+#: What each mode means, shown beneath the selector, for the reason
+#: ``integral_options.CONDUCTIVITY_NOTES`` gives: a claim about the result
+#: must not be hardcoded beside a control that can falsify it.
+CONDUCTIVITY_NOTES = {
+    "perfect": (
+        "Perfect conductor in any mount: efficiencies are relative to a "
+        "perfect reflector and sum to 1. A coating named in the geometry "
+        "panel is not consulted (the provenance panel says so)."
+    ),
+    "tabulated": (
+        "One interface into the coating named in the geometry panel, read "
+        "as a complex index at every wavelength. Efficiencies are absolute "
+        "and absorption is recorded; into a lossless material the "
+        "transmitted orders are recorded too, and R + T + A = 1 is a check."
+    ),
+}
+
+
+@dataclass(frozen=True, slots=True)
+class CMethodOptionsState:
+    """The C-method's own form fields, exactly as typed."""
+
+    truncation: str = "32"
+    conductivity: str = CONDUCTIVITY_MODES[0]
+
+    def with_field(self, name: str, value: Any) -> "CMethodOptionsState":
+        """Return a copy with one field changed."""
+        return replace(self, **{name: value})
+
+
+def build_options(
+    problem: Problem,
+    illumination: Illumination,
+    wavelengths: NDArray[np.float64],
+    form: CMethodOptionsState,
+) -> dict[str, Any]:
+    """Parse the C-method options and check the truncation holds every order.
+
+    Raises
+    ------
+    FormErrors
+        Same contract as :func:`gratinglab.gui.state.build`.
+    """
+    errors: list[FieldError] = []
+    truncation = _number(
+        form.truncation, "truncation", errors, minimum=1, integer=True
+    )
+    if truncation is not None and truncation > _MAX_TRUNCATION:
+        errors.append(
+            FieldError(
+                "truncation",
+                f"at most {_MAX_TRUNCATION}: the eigenproblem is dense and its "
+                "cost grows as N^3, so a sweep that has not settled by then is "
+                "the answer",
+            )
+        )
+    if form.conductivity not in CONDUCTIVITY_MODES:
+        errors.append(
+            FieldError(
+                "conductivity",
+                f"must be one of {', '.join(CONDUCTIVITY_MODES)}",
+            )
+        )
+    if errors:
+        raise FormErrors(tuple(errors))
+    assert truncation is not None
+
+    indices = None
+    if form.conductivity == "tabulated":
+        _name, indices, error = _tabulated_index(problem, wavelengths)
+        if error is not None:
+            raise FormErrors((error,))
+
+    floor = truncation_floor(problem, illumination, wavelengths, indices)
+    if truncation < floor.needed:
+        raise FormErrors((FieldError("truncation", floor.message),))
+
+    return {"truncation": int(truncation), "conductivity": form.conductivity}

{gratinglab-0.1.13 → gratinglab-0.2.1}/src/gratinglab/gui/docs.py

@@ -44,8 +44,10 @@ __all__ = [
 #: name for anything not listed here, so a new solver still gets a menu entry
 #: before anyone remembers to add a nicer title.
 _TITLES = {
+    "cmethod": "C-method (Chandezon)",
     "scalar": "Scalar (Kirchhoff)",
     "integral": "Integral (boundary integral equation)",
+    "rcwa": "RCWA (Fourier modal method)",
 }
 
 #: Non-solver reference pages: (key, title, filename relative to docs/).
@@ -105,6 +107,17 @@ def display_title(name: str) -> str:
     return _TITLES.get(name, name)
 
 
+def short_title(name: str) -> str:
+    """A solver's tab label: its display title without the bracketed gloss.
+
+    ``"Integral (boundary integral equation)"`` becomes ``"Integral"``. The
+    full title was the tab label until 2026-10-27, and with four tabs plus the
+    geometry dock it already overflowed the bar, so every new solver made it
+    worse. The full title stays in the Help menu and the tab's tooltip.
+    """
+    return display_title(name).split(" (", 1)[0]
+
+
 def find_theory_root(start: Path | None = None) -> Path | None:
     """Search upward from ``start`` for a ``docs/theory`` directory.
 

{gratinglab-0.1.13 → gratinglab-0.2.1}/src/gratinglab/gui/efficiency_plot.py

@@ -50,6 +50,14 @@ def draw_efficiency(
         scan.wavelengths, scan.total,
         color=theme.ink, ls="--", lw=1.0, alpha=0.7, label="Σ",
     )
+    transmitted = (
+        scan.transmission.total if scan.transmission is not None else 0.0
+    )
+    if scan.transmission is not None:
+        axes.plot(
+            scan.wavelengths, scan.transmission.total,
+            color=theme.ink, lw=1.0, ls=":", alpha=0.9, label="T",
+        )
     if scan.absorption is not None:
         # Under a finite-conductivity solve Σ alone is the reflected fraction
         # and sits below the unity line by exactly the absorbed one. Drawing
@@ -61,8 +69,9 @@ def draw_efficiency(
             color=theme.warn, lw=1.0, ls="-.", alpha=0.9, label="A",
         )
         axes.plot(
-            scan.wavelengths, scan.total + scan.absorption,
-            color=theme.ink, lw=1.0, ls="-", alpha=0.5, label="Σ + A",
+            scan.wavelengths, scan.total + transmitted + scan.absorption,
+            color=theme.ink, lw=1.0, ls="-", alpha=0.5,
+            label="Σ + T + A" if scan.transmission is not None else "Σ + A",
         )
     axes.axhline(1.0, color=theme.bad, lw=0.8, ls=":", alpha=0.8)
     axes.set_xlabel("wavelength (nm)")

{gratinglab-0.1.13 → gratinglab-0.2.1}/src/gratinglab/gui/provenance.py

@@ -147,6 +147,16 @@ def provenance_lines(
         lines.append(Line("normalization: ", "dim"))
         lines.append(Line(f"{normalization} ({detail})\n", "dim"))
 
+    if scan.transmission is not None:
+        lines.append(Line("transmission: ", "dim"))
+        lines.append(
+            Line(
+                f"T ∈ [{scan.transmission.total.min():.4f}, "
+                f"{scan.transmission.total.max():.4f}]\n",
+                "dim",
+            )
+        )
+
     if scan.absorption is not None:
         # A physical result, not a problem: `dim`, never an alarm tag. It also
         # explains the deficit in Σ below, which would otherwise read as a
@@ -163,7 +173,9 @@ def provenance_lines(
     # `check_energy_balance` folds absorption into the total when a scan
     # carries one, so the conserved quantity is R + A there. Naming it Σ
     # anyway would collide with the Σ curve on the plot, which is R alone.
-    conserved = "Σ + A" if scan.absorption is not None else "Σ"
+    conserved = "Σ" + (" + T" if scan.transmission is not None else "") + (
+        " + A" if scan.absorption is not None else ""
+    )
     lines.append(Line("energy balance: ", "dim"))
     lines.append(
         Line(