plesty.pol_pl ============= .. py:module:: plesty.pol_pl .. autoapi-nested-parse:: Polarization-dependent photoluminescence experiment module. Submodules ---------- .. toctree:: :maxdepth: 1 /reference/plesty/pol_pl/__main__/index /reference/plesty/pol_pl/experiment/index /reference/plesty/pol_pl/rig/index /reference/plesty/pol_pl/viz/index Classes ------- .. autoapisummary:: plesty.pol_pl.Experiment plesty.pol_pl.PolPlRig Functions --------- .. autoapisummary:: plesty.pol_pl.load_config Package Contents ---------------- .. 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:class:: PolPlRig(devices: Optional[collections.abc.Mapping[str, Any]] = None, env: Optional[plesty.lib.utils.settings.EnvSettings] = None, env_prefix: Optional[str] = None) Bases: :py:obj:`plesty.lib.device.composite_device.CompositeDevice` Half-wave-plate rotation stage + spectrometer as one instrument. Connect the rig's instruments, each on its own thread. Addresses are not arguments: each is read from ``_ADDRESS`` in the environment (``HWP_ADDRESS``, ``SPEC_ADDRESS``), so a deployment is configured by its ``.env``. :param devices: Sub-device overrides in the form :class:`CompositeDevice` accepts; defaults to the ``devices`` block of the packaged ``config.yaml``. :param env: Environment source for the address lookups. :param env_prefix: Deployment prefix for the derived variable names. :raises ValueError: If a sub-device's address is neither configured nor in the environment. :raises RuntimeError: If a device server cannot be reached. .. py:method:: init_state() -> None Reset what this rig remembers about its instruments. Per rig, not per process: a run builds its own rig, so a fresh run rewrites every setting and never inherits another run's idea of them. .. py:method:: home_hwp() -> bool Home the rotation stage and return its homed status. .. py:method:: set_hwp(angle_deg: float) -> float Move the half-wave plate to an absolute angle and return where it settled. Small steps from a known position run under a short window; larger or first moves keep the full mechanical budget. The stage answers only once it has stopped, so the reported angle is the one the spectrum is measured at. It is checked against the target: on a mismatch beyond ``position_tolerance_deg`` the move is issued once more, and a second mismatch raises, so the step is retried instead of recording a spectrum at the wrong angle. :param angle_deg: Target angle in degrees (applied modulo 360). :returns: The stage-reported angle in degrees. :raises RuntimeError: If the stage settles away from the target twice. .. py:method:: configure_spectrum(exposure_ms: float, frames: int, base_name: str) -> None Push one acquisition's settings to the spectrometer, writing only what changed. The file name is part of the settings rather than of the acquire call: LightField generates it from the base name. :param exposure_ms: Exposure time in milliseconds. :param frames: Frames stored in the one ``.spe`` file. :param base_name: File-name stem LightField generates from. .. py:method:: center_wavelength_nm() -> float Return the grating centre wavelength currently set on the spectrometer. .. py:method:: acquire_spectrum(exposure_ms: float, frames: int) -> dict[str, Any] Expose the spectrometer once and return the file it wrote. The path is compared with the one reported before the exposure, because LightField answers with its most recent file whether or not this acquisition produced one. :param exposure_ms: Exposure time in milliseconds (sizes the call window). :param frames: Frames stored by the acquisition. :returns: ``{"data_file": str, "started_at": datetime, "ended_at": datetime}`` — the path as the spectrometer host sees it, and the UTC bounds of the exposure. :raises RuntimeError: If the spectrometer reports no new file. .. py:method:: _write_spec(key: str, value: Any) -> None Push one spectrometer setting under the configured write budget. .. py:function:: load_config() -> dict[str, Any] Load the packaged module configuration (constants and running defaults). :returns: The parsed ``config.yaml`` shipped with this module.