sequince.checkpoint
===================

.. py:module:: sequince.checkpoint


Attributes
----------

.. autoapisummary::

   sequince.checkpoint.CHECKPOINT_VERSION


Classes
-------

.. autoapisummary::

   sequince.checkpoint.CheckpointWriter
   sequince.checkpoint.StepState
   sequince.checkpoint.SMCCheckpoint
   sequince.checkpoint.HDF5CheckpointWriter
   sequince.checkpoint.PickleCheckpointWriter


Functions
---------

.. autoapisummary::

   sequince.checkpoint.capture_step_states
   sequince.checkpoint.restore_steps


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

.. py:data:: CHECKPOINT_VERSION
   :value: 1


.. py:class:: CheckpointWriter(*, every = 1, save_rng = True)

   Bases: :py:obj:`abc.ABC`


   Base class for persisting committed SMC checkpoints.


   .. py:attribute:: requires_detached_checkpoint
      :value: True


      Whether the writer may retain the checkpoint after ``write`` returns.


   .. py:attribute:: every
      :value: 1



   .. py:attribute:: save_rng
      :value: True



   .. py:method:: is_due(next_iteration)

      Return whether a checkpoint is due after this iteration.



   .. py:method:: write(checkpoint)

      Apply this writer's options and persist the checkpoint.



.. py:class:: StepState

   Checkpoint state associated with one configured SMC step.


   .. py:attribute:: index
      :type:  int


   .. py:attribute:: module
      :type:  str


   .. py:attribute:: qualname
      :type:  str


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


   .. py:method:: from_step(index, step)
      :classmethod:



   .. py:method:: to_dict()


   .. py:method:: from_dict(payload)
      :classmethod:



.. py:function:: capture_step_states(steps)

   Capture mutable state from a configured step pipeline.


.. py:function:: restore_steps(steps, states)

   Restore step state after validating pipeline identity and order.


.. py:class:: SMCCheckpoint

   Detached end-of-iteration state for resuming an SMC run.


   .. py:attribute:: states
      :type:  tuple[sequince.state.ParticleState, ...]


   .. py:attribute:: next_iteration
      :type:  int


   .. py:attribute:: next_observation_index
      :type:  int


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


   .. py:attribute:: outputs
      :type:  tuple[tuple[Any, ...], ...]


   .. py:attribute:: step_states
      :type:  tuple[StepState, ...]


   .. py:attribute:: evaluation_counts
      :type:  sequince.target.EvaluationCounts


   .. py:attribute:: rng_state
      :type:  dict[str, Any] | None
      :value: None



   .. py:attribute:: observation
      :type:  Any
      :value: None



   .. py:attribute:: initial_state
      :type:  sequince.state.ParticleState | None
      :value: None



   .. py:attribute:: version
      :type:  int
      :value: 1



   .. py:property:: state
      :type: sequince.state.ParticleState


      Return the current state represented by this checkpoint.


   .. py:method:: from_runtime(state, context, result, steps, rng = None, *, detach = True)
      :classmethod:


      Capture a checkpoint after a completed SMC iteration.



   .. py:method:: to_dict()

      Return a detached plain-Python checkpoint representation.



   .. py:method:: from_dict(payload, *, copy_values = True)
      :classmethod:


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



   .. py:method:: restore_rng()

      Return a live ORNG generator restored from this checkpoint.



   .. py:method:: result(shared_context = None)

      Return the result states represented by this checkpoint.



   .. py:method:: save_pickle(file_path, protocol = None)

      Save this checkpoint as a versioned pickle payload.



   .. py:method:: load_pickle(file_path)
      :classmethod:


      Load a trusted checkpoint from a pickle file.



   .. py:method:: save_hdf5(h5_file, path = 'checkpoint', dsetname = 'runtime', protocol = None, *, replace_states = False)

      Append states and commit their count with the runtime payload.

      Interrupted writes leave the previous runtime readable. This protects
      against incomplete writes in a readable HDF5 file, not file corruption.



   .. py:method:: load_hdf5(h5_file, path = 'checkpoint', dsetname = 'runtime')
      :classmethod:


      Load a checkpoint from its recursive HDF5 representation.



.. py:class:: HDF5CheckpointWriter(file_path, *, every = 1, path = 'checkpoint', dsetname = 'runtime', save_rng = True)

   Bases: :py:obj:`CheckpointWriter`


   Persist committed SMC checkpoints to HDF5 at a fixed cadence.


   .. py:attribute:: requires_detached_checkpoint
      :value: False


      Whether the writer may retain the checkpoint after ``write`` returns.


   .. py:attribute:: file_path


   .. py:attribute:: path
      :value: 'checkpoint'



   .. py:attribute:: dsetname
      :value: 'runtime'



.. py:class:: PickleCheckpointWriter(file_path, *, every = 1, save_rng = True, protocol = None)

   Bases: :py:obj:`CheckpointWriter`


   Atomically persist committed SMC checkpoints as pickle files.


   .. py:attribute:: requires_detached_checkpoint
      :value: False


      Whether the writer may retain the checkpoint after ``write`` returns.


   .. py:attribute:: file_path


   .. py:attribute:: protocol
      :value: None