gratinglab 0.1.0__py3-none-any.whl

gratinglab/gui/docs.py

@@ -0,0 +1,189 @@
+"""Locating each solver's theory page.
+
+Pure and toolkit-free, like :mod:`gratinglab.gui.state`, because this is the one
+piece of "which page goes with which solver" logic worth testing on its own.
+
+``docs/theory/`` lives at the **repo root**, outside ``src/gratinglab/``, so it
+ships in a development checkout but not in a built wheel. That is a real
+limitation of a pre-alpha, locally-run tool -- not something to paper over by
+duplicating markdown into package data before there is a second solver to
+justify it. :func:`theory_pages` degrades to an explanatory, unavailable entry
+rather than raising when the directory cannot be found.
+
+Every *registered* solver gets an entry, available or not, so the Help menu
+always reflects what solvers exist. A solver with no page yet still shows up
+and says so, rather than silently vanishing from the menu until someone
+remembers to write it.
+
+Alongside the per-solver pages, :func:`general_pages` returns entries that are
+not tied to any solver -- currently just the normative ``conventions.md``,
+which every solver's page cross-references for shared geometry (the
+generalized grating equation, the angle conventions) rather than duplicating
+it. Kept as a separate function rather than folded into :func:`theory_pages`
+so that function's existing contract -- one entry per registered solver, no
+more, no less -- stays exactly true; a test asserts it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..solvers.base import available_solvers, get_solver
+
+__all__ = [
+    "TheoryPage",
+    "find_theory_root",
+    "theory_pages",
+    "general_pages",
+    "display_title",
+]
+
+#: Human-readable titles for known solvers. Falls back to the bare registry
+#: name for anything not listed here, so a new solver still gets a menu entry
+#: before anyone remembers to add a nicer title.
+_TITLES = {
+    "scalar": "Scalar (Kirchhoff)",
+    "integral": "Integral (boundary integral equation)",
+}
+
+#: Non-solver reference pages: (key, title, filename relative to docs/).
+_GENERAL_PAGES = (
+    ("conventions", "Grating Geometry & Conventions", "conventions.md"),
+    # Not a solver page -- nothing here approximates a wave equation -- but an
+    # efficiency computed from a measured profile inherits every assumption
+    # made while producing that profile, and those are invisible in the curve.
+    # It belongs beside the conventions for the same reason they do.
+    ("metrology", "Groove Metrology", "theory/metrology.md"),
+)
+
+#: How many parent directories to search before giving up. gui/docs.py sits at
+#: src/gratinglab/gui/, four levels below a repo root that holds docs/theory/,
+#: so this comfortably covers the dev-checkout case with room to spare.
+_MAX_SEARCH_DEPTH = 6
+
+
+@dataclass(frozen=True, slots=True)
+class TheoryPage:
+    """One Help-menu entry.
+
+    Attributes
+    ----------
+    name
+        Solver registry key, e.g. ``"scalar"``.
+    title
+        Display title for the menu.
+    available
+        Whether an actual page was found.
+    path
+        The theory file, if found.
+    text
+        The page content if available, otherwise a short explanation of why
+        not -- always something the viewer can show, never ``None``.
+    rigorous
+        The solver's own ``Capabilities.rigorous``. Used to decide whether the
+        viewer prefixes an approximate-method banner.
+    """
+
+    name: str
+    title: str
+    available: bool
+    path: Path | None
+    text: str
+    rigorous: bool
+
+
+def display_title(name: str) -> str:
+    """A solver's human-readable name, e.g. ``"scalar"`` -> ``"Scalar
+    (Kirchhoff)"``.
+
+    Public so both the Help menu and a solver's own tab label read the same
+    name -- there is exactly one place that decides what a solver is called,
+    not two that could quietly drift apart.
+    """
+    return _TITLES.get(name, name)
+
+
+def find_theory_root(start: Path | None = None) -> Path | None:
+    """Search upward from ``start`` for a ``docs/theory`` directory.
+
+    Returns ``None`` rather than raising if none is found within
+    :data:`_MAX_SEARCH_DEPTH` levels -- e.g. running from an installed wheel,
+    where ``docs/`` was never packaged.
+    """
+    here = (start or Path(__file__)).resolve()
+    for candidate in [here, *here.parents][: _MAX_SEARCH_DEPTH + 1]:
+        theory = candidate / "docs" / "theory"
+        if theory.is_dir():
+            return theory
+    return None
+
+
+def _load_page(
+    name: str, title: str, path: Path | None, *, rigorous: bool, not_written: str
+) -> TheoryPage:
+    """Build one entry, handling the three cases every page can be in.
+
+    Shared by :func:`theory_pages` and :func:`general_pages` so the "docs/ not
+    bundled" and "file missing" fallback text stays consistent between them.
+    """
+    if path is None:
+        return TheoryPage(
+            name=name, title=title, available=False, path=None,
+            text=(
+                "Documentation is not bundled with this installation "
+                "(docs/ ships in a development checkout, not in a built "
+                f"package). See the project repository for {not_written}."
+            ),
+            rigorous=rigorous,
+        )
+    if path.is_file():
+        return TheoryPage(
+            name=name, title=title, available=True, path=path,
+            text=path.read_text(encoding="utf-8"), rigorous=rigorous,
+        )
+    return TheoryPage(
+        name=name, title=title, available=False, path=path,
+        text=f"No page has been written yet for '{name}' ({not_written}).",
+        rigorous=rigorous,
+    )
+
+
+def theory_pages() -> tuple[TheoryPage, ...]:
+    """One entry per registered solver, in registration order.
+
+    Exactly one entry per name in ``available_solvers()`` -- a solver with no
+    page yet still appears, marked unavailable, rather than being silently
+    omitted until someone remembers to write it.
+    """
+    root = find_theory_root()
+    return tuple(
+        _load_page(
+            name,
+            display_title(name),
+            None if root is None else root / f"{name}.md",
+            rigorous=get_solver(name).capabilities.rigorous,
+            not_written=f"docs/theory/{name}.md",
+        )
+        for name in available_solvers()
+    )
+
+
+def general_pages() -> tuple[TheoryPage, ...]:
+    """Reference pages not tied to any one solver.
+
+    ``rigorous=True`` throughout: these are geometry/convention references,
+    not a solver's approximation, so the viewer's approximate-method banner
+    never applies to them.
+    """
+    root = find_theory_root()
+    return tuple(
+        _load_page(
+            name,
+            title,
+            None if root is None else root.parent / filename,
+            rigorous=True,
+            not_written=f"docs/{filename}",
+        )
+        for name, title, filename in _GENERAL_PAGES
+    )

gratinglab/gui/icon.py

@@ -0,0 +1,101 @@
+"""The app icon, drawn rather than stored.
+
+Rendered from matplotlib because this machine has no SVG rasteriser
+(``rsvg-convert`` / ``inkscape``), and generating the artwork keeps it
+reproducible and editable in the same language as the rest of the project.
+
+The motif is a blazed sawtooth with diffracted orders fanning out of it -- the
+thing this software computes. Deliberately few, thick elements so it stays
+legible at 16 px, which is where most icons fail.
+
+``tools/make_icon.py`` turns this into a macOS ``.icns``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+__all__ = ["render", "BACKGROUND", "FACET", "ORDER_COLORS"]
+
+#: Deep blue-black, so the spectrum reads against it at any size.
+BACKGROUND = "#101a2e"
+FACET = "#e8ecf5"
+
+#: Long to short wavelength, matching the fan direction. Four rather than six:
+#: at 16 px, six strokes blur into an unreadable smear, four stay distinct.
+ORDER_COLORS = ("#ff4d4d", "#ffc233", "#4ade80", "#4dc4ff")
+
+
+def render(path: str | Path, size: int = 1024) -> Path:
+    """Draw the icon to a square PNG.
+
+    Parameters
+    ----------
+    size
+        Pixels per side. 1024 is the largest macOS asks for; every smaller
+        variant is downsampled from it.
+    """
+    import matplotlib
+
+    matplotlib.use("Agg")
+    import numpy as np
+    from matplotlib.figure import Figure
+    from matplotlib.patches import FancyBboxPatch, Polygon
+
+    figure = Figure(figsize=(size / 100, size / 100), dpi=100)
+    axes = figure.add_axes((0, 0, 1, 1))
+    axes.set_xlim(0, 1)
+    axes.set_ylim(0, 1)
+    axes.axis("off")
+
+    # Rounded-square plate, inset like a macOS app icon.
+    axes.add_patch(
+        FancyBboxPatch(
+            (0.06, 0.06), 0.88, 0.88,
+            boxstyle="round,pad=0,rounding_size=0.20",
+            facecolor=BACKGROUND, edgecolor="none",
+        )
+    )
+
+    # Diffracted orders fanning from the blaze point. Drawn before the grating
+    # so the facets sit cleanly on top.
+    #
+    # Everything here is sized for the 16 px case: thick strokes, wide angular
+    # separation, few elements. A finer design looks better at 512 and turns to
+    # mush in the Finder list view, which is where an icon earns its keep.
+    origin = (0.26, 0.42)
+    for index, color in enumerate(ORDER_COLORS):
+        angle = np.radians(26 + index * 19.0)
+        axes.plot(
+            [origin[0], origin[0] + 0.62 * np.cos(angle)],
+            [origin[1], origin[1] + 0.62 * np.sin(angle)],
+            color=color, lw=size * 0.030, solid_capstyle="round",
+        )
+
+    # Incident ray, arriving at a shallow graze from the left.
+    axes.plot(
+        [0.10, origin[0]], [0.60, origin[1]],
+        color="#8fa3c8", lw=size * 0.022, solid_capstyle="round",
+    )
+
+    # Two big sawtooth teeth. Three read better at 512 px but disappear at 16;
+    # two survive the downsample and still say "blazed grating".
+    baseline, height = 0.16, 0.26
+    left, width = 0.14, 0.36
+    for tooth in range(2):
+        start = left + tooth * width
+        axes.add_patch(
+            Polygon(
+                [
+                    (start, baseline),
+                    (start + width * 0.82, baseline + height),
+                    (start + width * 0.82, baseline),
+                ],
+                closed=True, facecolor=FACET, edgecolor="none",
+            )
+        )
+
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    figure.savefig(path, dpi=100, facecolor="none", transparent=True)
+    return path

gratinglab/gui/integral_options.py

@@ -0,0 +1,219 @@
+"""The integral solver's own form: boundary condition, points, and their guards.
+
+The second solver's options module, made the way ``scalar_options.py`` said a
+second one should be: its own file, its own frozen state, its own
+``build_options`` raising :class:`~gratinglab.gui.state.FormErrors`, no
+toolkit import anywhere.
+
+Two knobs now, because the solver has two. ``conductivity`` chooses the
+boundary condition -- ``"perfect"`` (relative efficiency, no material) or
+``"tabulated"`` (the finite-conductivity system of Goray & Schmidt 2010,
+absolute efficiency, absorption recorded). The mesh guard follows that
+choice: the boundary field oscillates at the *reduced* wavelength
+``lambda / sin(gamma)`` on the vacuum side, and under ``"tabulated"`` also at
+``lambda / |sqrt(n^2 - cos^2 gamma)|` inside the material, which for anything
+but a soft-X-ray index is the shorter of the two. Both floors mirror the
+solver's own refusals (``solvers/integral``); validating here too means the
+error lands on the field that caused it, alongside every other form error,
+instead of surfacing as a ValueError from the worker thread.
+"""
+
+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.integral import _POINTS_PER_WAVELENGTH
+from .state import FieldError, FormErrors, _number
+
+__all__ = [
+    "CONDUCTIVITY_MODES",
+    "CONDUCTIVITY_NOTES",
+    "IntegralOptionsState",
+    "build_options",
+]
+
+#: Boundary sampling used only to estimate the arc length for the guards.
+#: Coarse is fine -- arc length converges long before the solve does.
+_ARC_SAMPLES = 512
+
+#: Selectable boundary conditions, in the order a form should offer them. The
+#: first is the solver's own default, so a freshly opened window and a bare
+#: ``integral.solve`` call agree.
+CONDUCTIVITY_MODES = ("perfect", "tabulated")
+
+#: What each mode means, in the words the tab shows beneath the selector. Kept
+#: here rather than in the widget for the reason `provenance.py` gives: what a
+#: panel *claims about a result* is a correctness question, and the old static
+#: label went stale the moment the solver grew a second boundary condition.
+CONDUCTIVITY_NOTES = {
+    "perfect": (
+        "Perfectly conducting boundary: 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": (
+        "Finite conductivity (Goray & Schmidt 2010): the coating named in "
+        "the geometry panel is read as a complex index at every wavelength. "
+        "Efficiencies are absolute, absorption is recorded, and R + A = 1. "
+        "Costs roughly twice as much per wavelength, on a finer mesh."
+    ),
+}
+
+
+@dataclass(frozen=True, slots=True)
+class IntegralOptionsState:
+    """Integral's own form fields, exactly as typed."""
+
+    boundary_points: str = "400"
+    conductivity: str = CONDUCTIVITY_MODES[0]
+
+    def with_field(self, name: str, value: Any) -> "IntegralOptionsState":
+        """Return a copy with one field changed."""
+        return replace(self, **{name: value})
+
+
+def build_options(
+    problem: Problem,
+    illumination: Illumination,
+    wavelengths: NDArray[np.float64],
+    form: IntegralOptionsState,
+) -> dict[str, Any]:
+    """Parse the integral options and check the mesh can resolve the field.
+
+    Raises
+    ------
+    FormErrors
+        Same contract as :func:`gratinglab.gui.state.build`.
+    """
+    errors: list[FieldError] = []
+    points = _number(
+        form.boundary_points, "boundary_points", errors, minimum=32, integer=True
+    )
+    # Validated here rather than left to the solver so a bad value surfaces on
+    # the field that produced it rather than as an UnsupportedConfiguration
+    # from a worker thread.
+    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 points is not None
+
+    arc_length = (
+        problem.profile.boundary(_ARC_SAMPLES).arc_length * problem.period
+    )
+    reduced = float(wavelengths.min()) / illumination.sin_gamma
+    needed = int(np.ceil(_POINTS_PER_WAVELENGTH * arc_length / reduced))
+    message = (
+        f"needs at least {needed} to give "
+        f"{_POINTS_PER_WAVELENGTH:g} nodes per transverse "
+        f"wavelength ({reduced:.4g} nm) along the "
+        f"{arc_length:.4g} nm boundary"
+    )
+
+    if form.conductivity == "tabulated":
+        # Sequential prerequisites, not parallel checks: there is no index to
+        # range-check without a material, and no metal-side floor without an
+        # index. So these short-circuit rather than accumulating.
+        name, indices, error = _tabulated_index(problem, wavelengths)
+        if error is not None:
+            raise FormErrors((error,))
+        assert name is not None and indices is not None
+        metal_needed, metal_message = _metal_floor(
+            name, indices, illumination, wavelengths, arc_length
+        )
+        # One error on one field: whichever side of the boundary binds harder.
+        # Reporting both would put two messages on `boundary_points` that a
+        # single number answers.
+        if metal_needed > needed:
+            needed, message = metal_needed, metal_message
+
+    if points < needed:
+        raise FormErrors((FieldError("boundary_points", message),))
+
+    return {"boundary_points": int(points), "conductivity": form.conductivity}
+
+
+def _tabulated_index(
+    problem: Problem, wavelengths: NDArray[np.float64]
+) -> "tuple[str | None, NDArray[np.complex128] | None, FieldError | None]":
+    """Resolve the material the tabulated boundary condition reads.
+
+    Mirrors ``solvers.integral._resolve_index``, but returns a
+    :class:`~gratinglab.gui.state.FieldError` instead of raising, so a missing
+    or unusable material lands on a form field rather than arriving as a
+    traceback from the worker thread.
+
+    ``lookup`` is called without an :class:`UnknownMaterial` guard on purpose:
+    :func:`gratinglab.gui.state.build` has already rejected any coating name
+    that is not in the library, so that branch is unreachable from the window
+    and a handler for it would be untested dead code.
+    """
+    from ..materials import lookup
+
+    name = problem.coating or problem.substrate
+    if name is None:
+        return None, None, FieldError(
+            "coating",
+            'conductivity="tabulated" reads a complex index at every '
+            "wavelength; name a coating in the geometry panel, or set "
+            'conductivity to "perfect" (which needs no material).',
+        )
+
+    table = lookup(name)
+    if not table.covers(wavelengths).all():
+        low, high = table.range_nm
+        return name, None, FieldError(
+            "wavelength_start",
+            f"{name} is tabulated over {low:.4g}-{high:.4g} nm; this scan "
+            f"runs {wavelengths.min():.4g}-{wavelengths.max():.4g} nm. "
+            "Extrapolating an optical constant is refused, so shorten the "
+            "scan or install a table that covers it.",
+        )
+
+    indices = np.asarray(table.n(wavelengths), dtype=np.complex128)
+    if (indices.imag < 0.0).any():
+        return name, None, FieldError(
+            "coating",
+            f"{name} tabulates a negative absorption (gain) inside this "
+            "scan; the transmission problem loses uniqueness there (Goray & "
+            "Schmidt 2010, section 2.B).",
+        )
+    return name, indices, None
+
+
+def _metal_floor(
+    name: str,
+    indices: NDArray[np.complex128],
+    illumination: Illumination,
+    wavelengths: NDArray[np.float64],
+    arc_length: float,
+) -> tuple[int, str]:
+    """The mesh floor the material side imposes, and what to say about it.
+
+    Same formula as the solver's own guard, so the two numbers agree: the
+    field inside a conductive material oscillates and decays on the scale
+    ``lambda / |sqrt(n^2 - cos^2 gamma)|``. For the shipped soft-X-ray tables
+    ``|n|`` is within a hair of 1 and this barely moves; for a visible-light
+    index of a few it is the binding constraint by a wide margin.
+    """
+    cos_gamma = float(np.sqrt(1.0 - illumination.sin_gamma**2))
+    factors = np.abs(np.sqrt(indices**2 - cos_gamma**2))
+    reduced = float((wavelengths / factors).min())
+    needed = int(np.ceil(_POINTS_PER_WAVELENGTH * arc_length / reduced))
+    return needed, (
+        f"needs at least {needed} with coating {name}: the field inside a "
+        f"conductive material oscillates and decays on the scale lambda/|n| "
+        f"({reduced:.4g} nm here), and the mesh must resolve it along the "
+        f'{arc_length:.4g} nm boundary. Raise it, or use conductivity="perfect".'
+    )