.. _py-causality/RealisabilityQuery:

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

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

.. class:: causality.RealisabilityQuery

    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.

    See also [ABFFMS-Realisability]_.

    .. 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[self.dg.findVertex(g)]``.

        :param DG.Vertex 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 DG.Vertex 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[self.dg.findVertex(g)]``.
    .. attribute:: respectTransit

        Access whether transit edges must conform to how they are used in the flow.
        Setting this to ``False`` may give results violating flow constraints.
    .. method:: findDAG(s)

        :param hyperflow.Solution 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[DAG]
        :raises: :class:`LogicError` if any graph ``g`` given as ``self[g]`` with non-zero count
            is not a vertex in the underlying derivation graph of the given flow solution,
            i.e., if ``self.dg.findVertex(g)`` returns a null vertex.