gratinglab 0.2.4__tar.gz → 0.2.6__tar.gz

{gratinglab-0.2.4/src/gratinglab.egg-info → gratinglab-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gratinglab
-Version: 0.2.4
+Version: 0.2.6
 Summary: Open platform for diffraction grating groove metrology and efficiency analysis
 Author: Jake McCoy, Aditi Gangadharan
 License: BSD-3-Clause

{gratinglab-0.2.4 → gratinglab-0.2.6}/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.2.4"
+__version__ = "0.2.6"
 
 __all__ = [
     "Illumination",

{gratinglab-0.2.4 → gratinglab-0.2.6}/src/gratinglab/gui/qt/theming.py

@@ -36,6 +36,7 @@ __all__ = [
     "current",
     "install",
     "manager",
+    "settings",
     "subscribe",
     "swatch",
 ]
@@ -47,13 +48,21 @@ _KEY = "appearance/theme"
 _PROPERTY = "_gratinglab_theme_manager"
 
 
-def _settings() -> QSettings:
+def settings() -> QSettings:
+    """The application's settings store, or the INI file ``GRATINGLAB_SETTINGS`` names.
+
+    Shared by everything the windows remember (the theme, the AFM column
+    width), so the test suite's redirect covers all of it at once.
+    """
     path = os.environ.get(SETTINGS_ENV)
     if path:
         return QSettings(path, QSettings.Format.IniFormat)
     return QSettings("gratinglab", "gratinglab")
 
 
+_settings = settings
+
+
 def palette(theme: Theme) -> QPalette:
     """A ``QPalette`` for ``theme``, with disabled text dimmed to its muted colour."""
     role = QPalette.ColorRole

{gratinglab-0.2.4 → gratinglab-0.2.6}/src/gratinglab/io/boundary.py

@@ -88,8 +88,10 @@ class BoundaryFile:
         This is the same problem ``BoundaryProfile.to_problem`` builds in
         process, which is the purpose of the format; see
         ``tests/test_io_boundary.py``.
-        Roughness is not in the file for the reason that method's docstring
-        gives: nothing here measures surface microroughness.
+        Roughness is not applied, for the reason that method's docstring
+        gives. The measured groove residual travels in
+        ``metrics['groove_residual_rms_nm']`` and is passed only on request,
+        as ``roughness=``.
         """
         from ..problem import Problem
 

{gratinglab-0.2.4 → gratinglab-0.2.6}/src/gratinglab/metrology/boundary/__init__.py

@@ -14,8 +14,10 @@ from .swaths import SwathStatistics, swath_statistics
 from .average import (
     flatten_endpoints,
     average_grooves,
+    groove_residuals,
     normalize_profile,
     profile_metrics,
+    select_grooves,
 )
 
 __all__ = [
@@ -25,6 +27,8 @@ __all__ = [
     'swath_statistics',
     'flatten_endpoints',
     'average_grooves',
+    'groove_residuals',
     'normalize_profile',
     'profile_metrics',
+    'select_grooves',
 ]

{gratinglab-0.2.4 → gratinglab-0.2.6}/src/gratinglab/metrology/boundary/average.py

@@ -7,7 +7,7 @@ profile front-end now comes from gratinglab.metrology.core instead of a private
 copy.
 """
 import numpy as np
-from scipy.interpolate import interp1d
+from scipy.interpolate import interp1d, make_interp_spline
 from scipy.ndimage import uniform_filter1d
 
 from ..core.processing import extract_single_groove
@@ -30,6 +30,36 @@ def flatten_endpoints(x, y):
     return y - line
 
 
+def select_grooves(x, y, groove_centers, period_nm, margin=0.0,
+                   min_half_width=10, require_full_period=True):
+    """
+    The grooves `average_grooves` averages, each centred on its own axis in µm.
+
+    Separate so that `groove_residuals` measures exactly the set that went
+    into the average, chosen by the same rules rather than a second copy of
+    them. The parameters mean what they mean in `average_grooves`.
+
+    Returns:
+        a list of (x_g, y_g), possibly empty
+    """
+    grooves = []
+    dx_nm = (x[1] - x[0]) * 1000
+    half_width = int(round((period_nm / 2) * (1 + margin) / dx_nm))
+
+    for center in groove_centers:
+        L = min(half_width, center, len(x) - 1 - center)
+        if require_full_period and L < half_width:
+            continue  # the scan edge cuts into this groove's period
+        if L > min_half_width:
+            x_g, y_g = extract_single_groove(x, y, center, period_nm, margin,
+                                             allow_asymmetric=False)
+            # Re-create the exactly symmetric axis the original used, so that
+            # floating point matches to the last bit.
+            x_g = np.linspace(-L * dx_nm, L * dx_nm, len(y_g)) / 1000
+            grooves.append((x_g, y_g))
+    return grooves
+
+
 def average_grooves(x, y, groove_centers, period_nm, margin=0.0, n_points=2000,
                     min_half_width=10, require_full_period=True):
     """
@@ -53,21 +83,9 @@ def average_grooves(x, y, groove_centers, period_nm, margin=0.0, n_points=2000,
     Returns:
         x_common, y_avg, y_std, n_used
     """
-    grooves = []
-    dx_nm = (x[1] - x[0]) * 1000
-    half_width = int(round((period_nm / 2) * (1 + margin) / dx_nm))
-
-    for center in groove_centers:
-        L = min(half_width, center, len(x) - 1 - center)
-        if require_full_period and L < half_width:
-            continue  # the scan edge cuts into this groove's period
-        if L > min_half_width:
-            x_g, y_g = extract_single_groove(x, y, center, period_nm, margin,
-                                             allow_asymmetric=False)
-            # Re-create the exactly symmetric axis the original used, so that
-            # floating point matches to the last bit.
-            x_g = np.linspace(-L * dx_nm, L * dx_nm, len(y_g)) / 1000
-            grooves.append((x_g, y_g))
+    grooves = select_grooves(x, y, groove_centers, period_nm, margin=margin,
+                             min_half_width=min_half_width,
+                             require_full_period=require_full_period)
 
     if len(grooves) == 0:
         raise ValueError(
@@ -90,6 +108,88 @@ def average_grooves(x, y, groove_centers, period_nm, margin=0.0, n_points=2000,
     return x_common, np.mean(y_aligned, axis=0), np.std(y_aligned, axis=0), len(grooves)
 
 
+def groove_residuals(grooves, x_common, y_avg, n_passes=3, n_steps=6):
+    """
+    How far each groove departs from the average, once registered to it.
+
+    This is the RMS residual of each averaged groove about the average: the
+    part of the measured profile that does not repeat from one groove to the
+    next. It is reported, not applied. `BoundaryProfile.to_problem` and
+    docs/theory/metrology.md section 4 say why it is not a Nevot-Croce sigma.
+
+    A plain difference against `y_avg` does not measure that. Each groove is
+    centred on the sample nearest its minimum, so the set is misregistered by
+    up to half a pixel, and on a facet steeper than 45 degrees half a pixel of
+    shift is several nanometres of height. On the synthetic sawtooth with no
+    noise at all, the plain difference reads 2.1 nm. So each groove is first
+    registered to the average by a sub-pixel shift and a height offset, fitted
+    by Gauss-Newton on a cubic spline of its own samples, and the average is
+    recomputed from the registered grooves, `n_passes` times over. The shift is
+    bounded to one pixel either way, and the window is the aligned window the
+    average uses less one pixel at each end, so a shifted groove is never
+    extrapolated.
+
+    The residual is then taken at each groove's own samples rather than on the
+    dense common axis, because interpolating onto that axis smooths pixel-scale
+    structure: it read white noise 10 to 15% low. It is scaled by
+    sqrt(N / (N - 1)), since the average contains the groove it is compared
+    with, and is undefined for a single groove.
+
+    `y_avg` itself is not changed. It is still the unregistered mean, and is
+    what is exported.
+
+    Returns:
+        dict with
+          rms_nm: over every groove, or None for fewer than two grooves
+          per_groove_nm: one RMS per groove, in the order of `grooves`
+          shift_px: each groove's registration shift, in pixels
+    """
+    n = len(grooves)
+    if n < 2:
+        return {'rms_nm': None, 'per_groove_nm': np.zeros(0),
+                'shift_px': np.zeros(0)}
+
+    dx = grooves[0][0][1] - grooves[0][0][0]
+    inner = (x_common > x_common[0] + dx) & (x_common < x_common[-1] - dx)
+    xi = x_common[inner]
+    reference = np.asarray(y_avg, dtype=float)[inner]
+    splines = [make_interp_spline(g[0], g[1], k=3) for g in grooves]
+    slopes = [spline.derivative() for spline in splines]
+    shifts = np.zeros(n)
+
+    for _ in range(n_passes):
+        registered = np.empty((n, len(xi)))
+        for k, (spline, slope) in enumerate(zip(splines, slopes)):
+            d = shifts[k]
+            for _ in range(n_steps):
+                r = spline(xi + d) - reference
+                # Least squares in (shift, offset). The offset's normal
+                # equation removes the means, which leaves one unknown.
+                g = slope(xi + d)
+                g = g - g.mean()
+                denom = np.dot(g, g)
+                if denom == 0:
+                    break
+                d = float(np.clip(d - np.dot(g, r - r.mean()) / denom, -dx, dx))
+            shifts[k] = d
+            curve = spline(xi + d)
+            registered[k] = curve - np.mean(curve - reference)
+        reference = registered.mean(axis=0)
+
+    at_reference = make_interp_spline(xi, reference, k=3)
+    mean_square = np.empty(n)
+    for k, (x_g, y_g) in enumerate(grooves):
+        xs = x_g - shifts[k]
+        keep = (xs >= xi[0]) & (xs <= xi[-1])
+        r = y_g[keep] - at_reference(xs[keep])
+        mean_square[k] = np.mean((r - r.mean()) ** 2)
+    mean_square *= n / (n - 1)
+
+    return {'rms_nm': float(np.sqrt(np.mean(mean_square))),
+            'per_groove_nm': np.sqrt(mean_square),
+            'shift_px': shifts / dx}
+
+
 def normalize_profile(x_avg, y_avg, period_nm, apply_smoothing=True,
                       smoothing_window=5):
     """

{gratinglab-0.2.4 → gratinglab-0.2.6}/src/gratinglab/metrology/boundary/pipeline.py

@@ -25,8 +25,8 @@ from ..core.region_mask import (GROOVE_REACH_PERIODS, bridge_nan,
                                 describe_mask, groove_spacings_px, has_mask,
                                 reject_grooves_near_nan,
                                 tip_correct_around_nan)
-from .average import (average_grooves, flatten_endpoints, normalize_profile,
-                      profile_metrics)
+from .average import (average_grooves, flatten_endpoints, groove_residuals,
+                      normalize_profile, profile_metrics, select_grooves)
 
 __all__ = ["BoundaryProfile", "build_boundary_profile"]
 
@@ -66,6 +66,16 @@ class BoundaryProfile:
                 f"period {self.period_nm:.2f} nm, "
                 f"depth {self.metrics['groove_depth']:.4f} of period")
 
+    @property
+    def groove_residual_rms_nm(self):
+        """RMS residual of the grooves about their average, in nm.
+
+        None when fewer than two grooves were averaged. What it measures, and
+        why `to_problem` does not use it unless asked to, is in that method's
+        docstring and in docs/theory/metrology.md section 4.
+        """
+        return self.metrics.get('groove_residual_rms_nm')
+
     def to_problem(self, *, coating=None, substrate=None, roughness=0.0,
                    blaze_angle=None):
         """This measured groove as an efficiency problem.
@@ -87,9 +97,11 @@ class BoundaryProfile:
         Parameters:
             coating, substrate: material names, resolved by
                 `gratinglab.materials` at solve time.
-            roughness: RMS surface roughness in nm. As the note below
-                explains, this class does not measure it, and 0.0 means "not
-                supplied", not "smooth".
+            roughness: RMS surface roughness in nm, the Nevot-Croce sigma.
+                0.0 means "not supplied", not "smooth". It stays 0.0 unless
+                the caller passes a number, including the groove residual
+                this class measures; the note below says why that is not
+                the default.
             blaze_angle: fitted facet angle in degrees, if the same scan was
                 also run through `core.analysis.extract_blaze_angle`. Without
                 it the scalar solver evaluates reflection on the mean surface,
@@ -98,13 +110,39 @@ class BoundaryProfile:
 
         A note on roughness: `Problem.roughness` means high-spatial-frequency
         surface roughness, the quantity with which Nevot-Croce damps a Fresnel
-        coefficient. This class computes no such number. `y_std_nm` is the
-        groove-to-groove form spread and `metrics['rms_slope']` is a slope
-        statistic; neither is surface microroughness, and passing either one
-        in here would produce an efficiency that appears valid but is wrong,
-        where an omitted value would at least be visibly missing. The
-        appropriate quantity, the RMS residual of each groove about this
-        average, is not computed yet.
+        coefficient. `y_std_nm` is the groove-to-groove form spread and
+        `metrics['rms_slope']` is a slope statistic, and neither is that.
+
+        `groove_residual_rms_nm` is the nearest thing this class measures: the
+        RMS of each groove about the average once registered to it, which is
+        the part of the profile that does not repeat with the period. It is
+        still not passed by default, for four reasons, each of which makes it
+        a different number from the sigma Nevot-Croce wants:
+
+        - It is measured on the row-averaged profile. Structure that varies
+          along a groove averages away over the scan lines, and for isotropic
+          roughness with a correlation length well under the scan height that
+          is nearly all of it. The number keeps only what is coherent along
+          the groove for the height of the scan, so it is a lower bound on the
+          surface's roughness in its band.
+        - Its band is not the sigma's band. It sees nothing finer than the
+          pixel pitch or the tip, a few nanometres, while the structure that
+          damps a soft X-ray reflection extends down to wavelengths near the
+          X-ray wavelength itself. At the other end it includes groove-scale
+          form error, whose correlation length is about a period, where
+          Nevot-Croce assumes a short one.
+        - Groove-to-groove form error removes light from the orders by
+          scattering it between them, a Debye-Waller factor on each order's
+          own momentum transfer, not a damping of the Fresnel coefficient at
+          the facet. Folding it into the facet reflectivity applies the wrong
+          factor to the right effect.
+        - It carries instrument terms: AFM noise divided by the square root of
+          the number of scan lines, and a floor where the surface has corners
+          sharper than a pixel (0.21 nm on the synthetic sawtooth).
+
+        A caller who accepts those can pass it, and the name then appears in
+        their own code, which is the point:
+        `profile.to_problem(roughness=profile.groove_residual_rms_nm)`.
         """
         # Imported here rather than at module scope: `boundary` is reachable
         # from the GUI preview, which has no reason to pull the solver stack in
@@ -217,6 +255,16 @@ def build_boundary_profile(data, scan_x_size, settings, orientation=None) -> Bou
         smoothing_window=settings.ggp_smoothing_window)
 
     metrics = profile_metrics(x_norm, y_norm, period_nm, n_used)
+    # The same grooves average_grooves used, chosen by the same rules.
+    residual = groove_residuals(
+        select_grooves(raw_x, flat_y, groove_centers, period_nm, margin=0.0,
+                       min_half_width=settings.ggp_min_half_width),
+        x_avg, y_avg)
+    metrics['groove_residual_rms_nm'] = residual['rms_nm']
+    metrics['groove_residual_per_groove_nm'] = residual['per_groove_nm'].tolist()
+    metrics['groove_residual_max_shift_px'] = (
+        float(np.max(np.abs(residual['shift_px'])))
+        if residual['rms_nm'] is not None else None)
     if orientation is not None:
         metrics.update(orientation.as_metrics())
     metrics['tip_correction'] = settings.tip_correction

{gratinglab-0.2.4 → gratinglab-0.2.6}/src/gratinglab/metrology/gui/qt/boundary_view.py

@@ -275,6 +275,11 @@ class BoundaryView(QWidget):
                             f"+/- {m['groove_rotation_stderr_deg']:.3f} deg"
                             + (", corrected" if m.get('groove_rotation_corrected')
                                else ", not corrected"))
+        rms = m.get('groove_residual_rms_nm')
+        # Labelled as a residual, not a roughness: it is not what to_problem
+        # applies, and the panel should not suggest otherwise.
+        residual = ("not measured, one groove" if rms is None
+                    else f"{rms:.3f} nm, not applied")
         self.metrics_label.setText(
             f"Period          : {p.period_nm:.2f} nm\n"
             f"Grooves averaged: {p.n_used} of {p.n_grooves}{edge}\n"
@@ -282,7 +287,8 @@ class BoundaryView(QWidget):
             f"Peak-to-valley  : {m['peak_to_valley']:.4f} of period\n"
             f"RMS slope       : {m['rms_slope']:.4f}\n"
             f"Max sidewall    : {m['max_angle_deg']:.2f} deg\n"
-            f"Max curvature   : {m['max_curvature']:.4f}{rotation}{tip}")
+            f"Max curvature   : {m['max_curvature']:.4f}\n"
+            f"Groove residual : {residual}{rotation}{tip}")
 
     def _show_placeholder(self, message="Load an AFM file in the Import tab"):
         self._placeholder = message

gratinglab-0.2.6/src/gratinglab/metrology/gui/qt/layout.py

@@ -0,0 +1,95 @@
+"""
+The controls-and-plot layout every AFM tab shares.
+
+Each tab was a fixed 272 px column of controls in a 292 px scroll area beside
+its plot, so long labels were crammed and nothing could be widened. A splitter
+replaces that: the column starts wide enough for its contents, cannot be
+dragged narrower than its widest control needs, and gives the plot every pixel
+the window gains.
+
+The width is one setting, not one per tab. Dragging the column in any tab
+moves it in the others, so switching tabs never makes the plot jump, and the
+width is saved as it is dragged, so the window opens at it next time. It is
+kept in the same store as the theme (``theming.settings``), which the test
+suite redirects to a scratch file.
+"""
+from __future__ import annotations
+
+import weakref
+
+from . import *  # noqa: F401,F403 - sets QT_API before matplotlib's shim loads
+
+from PySide6.QtCore import Qt
+from PySide6.QtWidgets import QFrame, QScrollArea, QSplitter, QWidget
+
+from gratinglab.gui.qt.theming import settings
+
+__all__ = ["controls_beside", "MIN_CONTROLS_WIDTH", "START_CONTROLS_WIDTH",
+           "WIDTH_KEY"]
+
+#: Narrower than this and the group boxes' labels start to wrap mid-word.
+MIN_CONTROLS_WIDTH = 260
+#: Where the column starts, unless its contents ask for more.
+START_CONTROLS_WIDTH = 320
+#: Where the chosen width is remembered.
+WIDTH_KEY = "afm/controls_width"
+
+# Every live splitter, so a drag in one tab can move the others. Weak, so a
+# closed window's splitters drop out on their own.
+_SPLITTERS: "weakref.WeakSet[QSplitter]" = weakref.WeakSet()
+
+
+def _saved_width() -> int | None:
+    value = settings().value(WIDTH_KEY)
+    try:
+        return int(value) if value is not None else None
+    except (TypeError, ValueError):
+        return None     # a hand-edited or corrupt value: fall back to the default
+
+
+def _follow(source: QSplitter) -> None:
+    """Remember ``source``'s column width and give it to every other tab."""
+    width = source.sizes()[0]
+    store = settings()
+    store.setValue(WIDTH_KEY, width)
+    store.sync()
+    for other in list(_SPLITTERS):
+        if other is source:
+            continue
+        try:
+            total = sum(other.sizes())
+            other.blockSignals(True)
+            other.setSizes([width, max(1, total - width)])
+            other.blockSignals(False)
+        except RuntimeError:
+            # Its window was closed and Qt has deleted it, while the Python
+            # wrapper waits for collection.
+            _SPLITTERS.discard(other)
+
+
+def controls_beside(controls: QWidget, plot: QWidget) -> QSplitter:
+    """A splitter holding the scrolling ``controls`` column and the ``plot``."""
+    scroll = QScrollArea()
+    scroll.setWidget(controls)
+    scroll.setWidgetResizable(True)
+    scroll.setFrameShape(QFrame.NoFrame)
+    # Width is the splitter's to decide; only the height should ever scroll.
+    scroll.setHorizontalScrollBarPolicy(Qt.ScrollBarAlwaysOff)
+
+    gutter = scroll.verticalScrollBar().sizeHint().width()
+    floor = max(MIN_CONTROLS_WIDTH, controls.minimumSizeHint().width() + gutter)
+    scroll.setMinimumWidth(floor)
+
+    splitter = QSplitter(Qt.Horizontal)
+    splitter.setChildrenCollapsible(False)
+    splitter.addWidget(scroll)
+    splitter.addWidget(plot)
+    splitter.setStretchFactor(0, 0)
+    splitter.setStretchFactor(1, 1)
+    # A remembered width wins, but never below what this tab's controls need.
+    start = max(_saved_width() or START_CONTROLS_WIDTH, floor)
+    splitter.setSizes([start, max(1, 4 * start)])
+
+    _SPLITTERS.add(splitter)
+    splitter.splitterMoved.connect(lambda *_: _follow(splitter))
+    return splitter

{gratinglab-0.2.4 → gratinglab-0.2.6}/src/gratinglab/metrology/io/metrics.py

@@ -25,6 +25,16 @@ def write_profile_metrics(path, metrics):
         f.write(f"RMS slope: {metrics['rms_slope']:.4f} (normalized units)\n")
         f.write(f"Max slope magnitude: {metrics['max_slope']:.4f}\n")
         f.write(f"Max curvature: {metrics['max_curvature']:.6f} (normalized units)\n")
+        # Written only by a pipeline that measures it, so a metrics dict from
+        # before it existed still writes. Not applied as roughness: see
+        # BoundaryProfile.to_problem.
+        if 'groove_residual_rms_nm' in metrics:
+            rms = metrics['groove_residual_rms_nm']
+            if rms is None:
+                f.write("Groove residual RMS: not measured (one groove)\n")
+            else:
+                f.write(f"Groove residual RMS: {rms:.3f} nm (about the average, "
+                        f"not applied as roughness)\n")
         # Present only when the pipeline ran a tip correction. Stated even so:
         # a corrected depth and an uncorrected one are different measurements,
         # and this sidecar is where a reader learns which this file holds.

{gratinglab-0.2.4 → gratinglab-0.2.6/src/gratinglab.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gratinglab
-Version: 0.2.4
+Version: 0.2.6
 Summary: Open platform for diffraction grating groove metrology and efficiency analysis
 Author: Jake McCoy, Aditi Gangadharan
 License: BSD-3-Clause

{gratinglab-0.2.4 → gratinglab-0.2.6}/src/gratinglab.egg-info/SOURCES.txt

@@ -145,6 +145,7 @@ tests/test_conditioning.py
 tests/test_convergence.py
 tests/test_cross_method.py
 tests/test_efficiency_table.py
+tests/test_four_way.py
 tests/test_fresnel.py
 tests/test_geometry.py
 tests/test_ggp.py