gratinglab 0.3.1__tar.gz → 0.3.2__tar.gz

{gratinglab-0.3.1/src/gratinglab.egg-info → gratinglab-0.3.2}/PKG-INFO

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

{gratinglab-0.3.1 → gratinglab-0.3.2}/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.1"
+__version__ = "0.3.2"
 
 __all__ = [
     "Illumination",

{gratinglab-0.3.1 → gratinglab-0.3.2}/src/gratinglab/metrology/core/processing.py

@@ -303,21 +303,42 @@ def raw_data_multi_group(data, scan_x_size, n_groups=10):
         n_groups = max(1, n_rows // 3)
         rows_per_group = n_rows // n_groups
     
+    # `n_rows` rarely divides by `n_groups`, and where the leftover lines go
+    # decides whether the bands survive reading the scan the other way up.
+    # Giving them all to the last band -- what this did until 0.3.2 -- moves
+    # every boundary by `leftover` when the rows are reversed, so one scan read
+    # by two routes is cut into two different sets of bands. Harmless while the
+    # image is untouched (0.002 deg of blaze angle), but `align_grooves` shears
+    # each row by an amount that depends on its distance from the centre, and
+    # on a sheared image the same reshuffle cost 0.067 deg between the raw
+    # .spm and the Gwyddion .txt export of one grating.
+    #
+    # So the leftover comes off the centre line and the two ends instead, which
+    # leaves the set of bands unchanged under a reversal. Exactly unchanged
+    # when `n_rows` is odd, since only then does the centre line map to itself;
+    # with an even line count and an odd leftover, one line is still unbanded
+    # from the near side, and that much asymmetry cannot be removed.
+    #
+    # With an even band count the dropped centre line falls on a boundary. With
+    # an odd one the middle band spans it, so that band's `group_ranges` entry
+    # is a line wider than the band -- the same way a masked gap already widens
+    # one -- and a caller slicing by that range reads the extra line.
+    banded = rows_per_group * n_groups
+    leftover = n_rows - banded
+    centre_line = leftover % 2
+    per_end = (leftover - centre_line) // 2
+    rows = np.arange(per_end, n_rows - per_end)
+    if centre_line:
+        rows = rows[rows != (n_rows - 1) // 2]
+
     profiles_nm = []
     group_ranges = []
-    
+
     for i in range(n_groups):
-        # Calculate row range for this group
-        start_row = i * rows_per_group
-        
-        # For the last group, include any remaining rows
-        if i == n_groups - 1:
-            end_row = n_rows
-        else:
-            end_row = (i + 1) * rows_per_group
-        
+        band = rows[i * rows_per_group:(i + 1) * rows_per_group]
+
         # Extract and average rows in this group
-        group_data = data[start_row:end_row, :]
+        group_data = data[band, :]
         profile_avg = nan_mean_rows(group_data)
         
         # Convert to nm and subtract minimum
@@ -325,7 +346,7 @@ def raw_data_multi_group(data, scan_x_size, n_groups=10):
         
         profiles_nm.append(profile_nm)
         # In the image's own line numbers, so a masked gap shows as a wider band
-        group_ranges.append((int(kept_rows[start_row]), int(kept_rows[end_row - 1]) + 1))
+        group_ranges.append((int(kept_rows[band[0]]), int(kept_rows[band[-1]]) + 1))
     
     # Package metadata
     group_info = {
@@ -334,11 +355,17 @@ def raw_data_multi_group(data, scan_x_size, n_groups=10):
         'rows_per_group': rows_per_group,
         'group_ranges': group_ranges,
         'rows_excluded': rows_excluded,
+        # Lines inside the image that no band could take, left out at the
+        # centre and the ends to keep the stack symmetric. Distinct from
+        # `rows_excluded`, which counts lines masked or dropped as scars.
+        'rows_unbanded': int(leftover),
     }
     
     print(f"  Extracted {n_groups} row-group profiles")
     print(f"    Rows per group: {rows_per_group}")
     print(f"    Total rows used: {n_groups * rows_per_group} of {n_rows}")
+    if leftover:
+        print(f"    Lines outside the bands (centre and ends): {leftover}")
     if rows_excluded:
         print(f"    Lines excluded (masked or dropped): {rows_excluded} of {all_rows}")
     

{gratinglab-0.3.1 → gratinglab-0.3.2}/src/gratinglab/metrology/io/spm.py

@@ -8,9 +8,9 @@ header section says where its bytes are and how to turn them into nanometres.
 
 The reader was written here instead of taken from a library because the format
 is small, this project depends on nothing beyond numpy/scipy/matplotlib, and
-the conversion has one pitfall (described below) that is best handled here.
+the conversion has two pitfalls (described below) that are best handled here.
 
-The pitfall is as follows. The height scale comes from a line like::
+The first is the height scale, which comes from a line like::
 
     \\@2:Z scale: V [Sens. ZsensSens] (0.0000000001872337 V/LSB) 0.804163 V
 
@@ -25,6 +25,20 @@ The result shows no visible sign of the error: the image is the right shape,
 the grooves are in the right places, and every blaze angle is silently
 incorrect. The reader was verified against a known export: with the right
 parameter, the peak-to-peak height matches to 1.0000.
+
+The second is the direction of the slow axis. The rows are returned reversed
+against the order the plane stores them, because that is what Gwyddion does
+and this project's measurements all came through Gwyddion exports. Gwyddion
+reverses every Nanoscope import unconditionally -- ``modules/file/nanoscope.c``
+calls ``gwy_data_field_invert(dfield, TRUE, FALSE, FALSE)`` straight after
+scaling the plane, and that first argument is ``yflipped``, documented as "the
+image will be flipped upside down". It does not consult ``\\Frame direction``,
+which reads ``Down`` on the files here.
+
+This showed up as a sign: the same grating measured -0.3722 deg of groove
+rotation read as a .spm and +0.3721 deg read as the Gwyddion .txt export of
+that scan. A flip does not move the blaze angle, so it went unnoticed until
+``groove_orientation`` began correcting for the rotation it reported.
 """
 from __future__ import annotations
 
@@ -299,7 +313,12 @@ def read_spm(path, channel: str = DEFAULT_CHANNEL,
         heights_nm = plane.reshape(described.rows, described.cols).astype(float) \
             * volts_per_lsb * nm_per_volt
 
-        return heights_nm * 1e-9, described.scan_x_size_um
+        # Reversed: see the module docstring. Gwyddion's importer flips every
+        # Nanoscope plane upside down, so its text export of a scan is
+        # row-reversed against the plane as stored, and this reader exists to
+        # agree with those exports -- the same reason DEFAULT_DIRECTION is
+        # Retrace.
+        return heights_nm[::-1] * 1e-9, described.scan_x_size_um
 
     available = list_channels(path)
     raise ValueError(

{gratinglab-0.3.1 → gratinglab-0.3.2}/src/gratinglab/metrology/wiki/facet-fitting.md

@@ -61,11 +61,11 @@ On the master sample:
 
 | FACET_TRIM | Mean blaze angle |
 |---|---|
-| 0.05 | 32.94° |
-| 0.10 | 33.23° |
-| 0.15 | 32.84° |
-| 0.20 | 31.58° |
-| 0.25 | 29.99° |
+| 0.05 | 32.89° |
+| 0.10 | 33.13° |
+| 0.15 | 32.71° |
+| 0.20 | 31.49° |
+| 0.25 | 29.94° |
 
 This is a 3.2° change across a plausible range of a single parameter, larger
 than most of the between-sample differences that this software is used to

{gratinglab-0.3.1 → gratinglab-0.3.2}/src/gratinglab/metrology/wiki/file-formats.md

@@ -2,7 +2,8 @@
 
 Three input formats are supported: the Bruker/Veeco Nanoscope `.spm` file,
 the Asylum Research `.ibw` file, and a text export from Gwyddion. On the same
-scan the `.spm` and text routes agree to within 0.002°. The `.ibw` route has
+scan the `.spm` and text routes agree to within 0.005°, and to 0.000009°
+with groove-orientation correction off. The `.ibw` route has
 not yet been checked against a file from an instrument; see its section.
 
 ## Text exports
@@ -68,11 +69,34 @@ signal and does not represent topography; passing it through a blaze-angle
 pipeline produces a plausible-looking number with no physical meaning.
 
 Retrace is the default because it is the plane from which this project's
-existing Gwyddion exports were taken: it correlates 0.98 with the export, while
-Trace correlates 0.90. With this default the two input routes agree by
+existing Gwyddion exports were taken: it correlates 1.000000 with the export,
+while Trace correlates 0.92. With this default the two input routes agree by
 construction. Both directions image the same grooves and either is a legitimate
 choice, and the GUI offers a selector when a `.spm` is loaded.
 
+### Which way up
+
+The rows are returned reversed against the order the plane stores them.
+
+Gwyddion reverses the rows of every Nanoscope import, unconditionally:
+`modules/file/nanoscope.c` calls `gwy_data_field_invert(dfield, TRUE, FALSE,
+FALSE)` immediately after scaling the plane, and the first argument of that
+function is `yflipped`, documented as "the image will be flipped upside down".
+It does not consult `\Frame direction`, which reads `Down` on the files here.
+So a Gwyddion export is upside down against the plane as stored, and since
+every measurement this project has made came through such an export, the
+reader follows Gwyddion rather than the file.
+
+Reading the plane as stored, which is what this did until 0.3.2, left the two
+routes mirror images of each other. A flip does not move the blaze angle, so
+nothing showed until `groove_orientation` began measuring the groove rotation:
+the same grating then read -0.3722° as a `.spm` and +0.3721° as the Gwyddion
+export of that scan. Both routes now report +0.372°.
+
+With the rows the right way up, the plane and the export agree to 0.00027 nm
+rms on a scan 115 nm deep, which is the five significant digits the text export
+writes and nothing else.
+
 ### The height scale, and how to misread it
 
 Raw samples are integers. They are converted to nanometres using a line such
@@ -137,24 +161,36 @@ reader's was.
 
 ## The two routes compared
 
-The same scan was processed by both routes:
+The same scan was processed by both routes, at the current defaults:
 
 | Route | N | Mean blaze angle | σ | Period |
 |---|---|---|---|---|
-| Gwyddion `.txt` | 100 | 27.913° | 2.127° | 314.33 nm |
-| Raw `.spm` | 100 | 27.911° | 2.126° | 314.33 nm |
-
-The means differ by 0.002°, against a standard deviation of 2.13°.
-
-The results are not bit-identical, and they are not expected to be: the export
-was flattened by Gwyddion while the `.spm` is raw, and the two differ by 7 nm
-RMS. This software, however, flattens every row-group profile itself before
-fitting, which removes the same background. The Gwyddion flattening step is
-therefore redundant for this pipeline.
+| Gwyddion `.txt` | 100 | 27.888° | 2.053° | 313.89 nm |
+| Raw `.spm` | 100 | 27.883° | 2.049° | 313.89 nm |
+
+The means differ by 0.005°, against a standard deviation of 2.05°. With
+`groove_orientation` off both routes read 27.915°, σ 2.165°, 314.33 nm — the
+same to every digit printed, and 0.000009° apart in full. The 0.005° with the
+correction on is not a disagreement about the heights: it is the slow-axis
+size, which the `.spm` header gives as 1.56640625 µm while Gwyddion's
+`# Height:` line rounds it to 1.566, so the two shear in slightly different
+pixels.
+
+The underlying arrays agree to 0.00027 nm RMS on a scan 115 nm deep, which is
+the five significant digits the text export writes and nothing else: no per-row
+offset (0.00001 nm), no plane, and no scale difference. The export is the plane.
+
+That is not what this page said until 0.3.2. It reported a 7 nm RMS difference
+and explained it as Gwyddion's flattening, which the pipeline's own row-group
+flattening then removed. Both the figure and the explanation were artefacts of
+reading the plane upside down (see "Which way up"): comparing a grating with
+its own mirror image is what produced the 7 nm. Together with the finding
+below, the `_flatten` in that filename appears to describe nothing that was
+ever done to the data.
 
 A further finding was made during this verification: the `_flatten.0_00003`
 companion file beside the raw scan is byte-identical to it. Gwyddion never wrote
-modified data, and the flattening existed only in the text export.
+modified data, and on the evidence above the text export carries none either.
 
 ## Practical notes
 

{gratinglab-0.3.1 → gratinglab-0.3.2}/src/gratinglab/metrology/wiki/row-groups.md

@@ -22,6 +22,25 @@ straightforwardly add information.
 Each band is flattened independently, because the background tilt is not
 necessarily uniform across the image.
 
+## Where the leftover lines go
+
+A line count rarely divides by the number of bands. The lines left over are
+left out, from the centre line and from the two ends, so that the bands sit
+symmetrically about the middle of the image. The count is reported as
+`rows_unbanded`, separately from the lines dropped as scars or masked away.
+
+The placement matters because the same scan can arrive either way up: a
+Nanoscope `.spm` and the Gwyddion text export of that scan disagree about
+which end of the slow axis is stored first. Until 0.3.2 the leftover lines
+were given to the last band, which made every boundary move when the rows were
+reversed. On an image that `groove_orientation` has sheared, each line is
+shifted by an amount that depends on its distance from the centre, so the
+reshuffle changed what each band averaged: on one 401-line scan it moved the
+mean blaze angle by 0.067°, where the two readings of that scan now agree to
+0.005° with the correction on and 0.000009° with it off. Centred bands are the
+same set of bands read either way, so the measurement no longer depends on the
+direction of the slow axis.
+
 ## Why grooves at a scan edge are rejected
 
 `EDGE_EXCLUSION_PERIODS` (0.6 by default) discards any groove detected within

{gratinglab-0.3.1 → gratinglab-0.3.2/src/gratinglab.egg-info}/PKG-INFO

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