plesty.pol_pl.__main__
======================

.. py:module:: plesty.pol_pl.__main__

.. autoapi-nested-parse::

   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.



Attributes
----------

.. autoapisummary::

   plesty.pol_pl.__main__.RIG
   plesty.pol_pl.__main__.SCHEMA
   plesty.pol_pl.__main__.MANIFEST
   plesty.pol_pl.__main__.cli


Functions
---------

.. autoapisummary::

   plesty.pol_pl.__main__.with_prominence
   plesty.pol_pl.__main__.configure
   plesty.pol_pl.__main__.check
   plesty.pol_pl.__main__.build_devices
   plesty.pol_pl.__main__.build_experiment


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

.. py:data:: RIG
   :type:  dict[str, list[str]]

.. py:data:: SCHEMA
   :type:  dict[str, list[plesty.lib.device.params.ConfigParameter]]

.. py:data:: MANIFEST

.. py:data:: cli

.. py:function:: 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.

   :param config: The loaded measurement configuration.
   :param 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.


.. py:function:: configure(args: Any, config: dict[str, Any]) -> dict[str, Any]

   Apply the command line's overrides to the loaded configuration.

   :param args: The parsed command line.
   :param config: The configuration as read from the YAML file.

   :returns: The configuration the run freezes into its plan.


.. py:function:: 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.

   :param args: The parsed command line.
   :param config: The configuration this run would use.


.. py:function:: build_devices(args: Any, config: dict[str, Any], skip: frozenset[str]) -> plesty.pol_pl.rig.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.

   :param args: The parsed command line.
   :param config: The measurement configuration.
   :param skip: Optional sub-devices to build the rig without.


.. py:function:: build_experiment(args: Any, config: dict[str, Any], run_root: Optional[str], devices: Any) -> plesty.lib.experiment.Experiment

   Build the experiment on the rig.

   :param args: The parsed command line.
   :param config: The measurement configuration, frozen into the run's plan.
   :param run_root: Where this run's checkpoint directory goes.
   :param devices: The connected rig, or ``None`` for ``--dry-run``.