gratinglab 0.3.3__tar.gz → 0.3.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gratinglab
-Version: 0.3.3
+Version: 0.3.4
 Summary: Open platform for diffraction grating groove metrology and efficiency analysis
 Author: Jake McCoy, Aditi Gangadharan
 License: BSD-3-Clause
@@ -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
@@ -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.3 → 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
@@ -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.3 → gratinglab-0.3.4}/pyproject.toml

@@ -145,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.
@@ -241,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.3 → 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.3"
+__version__ = "0.3.4"
 
 __all__ = [
     "Illumination",

{gratinglab-0.3.3 → 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.3 → 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.3 → 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.3 → gratinglab-0.3.4}/src/gratinglab/materials/__init__.py

@@ -6,6 +6,7 @@ from gratinglab import materials
 materials.available()          # every material in every library
 pt = materials.lookup("Pt")    # ~/.gratinglab/materials/Pt.txt, say
 mine = materials.from_cxro_file("Ni_CXRO.txt")   # any file, no library
+au = materials.typical("Au")   # a model, not a table: see typical.py
 ```
 
 A library is a directory of tables, one material per file, named for it:
@@ -13,8 +14,14 @@ A library is a directory of tables, one material per file, named for it:
 ultraviolet to infrared) or `Pt.ari` (PCGrate) is `coating="Pt"`. Yours is
 `~/.gratinglab/materials`, or whatever `GRATINGLAB_MATERIALS` names, and it is
 searched before the tables bundled with a checkout, so your own replaces a
-bundled one of the same name. The release packages bundle none, because CXRO's
-terms for redistributing its tables are not settled; `data/SOURCES.md` says so.
+bundled one of the same name. Neither the repository nor a release bundles
+any, because no published table is clearly public domain; `data/SOURCES.md`
+says so.
+
+A name beginning `typical:` (`coating="typical:Au"`) is not looked up in any
+library: it is the X-ray model in :mod:`.typical`, built from physical facts,
+approximate, and named so that a result says it used a model. A plain `"Au"`
+with no table still refuses rather than falling back to it.
 
 Lookup is by name, because that is what a
 :class:`~gratinglab.problem.Problem` carries: `coating="Au"` keeps a benchmark
@@ -45,11 +52,14 @@ from .optical import (
     write_ari,
 )
 from .refractiveindex import read_refractiveindex
+from .typical import PREFIX as TYPICAL_PREFIX
+from .typical import TypicalConstants, from_name, typical
 
 __all__ = [
     "HC_EV_NM",
     "LIBRARY_ENV",
     "OpticalConstants",
+    "TypicalConstants",
     "UnknownMaterial",
     "available",
     "data_dir",
@@ -62,12 +72,13 @@ __all__ = [
     "read_ari",
     "read_cxro",
     "read_refractiveindex",
+    "typical",
     "user_dir",
     "write_ari",
 ]
 
-#: Tables bundled with a checkout live here. The release packages ship none;
-#: see ``data/SOURCES.md``.
+#: Bundled tables would live here, and there are none, in a checkout or a
+#: release; see ``data/SOURCES.md``. The test suite points this elsewhere.
 _DATA = Path(__file__).parent / "data"
 
 #: Names your own library directories, separated by ``os.pathsep``. When set it
@@ -168,7 +179,12 @@ def available() -> tuple[str, ...]:
 
 
 def lookup(name: str) -> OpticalConstants:
-    """A material by name, e.g. ``"Au"``, from the first library that has it."""
+    """A material by name, e.g. ``"Au"``, from the first library that has it.
+
+    ``typical:<formula>[@<density>]`` is the model in :mod:`.typical` instead.
+    """
+    if name.startswith(TYPICAL_PREFIX):
+        return from_name(name)
     for directory in library_dirs():
         path = _tables(directory).get(name)
         if path is not None:

gratinglab-0.3.4/src/gratinglab/materials/data/SOURCES.md

@@ -0,0 +1,48 @@
+# Optical constants: none here, and where to get them
+
+This directory holds no tables, in the repository or in a release. gratinglab
+commits only data that is its own or in the public domain, and no published
+optical constants table is clearly either. CXRO's site states no data licence,
+and refractiveindex.info's files, though dedicated CC0, report other people's
+measurements.
+
+Until 2026-11-11 the repository carried one, `Au.txt`: a verbatim CXRO/Henke
+export of gold, 200 eV to 2 keV in 500 points, used by the test suite. It never
+shipped in a wheel or sdist, and it remains in the git history and in the
+source archives GitHub generates for releases up to 0.3.3. The suite now uses
+an invented gold-sized table, `tests/data/materials/Au.txt`, written by
+`make_au.py` beside it, and `coating="Au"` resolves to that file only inside
+the tests.
+
+An install therefore starts with no materials, and `lookup` refuses with a
+message naming the way out. The one exception is not a table:
+`coating="typical:Au"` and its siblings are an approximate X-ray model computed
+from physical facts (atomic numbers and weights, core-level binding energies
+from the X-ray Data Booklet, first ionization energies, densities), each stated
+with its source in `materials/typical.py`. See `docs/typical-materials.md`. Nothing in `gratinglab` requires a table to exist;
+`test_an_empty_data_directory_is_a_supported_state` holds it to that, and
+`test_the_package_data_directory_has_no_table` holds this directory empty.
+
+## Adding a material
+
+Put the table in your own library, `~/.gratinglab/materials` or a directory
+named in `GRATINGLAB_MATERIALS`, as `<Name>.txt` for a CXRO export, `<Name>.yml`
+for a refractiveindex.info file or `<Name>.ari` for PCGrate's format. That is
+searched before this directory, survives an upgrade, and is never published.
+See `materials/__init__.py`.
+
+| Kind | Where | Range |
+|---|---|---|
+| CXRO/Henke export | <https://henke.lbl.gov/optical_constants/>, `getdb2.html`, one material, energy scan | X-ray |
+| refractiveindex.info | <https://refractiveindex.info>, the YAML file for a dataset | ultraviolet to infrared |
+
+A table you add is governed by whoever published it, not by gratinglab's
+licence.
+
+## Citation
+
+Work using CXRO tables should cite the compilation behind them:
+
+> B.L. Henke, E.M. Gullikson, and J.C. Davis, *X-ray interactions:
+> photoabsorption, scattering, transmission, and reflection at E = 50–30000 eV,
+> Z = 1–92*, Atomic Data and Nuclear Data Tables **54** (2), 181–342 (1993).

{gratinglab-0.3.3 → gratinglab-0.3.4}/src/gratinglab/materials/optical.py

@@ -221,6 +221,15 @@ class OpticalConstants:
         """
         return self._near_unity(self.n(wavelength_nm))
 
+    def caveats(self, wavelength_nm: ArrayLike) -> tuple[str, ...]:
+        """Provenance warnings this material asks for at these wavelengths.
+
+        A table answers for its whole range, so it has none; a model may not
+        (``typical.TypicalConstants``). Every solver adds these to its
+        warnings, so a material can say where it should not be relied on.
+        """
+        return ()
+
     @staticmethod
     def _near_unity(n: NDArray[np.complex128]) -> NDArray[np.bool_]:
         return np.abs(n - 1.0) <= NEAR_UNITY