Merge pull request #217 from JoelPasvolsky/zephyr

Add zephyr to docs

docs/reference/drawing.rst

@@ -1,5 +1,6 @@
 .. _drawing:
 
+*******
 Drawing
 *******
 
@@ -22,7 +23,7 @@ Chimera Graph Functions
    draw_chimera
 
 Example
----------
+~~~~~~~
 
 This example uses the :func:`.chimera_layout()` function to show the positions
 of nodes of a simple 5-node NetworkX graph in a Chimera lattice. It then uses the
@@ -74,7 +75,7 @@ Pegasus Graph Functions
 	 pegasus_node_placer_2d
 
 Example
----------
+~~~~~~~
 
 This example uses the :func:`.draw_pegasus()` function to show the positions
 of nodes of a simple 5-node graph on a small Pegasus lattice.
@@ -101,3 +102,42 @@ of nodes of a simple 5-node graph on a small Pegasus lattice.
 	:alt: Graph H overlaid on a Pegasus lattice size 2.
 
 	Graph H (blue) overlaid on a small Pegasus lattice(yellow nodes and black edges).
+
+Zephyr Graph Functions
+----------------------
+
+.. automodule:: dwave_networkx.drawing.zephyr_layout
+
+.. autosummary::
+   :toctree: generated/
+
+   draw_zephyr
+	 draw_zephyr_embedding
+	 draw_zephyr_yield
+	 zephyr_layout
+
+Example
+~~~~~~~
+
+This example uses the :func:`.draw_zephyr_embedding` function to show the positions
+of a five-node clique on a small Zephyr graph.
+
+.. code-block:: python
+
+   >>> import dwave_networkx as dnx
+   >>> import matplotlib.pyplot as plt
+   >>> import networkx as nx
+   ...
+   >>> G = dnx.zephyr_graph(1)
+   >>> embedding = {"N1": [13, 44], "N2": [11], "N3": [41], "N4": [40], "N5": [9, 37]}
+   ...
+   >>> plt.ion()
+   >>> dnx.draw_zephyr_embedding(G, embedding, show_labels=True)
+
+.. figure:: ../_images/zephyr_embedding_5clique.png
+	:align: center
+	:name: zephyr_embedding_5clique.png
+	:scale: 60 %
+	:alt: Five-node clique embedded in a small Zephyr graph.
+
+	Five-node clique embedded in a small Zephyr graph.

docs/reference/generators.rst

@@ -15,6 +15,7 @@ D-Wave Systems
 
    chimera_graph
    pegasus_graph
+   zephyr_graph
 
 Example
 ~~~~~~~

docs/reference/utilities.rst

@@ -51,6 +51,24 @@ Pegasus
    pegasus_coordinates.pegasus_to_linear
    pegasus_coordinates.pegasus_to_nice
 
+
+Zephyr
+~~~~~~
+
+.. autosummary::
+   :toctree: generated/
+
+   zephyr_coordinates.graph_to_linear
+   zephyr_coordinates.graph_to_zephyr
+   zephyr_coordinates.iter_linear_to_zephyr
+   zephyr_coordinates.iter_linear_to_zephyr_pairs
+   zephyr_coordinates.iter_zephyr_to_linear
+   zephyr_coordinates.iter_zephyr_to_linear_pairs
+   zephyr_coordinates.linear_to_zephyr
+   zephyr_coordinates.zephyr_to_linear
+   zephyr_sublattice_mappings
+
+
 Exceptions
 ----------
 .. automodule:: dwave_networkx.exceptions

docs/reference/utilities/index.rst

@@ -8,3 +8,5 @@ Coordinates Conversion
 .. autoclass:: chimera_coordinates
 
 .. autoclass:: pegasus_coordinates
+
+.. autoclass:: zephyr_coordinates

dwave_networkx/drawing/zephyr_layout.py

@@ -169,14 +169,15 @@ def draw_zephyr(G, **kwargs):
         edges (i.e., :math:`i=j`) are treated as linear biases.
 
     kwargs : optional keywords
-       See networkx.draw_networkx() for a description of optional keywords,
-       with the exception of the ``pos`` parameter, which is not used by this
-       function. If ``linear_biases`` or ``quadratic_biases`` are provided,
-       any provided ``node_color`` or ``edge_color`` arguments are ignored.
+       See :func:`~networkx.drawing.nx_pylab.draw_networkx` for a description of
+       optional keywords, with the exception of the ``pos`` parameter, which is
+       unsupported. If the ``linear_biases`` or ``quadratic_biases`` parameters
+       are provided, any provided ``node_color`` or ``edge_color`` arguments are
+       ignored.
 
     Examples
     --------
-        This example plots a Zephyr graph with size parameter 2.
+    This example plots a Zephyr graph with size parameter 2.
 
     >>> import networkx as nx
     >>> import dwave_networkx as dnx
@@ -200,14 +201,14 @@ def draw_zephyr_embedding(G, *args, **kwargs):
         the :func:`dwave_networkx.zephyr_graph` function.
 
     emb : dict
-        Chains, as a dict of form {qubit: chain, ...}, where qubits are
-        nodes in G and chains are iterables of qubit labels.
+        Minor-embedding as a dict of form {node: chain, ...}, where ``node`` are
+        nodes in G and ``chain`` are iterables of qubit labels.
 
     embedded_graph : NetworkX graph (optional, default None)
         A graph that contains all keys of ``emb`` as nodes.  If specified,
         edges of G are considered interactions if and only if (1) they
         exist between two chains of ``emb`` and (2) the keys of the
-        corresponding chains are connected by an edge in embedded_graph.
+        corresponding chains are connected by an edge in  the given graph.
         If given, only couplers between chains based on this graph are displayed.
 
     interaction_edges : list (optional, default None)
@@ -233,10 +234,11 @@ def draw_zephyr_embedding(G, *args, **kwargs):
         in G), and these overlaps are displayed as concentric circles.
 
     kwargs : optional keywords
-       See networkx.draw_networkx() for a description of optional keywords,
-       with the exception of the ``pos`` parameter, which is not used by this
-       function. If ``linear_biases`` or ``quadratic_biases`` are provided,
-       any provided ``node_color`` or ``edge_color`` arguments are ignored.
+       See :func:`~networkx.drawing.nx_pylab.draw_networkx` for a description of
+       optional keywords, with the exception of the ``pos`` parameter, which is
+       unsupported. If the ``linear_biases`` or ``quadratic_biases`` parameters
+       are provided, any provided ``node_color`` or ``edge_color`` arguments are
+       ignored.
     """
     draw_embedding(G, zephyr_layout(G), *args, **kwargs)
 
@@ -257,17 +259,20 @@ def draw_zephyr_yield(G, **kwargs):
         length-4 tuples of floats between 0 and 1 inclusive.
 
     fault_shape : string, optional (default='x')
-        The shape of the fault nodes. Specification is as matplotlib.scatter
-        marker, one of 'so^>v<dph8'.
+        The shape of the fault nodes. Specification is as for
+        `Matplotlib's markers <https://matplotlib.org/stable/api/markers_api.html#module-matplotlib.markers>`_;
+        for example "o" (circle), "^" (triangle)", "s" (square) and many more
+        options.
 
     fault_style : string, optional (default='dashed')
         Edge fault line style (solid|dashed|dotted|dashdot)
 
     kwargs : optional keywords
-       See networkx.draw_networkx() for a description of optional keywords,
-       with the exception of the `pos` parameter which is not used by this
-       function. If `linear_biases` or `quadratic_biases` are provided,
-       any provided `node_color` or `edge_color` arguments are ignored.
+       See :func:`~networkx.drawing.nx_pylab.draw_networkx` for a description of
+       optional keywords, with the exception of the ``pos`` parameter, which is
+       unsupported. If the ``linear_biases`` or ``quadratic_biases`` parameters
+       are provided, any provided ``node_color`` or ``edge_color`` arguments are
+       ignored.
     """
     try:
         assert(G.graph["family"] == "zephyr")