gratinglab 0.3.1__tar.gz → 0.3.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gratinglab
-Version: 0.3.1
+Version: 0.3.3
 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"
@@ -287,8 +287,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

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

@@ -242,8 +242,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

{gratinglab-0.3.1 → gratinglab-0.3.3}/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.
 #

{gratinglab-0.3.1 → gratinglab-0.3.3}/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.3"
 
 __all__ = [
     "Illumination",

{gratinglab-0.3.1 → gratinglab-0.3.3}/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.1 → gratinglab-0.3.3}/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.1 → gratinglab-0.3.3}/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.1 → gratinglab-0.3.3}/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.