.. _cpp-causality/Stochsim:

**********************************************************
causality/Stochsim.hpp
**********************************************************
.. default-domain:: cpp
.. default-role:: cpp:expr

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


Class ``causality::MassActionKinetics``
--------------------------------------------------------------------------------------------------------------------------------

.. 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`.


Synopsis
^^^^^^^^

.. code-block:: c++
    
    struct MOD_DECL MassActionKinetics {
        MassActionKinetics(std::shared_ptr<dg::DG> dg_, std::function<double(dg::DG::HyperEdge)> rate);
        ~MassActionKinetics();
        MassActionKinetics(MassActionKinetics &&);
        MassActionKinetics &operator=(MassActionKinetics &&);
        MassActionKinetics(const MassActionKinetics &);
        MassActionKinetics &operator=(const MassActionKinetics &);
        void syncSize();
        std::pair<dg::DG::HyperEdge, double>
        draw(const std::vector<dg::DG::HyperEdge> &possibles, const PetriNetMarking &m);
    private:
        struct Pimpl;
        std::unique_ptr<Pimpl> p;
    };

Details
^^^^^^^

.. cpp:namespace-push:: causality::MassActionKinetics

.. function:: MassActionKinetics(std::shared_ptr<dg::DG> dg_, std::function<double(dg::DG::HyperEdge)> 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.

    :throws: :class:`LogicError` if `!dg_`.
    :throws: :class:`LogicError` if neither `dg_->hasActiveBuilder()` nor `dg_->isLocked()`.
    :throws: :class:`LogicError` if `!rate`.
.. function:: void syncSize()

    Enlarges the internal data structures to the current size of the underlying derivation graph.
.. function:: std::pair<dg::DG::HyperEdge, double> \
              draw(const std::vector<dg::DG::HyperEdge> &possibles, const PetriNetMarking &m)

    :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.

    :throws: :class:`LogicError` if `possibles.empty()`.
    :throws: :class:`LogicError` if an edge in `possibles` is null.
    :throws: :class:`LogicError` if an edge in `possibles` does not belong to the underlying derivation graph.
    :throws: :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.

.. cpp:namespace-pop::


Class ``causality::EventTrace``
--------------------------------------------------------------------------------------------------------------------------------

.. class:: causality::EventTrace
    

    A helper class to hold an initial state with a subsequent trace of events.
    An event is either a reaction/hyperedge being performed (an :class:`EdgeEvent`)
    or a transfer of tokens out or in to the system (a :class:`TransferEvent`).


Synopsis
^^^^^^^^

.. code-block:: c++
    
    struct MOD_DECL EventTrace {
        struct EdgeEvent {
            double time;
            dg::DG::HyperEdge edge;
        public:
            MOD_DECL friend bool operator==(const EdgeEvent &a, const EdgeEvent &b);
            MOD_DECL friend bool operator!=(const EdgeEvent &a, const EdgeEvent &b);
            MOD_DECL friend std::ostream &operator<<(std::ostream &s, const EdgeEvent &e);
        };
        struct TransferEvent {
            double time;
            dg::DG::Vertex vertex;
            int count;
        public:
            MOD_DECL friend bool operator==(const TransferEvent &a, const TransferEvent &b);
            MOD_DECL friend bool operator!=(const TransferEvent &a, const TransferEvent &b);
            MOD_DECL friend std::ostream &operator<<(std::ostream &s, const TransferEvent &e);
        };
        using Event = boost::variant<EdgeEvent, TransferEvent>;
        struct iterator : boost::iterator_facade<iterator, Event, std::random_access_iterator_tag, Event> {
            iterator();
            iterator(const EventTrace *t, int offset);
        private:
            friend class boost::iterator_core_access;
            Event dereference() const;
            bool equal(iterator other) const;
            void increment();
            // TODO: implement the rest to make it a true random-access iterator
            void advance(int n);
        private:
            const EventTrace *t;
            int offset;
        };
        using const_iterator = iterator;
    public:
        EventTrace(const PetriNetMarking &initialState);
        ~EventTrace();
        EventTrace(EventTrace &&);
        EventTrace &operator=(EventTrace &&);
        EventTrace(const EventTrace &);
        EventTrace &operator=(const EventTrace &);
    public:
        PetriNetMarking getInitialState() const;
        int size() const;
        const_iterator begin() const;
        const_iterator end() const;
        Event operator[](int i) const;
        MOD_DECL friend std::ostream &operator<<(std::ostream &s, const EventTrace &t);
    public:
        void addEdge(double time, dg::DG::HyperEdge e);
        void addTransfer(double time, dg::DG::Vertex v, int count);
    public:
        std::string print() const;
    private:
        struct Pimpl;
        std::unique_ptr<Pimpl> p;
    };

Details
^^^^^^^

.. cpp:namespace-push:: causality::EventTrace

.. type:: Event = boost::variant<EdgeEvent, TransferEvent>
.. type:: iterator
          const_iterator = iterator
.. function:: EventTrace(PetriNetMarking initialState)

    Construct an empty event trace with an initial state.
    A copy of the given marking is being stored.
.. function:: PetriNetMarking getInitialState() const

    :returns: a copy of the initial state for this event trace.
.. function:: int size() const

    :returns: the number of events in the trace.
.. function:: const_iterator begin() const
              const_iterator end() const

    :returns: the begin/end iterator for the range of events in the trace.
.. function:: Event operator[](int i) const

    :returns: the `i`\ th event in the trace.
    :throws: :class:`LogicError` if `i` is out of bounds.
.. function:: friend std::ostream &operator<<(std::ostream &s, const EventTrace &t)
.. function:: void addEdge(double time, dg::DG::HyperEdge e)

    Append an edge event to the trace.

    :throws: :class:`LogicError` if `!e`.
    :throws: :class:`LogicError` if `e` does not belong to the underlying derivation graph.
.. function:: void addTransfer(double time, dg::DG::Vertex v, int count)

    Append a transfer event to the trace.
    The `count` may be negative for extraction and positive for input.

    :throws: :class:`LogicError` if `!v`.
    :throws: :class:`LogicError` if `v` does not belong to the underlying derivation graph.
.. function:: std::string print() const

    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.

.. cpp:namespace-pop::


Class ``causality::EventTrace::EdgeEvent``
---------------------------------------------------------------

.. class:: causality::EventTrace::EdgeEvent


    .. var:: double time
    .. var:: dg::DG::HyperEdge edge


Class ``causality::EventTrace::TransferEvent``
---------------------------------------------------------------

.. class:: causality::EventTrace::TransferEvent

    .. var:: double time
    .. var:: dg::DG::Vertex vertex
    .. var:: int count