plesty.lib.experiment.schedule
==============================

.. py:module:: plesty.lib.experiment.schedule

.. autoapi-nested-parse::

   Experiment plans: ordered schedules of atomic measurement steps.

   A :class:`Plan` is the frozen schedule of an experiment run — an ordered list
   of :class:`Step` items, each the smallest unit of work that either completes
   (its result is persisted and journaled) or is re-run on resume. The plan is
   written to disk at run start and never mutated; its content hash lets a
   resumed run verify it is continuing the *same* schedule.



Classes
-------

.. autoapisummary::

   plesty.lib.experiment.schedule.Step
   plesty.lib.experiment.schedule.Plan


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

.. py:class:: Step

   One atomic measurement step in an experiment plan.

   :ivar id: Stable, deterministic identifier unique within the plan,
             e.g. ``"scan[x=3,y=5]"``. Resume matches completed steps
             by this id, so it must not depend on run time or randomness.
   :ivar op: Name of the experiment method to call for this step.
   :ivar params: Keyword arguments passed to the method.



   .. py:attribute:: id
      :type:  str


   .. py:attribute:: op
      :type:  str


   .. py:attribute:: params
      :type:  dict[str, Any]


   .. py:method:: to_dict() -> dict[str, Any]

      Return a JSON-serializable representation of the step.



   .. py:method:: from_dict(data: dict[str, Any]) -> Step
      :classmethod:


      Reconstruct a step from :meth:`to_dict` output.



.. py:class:: Plan(steps: list[Step], config: dict[str, Any] | None = None)

   A frozen, hashable schedule of atomic steps plus the run configuration.

   Usage:

   .. code-block:: python

       plan = Plan(
           steps=[Step(id=f"scan[{i}]", op="scan_point", params={"x": i}) for i in range(10)],
           config={"exposure_s": 0.1},
       )
       plan.save("runs/run_001/plan.json")

   Initialize the plan with its steps and optional configuration.

   :param steps: Ordered atomic steps; step ids must be unique.
   :param config: Experiment configuration recorded alongside the schedule.

   :raises ValueError: If two steps share the same id.


   .. py:attribute:: steps
      :type:  list[Step]


   .. py:attribute:: config
      :type:  dict[str, Any]


   .. py:method:: to_dict() -> dict[str, Any]

      Return a JSON-serializable representation of the plan.



   .. py:method:: from_dict(data: dict[str, Any]) -> Plan
      :classmethod:


      Reconstruct a plan from :meth:`to_dict` output.



   .. py:method:: content_hash() -> str

      Return a stable SHA-256 hash of the schedule and configuration.

      Used on resume to verify that the persisted plan matches the plan the
      experiment would generate now — resuming under changed parameters is
      refused rather than silently mixing two schedules.



   .. py:method:: save(path: str | pathlib.Path) -> pathlib.Path

      Write the plan as JSON to *path*, creating parent directories.



   .. py:method:: load(path: str | pathlib.Path) -> Plan
      :classmethod:


      Load a plan previously written by :meth:`save`.



   .. py:method:: __len__() -> int

      Return the number of steps in the plan.