plesty-pol-pl 0.2.0.dev1__py3-none-any.whl

plesty/pol_pl/__init__.py

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: 2026 Yunshuang Yuan
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+"""Polarization-dependent photoluminescence experiment module."""
+
+from typing import Any
+
+from plesty.lib.utils.config import module_config
+
+from plesty.pol_pl.experiment import Experiment
+from plesty.pol_pl.rig import PolPlRig
+
+__all__ = [
+    "Experiment",
+    "PolPlRig",
+    "load_config",
+]
+
+
+def load_config() -> dict[str, Any]:
+    """Load the packaged module configuration (constants and running defaults).
+
+    Returns:
+        The parsed ``config.yaml`` shipped with this module.
+    """
+    config: dict[str, Any] = module_config(__name__)
+    return config

plesty/pol_pl/__main__.py

@@ -0,0 +1,295 @@
+# SPDX-FileCopyrightText: 2026 Yunshuang Yuan
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+"""Entry point for running the polarization-dependent PL experiment as a standalone process.
+
+Device addresses and the shared disk are deployment facts and come from the
+environment (``HWP_ADDRESS``, ``SPEC_ADDRESS``, ``PLESTY_DATA``). The bench
+running the experiment serves each instrument on the bench ``setup.yaml`` names
+for it and gives the run its address; ``ExperimentCLI`` sets ``PLESTY_DATA`` at
+start-up from ``setup.yaml`` and the values its variables hold in ``.env``; one
+set by hand still wins. Measurement tuning lives in a YAML configuration file.
+
+``ExperimentCLI`` owns everything that is the same for every experiment —
+``--config``, ``--resume``, ``--run-root``, ``--dry-run`` and ``--manifest``,
+the preflight, the event loop, and the graceful stop. This module declares only
+what differs: :data:`SCHEMA`, what the run reads from the environment, and how
+the rig and the experiment are built.
+
+:data:`MANIFEST` is the contract. ``python -m plesty.pol_pl --manifest`` prints
+it, and a console builds this experiment's settings form from it without being
+taught anything about this module. It and ``config/default.yaml`` must declare
+the same keys — gate e3 checks that they do.
+"""
+
+import sys
+from copy import deepcopy
+from typing import Any, Optional
+
+from plesty.fss import HARMONICS
+from plesty.lib.device.params import ConfigParameter
+from plesty.lib.experiment import (
+    EnvVar,
+    Experiment as BaseExperiment,
+    ExperimentCLI,
+    Manifest,
+    yaml_parameter,
+)
+
+from .experiment import RUN_ROOT, Experiment
+from .rig import DEVICES, PolPlRig
+
+#: The rig: sub-device name → the operations this experiment calls on its
+#: server, as declared in the packaged ``config.yaml`` together with each
+#: server's time limits. The preflight checks them before the first step, so a
+#: server that is down or an address pointing at the wrong instrument is named
+#: at start-up instead of failing a spectrum halfway through the sweep.
+RIG: dict[str, list[str]] = {name: list(device["requires"]) for name, device in DEVICES.items()}
+
+#: What this experiment takes, group by group, as ``config/default.yaml`` sets
+#: it. A key whose value is a document rather than a scalar — the dot
+#: catalogue, the open-ended fit options — is declared with
+#: :func:`yaml_parameter`: no widget edits an arbitrary document, and a form
+#: that quietly rejected what the experiment accepts would be worse than none.
+SCHEMA: dict[str, list[ConfigParameter]] = {
+    "default": [
+        ConfigParameter(
+            "sample",
+            default="sample-000",
+            dtype=str,
+            description="Sample the dots are on; recorded with every spectrum.",
+        ),
+        yaml_parameter(
+            "qds",
+            "The dots to measure, in order: id and stage coordinates in µm. Each is assumed "
+            "already on the spectrometer when its steps begin.",
+            [{"id": "QD-01", "x_um": 0.0, "y_um": 0.0}],
+        ),
+        ConfigParameter(
+            "step_settle_s",
+            default=0.0,
+            dtype=float,
+            unit="s",
+            min_value=0.0,
+            description="Pause after the plate has settled, before each exposure.",
+        ),
+    ],
+    "hwp": [
+        ConfigParameter(
+            "start_deg",
+            default=0.0,
+            dtype=float,
+            unit="deg",
+            min_value=0.0,
+            max_value=360.0,
+            description="First half-wave-plate angle of the sweep.",
+        ),
+        ConfigParameter(
+            "stop_deg",
+            default=178.0,
+            dtype=float,
+            unit="deg",
+            min_value=0.0,
+            max_value=360.0,
+            description=(
+                "Last angle, included when whole steps reach it. The plate's polarization "
+                "pattern repeats every 90°, so 0–178° covers two periods."
+            ),
+        ),
+        ConfigParameter(
+            "step_deg",
+            default=2.0,
+            dtype=float,
+            unit="deg",
+            min_value=0.01,
+            max_value=90.0,
+            description="Increment between angles; must be positive.",
+        ),
+    ],
+    "spectra": [
+        ConfigParameter(
+            "exposure_ms",
+            default=1000.0,
+            dtype=float,
+            unit="ms",
+            min_value=1.0,
+            description="Spectrometer exposure per frame.",
+        ),
+        ConfigParameter(
+            "frames",
+            default=1,
+            dtype=int,
+            unit="",
+            min_value=1,
+            description="Frames acquired per angle; a stack is summed before the fit.",
+        ),
+        ConfigParameter(
+            "filename_prefix",
+            default="pol_pl",
+            dtype=str,
+            description="Prefix of the spectrum files the spectrometer writes.",
+        ),
+        ConfigParameter(
+            "file_visibility_timeout_s",
+            default=60.0,
+            dtype=float,
+            unit="s",
+            min_value=0.0,
+            description=(
+                "How long a written spectrum may take to appear on this machine's mount "
+                "before the step is treated as failed."
+            ),
+        ),
+    ],
+    "analysis": [
+        ConfigParameter(
+            "enabled",
+            default=True,
+            dtype=bool,
+            description="Run the fine-structure analysis after each dot's sweep.",
+        ),
+        ConfigParameter(
+            "rotator",
+            default="hwp",
+            dtype=str,
+            # From the analyzer's own table, not a copy of it: a list written
+            # out here would be a form offering fewer choices than the
+            # experiment accepts the moment plesty-fss gains one.
+            options=sorted(HARMONICS),
+            description=(
+                "Which rotator's angle the analysis fits against — a half-wave plate turns "
+                "the polarization twice as fast as a rotating polarizer."
+            ),
+        ),
+        yaml_parameter(
+            "fit_options",
+            "Passed to plesty.lib.analyzer.SpectrumFit — e.g. peaks: [775.1, 776.4], "
+            "window: 0.1, center_tolerance: 0.05. Empty: lines are found automatically.",
+            {},
+        ),
+    ],
+}
+
+MANIFEST = Manifest(
+    module="plesty.pol_pl",
+    title="Polarization PL",
+    schema=SCHEMA,
+    environment=[
+        EnvVar("HWP_ADDRESS", "ZMQ address of the rotation stage carrying the half-wave plate."),
+        EnvVar("SPEC_ADDRESS", "ZMQ address of the spectrometer server."),
+        EnvVar("PLESTY_DATA", "The shared data disk as this machine sees it."),
+    ],
+    run_root=RUN_ROOT,
+    viz="plesty.pol_pl.viz",
+)
+
+cli = ExperimentCLI(MANIFEST)
+#: Sub-devices the run can do without — none: without the stage there is no
+#: polarization sweep, without the spectrometer no spectrum.
+cli.optional()
+cli.add_argument(
+    "--prominence",
+    type=float,
+    default=None,
+    metavar="COUNTS",
+    sets="analysis.fit_options.prominence",
+    help=(
+        "Line-finding threshold: a line must stand at least this many counts above "
+        "its surroundings (default: analysis.fit_options.prominence of the configuration)."
+    ),
+)
+
+
+def with_prominence(config: dict[str, Any], prominence: Optional[float]) -> dict[str, Any]:
+    """Return *config* with the line-finding threshold set, or unchanged for ``None``.
+
+    The threshold is ``analysis.fit_options.prominence``: a line must stand at
+    least that many counts above its surroundings to be found. The run saves
+    the configuration it used, so the value set here is on record.
+
+    Args:
+        config:     The loaded measurement configuration.
+        prominence: The threshold in counts, or ``None`` to leave it alone.
+
+    Returns:
+        The configuration to freeze into the plan.
+
+    Raises:
+        ValueError: If *prominence* is not a positive number of counts.
+    """
+    if prominence is None:
+        return config
+    if prominence <= 0:
+        raise ValueError(f"prominence must be a positive number of counts, got {prominence}.")
+    updated = deepcopy(config)
+    analysis = updated.setdefault("analysis", {})
+    fit_options = dict(analysis.get("fit_options") or {})
+    fit_options["prominence"] = float(prominence)
+    analysis["fit_options"] = fit_options
+    return updated
+
+
+@cli.configure
+def configure(args: Any, config: dict[str, Any]) -> dict[str, Any]:
+    """Apply the command line's overrides to the loaded configuration.
+
+    Args:
+        args:   The parsed command line.
+        config: The configuration as read from the YAML file.
+
+    Returns:
+        The configuration the run freezes into its plan.
+    """
+    return with_prominence(config, args.prominence)
+
+
+@cli.check
+def check(args: Any, config: dict[str, Any]) -> None:
+    """Refuse an incomplete configuration before anything connects.
+
+    What only a hardware run needs — the shared data disk — is checked here
+    rather than in the experiment, so ``--dry-run`` works without it and a
+    missing disk costs nothing measured.
+
+    Args:
+        args:   The parsed command line.
+        config: The configuration this run would use.
+    """
+    planner = Experiment(config=config, run_root=cli.run_root(args))
+    Experiment.validate_hardware_config(planner.config, planner.data_root)
+
+
+@cli.rig
+def build_devices(args: Any, config: dict[str, Any], skip: frozenset[str]) -> PolPlRig:
+    """Build the rig, leaving out the sub-devices named in *skip*.
+
+    Each sub-device's address is read from its own ``<NAME>_ADDRESS``
+    environment variable. Called again on every start-up retry, so an edited
+    ``.env`` or a server started in the meantime is picked up.
+
+    Args:
+        args:   The parsed command line.
+        config: The measurement configuration.
+        skip:   Optional sub-devices to build the rig without.
+    """
+    chosen = {name: dict(device) for name, device in DEVICES.items() if name not in skip}
+    return PolPlRig(devices=chosen)
+
+
+@cli.build
+def build_experiment(
+    args: Any, config: dict[str, Any], run_root: Optional[str], devices: Any
+) -> BaseExperiment:
+    """Build the experiment on the rig.
+
+    Args:
+        args:     The parsed command line.
+        config:   The measurement configuration, frozen into the run's plan.
+        run_root: Where this run's checkpoint directory goes.
+        devices:  The connected rig, or ``None`` for ``--dry-run``.
+    """
+    return Experiment(devices=devices, config=config, run_root=run_root)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(cli.main())

plesty/pol_pl/config.yaml

@@ -0,0 +1,67 @@
+# pol_pl module configuration — constants and running defaults.
+# Loaded via plesty.pol_pl.load_config(); shipped inside the wheel.
+# Credentials never live here (see .env.example); host-specific values are
+# overridden via the environment or CLI arguments.
+# Measurement run tuning lives in config/*.yaml at the repository root and is
+# frozen into each run's plan — this file is for fixed module constants only.
+
+# Fixed module constants: which instruments this rig is made of, and how long
+# their operations are physically allowed to take. Properties of the hardware,
+# not of a measurement, which is why they are not run configuration.
+constants:
+  # The rig's sub-devices, written in the declarative form
+  # plesty.lib.device.composite_device.CompositeDevice takes verbatim: name →
+  # {address, env, timeout_ms, attempts, backoff_s}. No address appears here —
+  # each is read from <NAME>_ADDRESS in the environment (HWP_ADDRESS,
+  # SPEC_ADDRESS) by the platform convention, so a deployment is configured by
+  # its .env rather than by code or a tracked file.
+  #
+  # requires lists what each server must expose — the preflight turns "the
+  # port answers" into "it is the stage / the spectrometer". A wrong
+  # <NAME>_ADDRESS connects fine and would otherwise fail at the first angle.
+  devices:
+    hwp:
+      # Thorlabs K10CR1 rotation stage carrying the half-wave plate in front of
+      # the fixed polarizer (plesty-k10cr1). Routine calls are sub-second;
+      # moves and homing raise their own window per call (see waveplate).
+      timeout_ms: 5000
+      connect_deadline_s: 10
+      requires: [home_stage, move_absolute, get_position]
+    spec:
+      # Princeton Instruments LightField spectrometer
+      # (plesty-lightfield-spectrometer). Its socket is bound before LightField
+      # has started, so a connect during that start-up is answered late rather
+      # than refused — tens of seconds later. Waiting is what works; it costs
+      # nothing when the server is already up.
+      timeout_ms: 10000
+      connect_deadline_s: 90
+      requires: [write, query, acquire, get_recent_file, set_data_path]
+
+  # Operation budgets, in seconds — how long the physics may take.
+  waveplate:
+    # Must exceed the K10CR1 server's own budget — the firmware move timeout
+    # (60 s) plus its settle confirmation (plesty-k10cr1#2, up to another 60 s
+    # for a stage that never comes to rest) — so the stage errors before the
+    # client does.
+    move_timeout_s: 130.0
+    # A homing seek can traverse the full revolution at the slow homing speed.
+    home_timeout_s: 180.0
+    # Fast window for the small steps of a sweep (a 2° move takes ~1 s).
+    small_move_timeout_s: 5.0
+    # Moves beyond this, or from an unknown position, use the full budget.
+    small_step_deg: 10.0
+    # The stage reports its position only once it has settled, so the reported
+    # angle is checked against the target: a mismatch beyond this is a failed
+    # positioning, not noise. K10CR1 resolution is 26 µdeg.
+    position_tolerance_deg: 0.01
+
+  spectrometer:
+    # Slack added to exposure × frames for the acquire call: arming, readout,
+    # the .spe write to the network share, and the first file-generation setup.
+    acquire_grace_s: 120.0
+    # A settings write is sub-second; this covers a busy LightField.
+    write_timeout_s: 30.0
+
+# Runtime defaults, overridable per host via the environment or CLI.
+running:
+  timeout: 5