gratinglab 0.3.2__tar.gz → 0.3.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gratinglab
-Version: 0.3.2
+Version: 0.3.4
 Summary: Open platform for diffraction grating groove metrology and efficiency analysis
 Author: Jake McCoy, Aditi Gangadharan
 License: BSD-3-Clause
@@ -25,11 +25,11 @@ Requires-Dist: pydantic>=2.6
 Requires-Dist: endstation>=0.2.6
 Requires-Dist: threadpoolctl>=3.1
 Provides-Extra: dev
-Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest>=9.2; extra == "dev"
 Requires-Dist: pytest-qt>=4.5; extra == "dev"
 Requires-Dist: matplotlib>=3.8; extra == "dev"
 Requires-Dist: pandas>=2.1; extra == "dev"
-Requires-Dist: ruff>=0.16; extra == "dev"
+Requires-Dist: ruff>=0.17; extra == "dev"
 Provides-Extra: gui
 Requires-Dist: matplotlib>=3.8; extra == "gui"
 Requires-Dist: PySide6-Essentials!=6.12.0,>=6.7; python_version < "3.12" and extra == "gui"
@@ -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
@@ -287,8 +295,8 @@ same applies to the private reference corpus of efficiency tables:
 
 | Data | Environment variable | Default |
 |---|---|---|
-| AFM scans | `GRATINGLAB_AFM_DIR` | `~/Documents/afm_scans` |
-| Reference efficiency tables | `GRATINGLAB_REF_DIR` | `~/Documents/diffraction_efficiency` |
+| AFM scans | `GRATINGLAB_AFM_DIR` | `~/Documents/Research/afm_scans` |
+| Reference efficiency tables | `GRATINGLAB_REF_DIR` | `~/Documents/Research/diffraction_efficiency` |
 
 Tests that need either are skipped when it is absent, so the suite passes on a fresh
 clone. Most of the metrology tests do not need it: they run against a committed
@@ -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.2 → gratinglab-0.3.4}/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
@@ -242,8 +250,8 @@ same applies to the private reference corpus of efficiency tables:
 
 | Data | Environment variable | Default |
 |---|---|---|
-| AFM scans | `GRATINGLAB_AFM_DIR` | `~/Documents/afm_scans` |
-| Reference efficiency tables | `GRATINGLAB_REF_DIR` | `~/Documents/diffraction_efficiency` |
+| AFM scans | `GRATINGLAB_AFM_DIR` | `~/Documents/Research/afm_scans` |
+| Reference efficiency tables | `GRATINGLAB_REF_DIR` | `~/Documents/Research/diffraction_efficiency` |
 
 Tests that need either are skipped when it is absent, so the suite passes on a fresh
 clone. Most of the metrology tests do not need it: they run against a committed
@@ -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.2 → gratinglab-0.3.4}/pyproject.toml

@@ -62,7 +62,20 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-dev = ["pytest>=7", "pytest-qt>=4.5", "matplotlib>=3.8", "pandas>=2.1", "ruff>=0.16"]
+# The two floors that are not "the oldest version that works": pytest and ruff
+# are the gate the suite is judged by, and a local copy older than the one CI
+# resolves makes that gate quietly permissive rather than merely different.
+# `pytest>=7` let a local 9.1.1 accept `pytest.approx` over a list of tuples
+# that 9.2 refuses, so tests/test_txl.py passed here and failed on all four CI
+# legs; ruff gains rules between minors the same way, so an older copy passes
+# what `ruff check .` rejects there. Both floors therefore track what CI
+# installs, and raising them is part of taking a new version of either.
+#
+# The library floors below stay as genuine minimums. CI installs the newest of
+# everything on purpose -- that is what caught the pytest change -- and pinning
+# matplotlib or pandas to whatever it resolved this week would throw that away
+# while excluding environments the package supports.
+dev = ["pytest>=9.2", "pytest-qt>=4.5", "matplotlib>=3.8", "pandas>=2.1", "ruff>=0.17"]
 # The GUI is an optional extra: `pip install gratinglab` must never require
 # a toolkit.
 #
@@ -132,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.
@@ -228,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.2 → gratinglab-0.3.4}/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.2"
+__version__ = "0.3.4"
 
 __all__ = [
     "Illumination",

{gratinglab-0.3.2 → gratinglab-0.3.4}/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.2 → gratinglab-0.3.4}/src/gratinglab/geometry.py

@@ -27,6 +27,7 @@ __all__ = [
     "horizon_weights",
     "blaze_direction",
     "blaze_wavelength",
+    "littrow_alpha",
     "interference_factor",
 ]
 
@@ -466,6 +467,47 @@ def blaze_wavelength(
         return np.where(m != 0, numerator / m, np.inf)
 
 
+def littrow_alpha(order: int, wavelength: float, period: float, gamma: float) -> float:
+    r"""Azimuthal incidence angle that sends order ``order`` back along itself, in radians.
+
+    .. math::
+        \sin\alpha_L = \frac{m\lambda}{2 p \sin\gamma}
+
+    This is the grating equation with :math:`\beta_m = \alpha`, so the
+    diffracted order returns along the azimuth it arrived on. It is also the
+    facet angle a sawtooth needs to blaze into that order there, since
+    :func:`blaze_direction` gives :math:`\beta_b = 2\delta - \alpha = \alpha`
+    exactly when :math:`\delta = \alpha`.
+
+    Ported from PyXFocus ``grating.blazeYaw``, whose ``inc`` is the graze onto
+    the grating surface and whose yaw is measured in the surface from the
+    grooves. Neither is :math:`\gamma` or :math:`\alpha`; the two frames share
+    only the dispersion cosine, :math:`\cos(\text{inc})\sin\psi = \sin\gamma\sin\alpha`.
+    ``docs/conventions.md`` §10 records the mapping.
+
+    Raises
+    ------
+    ValueError
+        When :math:`|m\lambda| \ge 2 p \sin\gamma`, where no incidence angle
+        short of grazing reaches Littrow.
+    """
+    if period <= 0:
+        raise ValueError(f"period must be positive, got {period}")
+    if wavelength <= 0:
+        raise ValueError(f"wavelength must be positive, got {wavelength}")
+    if not 0 < gamma <= np.pi / 2:
+        raise ValueError(f"gamma must lie in (0, pi/2], got {gamma}")
+
+    s = order * wavelength / (2.0 * period * np.sin(gamma))
+    if not -1.0 < s < 1.0:
+        raise ValueError(
+            f"order {order} at wavelength {wavelength} cannot reach Littrow on period "
+            f"{period} at gamma {np.degrees(gamma):g} deg: it needs sin(alpha) = {s:.4g}. "
+            "Littrow is reachable only while |m * wavelength| < 2 * period * sin(gamma)."
+        )
+    return float(np.arcsin(s))
+
+
 def interference_factor(s: ArrayLike, n_grooves: int) -> NDArray[np.float64]:
     r"""The finite-:math:`N` grating interference function, ISSI eq. (8).
 

{gratinglab-0.3.2 → gratinglab-0.3.4}/src/gratinglab/gui/qt/setup_tab.py

@@ -193,9 +193,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

{gratinglab-0.3.2 → gratinglab-0.3.4}/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:

{gratinglab-0.3.2 → gratinglab-0.3.4}/src/gratinglab/illumination.py

@@ -5,11 +5,13 @@ incidence angle and the half-cone angle, because every mount reduces to it and i
 serialises readably. Direction cosines are available as a derived property.
 
 Three constructors exist so that each community can pass the angles it
-uses; they all resolve to the same internal state:
+uses; they all resolve to the same internal state. A fourth places a mount at
+Littrow for one order:
 
 >>> Illumination.classical(alpha=10.0)                  # in-plane
 >>> Illumination.conical(theta=10.0, phi=45.0)          # RCWA-style polar/azimuth
 >>> Illumination.offplane(graze=1.5, azimuth=0.97)      # extreme off-plane, X-ray
+>>> Illumination.littrow(1, 1.55, 400.0, graze=1.73)    # order 1 back on itself
 
 See ``docs/conventions.md`` §3 for the frame and the sign of ``alpha``.
 """
@@ -21,6 +23,8 @@ from typing import Literal
 import numpy as np
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
+from .geometry import littrow_alpha
+
 __all__ = ["Illumination", "Polarization"]
 
 Polarization = Literal["TE", "TM", "unpolarized"]
@@ -133,6 +137,45 @@ class Illumination(BaseModel):
         """
         return cls(alpha_deg=azimuth, gamma_deg=graze, polarization=polarization)
 
+    @classmethod
+    def littrow(
+        cls,
+        order: int,
+        wavelength: float,
+        period: float,
+        graze: float = 90.0,
+        polarization: Polarization = "TE",
+    ) -> "Illumination":
+        """The Littrow mount for one order at one wavelength.
+
+        Order ``order`` leaves along the azimuth it arrived on,
+        :math:`\\beta_m = \\alpha`. The default ``graze = 90`` is the in-plane
+        Littrow mount; a small ``graze`` is the off-plane one, with ``graze``
+        the half-cone angle :math:`\\gamma` exactly as in :meth:`offplane`.
+        The azimuth found is also the facet angle that blazes into this order
+        here; see :func:`gratinglab.geometry.littrow_alpha`.
+
+        Parameters
+        ----------
+        order
+            Diffraction order :math:`m`.
+        wavelength, period
+            In nm, or any unit the two share.
+        graze
+            Half-cone angle :math:`\\gamma`, degrees.
+
+        Raises
+        ------
+        ValueError
+            When the order cannot reach Littrow at this wavelength and cone.
+        """
+        alpha = littrow_alpha(order, wavelength, period, float(np.radians(graze)))
+        return cls(
+            alpha_deg=float(np.degrees(alpha)),
+            gamma_deg=graze,
+            polarization=polarization,
+        )
+
     @classmethod
     def from_direction_cosines(
         cls, ux: float, uy: float, uz: float, polarization: Polarization = "TE"

{gratinglab-0.3.2 → gratinglab-0.3.4}/src/gratinglab/io/boundary.py

@@ -225,8 +225,12 @@ def read_profile_file(path: "str | Path"):
 
     The format is chosen by suffix, because the two are unrelated formats and
     sniffing the content would only turn a clear refusal into a confusing one.
-    Only the JSON carries a period; read it with :func:`read_boundary_json`
-    to get that too.
+    Only the JSON carries a period *in nm*; a ``.ggp``'s control string may
+    carry the number without its unit, and ``read_ggp`` reports it. Read the
+    JSON with :func:`read_boundary_json` to get a period you can use.
+
+    All five of PCGrate's border profile types reach a profile through here --
+    see :mod:`gratinglab.io.ggp` -- so this is not polygonal-only.
     """
     path = Path(path)
     if path.suffix.lower() == ".json":

{gratinglab-0.3.2 → gratinglab-0.3.4}/src/gratinglab/io/efficiency_table.py

@@ -32,7 +32,7 @@ Format, confirmed by inspection of PCGrate-SX 6.7.1 output::
 Every line is tab-separated and right-padded with empty fields.
 
 Order indices come from the column headers, never from a positional offset.
-The prototype scripts in ``~/Documents/diffraction_efficiency`` read columns as
+The prototype scripts in ``~/Documents/Research/diffraction_efficiency`` read columns as
 ``data[i+11]``, which works only because ``np.genfromtxt`` splits the quoted
 label ``" Wav., nm"`` into two whitespace-delimited fields. That offset is
 different for every file and silently wrong if the order range changes.