gratinglab 0.1.3__tar.gz → 0.1.4__tar.gz

{gratinglab-0.1.3/src/gratinglab.egg-info → gratinglab-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gratinglab
-Version: 0.1.3
+Version: 0.1.4
 Summary: Open platform for diffraction grating groove metrology and efficiency analysis
 Author: Jake McCoy
 License: BSD-3-Clause
@@ -74,7 +74,11 @@ The two halves are one package because a file between them loses information. A
 PCGrate `.ggp` boundary carries a *shape* and not a grating: it cannot hold the period,
 so the period gets retyped, guessed, or recovered from a sidecar later.
 `BoundaryProfile.to_problem()` carries the period the scan measured, and the fitted
-facet angle with it.
+facet angle with it. To save a profile without losing that, write it as gratinglab's
+own `.json` (`gratinglab.io.boundary.write_boundary_json`): reading it back gives the
+same problem, and the efficiency window's "Load boundary profile" fills in the
+period from it. The metrology window's Boundary tab exports `.ggp`, `.json` or
+`.csv`, and its "Send to efficiency window" button opens the groove there directly.
 
 ```python
 from gratinglab.metrology.boundary import build_boundary_profile

{gratinglab-0.1.3 → gratinglab-0.1.4}/README.md

@@ -35,7 +35,11 @@ The two halves are one package because a file between them loses information. A
 PCGrate `.ggp` boundary carries a *shape* and not a grating: it cannot hold the period,
 so the period gets retyped, guessed, or recovered from a sidecar later.
 `BoundaryProfile.to_problem()` carries the period the scan measured, and the fitted
-facet angle with it.
+facet angle with it. To save a profile without losing that, write it as gratinglab's
+own `.json` (`gratinglab.io.boundary.write_boundary_json`): reading it back gives the
+same problem, and the efficiency window's "Load boundary profile" fills in the
+period from it. The metrology window's Boundary tab exports `.ggp`, `.json` or
+`.csv`, and its "Send to efficiency window" button opens the groove there directly.
 
 ```python
 from gratinglab.metrology.boundary import build_boundary_profile

{gratinglab-0.1.3 → gratinglab-0.1.4}/src/gratinglab/__init__.py

@@ -21,7 +21,7 @@ from .illumination import Illumination, Polarization
 from .resolution import ResolvingPower, resolving_power
 from .result import EfficiencyScan, OrderEfficiency, Provenance
 
-__version__ = "0.1.3"
+__version__ = "0.1.4"
 
 __all__ = [
     "Illumination",

gratinglab-0.1.4/src/gratinglab/gui/qt/gc_guard.py

@@ -0,0 +1,102 @@
+"""Run Python's cycle collector on the GUI thread, never on a worker's.
+
+Both windows do their heavy work on a ``QThread``: the metrology window's
+analysis and the main window's solves. Python's automatic collector runs on
+whichever thread happens to allocate past its threshold, so it regularly ran
+*inside* those workers, and when the garbage it found held Qt objects (a
+closed window, a figure from an earlier preview) it destroyed them off the GUI
+thread. Qt does not allow that, and on macOS it segfaults: CI run 39835186938
+died with ``Fatal Python error: Segmentation fault`` and "Garbage-collecting"
+at the top of the worker thread's stack, in the middle of an ordinary
+``genfromtxt``. The same thing can happen to a user: close some windows, press
+Run, and the application crashes.
+
+The remedy is the usual one for PySide and PyQt applications. While any window
+holds the guard, automatic collection is off, and a timer on the GUI thread
+runs the collector whenever the generation counts say it is due, so garbage is
+still collected promptly and always on the one thread allowed to free a Qt
+object. When the last window releases it, automatic collection is restored,
+so code that runs with no window open behaves exactly as before.
+
+A window that is closed but never deleted never releases it, so the guard
+also restores collection at interpreter exit, through ``atexit``, and collects
+once while Qt still exists. Without that, Python's own final collection freed
+the accumulated Qt garbage after Qt was gone: the ubuntu / py3.11 CI leg passed
+every test and then aborted with ``Fatal Python error: bool_dealloc``, twice,
+with one window still holding the guard at the end of the session.
+"""
+
+from __future__ import annotations
+
+import atexit
+import gc
+
+from PySide6.QtCore import QObject, QTimer
+from PySide6.QtWidgets import QApplication
+
+__all__ = ["guard", "is_active"]
+
+#: How often the GUI thread checks whether a collection is due. Checking is
+#: three integer comparisons; collecting happens only past the thresholds.
+INTERVAL_MS = 500
+
+_collector: "_Collector | None" = None
+_holders = 0
+
+
+class _Collector(QObject):
+    def __init__(self, parent: QObject) -> None:
+        super().__init__(parent)
+        self._timer = QTimer(self)
+        self._timer.timeout.connect(self.collect_if_due)
+        self._timer.start(INTERVAL_MS)
+
+    def collect_if_due(self) -> None:
+        """What the automatic collector would have done, on this thread."""
+        count0, count1, count2 = gc.get_count()
+        limit0, limit1, limit2 = gc.get_threshold()
+        if count0 > limit0:
+            generation = 2 if count2 > limit2 else 1 if count1 > limit1 else 0
+            gc.collect(generation)
+
+
+def guard(window: QObject) -> None:
+    """Keep the collector on the GUI thread for as long as ``window`` exists.
+
+    Call from the window's constructor, on the GUI thread. Each call is
+    released by that window's ``destroyed`` signal; the last release restores
+    automatic collection.
+    """
+    global _collector, _holders
+    if _holders == 0:
+        app = QApplication.instance()
+        # Whatever garbage already exists is collected here and now, on this
+        # thread, before any worker can start allocating.
+        gc.collect()
+        gc.disable()
+        _collector = _Collector(app if app is not None else window)
+    _holders += 1
+    window.destroyed.connect(_release)
+
+
+def _release(*_args) -> None:
+    global _collector, _holders
+    _holders = max(0, _holders - 1)
+    if _holders == 0 and _collector is not None:
+        _collector._timer.stop()
+        _collector.deleteLater()
+        _collector = None
+        gc.enable()
+
+
+@atexit.register
+def _restore_at_exit() -> None:
+    """Collect while Qt is still alive, and hand collection back to Python."""
+    if _holders > 0:
+        gc.enable()
+        gc.collect()
+
+
+def is_active() -> bool:
+    """True while some window holds the guard, so automatic collection is off."""
+    return _holders > 0

{gratinglab-0.1.3 → gratinglab-0.1.4}/src/gratinglab/gui/qt/geometry_panel.py

@@ -216,13 +216,40 @@ class GeometryPanel(QWidget):
 
     def load_profile(self) -> None:
         path, _ = QFileDialog.getOpenFileName(
-            self, "Load boundary profile", "", "PCGrate boundary (*.ggp);;All files (*)"
+            self, "Load boundary profile", "",
+            "Boundary profiles (*.json *.ggp);;"
+            "gratinglab boundary, with period (*.json);;"
+            "PCGrate boundary (*.ggp);;All files (*)",
         )
         if path:
-            self._fields["profile_path"].setText(path)
-            self._path_label.setText(Path(path).name)
-            self.changed.emit()
-            self.solve_requested.emit()
+            self.load_boundary_file(path)
+
+    def load_boundary_file(self, path: "str | Path") -> None:
+        """Use a boundary file as the profile, and its period if it has one.
+
+        A gratinglab ``.json`` carries the period it was measured at, so the
+        period field is set from it; a ``.ggp`` cannot, so the field is left as
+        it is, which is the one case where the user still has to supply it.
+        Also what the metrology window's "Send to efficiency window" calls.
+        """
+        path = Path(path)
+        note = ""
+        if path.suffix.lower() == ".json":
+            from ...io.boundary import read_boundary_json
+
+            try:
+                saved = read_boundary_json(path)
+            except (OSError, ValueError):
+                pass  # the form's own validation reports the reason
+            else:
+                self._fields["period"].setText(f"{saved.period_nm:.6g}")
+                note = f" (period {saved.period_nm:.6g} nm from the file)"
+        kind = self._fields["profile_kind"]
+        kind.setCurrentIndex(kind.findText("From file"))
+        self._fields["profile_path"].setText(str(path))
+        self._path_label.setText(path.name + note)
+        self.changed.emit()
+        self.solve_requested.emit()
 
 
 def _value(widget: QWidget) -> str:

{gratinglab-0.1.3 → gratinglab-0.1.4}/src/gratinglab/gui/qt/main_window.py

@@ -103,6 +103,10 @@ class MainWindow(QMainWindow):
         super().__init__(parent)
         self.setWindowTitle("GratingLab")
         self.resize(1180, 820)
+        # Solves run on a worker thread; keep the cycle collector off it.
+        from .gc_guard import guard
+
+        guard(self)
 
         self._parsed = None
         self._token = 0
@@ -313,6 +317,16 @@ class MainWindow(QMainWindow):
 
     # -- actions ---------------------------------------------------------
 
+    def open_boundary(self, path) -> None:
+        """Load a boundary profile file as the grating, as if chosen by hand.
+
+        The metrology window's "Send to efficiency window" calls this with a
+        gratinglab ``.json``, so the measured period arrives with the shape.
+        """
+        self.geometry.load_boundary_file(path)
+        if not self.geometry_dock.isVisible():
+            self.geometry_dock.show()
+
     def _geometry_edited(self) -> None:
         """A field was edited. Schedule a redraw; solve nothing.
 

{gratinglab-0.1.3 → gratinglab-0.1.4}/src/gratinglab/gui/state.py

@@ -246,9 +246,12 @@ def _build_profile(form: FormState, errors: list[FieldError]):
         errors.append(FieldError("profile_path", f"no such file: {path}"))
         return None
     try:
-        from ..io.ggp import read_profile
+        # A gratinglab .json or a PCGrate .ggp, by suffix. The JSON's period is
+        # applied to the form when the file is loaded (GeometryPanel), not here:
+        # the period field stays the one place the period is read from.
+        from ..io.boundary import read_profile_file
 
-        return read_profile(path)
+        return read_profile_file(path)
     except Exception as exc:  # the reader raises ValueError with a useful message
         errors.append(FieldError("profile_path", str(exc).split("\n")[0]))
         return None

gratinglab-0.1.4/src/gratinglab/io/boundary.py

@@ -0,0 +1,270 @@
+"""Saving a measured groove profile with its scale and where it came from.
+
+A ``.ggp`` holds a groove's *shape* and nothing else: it is normalised to one
+period and has no room for the period itself, so a profile written to one and
+read back has lost the number the solver's phase term scales by. That is the
+gap ``docs/roadmap.md`` item 5 names. Two formats close it here:
+
+``.json``, gratinglab's own
+    The normalised profile at full precision, the measured period in nm, the
+    groove count, the profile metrics, and provenance: the gratinglab version,
+    the scan it came from, how many grooves were detected and averaged, and
+    the analysis settings. :func:`read_boundary_json` reads it back, and its
+    :meth:`BoundaryFile.to_problem` gives the same :class:`~gratinglab.problem.Problem`
+    the in-process ``BoundaryProfile.to_problem`` does, so saving loses nothing.
+    The main window's "Load boundary profile" reads it and fills in the period.
+
+``.csv``, for everything else
+    One row per point, ``t`` and ``y`` as fractions of the period plus the same
+    points in nm, under ``#`` comment lines carrying the period, groove counts
+    and source. For a spreadsheet, MATLAB, or another code. Write-only: the
+    JSON is the one to read back.
+
+Both writers take any object with the fields of
+``gratinglab.metrology.boundary.BoundaryProfile`` (``x_norm``, ``y_norm``,
+``period_nm``, ``n_grooves``, ``n_used``, ``n_edge_rejected``, ``metrics``)
+rather than importing it, because the metrology package needs the plotting
+extra and this module must not.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import math
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+__all__ = [
+    "FORMAT",
+    "VERSION",
+    "BoundaryFile",
+    "read_boundary_json",
+    "read_profile_file",
+    "write_boundary_csv",
+    "write_boundary_json",
+]
+
+#: Identifies the file, so a reader can refuse an unrelated JSON by name
+#: rather than failing on a missing key three lines later.
+FORMAT = "gratinglab-boundary"
+
+#: Bumped when a reader of the previous version could misread a new file.
+#: Adding an optional key is not such a change.
+VERSION = 1
+
+
+@dataclass(frozen=True)
+class BoundaryFile:
+    """A groove profile read back from a gratinglab ``.json``."""
+
+    period_nm: float
+    #: Fractions of one period, as :class:`~gratinglab.profiles.FromProfileData` takes them.
+    t: tuple[float, ...]
+    y: tuple[float, ...]
+    #: Grooves averaged into this profile, carried onto the problem.
+    n_grooves: int | None = None
+    #: A fitted facet angle in degrees, if the writer had one.
+    blaze_angle: float | None = None
+    metrics: dict = field(default_factory=dict)
+    provenance: dict = field(default_factory=dict)
+
+    def profile(self):
+        """The shape, as the solvers take it."""
+        from ..profiles import FromProfileData
+
+        return FromProfileData(t=self.t, y=self.y, blaze_angle=self.blaze_angle)
+
+    def to_problem(self, *, coating=None, substrate=None, roughness=0.0):
+        """This groove as an efficiency problem, with the period it was measured at.
+
+        The same problem ``BoundaryProfile.to_problem`` builds in process,
+        which is the point of the format: see ``tests/test_io_boundary.py``.
+        Roughness is not in the file for the reason that method's docstring
+        gives: nothing here measures surface microroughness.
+        """
+        from ..problem import Problem
+
+        return Problem(
+            period=self.period_nm,
+            profile=self.profile(),
+            coating=coating,
+            substrate=substrate,
+            roughness=roughness,
+            n_grooves=self.n_grooves,
+        )
+
+
+def write_boundary_json(
+    path: "str | Path",
+    profile: Any,
+    *,
+    source: "str | Path | None" = None,
+    settings: Any = None,
+    blaze_angle: float | None = None,
+) -> Path:
+    """Write ``profile`` (a ``BoundaryProfile``) as a gratinglab ``.json``.
+
+    ``source`` names the scan it came from and ``settings`` is the
+    ``AnalysisSettings`` it was built with; both land in the provenance and
+    neither is required. Floats are written at full precision, so reading the
+    file back reproduces the profile exactly rather than to six decimals as a
+    ``.ggp`` does.
+    """
+    path = Path(path)
+    t, y = _points(profile)
+    document = {
+        "format": FORMAT,
+        "version": VERSION,
+        "period_nm": float(profile.period_nm),
+        "profile": {
+            "units": "t and y are fractions of one period",
+            "t": t,
+            "y": y,
+        },
+        "n_grooves": int(profile.n_used),
+        "blaze_angle_deg": None if blaze_angle is None else float(blaze_angle),
+        "metrics": _plain(profile.metrics),
+        "provenance": _provenance(profile, source, settings),
+    }
+    text = json.dumps(document, indent=1, allow_nan=False) + "\n"
+    path.write_bytes(text.encode("utf-8"))
+    return path
+
+
+def read_boundary_json(path: "str | Path") -> BoundaryFile:
+    """Read a gratinglab ``.json`` boundary profile.
+
+    Refuses, by name, a JSON that is not one, a newer version than this reader
+    knows, and a profile whose two columns differ in length or whose period is
+    not a positive number. The profile's own checks (at least two points, and
+    so on) run when :meth:`BoundaryFile.profile` builds it.
+    """
+    path = Path(path)
+    try:
+        document = json.loads(path.read_bytes().decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ValueError(f"{path}: not a JSON file ({exc})") from exc
+    if not isinstance(document, dict) or document.get("format") != FORMAT:
+        raise ValueError(f"{path}: not a gratinglab boundary profile (no format: {FORMAT!r})")
+    version = document.get("version")
+    if not isinstance(version, int) or version > VERSION:
+        raise ValueError(
+            f"{path}: boundary format version {version!r}; this gratinglab reads "
+            f"up to {VERSION}, so upgrade it to read this file")
+    period = document.get("period_nm")
+    if not isinstance(period, (int, float)) or not math.isfinite(period) or period <= 0:
+        raise ValueError(f"{path}: period_nm must be a positive number, got {period!r}")
+    points = document.get("profile") or {}
+    t, y = points.get("t"), points.get("y")
+    if not isinstance(t, list) or not isinstance(y, list) or len(t) != len(y):
+        raise ValueError(f"{path}: profile t and y must be two lists of equal length")
+    blaze = document.get("blaze_angle_deg")
+    n_grooves = document.get("n_grooves")
+    return BoundaryFile(
+        period_nm=float(period),
+        t=tuple(float(v) for v in t),
+        y=tuple(float(v) for v in y),
+        n_grooves=None if n_grooves is None else int(n_grooves),
+        blaze_angle=None if blaze is None else float(blaze),
+        metrics=document.get("metrics") or {},
+        provenance=document.get("provenance") or {},
+    )
+
+
+def write_boundary_csv(
+    path: "str | Path",
+    profile: Any,
+    *,
+    source: "str | Path | None" = None,
+    settings: Any = None,
+) -> Path:
+    """Write ``profile`` as a CSV table under ``#`` comment lines.
+
+    Columns ``t, y`` are fractions of one period and ``x_nm, y_nm`` the same
+    points scaled by the measured period, so a reader needs no other number to
+    plot it at true size. ``settings`` is accepted for symmetry with
+    :func:`write_boundary_json`; only the JSON records them in full.
+    """
+    path = Path(path)
+    t, y = _points(profile)
+    period = float(profile.period_nm)
+    prov = _provenance(profile, source, None)
+    # The column header comes FIRST and the comments after it: numpy's
+    # genfromtxt(names=True) takes names from line one even when it is a
+    # comment, so a comment there containing a comma became two junk column
+    # names. Header-first reads cleanly in numpy, pandas (comment="#") and a
+    # spreadsheet, whose first row is then the column names.
+    lines = [
+        "t,y,x_nm,y_nm",
+        f"# gratinglab boundary profile written by gratinglab {prov['gratinglab_version']}",
+        f"# period_nm: {period!r}",
+        f"# grooves: {prov['grooves_averaged']} averaged of {prov['grooves_detected']} detected",
+    ]
+    if prov.get("source"):
+        lines.append(f"# source: {prov['source']}")
+    lines.append(
+        "# t and y are fractions of one period; x_nm and y_nm are the same points times the period")
+    lines += [f"{ti!r},{yi!r},{ti * period!r},{yi * period!r}" for ti, yi in zip(t, y)]
+    path.write_bytes(("\n".join(lines) + "\n").encode("utf-8"))
+    return path
+
+
+def read_profile_file(path: "str | Path"):
+    """A profile from either a gratinglab ``.json`` or a PCGrate ``.ggp``.
+
+    By suffix, because the two are unrelated formats and sniffing 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.
+    """
+    path = Path(path)
+    if path.suffix.lower() == ".json":
+        return read_boundary_json(path).profile()
+    from .ggp import read_profile
+
+    return read_profile(path)
+
+
+def _points(profile: Any) -> tuple[list[float], list[float]]:
+    t = [float(v) for v in np.asarray(profile.x_norm, dtype=float)]
+    y = [float(v) for v in np.asarray(profile.y_norm, dtype=float)]
+    if len(t) != len(y):
+        raise ValueError("profile x_norm and y_norm differ in length")
+    return t, y
+
+
+def _provenance(profile: Any, source: "str | Path | None", settings: Any) -> dict:
+    from .. import __version__
+
+    record = {
+        "gratinglab_version": __version__,
+        "created_utc": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "source": None if source is None else str(source),
+        "grooves_detected": int(profile.n_grooves),
+        "grooves_averaged": int(profile.n_used),
+        "grooves_edge_rejected": int(profile.n_edge_rejected),
+    }
+    if settings is not None:
+        record["settings"] = _plain(
+            dataclasses.asdict(settings) if dataclasses.is_dataclass(settings) else dict(settings)
+        )
+    return record
+
+
+def _plain(value: Any) -> Any:
+    """JSON-safe: numpy scalars and arrays to Python, tuples to lists, NaN refused."""
+    if isinstance(value, dict):
+        return {str(k): _plain(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_plain(v) for v in value]
+    if isinstance(value, np.ndarray):
+        return [_plain(v) for v in value.tolist()]
+    if isinstance(value, np.generic):
+        value = value.item()
+    if isinstance(value, float) and not math.isfinite(value):
+        return None
+    return value