plesty.pol_pl.experiment ======================== .. py:module:: plesty.pol_pl.experiment .. autoapi-nested-parse:: Polarization-dependent photoluminescence of quantum dots. The atomic step is one analyser angle: rotate the half-wave plate in the detection path (in front of a fixed polarizer) to the next angle, then take one spectrum. After the last angle of a quantum dot, one analysis step runs the :class:`plesty.fss.FineStructure` analyzer over that dot's spectra and saves its result in the run: the fine-structure splitting of every emission line, with a flag saying whether the splitting could be measured from that line. All data lands on the shared disk, and frames never cross the network. Runs go under the experiment's root there (``pol-pl/``). The run routes the spectrometer once, at setup, to the run directory's ``raw/spec`` folder by its path relative to the shared point, which the spectrometer resolves under its own bench's view of the disk; the run records each spectrum by that folder and the file name the spectrometer reports, and reads it under its own ``PLESTY_DATA``. The framework commits each step's record to ``//records.jsonl`` the moment the step completes, so an interrupted sweep resumes at the exact angle it stopped (``run(resume=)``). Positioning is not automated: the steps assume the dot is already on the spectrometer. The catalogue coordinates are recorded in every spectrum record. Attributes ---------- .. autoapisummary:: plesty.pol_pl.experiment.ANGLE_KEY plesty.pol_pl.experiment.RUN_ROOT plesty.pol_pl.experiment._SPECTRUM_SUFFIXES plesty.pol_pl.experiment._DEFAULT_CONFIG Classes ------- .. autoapisummary:: plesty.pol_pl.experiment.Experiment Functions --------- .. autoapisummary:: plesty.pol_pl.experiment.angle_series plesty.pol_pl.experiment._is_finite plesty.pol_pl.experiment._finite Module Contents --------------- .. py:data:: ANGLE_KEY :value: 'hwp_deg' .. py:data:: RUN_ROOT :value: 'pol-pl' .. py:data:: _SPECTRUM_SUFFIXES :value: ('.spe', '.npz') .. py:data:: _DEFAULT_CONFIG :type: dict[str, Any] .. py:function:: angle_series(start_deg: float, stop_deg: float, step_deg: float) -> list[float] Return the inclusive angle series without float accumulation drift. :param start_deg: First angle in degrees. :param stop_deg: Last angle in degrees, included when reachable by whole steps. :param step_deg: Increment in degrees; must be positive. :returns: The commanded angles in degrees. :raises ValueError: If ``step_deg`` is not positive or ``stop_deg < start_deg``. .. py:class:: Experiment(devices: Optional[plesty.pol_pl.rig.PolPlRig] = None, config: Optional[dict[str, Any]] = None, run_root: str | pathlib.Path | None = None, **kwargs: Any) Bases: :py:obj:`plesty.lib.experiment.Experiment` Measure the polarization sweep of every catalogued quantum dot and analyse it. Configuration comes from a plain dict (loaded from ``config/*.yaml`` by ``__main__``) and is frozen into the plan, so a resumed run refuses a changed configuration. Instruments are reached exclusively through the :class:`~.rig.PolPlRig` composite passed at construction. Initialize and validate the plan-shaping configuration. The configuration is checked here, before anything connects, so a malformed sweep fails at the prompt rather than halfway through a run. What only a hardware run needs — the shared data disk — is checked by :meth:`validate_hardware_config`, so ``--dry-run`` works without it. :param devices: The instrument rig; ``None`` for plan-only inspection. :param config: Measurement configuration (see ``config/default.yaml``); missing sections take the defaults of this module. :param run_root: Directory under which each run creates its data directory; a relative one is under ``PLESTY_DATA`` (the share) — :data:`RUN_ROOT` for a run started by the command line. :param \*\*kwargs: Forwarded to the base ``Experiment`` (``name``, ``max_retries``, ``retry_sleep``, ``data_root``). :raises ValueError: If the configuration is malformed. .. py:attribute:: config .. py:attribute:: rig :value: None .. py:attribute:: _grating_center_nm :type: Optional[float] :value: None .. py:method:: build_plan() -> plesty.lib.experiment.Plan Expand the configuration into one step per dot per angle, plus one analysis per dot. Absolute angles, so no error accumulates along the sweep; resume granularity is the single angle. :returns: The frozen schedule. Step ids look like ``qd[QD-01]-hwp[004.00]`` and ``qd[QD-01]-analysis``. .. py:method:: record_rig() -> dict[str, Any] Record the instrument identities, so a run is replayable from its records. :returns: Each device's identity and the UTC time it was recorded. .. py:method:: measure_spectrum(sample: str, qd: str, x_um: float, y_um: float, angle_deg: float, exposure_ms: float, frames: int, settle_s: float = 0.0) -> dict[str, Any] Rotate the half-wave plate to one angle and take one spectrum. :param sample: Sample identifier. :param qd: Quantum-dot identifier from the catalogue. :param x_um: Catalogued chip X coordinate in micrometres. :param y_um: Catalogued chip Y coordinate in micrometres. :param angle_deg: Commanded absolute half-wave-plate angle in degrees. :param exposure_ms: Exposure time in milliseconds. :param frames: Frames stored in the spectrum file. :param settle_s: Pause after the plate has settled, before the exposure. :returns: identifiers, coordinates, commanded and reported angle, the spectrum file relative to the shared point, the exposure window and the grating centre wavelength. :rtype: The spectrum record :raises RuntimeError: If no rig is attached or the spectrometer wrote no file. :raises TimeoutError: If the file does not appear on this host's mount. .. py:method:: analyze_qd(qd: str) -> dict[str, Any] Analyse one quantum dot's polarization sweep with :class:`plesty.fss.FineStructure`. Reads the dot's spectra back from this run's records, fits every line in every spectrum and each line's position against the angle, and saves the analyzer's ``fine_structure`` and ``fit`` outputs under ``/analysis/``, where the run viewer (:mod:`.viz`) finds them, with the analyzer's report of them beside them (``.report.json``). Warnings the analyzer raises — a line whose fit moved onto a different line, a splitting that cannot be read from a line — are logged and kept in the record. :param qd: Quantum-dot identifier. :returns: position, fine-structure splitting ± σ in µeV, whether the splitting is valid, and polarization axis; plus the analyzer warnings and where the full results were saved. :rtype: Per emission line :raises RuntimeError: If the run has not started. :raises ValueError: If the run holds no spectrum of this dot. .. py:method:: setup() -> None :async: Check the configuration, connect, route the frames, home the plate. :raises ValueError: If the hardware configuration is incomplete. :raises RuntimeError: If this machine is not told where the Plesty share is. .. py:method:: teardown() -> None :async: Park the half-wave plate at 0° (best effort), then disconnect. .. py:method:: validate_plan_config(config: dict[str, Any]) -> None :classmethod: Validate everything that shapes the plan. :param config: The measurement configuration, defaults merged in. :raises ValueError: If a value is missing, of the wrong kind or out of range. .. py:method:: validate_hardware_config(config: dict[str, Any], data_root: Optional[str]) -> None :classmethod: Validate what a hardware run needs beyond a valid plan. The spectra are written by the spectrometer and read back here — to confirm each file arrived and to analyse the sweep — so this machine's view of the shared disk is required. :param config: The measurement configuration. :param data_root: The shared disk as this machine sees it. :raises ValueError: If the plan configuration is invalid or the shared disk is not configured. .. py:method:: _base_filename(qd: str, angle_deg: float) -> str Build the spectrometer file-name stem, e.g. ``pol_pl_QD-01_hwp004p00``. .. py:method:: _grating_center() -> Optional[float] Return the grating centre wavelength, queried once per process. A value the spectrometer cannot report is recorded as ``None`` with one warning; metadata must not abort a sweep whose spectra are fine. .. py:method:: _local_raw_path(data_file: str) -> pathlib.Path A recorded spectrum file, relative to the shared point, on this machine. The folder is the run's own (:meth:`raw_file`); only the name came from the spectrometer, and it is checked rather than trusted — it becomes a path this process reads — so it must name a spectrum. :raises RuntimeError: If the run has no data root. :raises ValueError: If the spectrometer's file is not a spectrum. .. py:method:: _wait_for_file(path: pathlib.Path) -> None Wait for a written spectrum to become visible on this machine's mount. :raises TimeoutError: If it does not appear within ``spectra.file_visibility_timeout_s``. .. py:method:: _require_rig() -> plesty.pol_pl.rig.PolPlRig Return the rig. :raises RuntimeError: If the experiment was built without one. .. py:function:: _is_finite(value: Any) -> bool Return whether *value* is a finite number (booleans excluded). .. py:function:: _finite(value: Any) -> Optional[float] Return *value* as a float, or ``None`` when it is not finite (for JSON records).