.. _cpp-dg/VertexMapper:

**********************************************************
dg/VertexMapper.hpp
**********************************************************
.. default-domain:: cpp
.. default-role:: cpp:expr

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


Class ``dg::VertexMapper``
--------------------------------------------------------------------------------------------------------------------------------

.. class:: dg::VertexMapper
    

    A class for enumerating all valid vertex maps for a given :class:`dg::DG::HyperEdge`.
    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.


Synopsis
^^^^^^^^

.. alias:: dg::VertexMapper
    :maxdepth: 2
    :noroot:


Details
^^^^^^^

.. cpp:namespace-push:: dg::VertexMapper

.. type:: Map = VertexMap<graph::Union, graph::Union>;

    The vertex map type.
.. class:: Result

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

    .. var:: std::shared_ptr<rule::Rule> r

        The rule used to generate the map.
    .. var:: Map map

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

    A random-access iterator over :type:`Result`\ s.
.. type:: const_iterator = iterator
.. function:: VertexMapper(DG::HyperEdge e)
              VertexMapper(DG::HyperEdge e, bool upToIsomorphismG, int leftLimit, int rightLimit, int verbosity)

    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 e: the hyperedge to construct vertex maps for.
    :param 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.
        Defaults to `true`.
    :param leftLimit: after bottom span generation, find this many isomorphisms back to the sources of the hyperedge.
        Defaults to 1.
    :param rightLimit: after bottom span generation, find this many isomorphisms back to the targets of the hyperedge.
        Defaults to :math:`2^{30}`.
    :param verbosity: the level of debug information to print. Defaults to 0.

        - 0 (or less): print no information.
        - 1: print debug information within the vertex mapping, but not debug information related to rule composition.
        - 10: also print information for morphism generation for rule composition.
        - 20: also print rule composition information.

    :throws: :class:`LogicError` if `!e`.
.. function:: DG::HyperEdge getEdge() const

    :returns: the hyperedge for which the mapper calculates vertex maps.
.. function:: graph::Union getLeft() const
              graph::Union getRight() const

    :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.
.. function:: const_iterator begin() const
              const_iterator end() const

    :returns: iterators for the range of vertex maps calculated by the mapper.
.. function:: std::size_t size() const

    :returns: `end() - begin()`
.. function:: Result operator[](std::size_t i) const

    :returns: `begin()[i]`
    :throws: :class:`LogicError` if `i >= size()`.

.. cpp:namespace-pop::