cramph.compiled_tick
====================

.. py:module:: cramph.compiled_tick


Classes
-------

.. autoapisummary::

   cramph.compiled_tick.PassInputKind
   cramph.compiled_tick.PassInput
   cramph.compiled_tick.LifeCycleChange
   cramph.compiled_tick.CompiledTick


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

.. py:class:: PassInputKind

   Bases: :py:obj:`enum.StrEnum`


   A value per node that a pass through the statechart reads on top of the life
   cycle, observation and last observation states.


   .. py:attribute:: LIFE_CYCLE_AT_CYCLE_START
      :value: 'life_cycle_at_cycle_start'


      The life cycle state the node entered the tick with.



   .. py:attribute:: TICK_OBSERVATION
      :value: 'tick_observation'


      What :meth:`~cramph.node.StatechartNode.on_tick`
      returned for the node this tick.



   .. py:attribute:: HAS_TICK_OBSERVATION
      :value: 'has_tick_observation'


      Whether :meth:`~cramph.node.StatechartNode.on_tick`
      returned an observation for the node this tick.



   .. py:attribute:: OWN_TRANSITION_TAKEN
      :value: 'own_transition_taken'


      Whether the node already took a transition triggered by its own conditions this
      tick.



.. py:class:: PassInput

   One value per node of a statechart that a pass reads, together with the
   variables standing for it in the compiled pass.


   .. py:attribute:: variables
      :type:  list[krrood.symbolic_math.symbolic_math.FloatVariable]

      The variable of every node, in node order.



   .. py:attribute:: data
      :type:  numpy.typing.NDArray[numpy.float64]

      The value of every node, in node order.



   .. py:method:: create(kind: PassInputKind, nodes: list[cramph.node.StatechartNode]) -> Self
      :classmethod:


      :param kind: What the values stand for.
      :param nodes: The nodes to hold a value for, in node order.
      :return: An input holding zero for every node.



.. py:class:: LifeCycleChange

   One node changing its life cycle state during a pass.


   .. py:attribute:: node
      :type:  cramph.node.StatechartNode

      The node whose life cycle state changed.



   .. py:attribute:: previous_state
      :type:  cramph.data_types.LifeCycleValues

      The life cycle state before the change.



   .. py:attribute:: new_state
      :type:  cramph.data_types.LifeCycleValues

      The life cycle state after the change.



   .. py:method:: run_callback() -> None

      Calls the callback of :attr:`node` that matches this change, e.g.
      :meth:`~StatechartNode.on_start`. A node that starts paused gets
      :meth:`~StatechartNode.on_start` and then
      :meth:`~StatechartNode.on_pause`. A change with no dedicated callback calls
      nothing.



.. py:class:: CompiledTick

   Brings every node of a statechart to the state it reaches in one tick.

   One compiled pass updates every node at once, reading the states the previous pass
   left. Passes repeat until no state changes, so how deeply nodes are nested does not
   change when they react to each other. Within a pass:

   1. A node observes if it was running when the tick started and is still
      running or paused. Its observation expression reads the states of the previous
      pass. A node that was paused when the tick started and is still running
      or paused keeps its observation. A node that stopped running during this tick keeps
      the observation it stopped on until the next one. Every other node
      observes Unknown.
   2. A node that has neither ended nor started the tick ended takes over its
      observation as its last observation.
   3. Every node takes its next life cycle transition, reading the observations of this
      pass and the life cycle state its parent reaches in this pass. A node takes at
      most one transition triggered by its own conditions per tick;
      transitions its parent forces on it always happen.

   .. note:: Life cycle callbacks run afterwards, once per change and in the order the
       changes happened, so no Python code runs between passes.


   .. py:attribute:: statechart
      :type:  cramph.statechart.Statechart

      The statechart whose nodes are updated.



   .. py:method:: compile() -> None

      Builds one pass through the statechart, compiles it and binds its inputs
      to the state arrays it reads, and to the world and float variable data of the
      context of :attr:`statechart`.



   .. py:method:: settle() -> list[LifeCycleChange]

      Runs passes until neither a life cycle state nor an observation changes, writing
      the result of every pass into the statechart.

      :return: Every life cycle change, in the order it happened.
      :raises TickDoesNotSettleError: If a pass returns the statechart
          to a state it already had in this tick, which it would then never
          leave, or if more passes than :attr:`_pass_budget` change it.