gratinglab 0.2.8__tar.gz → 0.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gratinglab
-Version: 0.2.8
+Version: 0.3.1
 Summary: Open platform for diffraction grating groove metrology and efficiency analysis
 Author: Jake McCoy, Aditi Gangadharan
 License: BSD-3-Clause
@@ -59,9 +59,12 @@ efficiency of a grating from such a profile.
 The AFM metrology is the part of the package in regular use. It measures blaze angles
 from a scan, averages the grooves into a single profile, reports how much that profile
 varies down the scan, corrects for the shape of the AFM tip where the data allow it,
-and exports the averaged groove as a boundary profile. The efficiency solvers are
-**experimental**: they pass their test suite but have not yet been used for real
-analysis, and their results should be treated as provisional.
+and exports the averaged groove as a boundary profile. The three rigorous
+efficiency solvers left experimental status in 0.3, after agreeing with one
+another and with a measured campaign whose groove was measured too (the TASTE
+comparison in `docs/findings.md`). Their known limits are stated in the table
+under Status, and a number from any of them is still evidence to check rather
+than a result to rely on.
 
 Rigorous methods for computing grating efficiency are well established, and open codes
 exist for several of them, although each carries its own conventions and
@@ -108,12 +111,24 @@ The project is at a pre-alpha stage. The AFM metrology is the more mature of its
 parts. On the efficiency side, the scalar and integral solvers, the comparison and
 convergence harnesses and the materials layer work end to end. They are checked
 against closed-form results, published benchmark tables, energy balance and
-reciprocity, but remain experimental until they have been used on real problems.
-Efficiencies are absolute when a coating is named, using an optical constant table
-supplied by the user (see Install). Since 0.2.0 two more rigorous backends sit
-beside them, both written in-house and both experimental: a rigorous coupled-wave
-analysis (RCWA), which also models coated gratings through conformal layers, and
-the C-method (Chandezon). Each has a tab in the efficiency window since 0.2.1.
+reciprocity. Efficiencies are absolute when a coating is named, using an optical
+constant table supplied by the user (see Install). Since 0.2.0 two more rigorous
+backends sit beside them, both written in-house: a rigorous coupled-wave analysis
+(RCWA), which also models coated gratings through conformal layers, and the
+C-method (Chandezon). Each has a tab in the efficiency window since 0.2.1.
+
+**Since 0.3 the three rigorous solvers are no longer experimental.** The
+criterion was use on a real problem: on the December 2018 TASTE campaign, 296
+measured efficiencies against the grating's own AFM groove, the integral method,
+the C-method and RCWA agree with one another to 2e-4 RMS and with the
+measurement to 0.038, so the residual is measured not to be the solver. The two
+defects that comparison found are dealt with. The C-method refuses a wall too
+steep for its truncation. The integral solver's absorption on a measured polygon
+under `conductivity="tabulated"` is fixed by `profile_smoothing="auto"`, which is
+opt-in because it moves finely sampled profiles at long wavelengths; with the
+default the polygon is solved as given, and the energy-balance warning names the
+option when it fires. A tightly rounded valley remains a recorded limitation.
+The scalar solver is an approximation and is described as one.
 
 **Every modelling method here still needs verification**, the rigorous ones
 included. The checks in the table below show that each method reproduces the
@@ -163,10 +178,10 @@ The method backends, in order of development:
 
 | Method | Status |
 |---|---|
-| Scalar (Kirchhoff, x-ray blaze form) | experimental; checked against closed-form results |
-| Integral method (boundary integral, conical, undercut-capable) | experimental; perfect and finite conductivity (`conductivity="tabulated"`, Goray & Schmidt 2010), absolute efficiencies with the absorbed fraction recorded; a corner-graded mesh for profiles with corners (`corner_grading=4`, the default since 0.2.7; `0` is the equal-arc mesh), under either boundary condition; checked against published benchmark tables (Maystre & Popov; Goray & Schmidt), energy balance and reciprocity |
-| RCWA (in-plane, conical, off-plane; Li factorization, S-matrix, layer stacks) | experimental, since 0.2.0; lamellar gratings exact and other profiles staircased, transmitted orders, and coatings through conformal layers (`Problem.layers`); checked against Fresnel, the Airy film formula, reciprocity, the integral solver, and published lamellar values (Granet; Lalanne & Hugonin; Gralak; Goray & Schmidt's conical tables). Not yet checked: staircase accuracy in metallic TM, and layers of a second material against an independent code |
-| C-method (Chandezon) | experimental, since 0.2.0; perfect conductor in any mount, and one interface into an absorbing or lossless material, conical and coupled; checked against Goray & Schmidt's Table 3, Fresnel and the integral solver. Refuses vertical facets and undercuts; converges slowly on sawtooth corners, and loses precision at high truncation on profiles deeper than about half the period, both reported in provenance. No coatings |
+| Scalar (Kirchhoff, x-ray blaze form) | an approximation; checked against closed-form results |
+| Integral method (boundary integral, conical, undercut-capable) | since 0.3 not experimental; perfect and finite conductivity (`conductivity="tabulated"`, Goray & Schmidt 2010), absolute efficiencies with the absorbed fraction recorded; a corner-graded mesh for profiles with corners (`corner_grading=4`, the default since 0.2.7; `0` is the equal-arc mesh), under either boundary condition; checked against published benchmark tables (Maystre & Popov; Goray & Schmidt), energy balance and reciprocity |
+| RCWA (in-plane, conical, off-plane; Li factorization, S-matrix, layer stacks) | since 0.2.0, not experimental since 0.3; lamellar gratings exact and other profiles staircased, transmitted orders, and coatings through conformal layers (`Problem.layers`); checked against Fresnel, the Airy film formula, reciprocity, the integral solver, and published lamellar values (Granet; Lalanne & Hugonin; Gralak; Goray & Schmidt's conical tables). Not yet checked: staircase accuracy in metallic TM, and layers of a second material against an independent code |
+| C-method (Chandezon) | since 0.2.0, not experimental since 0.3; perfect conductor in any mount, and one interface into an absorbing or lossless material, conical and coupled; checked against Goray & Schmidt's Table 3, Fresnel and the integral solver. Refuses vertical facets, undercuts, and walls too steep for the scan (the harmonics a wall needs grow with its slope times P sin γ / λ; measured against the integral solver, see the method note); converges slowly on sawtooth corners, and loses precision at high truncation on profiles deeper than about half the period, both reported in provenance. No coatings |
 
 The comparison harness also accepts an efficiency table already computed by an
 external program as one of its methods, so that comparison plots can be made without
@@ -458,9 +473,10 @@ derived product without prior written permission.
 
 **What you do not get.** The software is provided as is, without warranty of any kind,
 and the author is not liable for any use of it. That disclaimer carries more weight
-here than it does for most packages, because the efficiency solvers are experimental
-(see Status): a number this software produces is evidence to be checked against
-another method, not a result to be relied on because a computer printed it.
+here than it does for most packages, because the efficiency solvers are young and
+validated on few gratings (see Status): a number this software produces is evidence
+to be checked against another method, not a result to be relied on because a
+computer printed it.
 
 Contributions are accepted under the same licence. A pull request is taken as agreement
 that the contribution may be distributed under BSD-3-Clause.

{gratinglab-0.2.8 → gratinglab-0.3.1}/README.md

@@ -14,9 +14,12 @@ efficiency of a grating from such a profile.
 The AFM metrology is the part of the package in regular use. It measures blaze angles
 from a scan, averages the grooves into a single profile, reports how much that profile
 varies down the scan, corrects for the shape of the AFM tip where the data allow it,
-and exports the averaged groove as a boundary profile. The efficiency solvers are
-**experimental**: they pass their test suite but have not yet been used for real
-analysis, and their results should be treated as provisional.
+and exports the averaged groove as a boundary profile. The three rigorous
+efficiency solvers left experimental status in 0.3, after agreeing with one
+another and with a measured campaign whose groove was measured too (the TASTE
+comparison in `docs/findings.md`). Their known limits are stated in the table
+under Status, and a number from any of them is still evidence to check rather
+than a result to rely on.
 
 Rigorous methods for computing grating efficiency are well established, and open codes
 exist for several of them, although each carries its own conventions and
@@ -63,12 +66,24 @@ The project is at a pre-alpha stage. The AFM metrology is the more mature of its
 parts. On the efficiency side, the scalar and integral solvers, the comparison and
 convergence harnesses and the materials layer work end to end. They are checked
 against closed-form results, published benchmark tables, energy balance and
-reciprocity, but remain experimental until they have been used on real problems.
-Efficiencies are absolute when a coating is named, using an optical constant table
-supplied by the user (see Install). Since 0.2.0 two more rigorous backends sit
-beside them, both written in-house and both experimental: a rigorous coupled-wave
-analysis (RCWA), which also models coated gratings through conformal layers, and
-the C-method (Chandezon). Each has a tab in the efficiency window since 0.2.1.
+reciprocity. Efficiencies are absolute when a coating is named, using an optical
+constant table supplied by the user (see Install). Since 0.2.0 two more rigorous
+backends sit beside them, both written in-house: a rigorous coupled-wave analysis
+(RCWA), which also models coated gratings through conformal layers, and the
+C-method (Chandezon). Each has a tab in the efficiency window since 0.2.1.
+
+**Since 0.3 the three rigorous solvers are no longer experimental.** The
+criterion was use on a real problem: on the December 2018 TASTE campaign, 296
+measured efficiencies against the grating's own AFM groove, the integral method,
+the C-method and RCWA agree with one another to 2e-4 RMS and with the
+measurement to 0.038, so the residual is measured not to be the solver. The two
+defects that comparison found are dealt with. The C-method refuses a wall too
+steep for its truncation. The integral solver's absorption on a measured polygon
+under `conductivity="tabulated"` is fixed by `profile_smoothing="auto"`, which is
+opt-in because it moves finely sampled profiles at long wavelengths; with the
+default the polygon is solved as given, and the energy-balance warning names the
+option when it fires. A tightly rounded valley remains a recorded limitation.
+The scalar solver is an approximation and is described as one.
 
 **Every modelling method here still needs verification**, the rigorous ones
 included. The checks in the table below show that each method reproduces the
@@ -118,10 +133,10 @@ The method backends, in order of development:
 
 | Method | Status |
 |---|---|
-| Scalar (Kirchhoff, x-ray blaze form) | experimental; checked against closed-form results |
-| Integral method (boundary integral, conical, undercut-capable) | experimental; perfect and finite conductivity (`conductivity="tabulated"`, Goray & Schmidt 2010), absolute efficiencies with the absorbed fraction recorded; a corner-graded mesh for profiles with corners (`corner_grading=4`, the default since 0.2.7; `0` is the equal-arc mesh), under either boundary condition; checked against published benchmark tables (Maystre & Popov; Goray & Schmidt), energy balance and reciprocity |
-| RCWA (in-plane, conical, off-plane; Li factorization, S-matrix, layer stacks) | experimental, since 0.2.0; lamellar gratings exact and other profiles staircased, transmitted orders, and coatings through conformal layers (`Problem.layers`); checked against Fresnel, the Airy film formula, reciprocity, the integral solver, and published lamellar values (Granet; Lalanne & Hugonin; Gralak; Goray & Schmidt's conical tables). Not yet checked: staircase accuracy in metallic TM, and layers of a second material against an independent code |
-| C-method (Chandezon) | experimental, since 0.2.0; perfect conductor in any mount, and one interface into an absorbing or lossless material, conical and coupled; checked against Goray & Schmidt's Table 3, Fresnel and the integral solver. Refuses vertical facets and undercuts; converges slowly on sawtooth corners, and loses precision at high truncation on profiles deeper than about half the period, both reported in provenance. No coatings |
+| Scalar (Kirchhoff, x-ray blaze form) | an approximation; checked against closed-form results |
+| Integral method (boundary integral, conical, undercut-capable) | since 0.3 not experimental; perfect and finite conductivity (`conductivity="tabulated"`, Goray & Schmidt 2010), absolute efficiencies with the absorbed fraction recorded; a corner-graded mesh for profiles with corners (`corner_grading=4`, the default since 0.2.7; `0` is the equal-arc mesh), under either boundary condition; checked against published benchmark tables (Maystre & Popov; Goray & Schmidt), energy balance and reciprocity |
+| RCWA (in-plane, conical, off-plane; Li factorization, S-matrix, layer stacks) | since 0.2.0, not experimental since 0.3; lamellar gratings exact and other profiles staircased, transmitted orders, and coatings through conformal layers (`Problem.layers`); checked against Fresnel, the Airy film formula, reciprocity, the integral solver, and published lamellar values (Granet; Lalanne & Hugonin; Gralak; Goray & Schmidt's conical tables). Not yet checked: staircase accuracy in metallic TM, and layers of a second material against an independent code |
+| C-method (Chandezon) | since 0.2.0, not experimental since 0.3; perfect conductor in any mount, and one interface into an absorbing or lossless material, conical and coupled; checked against Goray & Schmidt's Table 3, Fresnel and the integral solver. Refuses vertical facets, undercuts, and walls too steep for the scan (the harmonics a wall needs grow with its slope times P sin γ / λ; measured against the integral solver, see the method note); converges slowly on sawtooth corners, and loses precision at high truncation on profiles deeper than about half the period, both reported in provenance. No coatings |
 
 The comparison harness also accepts an efficiency table already computed by an
 external program as one of its methods, so that comparison plots can be made without
@@ -413,9 +428,10 @@ derived product without prior written permission.
 
 **What you do not get.** The software is provided as is, without warranty of any kind,
 and the author is not liable for any use of it. That disclaimer carries more weight
-here than it does for most packages, because the efficiency solvers are experimental
-(see Status): a number this software produces is evidence to be checked against
-another method, not a result to be relied on because a computer printed it.
+here than it does for most packages, because the efficiency solvers are young and
+validated on few gratings (see Status): a number this software produces is evidence
+to be checked against another method, not a result to be relied on because a
+computer printed it.
 
 Contributions are accepted under the same licence. A pull request is taken as agreement
 that the contribution may be distributed under BSD-3-Clause.

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

{gratinglab-0.2.8 → gratinglab-0.3.1}/src/gratinglab/gui/cmethod_options.py

@@ -14,9 +14,10 @@ harmonics either side of the centre of the propagating orders.
 
 The guards mirror the solver's refusals so an error lands on the field that
 caused it instead of arriving as a ValueError from the worker thread. The
-truncation floor is not re-derived here: it is
-:func:`gratinglab.solvers.cmethod.truncation_floor`, the function the solver
-itself applies, so the form and the solver cannot disagree about it.
+truncation floors are not re-derived here: they are
+:func:`gratinglab.solvers.cmethod.truncation_floor` (the orders) and
+:func:`~gratinglab.solvers.cmethod.wall_floor` (a steep wall), the functions
+the solver itself applies, so the form and the solver cannot disagree.
 """
 
 from __future__ import annotations
@@ -29,7 +30,8 @@ from numpy.typing import NDArray
 
 from ..illumination import Illumination
 from ..problem import Problem
-from ..solvers.cmethod import _MAX_TRUNCATION, truncation_floor
+from ..solvers.base import UnsupportedConfiguration
+from ..solvers.cmethod import _MAX_TRUNCATION, truncation_floor, wall_floor
 from .integral_options import _tabulated_index
 from .state import FieldError, FormErrors, _number
 
@@ -119,5 +121,15 @@ def build_options(
     floor = truncation_floor(problem, illumination, wavelengths, indices)
     if truncation < floor.needed:
         raise FormErrors((FieldError("truncation", floor.message),))
+    # A steep wall's floor goes on the field too, but only while a truncation
+    # the field accepts can meet it. Past the ceiling, or on a profile the
+    # method cannot describe at all, the solver refuses the geometry with
+    # UnsupportedConfiguration, and the tab names that refusal instead.
+    try:
+        wall = wall_floor(problem, illumination, wavelengths, indices)
+    except UnsupportedConfiguration:
+        wall = None
+    if wall is not None and truncation < wall.needed <= _MAX_TRUNCATION:
+        raise FormErrors((FieldError("truncation", wall.message),))
 
     return {"truncation": int(truncation), "conductivity": form.conductivity}

{gratinglab-0.2.8 → gratinglab-0.3.1}/src/gratinglab/gui/comparison.py

@@ -50,13 +50,13 @@ _STYLES = ("-", "--", "-.", ":")
 
 #: Closes every comparison the panel reports. Two solvers agreeing is evidence
 #: that neither has a bug the other lacks, not that either is right: they can
-#: share an assumption, a material table or a geometry convention. Every
-#: method here is experimental, so the panel says so where agreement is shown,
-#: dimmed because it is a fact about the methods, not a fault in this run.
+#: share an assumption, a material table or a geometry convention. So the
+#: panel says so where agreement is shown, dimmed because it is a fact about
+#: the methods, not a fault in this run.
 VERIFICATION_NOTE = (
-    "\nagreement between solvers is not verification: every method here is "
-    "experimental and needs checking against measurement or a published "
-    "benchmark\n"
+    "\nagreement between solvers is not verification: they share the problem, "
+    "the optical constants and the conventions, so check against measurement "
+    "or a published benchmark\n"
 )
 
 #: More legend entries than this and the order legend takes a second column,

{gratinglab-0.2.8 → gratinglab-0.3.1}/src/gratinglab/io/ggp.py

@@ -10,10 +10,8 @@ points through :meth:`~gratinglab.profiles.FromProfileData.along_dispersion`
 and its inverse. The PCGrate corpus is what fixes the file's direction: the
 TASTE run matches only with ``x`` along ``+d-hat``.
 
-Canonical form::
+Default form, points only::
 
-    3 0 - Polygonal type
-    Period: 1 PSC: 1
     0.000000 0.000000
     0.012346 0.000808
     ...
@@ -22,19 +20,26 @@ The shared convention allows a scalar calculation and a PCGrate run to be
 driven from identical geometry, which isolates the method difference from any
 difference in assumed groove shape.
 
-Three header variants exist on disk, and only the first is accepted by PCGrate:
+Four header variants exist on disk:
 
-===================================  ================  ==============
-Header                               PCGrate accepts   Seen in
-===================================  ================  ==============
-``3 0 - Polygonal type`` + ``Period`` yes              most files
-``# 3 0 - Polygonal type`` (hashed)   **no**           ``*_fix6/7.ggp``
-``# X(normalized...)`` only           **no**           ``*_fix{,2,3,4}.ggp``
-===================================  ================  ==============
+===================================  ==============================
+Header                               Seen in
+===================================  ==============================
+none, points only                    Aditi's files, and the default
+``3 0 - Polygonal type`` + ``Period`` most legacy files
+``# 3 0 - Polygonal type`` (hashed)   ``*_fix6/7.ggp``
+``# X(normalized...)`` only           ``*_fix{,2,3,4}.ggp``
+===================================  ==============================
 
-This module reads all three, since they are real files that need to be loaded,
-and writes only the canonical form. ``np.savetxt(header=...)`` is what produces
-the hashed variants, so it must not be used here.
+Which of these PCGrate takes was never tested here. Until 2026-10-29 this
+docstring said only the ``3 0 - Polygonal type`` form loads, but that was
+inferred from which legacy files sat beside PCGrate runs. Aditi, who loads
+these into PCGrate through its border-profile import, reports that it does not
+want a header and that she used to delete it by hand, so the writer leaves it
+out unless asked. ``write_ggp(header=True)`` still writes the two-line form.
+
+This module reads all four. ``np.savetxt(header=...)`` is what produces the
+hashed variants, so it must not be used here.
 
 This is now the only ``.ggp`` writer in the project. The metrology package
 previously shipped a second copy, and the two were kept in agreement by a
@@ -70,7 +75,8 @@ __all__ = [
     "to_profile",
 ]
 
-#: The only header PCGrate accepts. Never prefix these lines with ``#``.
+#: The legacy two-line header, written only on request. Never prefix these
+#: lines with ``#``.
 GGP_HEADER = "3 0 - Polygonal type\nPeriod: 1 PSC: 1"
 
 _CANONICAL_FIRST = "3 0 - Polygonal type"
@@ -80,9 +86,10 @@ _CANONICAL_FIRST = "3 0 - Polygonal type"
 class GgpFile:
     """A parsed ``.ggp``, with the header provenance kept.
 
-    ``format_valid`` records whether the file as written would
-    load in PCGrate. This is surfaced because a hashed header fails there
-    while parsing without error here.
+    ``format_valid`` is False for the two hashed variants, which
+    ``np.savetxt(header=...)`` produces by accident, and True for a file with
+    no header or the uncommented two-line one. It records which form a file
+    is in, not a test against PCGrate; see the module docstring.
     """
 
     t: np.ndarray
@@ -187,9 +194,9 @@ def _numeric_pair(line: str) -> tuple[float, float] | None:
 
 
 def _classify(header_lines: list[str]) -> tuple[str, bool]:
-    """Name the header variant and say whether PCGrate would accept it."""
+    """Name the header variant and say whether it is one we write."""
     if not header_lines:
-        return "none", False
+        return "none", True
     if header_lines[0] == _CANONICAL_FIRST:
         return "canonical", True
     if header_lines[0].lstrip("# ").startswith("3 0"):
@@ -219,9 +226,9 @@ def write_ggp(
     t: ArrayLike | None = None,
     y: ArrayLike | None = None,
     fmt: str = "%f",
-    header: bool = True,
+    header: bool = False,
 ) -> Path:
-    """Write a profile in the canonical, PCGrate-loadable form.
+    """Write a profile as ``x y`` points for PCGrate.
 
     Pass either a ``profile`` or explicit ``t``/``y`` arrays. A profile is
     reflected onto the file's ``+d-hat`` axis, the inverse of
@@ -233,12 +240,11 @@ def write_ggp(
     that ends in one, as ``np.savetxt`` output does. The format is pinned by
     ``tests/test_ggp.py``; PCGrate rejects variations on it.
 
-    ``header=False`` leaves out the two :data:`GGP_HEADER` lines and writes
-    the points alone, as ``np.savetxt`` with no ``header`` does. It exists to
-    test the claim in the module docstring that PCGrate needs the header:
-    that claim comes from the files found on disk, not from PCGrate's
-    documentation, and Aditi's script writes headerless files (2026-10-27).
-    Reading such a file back reports ``header_variant == "none"``.
+    The points are written alone by default, with no header: Aditi reports
+    that PCGrate's border-profile import does not want one (2026-10-29).
+    ``header=True`` starts the file with the two legacy :data:`GGP_HEADER`
+    lines instead. Reading a headerless file back reports
+    ``header_variant == "none"``.
     """
     if (profile is None) == (t is None):
         raise ValueError("pass either a profile or both t and y, not both or neither")

{gratinglab-0.2.8 → gratinglab-0.3.1}/src/gratinglab/metrology/boundary/__init__.py

@@ -3,7 +3,8 @@ Boundary profile generation for PCGrate
 
 This package averages the detected grooves of an AFM scan into a single
 representative groove, normalises it to one period, and exports it as a
-PCGrate .ggp boundary profile.
+PCGrate .ggp boundary profile. `trace_cross_section` does the same for an SEM
+micrograph of a cleaved cross-section, and fits a trapezoid to it.
 
 It shares the profile front-end (loading, groove detection, groove windowing)
 with the blaze-angle analysis in gratinglab.metrology.core.
@@ -11,6 +12,7 @@ with the blaze-angle analysis in gratinglab.metrology.core.
 
 from .pipeline import BoundaryProfile, build_boundary_profile
 from .swaths import SwathStatistics, swath_statistics
+from .cross_section import CrossSection, TrapezoidFit, trace_cross_section
 from .average import (
     flatten_endpoints,
     average_grooves,
@@ -25,6 +27,9 @@ __all__ = [
     'build_boundary_profile',
     'SwathStatistics',
     'swath_statistics',
+    'CrossSection',
+    'TrapezoidFit',
+    'trace_cross_section',
     'flatten_endpoints',
     'average_grooves',
     'groove_residuals',