.. _py-dg/VertexMapper:

**********************************************************
dg/VertexMapper
**********************************************************
.. default-domain:: py

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

.. class:: DGVertexMapper

    A class for enumerating all valid vertex maps for a given :class:`DGHyperEdge`.
    That is, for such a hyperedge, collect the graphs associated with
    respectively the source and target vertices, and create the disjoint union of those graphs.
    Let the result be the graphs :math:`G'` and :math:`H'`.
    Then each rule :math:`p = (L\leftarrow K\rightarrow R)` associated with the hyperedge,
    generate direct derivations :math:`G\overset{p, m}{\Rightarrow} H`
    where :math:`G` is isomorphic to :math:`G'` and :math:`H` is isomorphic to :math:`H'`.

    Each recorded vertex map is a map :math:`V(G) \rightarrow V(H)`.
    Those maps are available in this class.

    .. method:: __init__(e, upToIsomorphismG=True, leftLimit=1, rightLimit=2**30)

        Construct a vertex map holder. It will immediately calculate all vertex maps for the derivations underlying the
        given hyperedge.
        By default all maps :math:`V(G) \rightarrow V(H)` are enumerated.
        To only enumerate a singular vertex map per rule, use ``upToIsomorphismG = True`` and ``leftLimit = rightLimit = 1``.

        :param DGHyperEdge e: the hyperedge to construct vertex maps for.
        :param bool upToIsomrophismG: whether to enumerate all :math:`m`, or just those such that all bottom spans
            :math:`(G\leftarrow D\rightarrow H)` up to isomorphism are generated.
        :param int leftLimit: after bottom span generation, find this many isomorphisms back to the sources of the hyperedge.
        :param int rightLimit: after bottom span generation, find this many isomorphisms back to the targets of the hyperedge.
        :raises: :class:`LogicError` if ``not e``.
    .. attribute:: edge

        (Read-only) The hyperedge to calculate vertex maps for.

        :type: DGHyperEdge
    .. attribute:: left
                   right

        :returns: the disjoint union of graphs from respectively the source and target vertices of the hyperedge.
            That is, the graphs :math:`G` and :math:`H` that are the domain and codomain graphs of the calculated
            vertex maps.
        :type: UnionGraph
    .. method:: __iter__()

        :returns: an iterator over the vertex maps,
            see :meth:`__getitem__` for the specific type.
    .. attribute:: size

        (Read-only) The number of vertex maps calculated.

        :type: int
    .. method:: __len__()

        :returns: :attr:`size`
        :rtype: int
    .. method:: __getitem__(i)

        :param int i: the index of the map to retrieve.
        :returns: the ``i``\ th vertex map.
        :rtype: Result
        :raises: :class:`LogicError` if ``i`` is out of range.
.. class:: DGVertexMapper.Result

    The value type returned for each vertex map.
    the rule used to generate the map, and then the actual map.

    .. attribute:: rule

        The rule used to generate the map.

        :type: Rule
    .. attribute:: map

        The actual vertex map :math:`V(G) \rightarrow V(H)`.

        :type: VertexMapUnionGraphUnionGraph