.. _py-dg/VertexMapper:

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

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

.. class:: DGVertexMapper

    A class for enumerating vertex maps for a given :class:`DG.HyperEdge`.

    For the given 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`, available via `DGVertexMapper.left` and `DGVertexMapper.right` respectively.
    Then each rule :math:`p = (L\leftarrow K\rightarrow R)` associated with the hyperedge,
    generate direct derivations :math:`\require{mathtools} G\xRightarrow{p, m} H'`.
    An isomorphism :math:`H'\rightarrow H` is then found to ensure we have generated the correct product.
    Each result can be described in the following commutative diagram.

    .. tikz:: A diagram describing each result generated by the vertex mapper.
        A consists of a double-pushout diagram for a direct derivation :math:`G\xRightarrow{p, m} H'`
        and an isomorphism :math:`H'\rightarrow H`.

        \matrix[matrix of math nodes, row sep=4em, column sep=4em]{
            |(L)| L        \& |(K)| K        \& |(R)| R    \\
            |(G)| G        \& |(D)| D        \& |(H')| H\smash{'}    \& |(H)| H    \\
        };
        \foreach \s/\t in {K/L, K/R, K/D} {
            \draw[->] (\s) to (\t);
        }
        \draw[->] (L) to node[auto] {$m$} (G);
        \draw[->] (D) to node[above] {$g\vphantom{h}$} (G);
        \draw[->] (D) to node[above] {$h\vphantom{g}$} (H');
        \draw[->] (R) to node[auto] {$a$} (H');
        \draw[->] (H') to node[auto] {$b$} (H);
        \draw[->] (R) to node[auto] {$m' = b\circ a$} (H);

    Each result is available in the form of three vertex maps:

    - :py:attr:`~DGVertexMapper.Result.map` (:math:`V(G) \rightarrow V(H)`): the vertex map of the derivation,
      which maps vertices of the input graph :math:`G` to the product graph :math:`H`.
      The map is defined as the composition :math:`b\circ h\circ g^{-1}`.
      Note that if the rule :math:`p` either creates or removes vertices, then the map is partial.
      As all morphisms are injective, the vertex map is as well.
    - :py:attr:`~DGVertexMapper.Result.match` (:math:`m\colon L\rightarrow G`): the match morphism.
    - :py:attr:`~DGVertexMapper.Result.comatch` (:math:`m'\colon L\rightarrow H`): the comatch morphism.
      It is defined as the composition :math:`b\circ a`.

    The vertex mapper can be configured in two ways via the constructor:

    - ``upToIsomorphismGDH``: this controls which spans :math:`G\leftarrow D\rightarrow H'` and match morphisms :math:`m\colon L\rightarrow G`
      are enumerated. When set `true` only a single representative of the span is generated per isomorphism class.
    - ``rightLimit``: this controls the amount of isomorphisms :math:`b\colon H'\rightarrow H` are generated.

    For example:

    - If you just want a single result, then use ``upToIsomorphismGDH = True`` and ``rightLimit = 1``.
    - If you want all different vertex maps :math:`V(G)\rightarrow V(H)`,
      then use ``upToIsomorphismGDH = True`` and ``rightLimit`` set to some arbitrary high value, e.g., :math:`2^{30}`.
    - If you are interested in all the different ways the rule can be matched to generate this direct derivation,
      but do not care about the specific vertex map :math:`V(G)\rightarrow V(H)`,
      then use ``upToIsomorphismGDH = False`` and ``rightLimit = 1``.
    - And finally, if you want all possible results,
      then use ``upToIsomorphismGDH = False`` and set ``rightLimit`` to some high value, e.g., :math:`2^{30}`.

    .. method:: __init__(e, upToIsomorphismGDH=True, rightLimit=2**30)

        Construct a vertex map holder, and immediately calculate vertex maps for the derivations underlying the
        given hyperedge.

        :param DG.HyperEdge e: the hyperedge to construct vertex maps for.
        :param bool upToIsomorphismGDH: whether to only enumerate spans :math:`G \leftarrow D\rightarrow H'` up to isomorphism, all :math:`m`, or just those such that all bottom spans
            :math:`(G\leftarrow D\rightarrow H)` up to isomorphism are generated.
            Defaults to ``True``.
        :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: DG.HyperEdge
    .. 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`.
        :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 result.

    .. attribute:: rule

        The rule used to generate the map.

        :type: Rule
    .. attribute:: map

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

        :type: VertexMapUnionGraphUnionGraph
    .. attribute:: match

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

        :type: VertexMapRuleLeftGraphUnionGraph
    .. attribute:: comatch

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

        :type: VertexMapRuleRightGraphUnionGraph