.. _py-causality/Flow:

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

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

.. class:: CausalityFlowQuery

    Representation of a query for a DAG that can be folded back into a given flow.
    The query is based on a derivation graph and can thus be used for any flow solution
    from a model based on that derivation graph.

    .. method:: __init__(dg)

        Construct a query with multiplicity 1 and no borrowing.

        :raises: :class:`LogicError` if ``dg`` is ``None``.
    .. attribute:: dg

        (Read-only) The underlying derivation graph.

        :type: DG
    .. attribute:: multiplicity

        Access the multiplicity of the query. It must be at least 1.

        :type: int
        :raises: (set) :class:`LogicError` if assigned a number less than 1.
    .. method:: __setitem__(v, count)
                   __setitem__(g, count)

        Set the amount of flow allowed to be borrowed at a given vertex.
        The version taking a graph as argument is equivalent to ``self[dg.findVertex(g)]``.

        :param DGVertex v: a vertex in the derivation graph the query is intended for.
        :param Graph g: a graph representing a vertex in the derivation graph the query is intended for.
        :param int count: the amount of tokens to allowed to be borrowed in a solution.
    .. method:: __getitem__(v)
                   __getitem__(g)

        :param DGVertex v: a vertex in the derivation graph the query is intended for.
        :param Graph g: a graph representing a vertex in the derivation graph the query is intended for.
        :rtype: int
        :returns: the amount of flow allowed to be borrowed at a given vertex.
            The version taking a graph as argument is equivalent to ``self[dg.findVertex(g)]``.
    .. attribute:: constrainRouting

        Access whether transit edges must conform to the routing expressed by the flow.
        Setting this to ``false`` may give results violating flow constraints.
    .. :method:: findDAG(s)

        :param FlowSolution s: the flow solution to query for a causality DAG.
        :returns: a causality DAG that can be folded back into the given flow solution,
            using the query settings in this object, if one can be found.
        :rtype: Optional[CausalityDAG]
        :raises: :class:`LogicError` if any graph ``g`` given to :func:`setBorrow` with non-zero count
            is not a vertex in the underlying derivation graph of the given flow solution,
            i.e., if `s.getFlow()->getDG()->findVertex(g)` returns a null vertex.