gratinglab 0.3.3__tar.gz → 0.3.5__tar.gz

{gratinglab-0.3.3/src/gratinglab.egg-info → gratinglab-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gratinglab
-Version: 0.3.3
+Version: 0.3.5
 Summary: Open platform for diffraction grating groove metrology and efficiency analysis
 Author: Jake McCoy, Aditi Gangadharan
 License: BSD-3-Clause
@@ -249,8 +249,9 @@ uv tool install "gratinglab[gui]"               # gratinglab-gui as a standalone
 
 From a checkout, use `pip install -e ".[dev,gui,metrology,refractiveindex]"` instead.
 
-No optical constant tables are distributed with the package, so absolute efficiencies
-require tables supplied by the user. A library is a directory of such tables, one
+Neither the package nor its repository carries optical constant tables, so absolute
+efficiencies, and the `coating="Au"` examples above, require tables supplied by the
+user. A library is a directory of such tables, one
 material per file, each named after its material:
 
 | File | From | Range |
@@ -264,7 +265,14 @@ Saving one as `~/.gratinglab/materials/Pt.yml` makes `coating="Pt"` available.
 `materials.from_cxro_file(path)` or `from_refractiveindex_file(path)` reads a single
 file without a library. The YAML files require the `refractiveindex` extra.
 [`SOURCES.md`](https://github.com/jamccoy/gratinglab/blob/master/src/gratinglab/materials/data/SOURCES.md)
-explains why no tables are distributed.
+explains why none are distributed.
+
+Without a table, `coating="typical:Au"` (or `typical:SiO2`, `typical:C@2.0` with
+a density) uses an approximate X-ray model built from physical facts, 30 eV to
+30 keV, for Au, Pt, Ni, C, Si and O. Where it cannot answer for its index, near
+an absorption edge or at low energy, the result's provenance says so.
+[`docs/typical-materials.md`](https://github.com/jamccoy/gratinglab/blob/master/docs/typical-materials.md)
+has the model and how far it agrees with real tables.
 
 The core install does not include a plotting stack, so a user who only runs the solvers
 does not install one. A subpackage that needs an optional extra names it when it is
@@ -392,6 +400,7 @@ gratinglab` regenerates the icon from the artwork in `gratinglab.gui.icon`.
 | [`docs/theory/scalar.md`](https://github.com/jamccoy/gratinglab/blob/master/docs/theory/scalar.md) | The derivation of the scalar solver, its closed-form results and its limits |
 | [`docs/theory/integral.md`](https://github.com/jamccoy/gratinglab/blob/master/docs/theory/integral.md) | The boundary-integral solver: conical formulation, perfect and finite conductivity |
 | [`docs/theory/metrology.md`](https://github.com/jamccoy/gratinglab/blob/master/docs/theory/metrology.md) | The assumptions of the AFM pipeline, what it measures and what it does not, including what tip erosion can recover |
+| [`docs/typical-materials.md`](https://github.com/jamccoy/gratinglab/blob/master/docs/typical-materials.md) | The X-ray index model used without a table, what it is checked against, and its measured accuracy |
 | [`docs/findings.md`](https://github.com/jamccoy/gratinglab/blob/master/docs/findings.md) | Empirical results, each with the evidence for it |
 | [`docs/references.md`](https://github.com/jamccoy/gratinglab/blob/master/docs/references.md) | The literature each part of the package is based on |
 | [`docs/mutation-testing.md`](https://github.com/jamccoy/gratinglab/blob/master/docs/mutation-testing.md) | What is mutated, what is not, and how to interpret a surviving mutant |
@@ -514,9 +523,11 @@ no such question.
 
 ### What this licence does not cover
 
-**Optical constant tables.** None are distributed with the package, and a table you
-add is governed by the terms of whoever published it, not by this licence. CXRO and
-refractiveindex.info each state their own, and a table exported from another program
+**Optical constant tables.** None are distributed with the package or kept in the
+repository: the suite runs on an invented gold-sized table of its own, and its
+refractiveindex.info reader fixtures are files that site dedicates CC0. A table you
+add is governed by the terms of whoever published it, not by this licence. refractiveindex.info
+dedicates its files CC0, CXRO states no terms at all, and a table exported from another program
 carries whatever that program's terms attach to it.
 [`SOURCES.md`](https://github.com/jamccoy/gratinglab/blob/master/src/gratinglab/materials/data/SOURCES.md)
 records where each kind comes from and why none ships here.

{gratinglab-0.3.3 → gratinglab-0.3.5}/README.md

@@ -204,8 +204,9 @@ uv tool install "gratinglab[gui]"               # gratinglab-gui as a standalone
 
 From a checkout, use `pip install -e ".[dev,gui,metrology,refractiveindex]"` instead.
 
-No optical constant tables are distributed with the package, so absolute efficiencies
-require tables supplied by the user. A library is a directory of such tables, one
+Neither the package nor its repository carries optical constant tables, so absolute
+efficiencies, and the `coating="Au"` examples above, require tables supplied by the
+user. A library is a directory of such tables, one
 material per file, each named after its material:
 
 | File | From | Range |
@@ -219,7 +220,14 @@ Saving one as `~/.gratinglab/materials/Pt.yml` makes `coating="Pt"` available.
 `materials.from_cxro_file(path)` or `from_refractiveindex_file(path)` reads a single
 file without a library. The YAML files require the `refractiveindex` extra.
 [`SOURCES.md`](https://github.com/jamccoy/gratinglab/blob/master/src/gratinglab/materials/data/SOURCES.md)
-explains why no tables are distributed.
+explains why none are distributed.
+
+Without a table, `coating="typical:Au"` (or `typical:SiO2`, `typical:C@2.0` with
+a density) uses an approximate X-ray model built from physical facts, 30 eV to
+30 keV, for Au, Pt, Ni, C, Si and O. Where it cannot answer for its index, near
+an absorption edge or at low energy, the result's provenance says so.
+[`docs/typical-materials.md`](https://github.com/jamccoy/gratinglab/blob/master/docs/typical-materials.md)
+has the model and how far it agrees with real tables.
 
 The core install does not include a plotting stack, so a user who only runs the solvers
 does not install one. A subpackage that needs an optional extra names it when it is
@@ -347,6 +355,7 @@ gratinglab` regenerates the icon from the artwork in `gratinglab.gui.icon`.
 | [`docs/theory/scalar.md`](https://github.com/jamccoy/gratinglab/blob/master/docs/theory/scalar.md) | The derivation of the scalar solver, its closed-form results and its limits |
 | [`docs/theory/integral.md`](https://github.com/jamccoy/gratinglab/blob/master/docs/theory/integral.md) | The boundary-integral solver: conical formulation, perfect and finite conductivity |
 | [`docs/theory/metrology.md`](https://github.com/jamccoy/gratinglab/blob/master/docs/theory/metrology.md) | The assumptions of the AFM pipeline, what it measures and what it does not, including what tip erosion can recover |
+| [`docs/typical-materials.md`](https://github.com/jamccoy/gratinglab/blob/master/docs/typical-materials.md) | The X-ray index model used without a table, what it is checked against, and its measured accuracy |
 | [`docs/findings.md`](https://github.com/jamccoy/gratinglab/blob/master/docs/findings.md) | Empirical results, each with the evidence for it |
 | [`docs/references.md`](https://github.com/jamccoy/gratinglab/blob/master/docs/references.md) | The literature each part of the package is based on |
 | [`docs/mutation-testing.md`](https://github.com/jamccoy/gratinglab/blob/master/docs/mutation-testing.md) | What is mutated, what is not, and how to interpret a surviving mutant |
@@ -469,9 +478,11 @@ no such question.
 
 ### What this licence does not cover
 
-**Optical constant tables.** None are distributed with the package, and a table you
-add is governed by the terms of whoever published it, not by this licence. CXRO and
-refractiveindex.info each state their own, and a table exported from another program
+**Optical constant tables.** None are distributed with the package or kept in the
+repository: the suite runs on an invented gold-sized table of its own, and its
+refractiveindex.info reader fixtures are files that site dedicates CC0. A table you
+add is governed by the terms of whoever published it, not by this licence. refractiveindex.info
+dedicates its files CC0, CXRO states no terms at all, and a table exported from another program
 carries whatever that program's terms attach to it.
 [`SOURCES.md`](https://github.com/jamccoy/gratinglab/blob/master/src/gratinglab/materials/data/SOURCES.md)
 records where each kind comes from and why none ships here.

{gratinglab-0.3.3 → gratinglab-0.3.5}/pyproject.toml

@@ -145,11 +145,11 @@ version = { attr = "gratinglab.__version__" }
 [tool.setuptools.packages.find]
 where = ["src"]
 
-# Optical constant TABLES do not ship: whether CXRO's may be redistributed is
-# not settled, so the wheel and sdist carry none and `available()` is empty on
-# install. That is the one place a checkout and an install differ on purpose,
-# and both halves are checked: the suite uses `data/Au.txt` from the checkout,
-# and release.yml asserts the wheel holds no table and that an install refuses
+# Optical constant TABLES do not ship, and the repository holds none: only
+# data that is ours or in the public domain is committed, and no published
+# table is clearly either. So `available()` is empty on install. The suite
+# uses an invented table from `tests/data/materials/` instead, and
+# release.yml asserts the wheel holds no table and that an install refuses
 # `lookup("Au")` with the message that says what to do instead. A missing table
 # raises rather than degrading, so the difference cannot pass for a result.
 # SOURCES.md ships, because it is how a user finds out where to get one.
@@ -241,7 +241,7 @@ do_not_mutate = [
     # are covered by tests/test_illumination.py and tests/test_profiles.py.
     "*/illumination.py",
     "*/problem.py",
-    "*/profiles.py",
+    "*/profiles/*",
 ]
 
 # corpus.toml, which the reference tests read.

{gratinglab-0.3.3 → gratinglab-0.3.5}/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.3.3"
+__version__ = "0.3.5"
 
 __all__ = [
     "Illumination",

{gratinglab-0.3.3 → gratinglab-0.3.5}/src/gratinglab/compare.py

@@ -173,6 +173,8 @@ class Residuals:
     with no stated uncertainty cannot say how far off it is in those units.
     ``propagating`` is the *model's* flag: a measured order that the model
     calls evanescent is a disagreement worth seeing, and its ``model`` is 0.
+    :meth:`evanescent_warning` says how many there are and in which orders,
+    because the residual alone cannot tell a wrong mount from a wrong model.
     """
 
     measurement: str
@@ -201,8 +203,11 @@ class Residuals:
 
         ``chi2`` sums ``pull**2`` over the points that have a sigma, and
         ``n_with_sigma`` says how many that was, so the number is never read
-        without its denominator. ``at_wavelength`` and ``at_order`` locate the
-        largest absolute residual.
+        without its denominator. ``n_evanescent`` counts the measured points
+        on orders the model does not propagate, which are inside every other
+        figure here at a model value of exactly 0; see
+        :meth:`evanescent_warning`. ``at_wavelength`` and ``at_order`` locate
+        the largest absolute residual.
         """
         residual = self.residual
         pull = self.pull
@@ -214,10 +219,50 @@ class Residuals:
             "chi2": float(np.sum(pull[finite] ** 2)),
             "n_points": float(len(self)),
             "n_with_sigma": float(np.count_nonzero(finite)),
+            "n_evanescent": float(np.count_nonzero(~self.propagating)),
             "at_wavelength": float(self.wavelength[worst]),
             "at_order": int(self.order[worst]),
         }
 
+    def evanescent_warning(self) -> str | None:
+        """Say which measured points the model cannot propagate, or None.
+
+        Something was measured at each of these points, so either the model
+        or the mount it was given is wrong there. Two shapes are common and
+        they mean different things. A point or two at the end of the arc,
+        the most negative or most positive order at its energy, can be a
+        real order close to its cutoff. Whole orders stranded at every
+        wavelength they were measured at is a mount problem, and the sign
+        of alpha is the first thing to check: the June 2017 SCIL campaign's angle file put 59
+        of 123 points there, and the only symptom without this count was an
+        RMS residual of 0.157 (``docs/findings.md``).
+
+        Nothing is decided here. The message gives the count per order,
+        against how many points that order has, and leaves the reading to
+        whoever runs the comparison. It is not raised as a Python warning,
+        because the edge-of-arc case is legitimate and a campaign that has
+        one would warn on every run.
+        """
+        stranded = ~self.propagating
+        if not stranded.any():
+            return None
+        parts = []
+        for m in np.unique(self.order[stranded]):
+            in_order = self.order == m
+            parts.append(
+                f"m={int(m):+d} ({np.count_nonzero(stranded & in_order)} of "
+                f"{np.count_nonzero(in_order)})"
+            )
+        return (
+            f"{np.count_nonzero(stranded)} of {len(self)} measured points in "
+            f"{self.measurement!r} fall on orders {self.method!r} does not "
+            f"propagate, where it reads exactly 0: {', '.join(parts)}. A point "
+            "at the end of the arc can be a real order near its cutoff. A whole "
+            "order stranded usually means the mount is wrong: check the sign of "
+            "alpha first, and take the one under which the measured orders "
+            "propagate (docs/conventions.md, section 4)."
+        )
+
 
 @dataclass(frozen=True, slots=True)
 class Comparison:

{gratinglab-0.3.3 → gratinglab-0.3.5}/src/gratinglab/gui/mathtext.py

@@ -173,7 +173,12 @@ def strip_boxed(latex: str) -> str:
 
 
 def render_math_png(
-    latex: str, *, dpi: int = 140, color: str = "black"
+    latex: str,
+    *,
+    dpi: int = 140,
+    color: str = "black",
+    axis_pt: float | None = None,
+    min_height_pt: float = 0.0,
 ) -> bytes | None:
     r"""Rasterize a LaTeX string (no `$` delimiters) to PNG bytes.
 
@@ -192,6 +197,20 @@ def render_math_png(
     confirmed that mathtext's parser does not tolerate an embedded ``\n``. Any
     run of whitespace is therefore collapsed to a single space before parsing,
     which matches what plain LaTeX would do with the same source.
+
+    ``axis_pt`` is for an equation set inside a line of text. Qt places an
+    image aligned ``vertical-align: middle`` with its centre a quarter of the
+    font's x-height above the baseline, so given that height in points of the
+    10 pt render, space is added above or below until the image's centre lands
+    there exactly when the equation's own baseline sits on the text's. Without
+    it the image's bottom edge sits on the baseline, and every symbol with a
+    descender rides above the line.
+
+    That rule holds only for an image at least about three x-heights tall;
+    Qt sets a shorter one higher, by an amount that depends on its height
+    (measured with PySide6 6.11 on 2026-11-12, by scanning solid images from
+    8 to 32 px against a 14 px font). ``min_height_pt`` pads the image evenly
+    above and below up to that height, which keeps the centre where it was.
     """
     import io
     import re
@@ -205,7 +224,69 @@ def render_math_png(
 
     buffer = io.BytesIO()
     try:
-        math_to_image(f"${normalized}$", buffer, dpi=dpi, format="png", color=color)
+        if axis_pt is None:
+            math_to_image(f"${normalized}$", buffer, dpi=dpi, format="png", color=color)
+            return buffer.getvalue()
+        return _inline_png(normalized, dpi, color, axis_pt, min_height_pt)
     except ValueError:
         return None
+
+
+def _inline_png(
+    latex: str, dpi: int, color: str, axis_pt: float, min_height_pt: float
+) -> bytes:
+    """An inline equation as a transparent PNG, padded about its baseline.
+
+    The baseline is measured rather than taken from mathtext's box depth,
+    which is the layout box and not where the glyphs land: rasterised at
+    101 dpi the two differ by a pixel in either direction depending on the
+    expression. So the expression is rendered a second time with an upright
+    ``x`` after it, which sits on the baseline, and the bottom of that ``x``
+    is read off. The two renders share one vertical frame whenever the ``x``
+    is no taller and no deeper than the expression, which is any expression
+    holding a letter or digit; otherwise the box depth is used.
+    """
+    import io
+
+    import numpy as np
+    from matplotlib.colors import to_rgb
+    from matplotlib.image import imsave
+    from matplotlib.mathtext import MathTextParser
+
+    parser = MathTextParser("agg")
+    ink = np.asarray(parser.parse(f"${latex}$", dpi=dpi).image)
+    probe = parser.parse(f"${latex}" + r"\mathrm{x}$", dpi=dpi)
+    probe_ink = np.asarray(probe.image)
+    rows = ink.shape[0]
+    if probe_ink.shape[0] == rows:
+        # The rightmost couple of points of the x: its right leg ends on
+        # the baseline, and nothing of the expression reaches that far.
+        columns = np.flatnonzero(probe_ink.max(axis=0))
+        leg = probe_ink[:, columns[-1] - max(1, round(2 * dpi / 72)) + 1 : columns[-1] + 1]
+        baseline = int(np.flatnonzero(leg.max(axis=1) > 100)[-1]) + 1
+    else:
+        rendered = parser.parse(f"${latex}$", dpi=dpi)
+        baseline = int(rendered.height - rendered.depth) - 1
+
+    # Centre on the axis: (above - below) / 2 must equal the axis height.
+    scale = dpi / 72.0
+    above, below = float(baseline), float(rows - baseline)
+    excess = (above - below) - 2 * axis_pt * scale
+    if excess > 0:
+        below += excess
+    else:
+        above -= excess
+    short = min_height_pt * scale - (above + below)
+    if short > 0:
+        above += short / 2
+        below += short / 2
+    top = round(above) - baseline
+    bottom = round(below) - (rows - baseline)
+
+    alpha = np.pad(ink, ((top, bottom), (0, 0))).astype(float) / 255.0
+    rgba = np.empty(alpha.shape + (4,))
+    rgba[..., :3] = to_rgb(color)
+    rgba[..., 3] = alpha
+    buffer = io.BytesIO()
+    imsave(buffer, rgba, format="png")
     return buffer.getvalue()

{gratinglab-0.3.3 → gratinglab-0.3.5}/src/gratinglab/gui/qt/setup_tab.py

@@ -36,13 +36,12 @@ from PySide6.QtWidgets import (
     QLabel,
     QMessageBox,
     QPushButton,
-    QTextBrowser,
     QVBoxLayout,
     QWidget,
 )
 
 from ..docs import TheoryPage
-from .theory_viewer import render_into
+from .theory_viewer import ReadingBrowser, render_into
 
 #: What each reader's ``source`` string starts with, and what to cite for it.
 _CITATIONS = {
@@ -193,9 +192,9 @@ code changes. Or load a table from anywhere without adding it:
 
 {citations}
 
-The package ships no tables: CXRO's terms for redistributing them inside a
-BSD-3 package have not been confirmed, and `SOURCES.md` beside the bundled
-directory records why. Each table's source names the file it was read from,
+The package ships no tables: it carries only data that is its own or in the
+public domain, and no published table is clearly either. `SOURCES.md` beside
+the bundled directory records why. Each table's source names the file it was read from,
 so a result's provenance says which library answered.
 
 ## Surface roughness
@@ -242,7 +241,7 @@ class SetupTab(QWidget):
 
     def __init__(self, parent: QWidget | None = None) -> None:
         super().__init__(parent)
-        self._browser = QTextBrowser()
+        self._browser = ReadingBrowser()
         self._browser.setOpenExternalLinks(False)
         self._browser.setOpenLinks(False)
         # Links leave for the system browser; the page itself never navigates.

gratinglab-0.3.5/src/gratinglab/gui/qt/theory_viewer.py

@@ -0,0 +1,210 @@
+"""The read-only viewer for one theory or reference page.
+
+The viewer is thin by design. :mod:`gratinglab.gui.richtext` turns the page
+into HTML and a list of rasterised equations, and this class only passes both
+to a `QTextBrowser`. Everything that could be wrong in a non-trivial way
+(table structure, escaping, math placement, the approximate-method banner) is
+decided and tested in that module, without a window.
+
+Images are registered with `QTextDocument.addResource` instead of being
+embedded as `data:` URIs, because `loadResource` does not handle `data:` by
+default. This also removes the least elegant detail of the Tk viewer: a list
+monkey-patched onto the window solely to keep `PhotoImage` objects alive
+against garbage collection while Tk was still displaying them.
+
+:class:`ReadingBrowser` is the page itself: a slightly larger font than the
+widgets around it, and a text column kept to a readable width and centred,
+so a wide window adds margin rather than longer lines. The math is sized
+from that font, so an equation in a sentence matches the words beside it.
+"""
+
+from __future__ import annotations
+
+from PySide6.QtCore import Qt, QUrl
+from PySide6.QtGui import (
+    QFontMetricsF,
+    QImage,
+    QTextBlockFormat,
+    QTextCursor,
+    QTextDocument,
+    QTextImageFormat,
+)
+from PySide6.QtWidgets import QTextBrowser, QVBoxLayout, QWidget
+
+from .. import richtext
+
+__all__ = ["ReadingBrowser", "TheoryViewer", "render_into"]
+
+#: Body text relative to the application font. The pages are long prose, and
+#: the 9 pt that suits a button is small for reading paragraphs of it.
+READING_SCALE = 1.15
+
+#: Widest the text column grows, in ems of the reading font: about 100
+#: characters of prose a line. A display equation wider than that widens the
+#: column to fit rather than scrolling sideways.
+READING_WIDTH_EMS = 50
+
+#: Space either side of the column, in pixels, when the window is narrower
+#: than the column.
+READING_MARGIN = 24
+
+#: Space around tables, which Qt otherwise sets flush against the paragraph
+#: above them.
+_STYLE = "table { margin-top: 6px; margin-bottom: 10px; } th { text-align: left; }"
+
+#: Extra space between lines, as a fraction of the font's pixel size. Added
+#: as a fixed distance rather than CSS ``line-height: 135%``, which scales
+#: each line's own height and so opens a wide gap around every line holding
+#: an equation.
+LEADING = 0.3
+
+
+class ReadingBrowser(QTextBrowser):
+    """A `QTextBrowser` laid out for reading a page rather than a log."""
+
+    def __init__(self, parent: QWidget | None = None) -> None:
+        super().__init__(parent)
+        font = self.font()
+        font.setPointSizeF(font.pointSizeF() * READING_SCALE)
+        self.setFont(font)
+        self.document().setDefaultFont(font)
+        self.document().setDefaultStyleSheet(_STYLE)
+        self._widest_image = 0.0
+
+    def resizeEvent(self, event) -> None:  # noqa: N802 - Qt's spelling
+        super().resizeEvent(event)
+        self._centre_column()
+
+    def pixel_size(self) -> float:
+        """The reading font's size in pixels.
+
+        From the point size and the screen's DPI rather than `QFontInfo`,
+        which reports the matched font and so reads near zero where no system
+        fonts are installed, as on the offscreen CI runs.
+        """
+        return self.font().pointSizeF() * self.logicalDpiY() / 72.0
+
+    def _centre_column(self) -> None:
+        column = max(self.pixel_size() * READING_WIDTH_EMS, self._widest_image)
+        spare = self.viewport().width() - column
+        side = max(READING_MARGIN, spare / 2)
+        root = self.document().rootFrame()
+        frame = root.frameFormat()
+        if frame.leftMargin() == side and frame.rightMargin() == side:
+            return
+        frame.setLeftMargin(side)
+        frame.setRightMargin(side)
+        frame.setTopMargin(READING_MARGIN / 2)
+        frame.setBottomMargin(READING_MARGIN)
+        root.setFrameFormat(frame)
+
+    def setHtml(self, text: str) -> None:  # noqa: N802 - Qt's spelling
+        # setHtml replaces the root frame's format along with the content.
+        super().setHtml(text)
+        leading = QTextBlockFormat()
+        leading.setLineHeight(
+            round(self.pixel_size() * LEADING),
+            QTextBlockFormat.LineHeightTypes.LineDistanceHeight.value,
+        )
+        cursor = QTextCursor(self.document())
+        cursor.select(QTextCursor.SelectionType.Document)
+        cursor.mergeBlockFormat(leading)
+        self._widest_image = _widest_image(self.document())
+        self._centre_column()
+
+
+def _widest_image(document: QTextDocument) -> float:
+    """The widest image in a document, in pixels, tables included."""
+    widest = 0.0
+    block = document.begin()
+    while block.isValid():
+        fragments = block.begin()
+        while not fragments.atEnd():
+            fmt = fragments.fragment().charFormat()
+            if fmt.isImageFormat():
+                widest = max(widest, QTextImageFormat(fmt).width())
+            fragments += 1
+        block = block.next()
+    return widest
+
+
+def render_into(
+    browser: QTextBrowser, page, *, device_pixel_ratio: float, text_color: str
+) -> None:
+    """Render a page into an existing `QTextBrowser`, images and all.
+
+    It is shared by :class:`TheoryViewer` and :class:`~.setup_tab.SetupTab`,
+    both of which show "one markdown-ish page, typeset, in a browser," and the
+    second use is what justified factoring this function out instead of
+    copying it.
+    """
+    font = browser.document().defaultFont()
+    pixels = font.pointSizeF() * browser.logicalDpiY() / 72.0
+    rendered = richtext.to_html(
+        page,
+        device_pixel_ratio=device_pixel_ratio,
+        color=text_color,
+        inline_dpi=richtext.math_dpi(pixels),
+        display_dpi=richtext.math_dpi(pixels, display=True),
+        **richtext.inline_metrics(pixels, QFontMetricsF(font).xHeight()),
+    )
+    document = browser.document()
+    for image in rendered.images:
+        document.addResource(
+            QTextDocument.ResourceType.ImageResource,
+            QUrl(image.key),
+            QImage.fromData(image.png, "PNG"),
+        )
+    browser.setHtml(rendered.html)
+
+
+class TheoryViewer(QWidget):
+    """One page, typeset."""
+
+    def __init__(self, page, parent: QWidget | None = None) -> None:
+        # A window in its own right rather than a modal dialog: reading the
+        # theory while adjusting the grating is the point.
+        super().__init__(parent)
+        self.setWindowFlag(Qt.WindowType.Window)
+        self.setWindowTitle(page.title)
+        self.resize(860, 720)
+
+        self._browser = ReadingBrowser()
+        self._browser.setOpenExternalLinks(False)
+        # Relative links between doc pages point at files on disk that this
+        # viewer has no route to open. Following them would empty the window.
+        self._browser.setOpenLinks(False)
+
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(0, 0, 0, 0)
+        layout.addWidget(self._browser)
+
+        self.set_page(page)
+        from . import theming
+
+        # Equations are images rasterised in the text colour, so a theme
+        # change re-renders the page rather than only repainting it.
+        theming.subscribe(self._on_theme)
+
+    def _on_theme(self, _theme) -> None:
+        # A bound method so Qt disconnects it with the window (see SetupTab).
+        self.set_page(self._page)
+
+    def set_page(self, page) -> None:
+        """Render a page into the browser, images and all."""
+        self._page = page
+        render_into(
+            self._browser,
+            page,
+            device_pixel_ratio=self.devicePixelRatioF(),
+            text_color=self._text_color(),
+        )
+
+    def _text_color(self) -> str:
+        """Rasterise math in the palette's own text colour.
+
+        Equations are images, so they do not follow a stylesheet the way the
+        surrounding prose does. Black math on a dark theme would be unreadable
+        only because its colour had been fixed at render time.
+        """
+        return self.palette().windowText().color().name()

{gratinglab-0.3.3 → gratinglab-0.3.5}/src/gratinglab/gui/qt/worker.py

@@ -26,6 +26,8 @@ and the clear is silently lost.
 
 from __future__ import annotations
 
+import inspect
+import os
 import threading
 from typing import TYPE_CHECKING, NamedTuple
 
@@ -79,6 +81,32 @@ def _energy(scan) -> "EnergyReport":
     return check_energy_balance(scan, tolerance=_ENERGY_DEVIATION_WARN)
 
 
+#: Threads a scan's wavelengths are solved on, for the solvers that take
+#: ``workers``. The library defaults to 1, and nothing in the window passed
+#: anything else, so a scan used one core of however many there were. A
+#: 32-wavelength integral scan on MC1 (16 cores) took 5.05 s at 1, 1.69 s at
+#: 4, 1.34 s at 8 and 1.22 s at 12, identical to the serial result each time,
+#: so 8 is where it stops paying. One core is left for the window itself.
+_SCAN_WORKERS = max(1, min(8, (os.cpu_count() or 2) - 1))
+
+
+def _with_workers(method: str, options: dict) -> dict:
+    """``options`` with :data:`_SCAN_WORKERS` added, if ``method`` takes it.
+
+    A ``workers`` already present is kept. The solver's own signature is what
+    decides, so a solver that gains the option later is covered without an
+    edit here, and one without it (scalar, the C-method) is never sent a
+    keyword it would refuse.
+    """
+    from ...solvers.base import get_solver
+
+    if "workers" in options:
+        return options
+    if "workers" not in inspect.signature(get_solver(method).solve).parameters:
+        return options
+    return {**options, "workers": _SCAN_WORKERS}
+
+
 class SolveWorker(QObject):
     """Run one solve at a time on a dedicated thread, for whichever solver asked.
 
@@ -123,7 +151,7 @@ class SolveWorker(QObject):
                 geometry.illumination,
                 geometry.wavelengths,
                 [method],
-                options={method: options},
+                options={method: _with_workers(method, options)},
                 progress=self._reporter(token, cancel),
             )[0]
             self.finished.emit(token, method, SolveResult(scan, _energy(scan)))
@@ -172,7 +200,11 @@ class SolveWorker(QObject):
                 geometry.illumination,
                 geometry.wavelengths,
                 progress=self._reporter(token, cancel),
-                **{k: v for k, v in options.items() if k != knob},
+                **{
+                    k: v
+                    for k, v in _with_workers(method, options).items()
+                    if k != knob
+                },
             )
             self.converged.emit(
                 token,
@@ -238,7 +270,7 @@ class SolveWorker(QObject):
                         geometry.illumination,
                         geometry.wavelengths,
                         [method],
-                        options={method: method_options},
+                        options={method: _with_workers(method, method_options)},
                         progress=step,
                     )[0]
                 except Cancelled: