:mod:`ocd.states` -- OCD state machines
=======================================

.. automodule:: ocd.states

Variables
---------

.. autodata:: ocd.states.TCS_HEARTBEAT_TOPIC
.. autodata:: ocd.states.STATE_CHANGE_TOPIC
.. autodata:: ocd.states.STATE_NAME_TOPIC

:class:`BaseState` -- The state machines API
--------------------------------------------

.. autoclass:: ocd.states.BaseState
    :members:
    :private-members:
    :show-inheritance:

:class:`RunShotState` -- Keep track of the shots run by OCD
-----------------------------------------------------------

.. autoclass:: ocd.states.RunShotState
    :members:
    :private-members:
    :show-inheritance:

.. image:: _static/run_shot_state.png

:class:`MetrologyState` -- Monitor the metrology
------------------------------------------------

.. autoclass:: ocd.states.MetrologyState
    :members:
    :private-members:
    :show-inheritance:

.. image:: _static/metrology_state.png

:class:`HetdexAllowedState` -- It is time to run HETDEX?
--------------------------------------------------------

.. autodata:: ocd.states.HETDEX_ALLOWED_TOPIC
.. autodata:: ocd.states.HETDEX_CHANGED_TOPIC
.. autodata:: ocd.states.HETDEX_TOGGLE
.. autodata:: ocd.states.HETDEX_CHANGED

.. autoclass:: ocd.states.HetdexAllowedState
    :members:
    :private-members:
    :show-inheritance:

.. image:: _static/hetdex_allowed_state.png

:class:`MetaState` -- Meta state machine
----------------------------------------

This machine aggregates the state of other machines and according to their
states switch between the :attr:`satisfied` and :attr:`not_satisfied` states.
Consider the following case::

    >>> run_shot = RunShotState()
    >>> hetdex_allowed = HetdexAllowedState()
    >>> meta = MetaState([(run_shot, 'idle'), (hetdex_allowed. 'allowed')])

If ``run_shot.state == idle`` and ``hetdex_allowed == allowed``, then
``meta.state == satisfied``. Any other combination of states of ``run_shot``
and ``hetdex_allowed`` results in ``meta.state == not_satisfied``.


.. autoclass:: ocd.states.MetaState
    :members:
    :private-members:
    :show-inheritance:

.. image:: _static/meta_state.png

Mixin classes and helpers
-------------------------

.. autoclass:: ocd.states.CallbackMixin
    :members:
    :private-members:
    :show-inheritance:

.. autoclass:: ocd.states.StateMixin
    :members:
    :private-members:
    :show-inheritance:

Inheritance scheme
------------------

.. inheritance-diagram:: ocd.states