plesty.pol_pl.rig
=================

.. py:module:: plesty.pol_pl.rig

.. autoapi-nested-parse::

   Instrument composite (rig) for the polarization-dependent PL experiment.

   Wires the two remote device servers of the measurement into one
   :class:`~plesty.lib.device.composite_device.CompositeDevice`:

   - ``hwp``  — Thorlabs K10CR1 rotation stage carrying the half-wave plate in the
     detection path, in front of a fixed polarizer (``plesty-k10cr1``),
   - ``spec`` — Princeton Instruments LightField spectrometer
     (``plesty-lightfield-spectrometer``).

   Everything the composite already does is used rather than repeated: the
   resilient ``call`` (timeout → reconnect → retry) and one thread per sub-device.
   What is left here is the rig's own vocabulary: home the plate, move it, set up
   an acquisition, acquire a spectrum. The experiment layer never issues a raw
   device command.

   The instruments and their operation budgets are declared in the packaged
   ``config.yaml``; the server addresses come from the environment. Neither is
   written in this file.

   Frame data never crosses the transport: the spectrometer writes each ``.spe``
   to the data path the run routed it to, and reports only the file path.



Attributes
----------

.. autoapisummary::

   plesty.pol_pl.rig._logger
   plesty.pol_pl.rig.DEVICES
   plesty.pol_pl.rig._HWP
   plesty.pol_pl.rig._SPEC
   plesty.pol_pl.rig._STATIC_SPEC_SETTINGS


Classes
-------

.. autoapisummary::

   plesty.pol_pl.rig.PolPlRig


Functions
---------

.. autoapisummary::

   plesty.pol_pl.rig.angular_error_deg


Module Contents
---------------

.. py:data:: _logger

.. py:data:: DEVICES
   :type:  dict[str, Any]

.. py:data:: _HWP

.. py:data:: _SPEC

.. py:data:: _STATIC_SPEC_SETTINGS
   :type:  tuple[tuple[str, Any], ...]
   :value: (('CameraSettings.HardwareIOTriggerResponse', 'NoResponse'),...


.. py:function:: angular_error_deg(reported_deg: float, target_deg: float) -> float

   Return the signed shortest angular distance from *target* to *reported*.


.. 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 ``<NAME>_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.