gratinglab 0.1.0__py3-none-any.whl

gratinglab/__init__.py

@@ -0,0 +1,35 @@
+"""gratinglab -- an open comparison platform for grating efficiency analysis.
+
+The organising idea is that the physical problem and the numerical method are
+separate objects, and the problem spec is serializable. One ``Problem`` goes to
+every solver, so disagreement between methods becomes visible instead of hidden
+behind incompatible conventions.
+
+``docs/conventions.md`` is normative. In short: time dependence ``exp(-iwt)``,
+lossy ``n = n' + ik``, grating equation
+``sin(alpha) + sin(beta_m) = m*lambda/(p*sin(gamma))``, efficiencies absolute,
+lengths in nm, angles in degrees at the API boundary.
+
+>>> from gratinglab import Illumination
+>>> Illumination.offplane(graze=1.5, azimuth=0.97).gamma_deg
+1.5
+"""
+
+from __future__ import annotations
+
+from .illumination import Illumination, Polarization
+from .resolution import ResolvingPower, resolving_power
+from .result import EfficiencyScan, OrderEfficiency, Provenance
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Illumination",
+    "Polarization",
+    "EfficiencyScan",
+    "OrderEfficiency",
+    "Provenance",
+    "ResolvingPower",
+    "resolving_power",
+    "__version__",
+]

gratinglab/checks.py

@@ -0,0 +1,263 @@
+r"""Physics self-checks: validate the *model*, not just the arithmetic.
+
+The closed-form tests in ``tests/test_scalar.py`` confirm that a Fourier
+integral is evaluated correctly. They cannot confirm that the integrand is the
+right one, because the expected values are derived from the same formula the
+solver implements. Two checks here close that gap, and neither needs reference
+data or a closed form:
+
+**Reciprocity** (:func:`check_reciprocity`) follows from Lorentz reciprocity and
+constrains the *structure* of the phase function. It is sharp: on the scalar
+solver it holds to ~1e-17, and breaking the :math:`\alpha \leftrightarrow \beta`
+symmetry of :math:`\Phi` pushes the violation to ~4e-1 -- sixteen orders of
+magnitude of discrimination.
+
+**Energy balance** (:func:`check_energy_balance`) catches the other class of
+error. Summed efficiency exceeding unity is unphysical for any passive
+structure, whatever method produced it. This is the check that found the
+unphysical finite-conductivity run in the reference corpus.
+
+Both take a solver rather than a scan where possible, so every backend added
+later inherits them without new code.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from .geometry import beta as beta_from_sin
+from .geometry import is_propagating, sin_beta
+from .illumination import Illumination
+from .problem import Problem
+from .result import EfficiencyScan
+
+__all__ = [
+    "ReciprocityReport",
+    "EnergyReport",
+    "check_reciprocity",
+    "check_energy_balance",
+]
+
+#: Illumination is undefined at exactly grazing, so reciprocal geometries
+#: within this margin of +/-90 degrees are skipped rather than clamped.
+_GRAZING_MARGIN_DEG = 0.5
+
+
+@dataclass(frozen=True, slots=True)
+class ReciprocityReport:
+    """Outcome of a reciprocity check."""
+
+    max_violation: float
+    worst_order: int | None
+    worst_wavelength: float | None
+    pairs_tested: int
+    tolerance: float
+
+    @property
+    def passed(self) -> bool:
+        return self.pairs_tested > 0 and self.max_violation <= self.tolerance
+
+    def __str__(self) -> str:  # pragma: no cover - cosmetic
+        if not self.pairs_tested:
+            return "reciprocity: no testable pairs"
+        verdict = "pass" if self.passed else "FAIL"
+        return (
+            f"reciprocity: {verdict} -- worst {self.max_violation:.3e} "
+            f"at order {self.worst_order}, lambda={self.worst_wavelength:g} nm "
+            f"({self.pairs_tested} pairs, tol {self.tolerance:.1e})"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class EnergyReport:
+    """Outcome of an energy-balance check."""
+
+    total: NDArray[np.float64]
+    wavelengths: NDArray[np.float64]
+    tolerance: float
+    lossless: bool
+
+    @property
+    def max_excess(self) -> float:
+        """How far above unity the summed efficiency ever goes.
+
+        Positive means unphysical: a passive grating cannot return more power
+        than it receives, by any method.
+        """
+        return float(self.total.max() - 1.0)
+
+    @property
+    def max_deficit(self) -> float:
+        """How far below unity. Expected for absorbing or non-rigorous methods."""
+        return float(1.0 - self.total.min())
+
+    @property
+    def unphysical(self) -> NDArray[np.bool_]:
+        """Wavelengths where efficiency exceeds unity beyond tolerance."""
+        return self.total > 1.0 + self.tolerance
+
+    @property
+    def passed(self) -> bool:
+        if self.lossless:
+            return bool(np.abs(self.total - 1.0).max() <= self.tolerance)
+        return not bool(self.unphysical.any())
+
+    def __str__(self) -> str:  # pragma: no cover - cosmetic
+        verdict = "pass" if self.passed else "FAIL"
+        return (
+            f"energy balance: {verdict} -- total in "
+            f"[{self.total.min():.4f}, {self.total.max():.4f}], "
+            f"{int(self.unphysical.sum())} of {len(self.total)} points above unity"
+        )
+
+
+def check_reciprocity(
+    solver,
+    problem: Problem,
+    illumination: Illumination,
+    wavelengths: ArrayLike,
+    *,
+    tolerance: float = 1e-9,
+    max_orders: int | None = 12,
+    **options,
+) -> ReciprocityReport:
+    r"""Verify Lorentz reciprocity for a solver.
+
+    Reversing the diffracted ray of order :math:`m` gives an incidence azimuth
+    :math:`\alpha' = \beta_m`, and order :math:`m` then exits along
+    :math:`\alpha`. Reciprocity requires
+
+    .. math::
+        \mathscr{E}_m(\alpha) = \mathscr{E}_m(\beta_m)
+
+    This constrains the phase function to be symmetric under
+    :math:`\alpha \leftrightarrow \beta_m`, which is exactly the structure
+    :math:`\cos\alpha + \cos\beta_m` in the scalar model. A solver that used
+    :math:`2\cos\alpha`, or subtracted rather than added, fails immediately.
+
+    Parameters
+    ----------
+    max_orders
+        Cap on how many orders to test per wavelength, since each one costs an
+        extra solve. ``None`` tests all of them.
+
+    Notes
+    -----
+    Orders diffracting within half a degree of grazing are skipped: the
+    reciprocal illumination is undefined there, and clamping it would compare
+    two different geometries.
+    """
+    wavelengths = np.atleast_1d(np.asarray(wavelengths, dtype=np.float64))
+
+    # Collected rather than tracked with a running maximum. A running max
+    # seeded at 0.0 never updates when a solver is *exactly* reciprocal, which
+    # left the report with worst_order=None on platforms whose BLAS returns a
+    # bitwise-zero difference -- the better the solver, the worse the report.
+    violations: list[tuple[float, int, float]] = []
+
+    for wavelength in wavelengths:
+        forward = solver.solve(problem, illumination, [wavelength], **options).at(
+            wavelength
+        )
+        orders = forward.propagating_orders
+        if max_orders is not None and len(orders) > max_orders:
+            # Keep the strongest orders: a violation there matters most, and
+            # near-zero orders make the comparison meaningless.
+            strength = np.array([forward[int(m)] for m in orders])
+            orders = orders[np.argsort(strength)[::-1][:max_orders]]
+
+        for order in orders:
+            sine = sin_beta(
+                order,
+                wavelength,
+                problem.period,
+                illumination.sin_alpha,
+                illumination.sin_gamma,
+            )
+            if not is_propagating(sine):
+                continue
+            beta_deg = float(np.degrees(beta_from_sin(sine)))
+            if abs(beta_deg) > 90.0 - _GRAZING_MARGIN_DEG:
+                continue
+
+            reversed_illumination = Illumination(
+                alpha_deg=beta_deg,
+                gamma_deg=illumination.gamma_deg,
+                polarization=illumination.polarization,
+            )
+            backward = solver.solve(
+                problem, reversed_illumination, [wavelength], **options
+            ).at(wavelength)
+
+            violations.append(
+                (
+                    abs(forward[int(order)] - backward[int(order)]),
+                    int(order),
+                    float(wavelength),
+                )
+            )
+
+    if not violations:
+        return ReciprocityReport(
+            max_violation=0.0,
+            worst_order=None,
+            worst_wavelength=None,
+            pairs_tested=0,
+            tolerance=tolerance,
+        )
+
+    worst, worst_order, worst_wavelength = max(violations, key=lambda item: item[0])
+    return ReciprocityReport(
+        max_violation=worst,
+        worst_order=worst_order,
+        worst_wavelength=worst_wavelength,
+        pairs_tested=len(violations),
+        tolerance=tolerance,
+    )
+
+
+def check_energy_balance(
+    scan: EfficiencyScan,
+    *,
+    tolerance: float = 1e-6,
+    lossless: bool = False,
+) -> EnergyReport:
+    """Verify that summed efficiency is physically admissible.
+
+    Parameters
+    ----------
+    lossless
+        Require ``sum == 1`` exactly (within tolerance). Use for a perfectly
+        conducting or otherwise lossless structure, where the sum rule is a
+        theorem. Default ``False`` only requires ``sum <= 1``, which holds for
+        **any** passive grating by **any** method -- a weaker claim, but one
+        that never has a legitimate exception.
+
+    Notes
+    -----
+    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 gets checked: ``R + A = 1``
+    is a theorem for a one-interface absorbing grating, so ``lossless=True``
+    is again the right mode for the finite-conductivity integral method --
+    and it is a genuine two-sided check, because the absorption comes from a
+    boundary integral of the densities, not from ``1 - R``.
+
+    The default direction matters. A deficit is ordinary: power goes into
+    absorption, into evanescent orders, or is missed by an approximate method.
+    An *excess* is not, and this is the check that identified the unphysical
+    finite-conductivity run in the reference corpus, where summed efficiency
+    reached 3.6.
+    """
+    total = np.asarray(scan.total, dtype=np.float64)
+    if scan.absorption is not None:
+        total = total + scan.absorption
+    return EnergyReport(
+        total=total,
+        wavelengths=scan.wavelengths,
+        tolerance=tolerance,
+        lossless=lossless,
+    )

gratinglab/compare.py

@@ -0,0 +1,233 @@
+"""Run one problem through several methods and line the answers up.
+
+This is the point of the project. A comparison is only honest if every method
+saw the same physics, so :func:`sweep` takes one :class:`~gratinglab.problem.Problem`
+and one :class:`~gratinglab.illumination.Illumination` and hands them to each
+backend unchanged.
+
+Precomputed results are first-class participants. An imported PCGrate table is
+passed in exactly like a live solver, so scalar-versus-integral-method plots are
+available without a PCGrate licence.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Iterable, Sequence
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from .illumination import Illumination
+from .problem import Problem
+from .result import EfficiencyScan
+from .solvers.base import Progress, get_solver
+
+__all__ = ["sweep", "align", "Comparison", "records"]
+
+#: A method is either a registered solver name or an already-computed scan.
+Method = str | EfficiencyScan
+
+
+def sweep(
+    problem: Problem,
+    illumination: Illumination,
+    wavelengths: ArrayLike,
+    methods: Sequence[Method],
+    options: dict[str, dict[str, Any]] | None = None,
+    *,
+    progress: "Progress | None" = None,
+) -> list[EfficiencyScan]:
+    """Solve ``problem`` with each method on a common wavelength grid.
+
+    Parameters
+    ----------
+    methods
+        Registered solver names (``"scalar"``), or :class:`EfficiencyScan`
+        objects for precomputed data such as an imported PCGrate table. A
+        precomputed scan is **resampled onto** ``wavelengths`` -- see
+        :func:`align` for how, and for the caveat.
+    options
+        Per-method keyword arguments, keyed by method name, e.g.
+        ``{"scalar": {"quadrature_points": 8192}}``.
+    progress
+        Called ``(done, total)`` over the **whole sweep**, not per method, so
+        a bar driven by it never restarts at a method boundary. Units are
+        wavelengths, and ``total`` is ``len(methods) * len(wavelengths)``.
+
+        Raising from it aborts the sweep -- see
+        :class:`~gratinglab.solvers.base.SolveCancelled`. A keyword of its own
+        rather than an entry in ``options``, so it can never collide with a
+        solver's own parameter name.
+    """
+    wavelengths = np.atleast_1d(np.asarray(wavelengths, dtype=np.float64))
+    options = options or {}
+    per_method = len(wavelengths)
+    total = len(methods) * per_method
+
+    scans: list[EfficiencyScan] = []
+    for index, method in enumerate(methods):
+        finished = index * per_method
+
+        if isinstance(method, EfficiencyScan):
+            # Resampling is instant, so this block completes at once. Stepping
+            # the counter by the whole block is honest; pretending a
+            # precomputed table has wavelengths still to compute is not.
+            scans.append(_resample(method, wavelengths))
+            if progress is not None:
+                progress(finished + per_method, total)
+            continue
+
+        solver = get_solver(method)
+        forwarded = _progress_option(solver, progress, finished, total)
+        scans.append(
+            solver.solve(
+                problem, illumination, wavelengths,
+                **forwarded, **options.get(method, {}),
+            )
+        )
+        if progress is not None and not forwarded:
+            # Only for a solver that did *not* report: this is what stops the
+            # bar stalling at a method boundary. One that did report already
+            # ended its block exactly here, and repeating the call would emit
+            # a duplicate for no reason.
+            progress(finished + per_method, total)
+    return scans
+
+
+def _progress_option(
+    solver, progress: "Progress | None", finished: int, total: int
+) -> dict[str, Any]:
+    """``{"progress": ...}`` for a solver that declared it, else ``{}``.
+
+    A backend that has not been updated -- including a third-party one
+    arriving through the ``gratinglab.solvers`` entry point -- has an explicit
+    signature that would raise ``TypeError`` on an unexpected keyword, which
+    is why :attr:`~gratinglab.solvers.base.Capabilities.reports_progress` is
+    declared rather than assumed.
+    """
+    if progress is None or not solver.capabilities.reports_progress:
+        return {}
+    return {"progress": lambda done, _per_method: progress(finished + done, total)}
+
+
+def _resample(scan: EfficiencyScan, wavelengths: NDArray[np.float64]) -> EfficiencyScan:
+    """Put a precomputed scan on ``wavelengths`` by nearest-neighbour lookup.
+
+    Nearest-neighbour rather than interpolation, deliberately: efficiency curves
+    have sharp features at order passing-off, and interpolating across one
+    invents a value that no method produced. Points outside the source range
+    are marked non-propagating rather than extrapolated.
+    """
+    source = scan.wavelengths
+    index = np.abs(wavelengths[:, None] - source[None, :]).argmin(axis=1)
+    inside = (wavelengths >= source.min()) & (wavelengths <= source.max())
+
+    efficiency = scan.efficiency[index]
+    propagating = scan.propagating[index]
+    efficiency = np.where(inside[:, None], efficiency, 0.0)
+    propagating = propagating & inside[:, None]
+
+    return EfficiencyScan(
+        wavelengths=wavelengths,
+        orders=scan.orders,
+        efficiency=efficiency,
+        propagating=propagating,
+        provenance=scan.provenance,
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class Comparison:
+    """Several methods on one wavelength grid and one order set."""
+
+    wavelengths: NDArray[np.float64]
+    orders: NDArray[np.int64]
+    methods: tuple[str, ...]
+    #: ``(n_methods, n_wavelengths, n_orders)``
+    efficiency: NDArray[np.float64]
+    scans: tuple[EfficiencyScan, ...]
+
+    def order(self, m: int) -> dict[str, NDArray[np.float64]]:
+        """Efficiency in order ``m`` versus wavelength, per method."""
+        column = int(np.flatnonzero(self.orders == m)[0])
+        return {
+            name: self.efficiency[i, :, column]
+            for i, name in enumerate(self.methods)
+        }
+
+    def difference(self, a: str, b: str) -> NDArray[np.float64]:
+        """Signed ``a - b`` over the full grid."""
+        return self.efficiency[self.methods.index(a)] - self.efficiency[
+            self.methods.index(b)
+        ]
+
+    def max_abs_difference(self, a: str, b: str) -> float:
+        return float(np.abs(self.difference(a, b)).max())
+
+    def summary(self, a: str, b: str) -> dict[str, float]:
+        """Where and how much two methods disagree.
+
+        The headline number of the whole project: not "do they agree" but
+        "by how much, and where".
+        """
+        delta = self.difference(a, b)
+        flat = int(np.abs(delta).argmax())
+        row, column = np.unravel_index(flat, delta.shape)
+        return {
+            "max_abs_difference": float(np.abs(delta).max()),
+            "rms_difference": float(np.sqrt(np.mean(delta**2))),
+            "at_wavelength": float(self.wavelengths[row]),
+            "at_order": int(self.orders[column]),
+        }
+
+
+def align(scans: Iterable[EfficiencyScan]) -> Comparison:
+    """Put several scans on a shared order set.
+
+    All scans must already share a wavelength grid -- :func:`sweep` arranges
+    that. Orders are unioned, so a method that resolves fewer orders reports
+    zero for the rest rather than being silently truncated to the smallest
+    common set.
+    """
+    scans = tuple(scans)
+    if not scans:
+        raise ValueError("nothing to compare")
+
+    reference = scans[0].wavelengths
+    for scan in scans[1:]:
+        if not np.allclose(scan.wavelengths, reference):
+            raise ValueError(
+                "scans are on different wavelength grids; use sweep() so every "
+                "method is evaluated on the same one"
+            )
+
+    orders = np.unique(np.concatenate([scan.orders for scan in scans]))
+    stacked = np.zeros((len(scans), len(reference), len(orders)))
+    for i, scan in enumerate(scans):
+        column = np.searchsorted(orders, scan.orders)
+        stacked[i][:, column] = scan.efficiency
+
+    names = _unique_names(scans)
+    return Comparison(
+        wavelengths=reference,
+        orders=orders,
+        methods=names,
+        efficiency=stacked,
+        scans=scans,
+    )
+
+
+def _unique_names(scans: Sequence[EfficiencyScan]) -> tuple[str, ...]:
+    """Method labels, disambiguated if two scans share a method name."""
+    names, seen = [], {}
+    for scan in scans:
+        base = scan.provenance.method
+        seen[base] = seen.get(base, 0) + 1
+        names.append(base if seen[base] == 1 else f"{base}#{seen[base]}")
+    return tuple(names)
+
+
+def records(scans: Iterable[EfficiencyScan]) -> list[dict[str, Any]]:
+    """Tidy long-form rows across several scans, ready for a DataFrame."""
+    return [row for scan in scans for row in scan.to_records()]