.. _py-causality/Stochsim:

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

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

.. class:: causality.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`.

    .. method:: __init__(dg, inputRate, reactionRate, outputRate)

        Construct a new instance, based on the given derivation graph.
        The return value of the rate callbacks must be 1) the rate and 2) a boolean telling whether
        the library should cache the rate. If ``True`` no more calls with the same argument will be made.

        :param DG dg: the underlying derivation graph.
        :param inputRate: the injection rate callback or constant.
        :type inputRate: Callable[[DG.Vertex], tuple[float, bool]] or tuple[float, bool]
        :param reactionRate: the reaction rate callback or constant.
        :type reactionRate: Callable[[DG.Vertex], tuple[float, bool]] or tuple[float, bool]
        :param outputRate: the drain rate callback or constant.
        :type outputRate: Callable[[DG.Vertex], tuple[float, bool]] or tuple[float, bool]
        :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(m)

        :param Marking m: the population to take into account.
        :returns: one of the hyperedges enabled in ``m``, 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.

            If no events are possible, then the second component is 0.

            Use :func:`rngReseed` to seed the pseudo-random bit generator used for the selection.
        :rtype: tuple[Union[EdgeAction, InputAction, OutputAction], float]
        :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.