Added sublattice generators

It is often useful to find mappings from small qubit topologies into
larger ones.  We provide a set of generators, which enable a user to
easily adapt an emedding found in a small graph, to one found in a
larger graph.  This functionality can be used to implement a tiling
composite, for example.  We provide these functions to find Chimera
sublattices in Chimera, Pegasus and Zephyr, as well as Pegasus
sublattices in Pegasus and Zephyr sublattices in Zephyr.

dwave_networkx/generators/chimera.py

@@ -24,11 +24,15 @@
 
 from dwave_networkx.exceptions import DWaveNetworkXException
 
+from itertools import product
+
 __all__ = ['chimera_graph',
            'chimera_coordinates',
            'find_chimera_indices',
            'chimera_to_linear',
-           'linear_to_chimera']
+           'linear_to_chimera',
+           'chimera_sublattice_mappings',
+           ]
 
 
 def chimera_graph(m, n=None, t=None, create_using=None, node_list=None, edge_list=None, data=True, coordinates=False):
@@ -488,6 +492,15 @@ def graph_to_chimera(self, g):
                 f"Node labeling {labels} not recognized.  Input must be generated by dwave_networkx.chimera_graph."
             )
 
+class __chimera_coordinates_cache_dict(dict):
+    """An internal-use cached factory for `chimera_coordinates` objects"""
+
+    def __missing__(self, key):
+        self[key] = val = chimera_coordinates(*key)
+        return val
+
+
+_chimera_coordinates_cache = __chimera_coordinates_cache_dict()
 
 def linear_to_chimera(r, m, n=None, t=None):
     """Convert the linear index `r` into a chimera index.
@@ -523,7 +536,7 @@ def linear_to_chimera(r, m, n=None, t=None):
     (3, 2, 1, 0)
 
     """
-    return chimera_coordinates(m, n, t).linear_to_chimera(r)
+    return _chimera_coordinates_cache[m, n, t].linear_to_chimera(r)
 
 
 def chimera_to_linear(i, j, u, k, m, n=None, t=None):
@@ -560,4 +573,126 @@ def chimera_to_linear(i, j, u, k, m, n=None, t=None):
     212
 
     """
-    return chimera_coordinates(m, n, t).chimera_to_linear((i, j, u, k))
+    return _chimera_coordinates_cache[m, n, t].chimera_to_linear((i, j, u, k))
+
+
+def _chimera_sublattice_mapping(source_to_chimera, chimera_to_target, offset):
+    """Constructs a mapping from one chimera graph to another, via an offset.
+    This function is used by chimera_sublattice_mappings, and serves to 
+    construct a closure that is stable under iteration therein.
+
+    Parameters
+    ----------
+        source_to_chimera : function
+            A function mapping a source node to a chimera-coordinate 
+        chimera_to_target: function
+            A function mapping a chimera coordinate to a target nodes
+        offset : tuple (int, int)
+            A pair of ints representing the y- and x-offset of the sublattice
+
+    Returns
+    -------
+        mapping : function
+            The function implementing the mapping from the source Chimera
+            graph to the target Chimera graph.  We store ``offset`` in the
+            attribute ``mapping.offset`` for later reconstruction.
+        
+    """
+    y_offset, x_offset = offset
+
+    def mapping(q):
+        y, x, u, k = source_to_chimera(q)
+        return chimera_to_target((y + y_offset, x + x_offset, u, k))
+
+    #store the offset in the mapping, so the user can reconstruct it
+    mapping.offset = offset
+
+    return mapping
+
+
+def chimera_sublattice_mappings(source, target, offset_list=None):
+    """Yields mappings from a Chimera graph into a larger Chimera graph.
+    
+    A sublattice mapping is a function from nodes of a
+    ``chimera_graph(m_s, n_s, t)`` to nodes of a ``chimera_graph(m_t, n_t, t)``
+    with ``m_s <= m_t`` and ``n_s <= n_t``.  This is used to identify subgraphs 
+    of the target Chimera graphs which are isomorphic to the source Chimera
+    graph.  However, if the target graph is not of perfect yield, these 
+    functions do not generally produce isomorphisms (for example, if a node is
+    missing in the target graph, it may still appear in the image of the source
+    graph).
+    
+    Note that we do not produce mappings between Chimera graphs of different
+    tile parameters, and the mappings produced are not exhaustive.  The mappings
+    take the form
+    
+        ``(y, x, u, k) -> (y+y_offset, x+x_offset, u, k)``
+        
+    preserving the orientation and tile index of nodes.  We use the notation of
+    Chimera coordinates above, but either or both of the target graph may have
+    integer or coordinate labels.
+    
+    Academic note: the full group of isomorphisms of a Chimera graph includes 
+    mappings which permute tile indices on a per-row and per-column basis, in
+    addition to reflections and rotations of the grid of unit cells where 
+    rotations by 90 and 270 degrees induce a change in orientation.  The full
+    set of sublattice mappings would take those isomorphisms into account; we do
+    not undertake that complexity here.
+    
+    Parameters
+    ----------
+        source : NetworkX Graph
+            The Chimera graph that nodes are input from
+        target : NetworkX Graph
+            The Chimera graph that nodes are input from
+        offset_list : iterable (tuple), optional (default None)
+            An iterable of offsets.  This can be used to reconstruct a set of
+            mappings, as the offset used to generate a single mapping is stored
+            in the ``offset`` attribute of that mapping.
+            
+    Yields
+    ------
+        mapping : function
+            A function from nodes of the source graph, to nodes of the target
+            graph.  The offset used to generate this mapping is stored in
+            ``mapping.offset`` -- these can be collected and passed into 
+            ``offset_list`` in a later session.
+
+    """
+    if not (source.graph.get('family') == target.graph.get('family') == 'chimera'):
+        raise ValueError("source and target graphs must be Chimera graphs constructed by dwave_networkx.chimera_graph")
+
+    t = source.graph['tile']
+    if t != target.graph['tile']:
+        raise ValueError("Cannot construct a sublattice mappings between Chimera graphs with different tile parameters")
+
+    m_s = source.graph['rows']
+    n_s = source.graph['columns']
+    labels_s = source.graph['labels']
+    if labels_s == 'int':
+        source_to_chimera = _chimera_coordinates_cache[m_s, n_s, t].linear_to_chimera
+    elif labels_s == 'coordinate':
+        def source_to_chimera(q):
+            return q
+    else:
+        raise ValueError(f"Chimera node labeling {labels_s} not recognized")
+
+    m_t = target.graph['rows']
+    n_t = target.graph['columns']
+    labels_t = target.graph['labels']
+    if labels_t == 'int':
+        chimera_to_target = _chimera_coordinates_cache[m_t, n_t, t].chimera_to_linear
+    elif labels_t == 'coordinate':
+        def chimera_to_target(q):
+            return q
+    else:
+        raise ValueError(f"Chimera node labeling {labels_t} not recognized")
+
+    if offset_list is None:
+        y_offsets = range(m_t - m_s + 1)
+        x_offsets = range(n_t - n_s + 1)
+        offset_list = product(y_offsets, x_offsets)
+
+    for offset in offset_list:
+        yield _chimera_sublattice_mapping(source_to_chimera, chimera_to_target, offset)
+