* implemented god-functions for sublattice mappings, instead of the

    clunky interface originally proposed
* removed nice_coordinates from Zephyr, in favor of multiple sublattice
    mappings from Chimera to Zephyr
* added functionality for sublattice mappings from Chimera to Pegasus

dwave_networkx/generators/chimera.py

@@ -30,7 +30,9 @@
            '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):
@@ -50,7 +52,7 @@ def chimera_graph(m, n=None, t=None, create_using=None, node_list=None, edge_lis
     node_list : iterable (optional, default None)
         Iterable of nodes in the graph. If None, calculated
         from (m, n, t). Note that this list is used to remove nodes,
-        so any nodes specified not in `range(m * n * 2 * t)` are not added.
+        so any nodes specified not in ``range(m * n * 2 * t)`` are not added.
     edge_list : iterable (optional, default None)
         Iterable of edges in the graph. If None, edges are
         generated as described below. The nodes in each edge must be
@@ -502,58 +504,6 @@ def graph_to_chimera(self, g):
             )
 
 
-    def sublattice_offsets(self, m_sub, n_sub = None):
-        """Generate offsets to be produce sublattice mappings.  A sublattice
-        mapping is an embedding from `chimera_graph(m_sub, n_sub)` to
-        `chimear_graph(m, n)`.
-
-        Each offset is a tuple (m_sub, n_sub, y0, x0) of ints representing
-        offsets in the chimera coordinate system (not discussed here).
-        """
-        if n_sub is None:
-            n_sub = m_sub
-
-        m, n, _ = self.args
-        y_offsets = range(m - m_sub + 1)
-        x_offsets = range(n - n_sub + 1)
-        yield from product([m_sub], [n_sub], y_offsets, x_offsets)
-
-    @staticmethod
-    def sublattice_chimera_mapping(offset):
-        """Return a mapping from `chimera_graph(m_sub, n_sub)` to 
-        `chimera_graph(m, n)` according to the `offset = (m_sub, n_sub, y0, x0)`.
-        The returned function takes a single chimera coordinate argument, and 
-        returns a chimera coordinate.
-        """
-        _, _, y_offset, x_offset = offset
-        def mapping(q):
-            y, x, u, k = q
-            return y + y_offset, x + x_offset, u, k
-
-        return mapping
-
-    def sublattice_linear_mapping(self, offset):
-        """Return a mapping from `chimera_graph(m_sub, n_sub)` to 
-        `chimera_graph(m, n)` according to the `offset = (m_sub, n_sub, y0, x0)`.
-        The returned function takes a single linear index argument, and returns
-        a linear index.
-        
-        Note, this function assumes that both the source and target graph have
-        the same tile size.  If this is not the case, please file a feature
-        request at https://github.com/dwavesystems/dwave-networkx/
-        """
-        _, _, t = self.args
-        m_sub, n_sub, _, _ = offset
-        to_chimera = _chimera_coordinates_cache[m_sub, n_sub, t].linear_to_chimera
-        chimera_mapping = self.sublattice_chimera_mapping(offset)
-        to_linear = self.chimera_to_linear
-
-        def mapping(q):
-            return to_linear(chimera_mapping(to_chimera(q)))
-
-        return mapping
-
-
 def linear_to_chimera(r, m, n=None, t=None):
     """Convert the linear index `r` into a chimera index.
 
@@ -588,7 +538,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):
@@ -625,4 +575,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)
+