.. _py-causality/DGPetri:

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

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

.. class:: DGPetriNet

    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.

    .. method:: __init__(dg)

        Calls :meth:`syncSize`.

        :param DG dg: the derivation graph to adapt.
        :returns: a new Petri net, adapting the given derivation graph.
        :raises: :class:`LogicError` if ``dg`` is ``None``.
        :raises: :class:`LogicError` if neither ``dg.hasActiveBuilder`` nor ``dg.locked``.
    .. attribute:: dg

        (Read-only) The underlying derivation graph.

        :type: DG
    .. method:: syncSize()

        Enlarges the internal data structures to the current size of the underlying derivation graph.
    .. method:: getPostPlaces(e)

        :param DGHyperEdge e: the hyperedge to find unique targets for.
        :returns: a list of unique targets for the given hyperedge.
        :rtype: list[DGVertex]

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

    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.

    .. method:: __init__(net)

        :param DGPetriNet net: the Petri net to construct a marking for.
        :raises: :class:`LogicError` if ``net`` is ``None``.
    .. attribute:: net

        (Read-only) The underlying Petri net.

        :type: DGPetriNet
    .. method:: syncSize()

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

        Calls ``net.syncSize()``.
    .. method:: __eq__()
    .. method:: add(v, c)

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

        :param DGVertex v: the place to add tokens to.
        :param int c: the amount of tokens to add.
        :returns: the new total token count on `v`.
        :rtype: int
        :raises: :class:`LogicError` if ``not v``.
        :raises: :class:`LogicError` if ``v.dg != self.net.dg``.
        :throws: :class:`LogicError` if ``c < 0``.

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

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

        :param DGVertex v: the place to remove tokens from.
        :param int c: the amount of tokens to remove.
        :returns: the new total token count on `v`.
        :rtype: int
        :raises: :class:`LogicError` if ``not v``.
        :raises: :class:`LogicError` if ``v.dg != self.net.dg``.
        :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.
    .. method:: __getitem__(v)

        :param DGVertex v: the place to remove tokens from.
        :returns: the token count for `v`.
        :rtype: int
        :raises: :class:`LogicError` if ``not v``.
        :raises: :class:`LogicError` if ``v.dg != self.net.dg``.

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

        (Read-only) The total number of tokens in the marking.

        :type: int
    .. method:: getAllEnabled()

        :returns: a list of all hyperedges currently enabled for firing.
        :rtype: list[DGHyperEdge]
    .. method:: getNonZeroPlaces()

        :returns: a list of all vertices with tokens.
        :rtype: list[DGVertex]
    .. method:: getEmptyPostPlaces(e)

        :param DGHyperEdge e: the edge to query for empty post places.
        :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.
        :rtype: list[DGVertex]
        :raises: :class:`LogicError` if ``not e``.
        :raises: :class:`LogicError` if ``e.dg != self.net.dg``.
    .. method:: isEnabled(e)

        :param DGHyperEdge e: the edge to query for being enabled.
        :returns: whether the given hyperedge is enabled for firing.
        :rtype: bool
        :raises: :class:`LogicError` if ``not e``.
        :raises: :class:`LogicError` if ``e.dg != self.net.dg``.
    .. method:: fire(e)

        :param DGHyperEdge e: the edge to fire.
        :raises: :class:`LogicError` if ``not e``.
        :raises: :class:`LogicError` if ``e.dg != self.net.dg``.
        :raises: :class:`LogicError` if ``not self.isEnabled(e)``.