.. _cpp-causality/Petri:

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

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


Class ``causality::PetriNet``
--------------------------------------------------------------------------------------------------------------------------------

.. class:: causality::PetriNet
    

    Adaptation of a derivation graph into a Petri net.
    Importantly, if the underlying derivation graph is enlarged then
    :func:`syncSize` must be called before calling certain other
    methods on the object.


Synopsis
^^^^^^^^

.. code-block:: c++
    
    class MOD_DECL PetriNet {
        explicit PetriNet(std::shared_ptr<dg::DG> dg_);
    public:
        ~PetriNet();
        std::shared_ptr<dg::DG> getDG() const;
        const lib::causality::PetriNet &getNet() const;
        void syncSize();
        std::vector<dg::DG::Vertex> getPostPlaces(dg::DG::HyperEdge e) const;
    public:
        static std::shared_ptr<PetriNet> make(std::shared_ptr<dg::DG> dg_);
    private:
        struct Pimpl;
        std::unique_ptr<Pimpl> p;
    };

Details
^^^^^^^

.. cpp:namespace-push:: causality::PetriNet

.. function:: std::shared_ptr<dg::DG> getDG() const

    :returns: the underlying derivation graph.
.. function:: void syncSize()

    Enlarges the internal data structures to the current size of the underlying derivation graph.
.. function:: std::vector<dg::DG::Vertex> getPostPlaces(dg::DG::HyperEdge e) const

    :returns: a list of unique targets for the given hyperedge.

    Requires :func:`syncSize` to have been called since the last time the underlying derivation graph has changed size.
.. function:: static std::shared_ptr<PetriNet> make(std::shared_ptr<dg::DG> dg_)

    Calls :func:`syncSize`.

    :returns: a new Petri net, adapting the given derivation graph.
    :throws: :class:`LogicError` if `dg_` is null.
    :throws: :class:`LogicError` if neither `dg_->hasActiveBuilder()` nor `dg_->isLocked()`.

.. cpp:namespace-pop::


Class ``causality::PetriNetMarking``
--------------------------------------------------------------------------------------------------------------------------------

.. class:: causality::PetriNetMarking
    

    Representation of a marking on a Petri net.
    Importantly, if the underlying derivation graph is enlarged then
    :func:`syncSize` must be called before calling certain other
    methods on the object.


Synopsis
^^^^^^^^

.. code-block:: c++
    
    struct MOD_DECL PetriNetMarking {
        explicit PetriNetMarking(std::shared_ptr<PetriNet> net);
        // pre: &net->getNet() == &marking.getNet()
        explicit PetriNetMarking(std::shared_ptr<PetriNet> net, const lib::causality::PetriNetMarking &marking);
        ~PetriNetMarking();
        PetriNetMarking(PetriNetMarking&&);
        PetriNetMarking &operator=(PetriNetMarking&&);
        PetriNetMarking(const PetriNetMarking&);
        PetriNetMarking &operator=(const PetriNetMarking&);
        std::shared_ptr<PetriNet> getNet() const;
        const lib::causality::PetriNetMarking &getMarking() const;
        void syncSize();
        MOD_DECL friend std::ostream &operator<<(std::ostream &s, const PetriNetMarking &m);
        int add(dg::DG::Vertex v, int c);
        int remove(dg::DG::Vertex v, int c);
        int operator[](dg::DG::Vertex v) const;
        int getNumTokens() const;
        std::vector<dg::DG::HyperEdge> getAllEnabled() const;
        std::vector<dg::DG::Vertex> getNonZeroPlaces() const;
        std::vector<dg::DG::Vertex> getEmptyPostPlaces(dg::DG::HyperEdge e) const;
        bool isEnabled(dg::DG::HyperEdge e) const;
        void fire(dg::DG::HyperEdge e);
    private:
        struct Pimpl;
        std::unique_ptr<Pimpl> p;
    };

Details
^^^^^^^

.. cpp:namespace-push:: causality::PetriNetMarking

.. function:: explicit PetriNetMarking(std::shared_ptr<PetriNet> net)

    :throws: :class:`LogicError` if `net` is null.
.. function:: std::shared_ptr<PetriNet> getNet() const

    :returns: the underlying Petri net.
.. function:: void syncSize()

    Enlarges the internal data structures to the current size of the underlying derivation graph.

    Calls `getNet().syncSize()`.
.. function:: friend std::ostream &operator<<(std::ostream &s, const PetriNetMarking &m)

    Requires :func:`syncSize` to have been called since the last time the underlying derivation graph has changed size.
.. function:: int add(dg::DG::Vertex v, int c)

    Add `c` tokens on the place `v`.

    :returns: the new total token count on `v`.
    :throws: :class:`LogicError` if `!v`.
    :throws: :class:`LogicError` if `v.getDG() != getNet()->getDG()`.
    :throws: :class:`LogicError` if `c < 0`.

    Requires :func:`syncSize` to have been called since the last time the underlying derivation graph has changed size.
.. function:: int remove(dg::DG::Vertex v, int c)

    Remove `c` tokens from the place `v`.

    :returns: the new total token count on `v`.
    :throws: :class:`LogicError` if `!v`.
    :throws: :class:`LogicError` if `v.getDG() != getNet()->getDG()`.
    :throws: :class:`LogicError` if `c < 0`.
    :throws: :class:`LogicError` if not enough tokens are left to remove all `c`.

    Requires :func:`syncSize` to have been called since the last time the underlying derivation graph has changed size.
.. function:: int operator[](dg::DG::Vertex v)

    :returns: the token count for `v`.
    :throws: :class:`LogicError` if `!v`.
    :throws: :class:`LogicError` if `v.getDG() != getNet()->getDG()`.

    Requires :func:`syncSize` to have been called since the last time the underlying derivation graph has changed size.
.. function:: int getNumTokens() const

    :returns: the total number of tokens in the marking.
.. function:: std::vector<dg::DG::HyperEdge> getAllEnabled() const

    :returns: a list of all hyperedges currently enabled for firing.
.. function:: std::vector<dg::DG::Vertex> getNonZeroPlaces() const

    :returns: a list of all vertices with tokens.
.. function:: std::vector<dg::DG::Vertex> getEmptyPostPlaces(dg::DG::HyperEdge e) const

    :returns: a list of all target vertices of the given hyperedge that do not have any tokens.
        The list represents a set, so if vertex is a target multiple times it will only be included once.
    :throws: :class:`LogicError` if `!e`.
    :throws: :class:`LogicError` if `e.getDG() != getNet()->getDG()`.
.. function:: bool isEnabled(dg::DG::HyperEdge e) const

    :returns: whether the given hyperedge is enabled for firing.
    :throws: :class:`LogicError` if `!e`.
    :throws: :class:`LogicError` if `e.getDG() != getNet()->getDG()`.
.. function:: void fire(dg::DG::HyperEdge e)

    Fire the given edge.

    :throws: :class:`LogicError` if `!e`.
    :throws: :class:`LogicError` if `e.getDG() != getNet()->getDG()`.
    :throws: :class:`LogicError` if `!isEnabled(e)`.

.. cpp:namespace-pop::