.. _py-causality/Stochsim:

**********************************************************
causality/Stochsim
**********************************************************
.. default-domain:: py

.. py:currentmodule:: mod
.. cpp:namespace:: mod


Class ``MassActionKinetics``
--------------------------------------------------------------------------------------------------------------------------------

.. py:class:: MassActionKinetics

    A helper class for performing stochastic simulations where
    events are drawn according to the law of mass action.
    Importantly, if the underlying derivation graph is enlarged then
    :func:`syncSize` must be called before calling :func:`draw`.

.. py:function:: __init__(dg, rate)

    Construct a new instance, based on the given derivation graph.
    When evaluating reactions/hyperedges, the given callback is used to set the reaction rate.
    This rate may be cached by the object.

    :param DG dg: the underlying derivation graph.
    :param rate: the rate callback or constant.
    :type rate: Callable[[DGHyperEdge], float] or float
    :raises: :class:`LogicError` if ``not dg``.
    :raises: :class:`LogicError` if neither ``dg.hasActiveBuilder`` nor ``dg.locked``.

    .. method:: syncSize()

        Enlarges the internal data structures to the current size of the underlying derivation graph.
    .. method:: draw(possibles, m)

        :param possibles: the list of hyperedges to draw from.
        :type possibles: list[DGHyperEdge]
        :param PetriNetMarking m: the population to take into account.
        :returns: one of the given hyperedges, randomly selected according to the low of mass action
            based on the given population/marking and the reaction rates.
            The second returned component is the sum of reactivity for the given reactions/hyperedges.

            Use :func:`rngReseed` to seed the pseudo-random bit generator used for the selection.
        :rtype: tuple[DGHyperEdge, float]
        :raises: :class:`LogicError` if ``possibles`` is empty.
        :raises: :class:`LogicError` if an edge in ``possibles`` is null.
        :raises: :class:`LogicError` if an edge in ``possibles`` does not belong to the underlying derivation graph.
        :raises: :class:`LogicError` if ``m`` is not a marking on the underlying derivation graph.

        Requires :func:`syncSize` to have been called since the last time the underlying derivation graph has changed size.

Class ``EventTrace``
--------------------------------------------------------------------------------------------------------------------------------

.. py:class:: EventTrace

    A representation of a trace of events starting from an initial marking.
    An event is either a reaction/hyperedge being performed
    or a transfer of tokens out or in to the system.

    .. method:: __init__(initialState)

        Construct an empty event trace with an initial state.
        A copy of the given marking is being stored.

        :param PetriNetMarking initialState: the marking to used as the initial state.
    .. attribute:: initialState

        (Read-only) Read a copy of the initial state for this event trace.

        :type: PetriNetMarking
    .. method:: __len__()

        :returns: the number of events in the trace.
        :rtype: int
    .. method:: __getitem__()

        :returns: the ``i``\ th event in the trace.
        :rtype: EdgeEvent or TransferEvent
        :raises: :class:`LogicError` if ``i`` is out of bounds.
    .. method:: __str__()
    .. method:: addEdge(time, e)

        Append an edge event to the trace.

        :param float time: the time associated with the event.
        :param DGHyperEdge e: the hyperedge implementing the event
        :raises: :class:`LogicError` if ``not e``.
        :raises: :class:`LogicError` if ``e`` does not belong to the underlying derivation graph.
    .. method:: addTransfer(time, v, count)

        Append an edge event to the trace.

        :param float time: the time associated with the event.
        :param DGVertex v: the vertex to transfer.
        :param int count: the number of copies of `v` to transfer.
            It may be negative for extraction and positive for input.
        :raises: :class:`LogicError` if ``not v``.
        :raises: :class:`LogicError` if ``v`` does not belong to the underlying derivation graph.
    .. method:: print()

    Create a plot of the counts throughout the event trace at each time point.
    If the times given to :func:`addEdge` and :func:`addTransfer` at any point were decreasing
    or below 0, the resulting plot may fail to compile or look strange.

    :returns: the filename for the PDF that will be compiled by the post processor.
    :rtype: str

Class ``EventTrace.EdgeEvent``
--------------------------------------------------------------------------------------------------------------------------------

.. py:class:: EventTrace.EdgeEvent

    A representation of an edge event in an event trace.

    .. attribute:: time

        (Read-only) the associated time for the event.

        :type: float
    .. attribute:: edge

        (Read-only) the hyperedge for the event.

        :type: DGHyperEdge

Class ``EventTrace.TransferEvent``
--------------------------------------------------------------------------------------------------------------------------------

.. py:class:: EventTrace.TransferEvent

    A representation of a trasfer event in an event trace.

    .. attribute:: time

        (Read-only) the associated time for the event.

        :type: float
    .. attribute:: vertex

        (Read-only) the vertex being transferred.

        :type: DGVertex
    .. attribute:: count

        (Read-only) the amount being transferred.
        It is negative for extraction and positive for input.

        :type: int