gratinglab 0.1.0__py3-none-any.whl

gratinglab/gui/mathtext.py

@@ -0,0 +1,209 @@
+r"""Rendering LaTeX math from a theory page, without a markdown dependency.
+
+A theory page's `$$\Phi_m(x) = ...$$` should not reach a reader as literal
+source, backslashes and all. This module is the pure half of the fix:
+splitting a markdown string into text and math spans, and rasterizing math
+spans to PNG bytes via :func:`matplotlib.mathtext.math_to_image`, which is
+already a dependency (it is what draws every axis label in the plots) and
+needs no live display to run -- the whole pipeline down to PNG bytes is
+headlessly testable. Only the final step of turning those bytes into an
+embeddable image lives in :mod:`gratinglab.gui.richtext` and
+:mod:`gratinglab.gui.qt.theory_viewer`, where it needs a real Qt document.
+
+Two things worth knowing before touching this file:
+
+**`\boxed{...}` is not supported by mathtext** (confirmed by testing --
+it raises `ValueError` wrapping a `ParseFatalException`). `scalar.md`'s two
+headline equations use it. :func:`strip_boxed` removes the wrapper by counting
+braces rather than by regex, because the boxed content itself contains nested
+braces (`\boxed{\;G_m = \int_0^1 e^{i\Phi_m(t)}\, ...\;}`) and a naive
+`\boxed\{(.*)\}` pattern would either stop at the first inner `}` or, greedy,
+swallow past the intended end. The visual rectangle is not reproduced --
+mathtext has no boxed macro, and rebuilding one would mean splitting a single
+display equation into multiple sub-images for a cosmetic rule. The equation
+still renders correctly and reads as its own centered line, which is the part
+that matters.
+
+**A render failure degrades, it does not crash the viewer.** `render_math_png`
+returns `None` rather than propagating the parser's exception, so one
+unsupported macro in a future edit shows as visible raw source for that one
+span -- diagnosable at a glance -- rather than taking down the whole page.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+__all__ = ["Segment", "split_segments", "strip_boxed", "render_math_png"]
+
+
+@dataclass(frozen=True, slots=True)
+class Segment:
+    """One piece of a theory page: either plain text or a math span.
+
+    Attributes
+    ----------
+    kind
+        ``"text"`` or ``"math"``.
+    content
+        For ``"text"``, the literal markdown text. For ``"math"``, the LaTeX
+        source with its `$` or `$$` delimiters already stripped.
+    display
+        Only meaningful for ``"math"``: ``True`` for `$$...$$` (its own
+        centered line), ``False`` for inline `$...$`.
+    """
+
+    kind: Literal["text", "math"]
+    content: str
+    display: bool = False
+
+
+def split_segments(markdown: str) -> tuple[Segment, ...]:
+    r"""Split markdown into alternating text and math segments.
+
+    Recognises `$$...$$` (display) and `$...$` (inline). A backslash-escaped
+    `\$` is never a delimiter and is emitted as a literal `$` in the
+    surrounding text segment. An odd, unterminated `$` (or `$$`) at the end of
+    the string is treated as literal text rather than raising -- a markdown
+    source with a typo should degrade to showing the stray dollar sign, not
+    crash the viewer that is trying to fix rendering problems.
+    """
+    segments: list[Segment] = []
+    buffer: list[str] = []
+    i, n = 0, len(markdown)
+
+    def flush_text() -> None:
+        if buffer:
+            segments.append(Segment(kind="text", content="".join(buffer)))
+            buffer.clear()
+
+    while i < n:
+        char = markdown[i]
+
+        if char == "\\" and i + 1 < n and markdown[i + 1] == "$":
+            buffer.append("$")
+            i += 2
+            continue
+
+        if char == "$":
+            display = markdown[i : i + 2] == "$$"
+            delimiter = "$$" if display else "$"
+            start = i + len(delimiter)
+            end = _find_unescaped(markdown, delimiter, start)
+            if end == -1:
+                # No closing delimiter: treat the rest as literal text rather
+                # than silently dropping content or raising.
+                buffer.append(markdown[i:])
+                i = n
+                continue
+            flush_text()
+            segments.append(
+                Segment(kind="math", content=markdown[start:end], display=display)
+            )
+            i = end + len(delimiter)
+            continue
+
+        buffer.append(char)
+        i += 1
+
+    flush_text()
+    return tuple(segments)
+
+
+def _find_unescaped(text: str, delimiter: str, start: int) -> int:
+    """Index of the next ``delimiter`` in ``text`` from ``start``, skipping
+    escaped occurrences. -1 if none."""
+    i = start
+    while True:
+        i = text.find(delimiter, i)
+        if i == -1:
+            return -1
+        if i > 0 and text[i - 1] == "\\":
+            i += len(delimiter)
+            continue
+        return i
+
+
+def strip_boxed(latex: str) -> str:
+    r"""Remove every ``\boxed{...}`` wrapper, keeping its inner content.
+
+    Brace-counting, not regex: the content inside ``\boxed{}`` routinely
+    contains its own nested braces (subscripts, ``\left\{`` groups, fractions),
+    so a pattern like ``\\boxed\{(.*)\}`` cannot reliably find the matching
+    close brace. Handles more than one ``\boxed{}`` in the same string, as in
+    the side-by-side pair in `scalar.md` section 3.
+
+    A ``\boxed`` with no matching close brace is left as-is -- the string is
+    passed through unchanged from that point, rather than raising on malformed
+    input this function did not create.
+    """
+    marker = "\\boxed{"
+    result: list[str] = []
+    i, n = 0, len(latex)
+
+    while i < n:
+        start = latex.find(marker, i)
+        if start == -1:
+            result.append(latex[i:])
+            break
+
+        result.append(latex[i:start])
+        depth = 1
+        j = start + len(marker)
+        while j < n and depth > 0:
+            if latex[j] == "{":
+                depth += 1
+            elif latex[j] == "}":
+                depth -= 1
+            j += 1
+
+        if depth != 0:
+            # No matching close brace: not well-formed \boxed{}; leave the
+            # remainder untouched rather than guessing.
+            result.append(latex[start:])
+            i = n
+            break
+
+        result.append(latex[start + len(marker) : j - 1])
+        i = j
+
+    return "".join(result)
+
+
+def render_math_png(
+    latex: str, *, dpi: int = 140, color: str = "black"
+) -> bytes | None:
+    r"""Rasterize a LaTeX string (no `$` delimiters) to PNG bytes.
+
+    Returns ``None`` on any parser failure -- an unsupported macro, malformed
+    LaTeX -- instead of raising, so the caller can fall back to showing the raw
+    source for that one span. ``\boxed{}`` wrappers are stripped first (see
+    module docstring); everything else the project's docs use
+    (`\operatorname`, `\text`, `\qquad`, Greek letters, `\left[...\right]`,
+    sub/superscripts) is supported by mathtext directly, confirmed by testing.
+
+    A display equation split across source lines for readability (e.g. a long
+    ``$$...$$`` wrapped onto a second, indented line) carries a literal
+    newline and leading whitespace into its LaTeX source once markdown
+    delimiters are stripped. Ordinary TeX ignores such whitespace, but
+    mathtext's parser does not tolerate an embedded ``\n`` -- confirmed by
+    testing -- so any run of whitespace is collapsed to a single space before
+    parsing, matching what plain LaTeX would do with the same source.
+    """
+    import io
+    import re
+
+    import matplotlib
+
+    matplotlib.use("Agg")  # no display needed; safe to call repeatedly
+    from matplotlib.mathtext import math_to_image
+
+    normalized = re.sub(r"\s+", " ", strip_boxed(latex)).strip()
+
+    buffer = io.BytesIO()
+    try:
+        math_to_image(f"${normalized}$", buffer, dpi=dpi, format="png", color=color)
+    except ValueError:
+        return None
+    return buffer.getvalue()

gratinglab/gui/orders.py

@@ -0,0 +1,152 @@
+"""Which diffraction orders the efficiency plot draws.
+
+Previously one line in the widget layer::
+
+    if values.max() < 1e-4:
+        continue
+
+An untested, unoverridable, invisible rule: an order below the threshold
+vanished from the plot with nothing to say it had. That is the wrong shape for
+this project -- the same objection as renormalising away an energy defect. The
+threshold survives as a *default*, because it is a sensible one, but it is now
+listed, labelled with the peak it was judged on, and overridable.
+
+The logic lives here rather than in the panel so the default can be tested
+without a window, and so the rule is written down somewhere a reader will find
+it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Iterable, Sequence
+
+
+if TYPE_CHECKING:  # pragma: no cover - imports for type checkers only
+    from ..result import EfficiencyScan
+
+__all__ = [
+    "OrderSummary",
+    "DEFAULT_THRESHOLD",
+    "DEFAULT_LIMIT",
+    "summarize",
+    "default_visible",
+    "carry_over",
+    "describe",
+]
+
+#: Peak efficiency below which an order is hidden by default. Inherited from
+#: the rule it replaces, so the plot looks the same on first open.
+DEFAULT_THRESHOLD = 1e-4
+
+#: At most this many curves by default, largest peaks first. New, and the part
+#: that actually protects the plot: an X-ray geometry can propagate hundreds of
+#: orders, and the old code's only defence was a legend that grew columns.
+DEFAULT_LIMIT = 20
+
+
+@dataclass(frozen=True, slots=True)
+class OrderSummary:
+    """One diffraction order, as the visibility panel needs to describe it.
+
+    Attributes
+    ----------
+    order
+        The diffraction order `m`.
+    column
+        Its column in ``scan.efficiency``. Carried explicitly so a caller never
+        has to search ``scan.orders`` again, and cannot get the mapping wrong.
+    peak
+        Largest efficiency over the scanned wavelengths. What the default rule
+        judges, and what the panel shows next to each entry.
+    ever_propagating
+        Whether the order propagates at any wavelength in the scan. An order
+        that is evanescent throughout has nothing to plot; it is listed anyway,
+        greyed, because "this order exists and carries nothing" is information.
+    """
+
+    order: int
+    column: int
+    peak: float
+    ever_propagating: bool
+
+
+def summarize(scan: "EfficiencyScan") -> tuple[OrderSummary, ...]:
+    """Describe every order in a scan, in the scan's own order."""
+    peaks = scan.efficiency.max(axis=0)
+    propagating = scan.propagating.any(axis=0)
+    return tuple(
+        OrderSummary(
+            order=int(order),
+            column=column,
+            peak=float(peaks[column]),
+            ever_propagating=bool(propagating[column]),
+        )
+        for column, order in enumerate(scan.orders)
+    )
+
+
+def default_visible(
+    summaries: Sequence[OrderSummary],
+    *,
+    threshold: float = DEFAULT_THRESHOLD,
+    limit: int = DEFAULT_LIMIT,
+) -> frozenset[int]:
+    """The orders worth drawing before the user says otherwise.
+
+    Two rules, in this sequence: peak at or above ``threshold``, then the
+    ``limit`` largest of those. Ties are broken by order index so the result is
+    deterministic -- a plot that redrew differently for the same scan would be
+    its own small bug.
+
+    Returning a set of *orders* rather than columns means the choice survives a
+    re-solve that changes how many orders propagate, which is what
+    :func:`carry_over` relies on.
+    """
+    candidates = [s for s in summaries if s.peak >= threshold]
+    candidates.sort(key=lambda s: (-s.peak, s.order))
+    return frozenset(s.order for s in candidates[:limit])
+
+
+def carry_over(
+    previous_visible: Iterable[int],
+    previous_orders: Iterable[int],
+    summaries: Sequence[OrderSummary],
+    *,
+    threshold: float = DEFAULT_THRESHOLD,
+    limit: int = DEFAULT_LIMIT,
+) -> frozenset[int]:
+    """Reapply a user's choices to a freshly solved scan.
+
+    Nudging the blaze angle and re-solving must not silently re-check the
+    orders someone deliberately unchecked. So: an order that existed before
+    keeps whatever it was, shown or hidden; an order that has only just
+    appeared gets the default rule; an order that no longer exists is dropped
+    rather than remembered, since a stale selection would resurrect on the next
+    unrelated re-solve.
+
+    ``previous_orders`` -- every order the last scan had, not just the visible
+    ones -- is what separates "hidden on purpose" from "not seen before". With
+    only the visible set the two are indistinguishable, and an unchecked order
+    would silently re-check itself on the next solve.
+
+    Pass empty iterables for the first solve; everything is then new and the
+    result is exactly :func:`default_visible`.
+    """
+    seen_before = frozenset(previous_orders)
+    still_exists = {s.order for s in summaries}
+    kept = frozenset(previous_visible) & still_exists
+    fresh = [s for s in summaries if s.order not in seen_before]
+    return kept | default_visible(fresh, threshold=threshold, limit=limit)
+
+
+def describe(summary: OrderSummary) -> str:
+    """One entry's label, e.g. ``m=+3   peak 0.4127``.
+
+    Signed, always, because the sign of the order is the physics -- `+3` and
+    `-3` diffract to opposite sides -- and an unsigned `3` in a list next to
+    `-3` reads as ambiguous rather than positive.
+    """
+    if not summary.ever_propagating:
+        return f"m={summary.order:+d}   evanescent"
+    return f"m={summary.order:+d}   peak {summary.peak:.4f}"

gratinglab/gui/provenance.py

@@ -0,0 +1,273 @@
+"""What the provenance panel says, decided without a toolkit.
+
+The panel is the reason the GUI is worth having rather than a toy: it is where
+a result declares how far it can be trusted. That makes *which line gets which
+colour* a correctness question, not a styling one, and correctness questions do
+not belong in a widget.
+
+So this module owns the decision and returns :class:`Line` tuples; the widget
+layer only paints them. The rule the tests exist to protect is that **things
+which are not wrong must not look wrong**: ``converged is None`` means "not yet
+checked", true for every solver until the convergence harness lands, and a
+coating-free run giving relative efficiency is the correct default. Both once
+rendered identically to a real problem, which is how a fully successful run
+could read as broken. The convergence harness exists now, so ``None`` means
+"this solve did not sweep" rather than "nothing can" -- still not a failure.
+"""
+
+from __future__ import annotations
+
+import html
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Sequence
+
+if TYPE_CHECKING:  # pragma: no cover - imports for type checkers only
+    from ..checks import EnergyReport
+    from ..result import EfficiencyScan
+    from .state import FieldError
+
+__all__ = [
+    "Line",
+    "TAG_COLORS",
+    "provenance_lines",
+    "error_lines",
+    "to_html",
+    "about_text",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class Line:
+    """One run of panel text and the tag that colours it.
+
+    A ``tag`` of ``None`` is ordinary body text. Lines are emitted in reading
+    order and a single visual line may be several ``Line`` objects, so that a
+    neutral label can introduce a coloured value -- ``"energy balance: "``
+    dimmed, then the range in green or red.
+    """
+
+    text: str
+    tag: str | None = None
+
+
+#: Only four, and their meanings are load-bearing. ``dim`` is for facts about
+#: the run, ``ok``/``bad`` for a verdict that was actually reached, and ``warn``
+#: for a validity guard the solver itself raised.
+TAG_COLORS: dict[str, str] = {
+    "warn": "#a5370d",
+    "bad": "#b00020",
+    "ok": "#0a7d28",
+    "dim": "#666666",
+}
+
+#: Tags that read as "something is wrong here". The invariant this module
+#: exists to protect is about which text may carry one.
+ALARM_TAGS = frozenset({"warn", "bad"})
+
+
+def provenance_lines(
+    scan: "EfficiencyScan",
+    energy: "EnergyReport",
+    lambda_over_period: float,
+    *,
+    cancelled: bool = False,
+) -> tuple[Line, ...]:
+    """Everything the panel says about one completed solve.
+
+    ``lambda_over_period`` is passed in rather than a parsed form, so this
+    function needs nothing from the GUI and is trivial to call from a test.
+
+    ``cancelled`` marks the case where the user asked to stop and the result on
+    screen is the *previous* one. The solve really does stop now -- the solver
+    checks at every wavelength -- so this no longer has to hedge about work
+    continuing in the background.
+    """
+    provenance = scan.provenance
+    lines: list[Line] = []
+
+    truncation = provenance.truncation
+    knob = (
+        f"{truncation} {_knob_label(provenance.method)}  ·  "
+        if truncation is not None
+        else ""
+    )
+    lines.append(
+        Line(
+            f"{provenance.method} {provenance.version}  ·  "
+            f"{knob}"
+            f"{_milliseconds(provenance.wall_time_s)}  ·  "
+            f"λ/period = {lambda_over_period:.4g}\n"
+        )
+    )
+
+    if cancelled:
+        # It used to say the calculation was "still finishing", which was true
+        # then and would be a lie now: the solver checks for cancellation at
+        # every wavelength and raises out of its own loop.
+        lines.append(
+            Line(
+                "cancelled — the calculation stopped; showing the previous "
+                "result\n",
+                "dim",
+            )
+        )
+
+    lines.append(Line("convergence: ", "dim"))
+    study = provenance.notes.get("convergence")
+    if provenance.converged is None:
+        # Not a failure. `gratinglab.convergence` exists, but a plain solve
+        # does not run it -- a sweep costs several solves and is the caller's
+        # decision, not a hidden tax on pressing Solve. So this stays the
+        # ordinary state and must not be styled as alarming.
+        lines.append(Line("not checked — see gratinglab.convergence\n", "dim"))
+    elif provenance.converged:
+        lines.append(Line("yes", "ok"))
+        lines.append(Line(_evidence(study), "dim"))
+    else:
+        lines.append(Line("NO", "bad"))
+        lines.append(Line(_evidence(study), "dim"))
+
+    normalization = provenance.notes.get("normalization")
+    if normalization:
+        # The detail comes from whether a coating was *resolved*, which is a
+        # different question from whether its reflectivity was applied -- so
+        # "relative (Au ...)" is a real and honest state, meaning the material
+        # is known and not yet used. Deriving the wording from `normalization`
+        # alone would report "no coating" for it.
+        # Two keys because two solvers mean two things by it: scalar's
+        # `coating` is the material whose Fresnel amplitude was applied, the
+        # integral solver's `material` is the one its boundary condition read.
+        # Either is the honest detail; neither present means none was used.
+        detail = (
+            provenance.notes.get("coating")
+            or provenance.notes.get("material")
+            or "no coating"
+        )
+        lines.append(Line("normalization: ", "dim"))
+        lines.append(Line(f"{normalization} ({detail})\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
+        # method losing power it never lost.
+        lines.append(Line("absorption: ", "dim"))
+        lines.append(
+            Line(
+                f"A ∈ [{scan.absorption.min():.4f}, "
+                f"{scan.absorption.max():.4f}]\n",
+                "dim",
+            )
+        )
+
+    # `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 "Σ"
+    lines.append(Line("energy balance: ", "dim"))
+    lines.append(
+        Line(
+            f"{conserved} ∈ [{energy.total.min():.4f}, {energy.total.max():.4f}]"
+            f"{'' if energy.passed else '  — EXCEEDS UNITY'}\n",
+            "ok" if energy.passed else "bad",
+        )
+    )
+
+    for warning in provenance.warnings:
+        lines.append(Line(f"  ⚠ {warning}\n", "warn"))
+
+    return tuple(lines)
+
+
+def _knob_label(method: str) -> str:
+    """What this method's truncation count is a count *of*.
+
+    Read off the registry rather than a table kept here, so a solver added
+    later names its own knob without editing this module -- the header said
+    "quadrature pts" for every method, which was wrong for the integral
+    solver's boundary points from the day that tab existed. Falls back for
+    imported reference data, whose `method` need not be a registered solver
+    at all.
+    """
+    from ..solvers.base import get_solver
+
+    try:
+        knob = get_solver(method).capabilities.accuracy_knob
+    except (KeyError, ImportError):
+        return "truncation"
+    return knob.replace("_", " ") if knob else "truncation"
+
+
+def _evidence(study: Any) -> str:
+    """What a convergence verdict rests on, in one dim trailing clause.
+
+    A bare "yes" is a claim; the knob value and the swept range are what let a
+    reader check it -- and `converged_at` is the actionable half, since it is
+    usually cheaper than the value it took to prove it. Degrades to a bare
+    newline for a verdict that arrived without its study, rather than
+    inventing detail for it.
+    """
+    if not isinstance(study, dict):
+        return "\n"
+    knob = study.get("knob", "accuracy")
+    at, values = study.get("converged_at"), study.get("values") or []
+    swept = f", swept to {values[-1]}" if values else ""
+    if at is None:
+        return f" — {knob} still moving{swept}\n"
+    return f" — {knob}={at} is enough{swept}\n"
+
+
+def error_lines(errors: Sequence["FieldError"]) -> tuple[Line, ...]:
+    """The panel's other job: say which fields stopped the solve."""
+    lines = [Line(f"{len(errors)} field(s) need attention\n", "bad")]
+    lines.extend(Line(f"  • {e.field}: {e.message}\n", "bad") for e in errors)
+    return tuple(lines)
+
+
+def solving_lines(method: str, wavelength_count: int) -> tuple[Line, ...]:
+    """Shown while a solve is in flight, in place of a stale verdict."""
+    return (
+        Line(f"solving — {method}, {wavelength_count} wavelengths…\n", "dim"),
+    )
+
+
+def to_html(lines: Sequence[Line]) -> str:
+    """Render lines as the small HTML subset Qt's rich text engine accepts.
+
+    Escaped, so a solver warning containing ``<`` or ``&`` -- and the docs do
+    carry ampersands -- cannot silently become markup or vanish.
+    """
+    parts: list[str] = []
+    for line in lines:
+        body = html.escape(line.text).replace("\n", "<br>")
+        color = TAG_COLORS.get(line.tag) if line.tag else None
+        parts.append(f'<span style="color:{color}">{body}</span>' if color else body)
+    return f'<div style="white-space:pre-wrap">{"".join(parts)}</div>'
+
+
+def alarming_text(lines: Sequence[Line]) -> str:
+    """Every character styled as a problem, concatenated.
+
+    Exists for the tests that assert something is *not* flagged, which is
+    otherwise awkward to phrase and was previously done by walking Tk tag
+    index pairs.
+    """
+    return "".join(line.text for line in lines if line.tag in ALARM_TAGS)
+
+
+def about_text(version: str) -> str:
+    """The About box, as a string so it can be asserted without a dialog."""
+    return (
+        "GratingLab\n"
+        f"Version {version}\n\n"
+        "An open comparison platform for grating efficiency analysis: "
+        "scalar, RCWA, C-method and integral-method solvers driven from "
+        "one problem spec.\n\n"
+        "BSD-3-Clause."
+    )
+
+
+def _milliseconds(wall_time_s: Any) -> str:
+    """Wall time for the header, tolerant of a solver that recorded none."""
+    if wall_time_s is None:
+        return "time not recorded"
+    return f"{wall_time_s * 1e3:.0f} ms"

gratinglab/gui/qt/__init__.py

@@ -0,0 +1,20 @@
+"""The widget layer, and the only part of the GUI allowed to import a toolkit.
+
+That boundary is a package boundary rather than a convention so a test can
+enforce it: `tests/test_gui_qt.py` walks every module under `gui/` outside this
+subpackage and fails if PySide6 appears. The drift it prevents is the ordinary
+kind -- someone needing "just a QColor" in a module that was pure.
+
+Everything here should be thin. If a question can be answered without a window
+it belongs in `gui/state.py`, `gui/provenance.py`, `gui/richtext.py` or
+`gui/orders.py`, all of which are pure and tested headlessly.
+"""
+
+from __future__ import annotations
+
+import os
+
+# matplotlib's Qt shim picks a binding from sys.modules first and QT_API
+# second. Without this, a stray PyQt5 in the environment would win and its
+# canvas would refuse to parent into a PySide6 window.
+os.environ.setdefault("QT_API", "PySide6")