Merge pull request #226 from qwriter/copyedit_drawing

Fix typos and styling.

Author: arcondello

docs/reference/drawing.rst

@@ -4,13 +4,10 @@
 Drawing
 *******
 
-Tools to visualize topologies of D-Wave QPUs and weighted graph problems on them.
+Tools to visualize topologies of D-Wave QPUs and weighted :term:`graph` problems on them.
 
 .. currentmodule:: dwave_networkx
 
-.. note:: Some functionality requires `NumPy <https://scipy.org>`_ and/or
-	 `Matplotlib <https://matplotlib.org>`_\ .
-
 Chimera Graph Functions
 -----------------------
 
@@ -20,7 +17,10 @@ Chimera Graph Functions
    :toctree: generated/
 
    chimera_layout
+   chimera_node_placer_2d
    draw_chimera
+   draw_chimera_embedding
+   draw_chimera_yield
 
 Example
 ~~~~~~~
@@ -53,12 +53,13 @@ positions on a Chimera unit cell.
    >>> # matplotlib commands to add labels to graphic not shown
 
 .. figure:: ../_images/chimera_layout_0-rightside.png
-	:align: center
-	:name: chimera_layout_0-rightside
-	:scale: 60 %
-	:alt: Graph H overlaid on a Chimera unit cell.
+    :align: center
+    :name: chimera_layout_0-rightside
+    :scale: 60 %
+    :alt: Graph H overlaid on a Chimera unit cell.
 
-	Graph H (blue) overlaid on a Chimera unit cell (red nodes and black edges).
+    Graph ``H`` (blue) overlaid on a Chimera unit cell (red nodes and black edges),
+    which is rendered in a cross layout.
 
 
 Pegasus Graph Functions
@@ -70,9 +71,10 @@ Pegasus Graph Functions
    :toctree: generated/
 
    draw_pegasus
-	 draw_pegasus_embedding
-	 pegasus_layout
-	 pegasus_node_placer_2d
+   draw_pegasus_embedding
+   draw_pegasus_yield
+   pegasus_layout
+   pegasus_node_placer_2d
 
 Example
 ~~~~~~~
@@ -86,22 +88,23 @@ of nodes of a simple 5-node graph on a small Pegasus lattice.
    >>> import matplotlib.pyplot as plt
    >>> G = dnx.pegasus_graph(2)
    >>> H = dnx.pegasus_graph(2, node_list=[4, 40, 41, 42, 43],
-	             edge_list=[(4, 40), (4, 41), (4, 42), (4, 43)])
+                 edge_list=[(4, 40), (4, 41), (4, 42), (4, 43)])
    >>> # Show graph H on a small Pegasus lattice
    >>> plt.ion()
    >>> # Show graph H on a small Pegasus lattice
    >>> plt.ion()
    >>> dnx.draw_pegasus(G, with_labels=True, crosses=True, node_color="Yellow")
    >>> dnx.draw_pegasus(H, crosses=True, node_color='b', style='dashed',
-	         edge_color='b', width=3)
+             edge_color='b', width=3)
 
 .. figure:: ../_images/pegasus_layout_h_on_g.png
-	:align: center
-	:name: pegasus_layout_h_on_g.png
-	:scale: 60 %
-	:alt: Graph H overlaid on a Pegasus lattice size 2.
+    :align: center
+    :name: pegasus_layout_h_on_g.png
+    :scale: 60 %
+    :alt: Graph ``H`` overlaid on a Pegasus lattice size 2.
 
-	Graph H (blue) overlaid on a small Pegasus lattice(yellow nodes and black edges).
+    Graph ``H`` (blue) overlaid on a small Pegasus lattice (yellow nodes and black edges),
+    which is rendered in a cross layout.
 
 Zephyr Graph Functions
 ----------------------
@@ -112,9 +115,10 @@ Zephyr Graph Functions
    :toctree: generated/
 
    draw_zephyr
-	 draw_zephyr_embedding
-	 draw_zephyr_yield
-	 zephyr_layout
+   draw_zephyr_embedding
+   draw_zephyr_yield
+   zephyr_layout
+   zephyr_node_placer_2d
 
 Example
 ~~~~~~~
@@ -135,9 +139,9 @@ of a five-node clique on a small Zephyr graph.
    >>> 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.
+    :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.
+    Five-node clique embedded in a small Zephyr graph.

dwave_networkx/drawing/chimera_layout.py

@@ -14,7 +14,7 @@
 #
 # ================================================================================================
 """
-Tools to visualize Chimera lattices and weighted graph problems on them.
+Tools to visualize :term:`Chimera` lattices and weighted :term:`graph` problems on them.
 """
 
 import networkx as nx
@@ -28,33 +28,34 @@
 
 
 def chimera_layout(G, scale=1., center=None, dim=2):
-    """Positions the nodes of graph G in a Chimera cross topology.
+    """Positions the nodes of graph ``G`` in a Chimera layout.
 
-    NumPy (https://scipy.org) is required for this function.
+    Unit cells are rendered in a cross layout.
 
     Parameters
     ----------
     G : NetworkX graph
-        Should be a Chimera graph or a subgraph of a
-        Chimera graph. If every node in G has a `chimera_index`
-        attribute, those are used to place the nodes. Otherwise makes
-        a best-effort attempt to find positions.
+        :term:`Chimera` :term:`graph` or :term:`subgraph` of a
+        Chimera graph. If every node in ``G`` has a ``chimera_index``
+        attribute, the node position in the ``chimera_index``
+        attribute is used to place each node. Otherwise,
+        a best-effort attempt is made to find the node positions.
 
     scale : float (default 1.)
-        Scale factor. When scale = 1,  all positions fit within [0, 1]
+        Scale factor. If ``scale`` = 1, all positions fit within [0, 1]
         on the x-axis and [-1, 0] on the y-axis.
 
     center : None or array (default None)
         Coordinates of the top left corner.
 
     dim : int (default 2)
-        Number of dimensions. When dim > 2, all extra dimensions are
+        Number of dimensions. If ``dim`` > 2, all extra dimensions are
         set to 0.
 
     Returns
     -------
     pos : dict
-        A dictionary of positions keyed by node.
+        Dictionary of positions keyed by node.
 
     Examples
     --------
@@ -106,13 +107,13 @@ def chimera_layout(G, scale=1., center=None, dim=2):
 
 
 def chimera_node_placer_2d(m, n, t, scale=1., center=None, dim=2):
-    """Generates a function that converts Chimera indices to x, y
-    coordinates for a plot.
+    """Generates a function that converts Chimera indices to x- and
+    y-coordinates for a plot.
 
     Parameters
     ----------
     m : int
-        Number of rows in the Chimera lattice.
+        Number of rows in the :term:`Chimera` lattice.
 
     n : int
         Number of columns in the Chimera lattice.
@@ -121,22 +122,21 @@ def chimera_node_placer_2d(m, n, t, scale=1., center=None, dim=2):
         Size of the shore within each Chimera tile.
 
     scale : float (default 1.)
-        Scale factor. When scale = 1,  all positions fit within [0, 1]
+        Scale factor. If ``scale`` = 1, all positions fit within [0, 1]
         on the x-axis and [-1, 0] on the y-axis.
 
     center : None or array (default None)
         Coordinates of the top left corner.
 
     dim : int (default 2)
-        Number of dimensions. When dim > 2, all extra dimensions are
+        Number of dimensions. If ``dim`` > 2, all extra dimensions are
         set to 0.
 
     Returns
     -------
-    xy_coords : function
-        A function that maps a Chimera index (i, j, u, k) in an
-        (m, n, t) Chimera lattice to x,y coordinates such as
-        used by a plot.
+    xy_coords : Function
+        Function that maps a Chimera index ``(i, j, u, k)`` in an
+        ``(m, n, t)`` Chimera lattice to x- and y-coordinates.
 
     """
     import numpy as np
@@ -190,30 +190,31 @@ def _xy_coords(i, j, u, k):
 
 
 def draw_chimera(G, **kwargs):
-    """Draws graph G in a Chimera cross topology.
+    """Draws graph ``G`` in a Chimera layout.
 
-    If `linear_biases` and/or `quadratic_biases` are provided, these
-    are visualized on the plot.
+    Unit cells are rendered in a cross layout.
 
     Parameters
     ----------
     G : NetworkX graph
-        Should be a Chimera graph or a subgraph of a Chimera graph.
+        :term:`Chimera` :term:`graph` or a :term:`subgraph` of a Chimera graph.
 
     linear_biases : dict (optional, default {})
-        A dict of biases associated with each node in G. Should be of
-        form {node: bias, ...}. Each bias should be numeric.
+        Linear biases for all nodes of ``G`` as a dict of
+        the form ``{node: bias, ...}``, where each bias is numeric.
+        If specified, the linear biases are visualized on the plot.
 
     quadratic_biases : dict (optional, default {})
-        A dict of biases associated with each edge in G. Should be of
-        form {edge: bias, ...}. Each bias should be numeric. Self-loop
+        Quadratic biases for all edges of ``G`` as a dict of
+        the form ``{edge: bias, ...}``, where each bias is numeric. Self-loop
         edges (i.e., :math:`i=j`) are treated as linear biases.
+        If specified, the quadratic biases are visualized on the plot.
 
     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.
+       Parameters in :func:`~networkx.drawing.nx_pylab.draw_networkx`, except for the ``pos`` parameter.
+       If the ``linear_biases`` or ``quadratic_biases`` parameters are specified,
+       the :func:`~networkx.drawing.nx_pylab.draw_networkx` ``node_color``
+       or ``edge_color`` parameters are ignored.
 
     Examples
     --------
@@ -230,87 +231,86 @@ def draw_chimera(G, **kwargs):
 
 
 def draw_chimera_embedding(G, *args, **kwargs):
-    """Draws an embedding onto the chimera graph G, according to layout.
-
-    If interaction_edges is not None, then only display the couplers in that
-    list.  If embedded_graph is not None, the only display the couplers between
-    chains with intended couplings according to embedded_graph.
+    """Draws an embedding onto the Chimera graph ``G``.
 
     Parameters
     ----------
     G : NetworkX graph
-        Should be a Chimera graph or a subgraph of a Chimera graph.
+        :term:`Chimera` :term:`graph` or a :term:`subgraph` of a Chimera graph.
 
     emb : dict
-        A dict of chains associated with each node in G.  Should be
-        of the form {node: chain, ...}.  Chains should be iterables
-        of qubit labels (qubits are nodes in G).
+        Embedding for all nodes of ``G`` as a dict of chains
+        of the form ``{node: chain, ...}``. where chains are iterables
+        of qubit labels. Qubits are nodes in ``G``.
 
     embedded_graph : NetworkX graph (optional, default None)
-        A graph which contains all keys of emb as nodes.  If specified,
-        edges of G will be considered interactions if and only if they
-        exist between two chains of emb if their keys are connected by
-        an edge in embedded_graph
+        Graph which contains all keys of the ``emb`` parameter as nodes. If specified,
+        the edges of ``G`` are considered to be interactions if and only if they
+        exist between two chains of the ``emb`` parameter and if their keys are connected by
+        an edge in the ``embedded_graph`` parameter; only the couplers for edges of ``G``
+        that are considered to be interactions are displayed.
 
     interaction_edges : list (optional, default None)
-        A list of edges which will be used as interactions.
+        Interactions as a list of edges.
+        If this parameter is specified, only the couplers in the list are displayed.
 
     show_labels: boolean (optional, default False)
-        If show_labels is True, then each chain in emb is labelled with its key.
+        If True, each chain in the ``emb`` parameter is labelled with its key.
 
     chain_color : dict (optional, default None)
-        A dict of colors associated with each key in emb.  Should be
-        of the form {node: rgba_color, ...}.  Colors should be length-4
-        tuples of floats between 0 and 1 inclusive. If chain_color is None,
-        each chain will be assigned a different color.
+        Chain colors associated with each key in the ``emb`` parameter as a dict
+        of the form ``{node: rgba_color, ...}``, where colors must be length-4
+        tuples of floats between 0 and 1, inclusive. If None,
+        each chain is assigned a different color.
 
     unused_color : tuple (optional, default (0.9,0.9,0.9,1.0))
-        The color to use for nodes and edges of G which are not involved
-        in chains, and edges which are neither chain edges nor interactions.
-        If unused_color is None, these nodes and edges will not be shown at all.
+        Color to use for graph ``G``'s nodes and edges that are not part of
+        chains, and edges that are neither chain edges nor interactions.
+        If None, these nodes and edges are not shown.
 
     overlapped_embedding: boolean (optional, default False)
-        If overlapped_embedding is True, then chains in emb may overlap (contain
-        the same vertices in G), and the drawing will display these overlaps as
+        If True, chains in the ``emb`` parameter may overlap (contain
+        the same vertices in ``G``), and the drawing displays these overlaps 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.
+       Parameters in :func:`~networkx.drawing.nx_pylab.draw_networkx`, except for the ``pos`` parameter.
+       If the ``linear_biases`` or ``quadratic_biases`` parameters are specified,
+       the :func:`~networkx.drawing.nx_pylab.draw_networkx` ``node_color``
+       or ``edge_color`` parameters are ignored.
     """
     draw_embedding(G, chimera_layout(G), *args, **kwargs)
 
 
 def draw_chimera_yield(G, **kwargs):
-    """Draws the given graph G with highlighted faults, according to layout.
+    """Draws graph ``G`` with highlighted faults.
 
     Parameters
     ----------
     G : NetworkX graph
-        The graph to be parsed for faults
+        :term:`Graph` to be parsed for faults.
 
     unused_color : tuple or color string (optional, default (0.9,0.9,0.9,1.0))
-        The color to use for nodes and edges of G which are not faults.
-        If unused_color is None, these nodes and edges will not be shown at all.
+        Color to use for graph ``G``'s nodes and edges which are not faults.
+        If None, these nodes and edges are not shown.
 
     fault_color : tuple or color string (optional, default (1.0,0.0,0.0,1.0))
-        A color to represent nodes absent from the graph G. Colors should be
-        length-4 tuples of floats between 0 and 1 inclusive.
+        Color to represent nodes that are absent from graph ``G``. Colors must be
+        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'.
+        Shape of the fault nodes. The shapes are the same as those specified for
+        `Matplotlib markers <https://matplotlib.org/stable/api/markers_api.html#module-matplotlib.markers>`_.
 
     fault_style : string, optional (default='dashed')
-        Edge fault line style (solid|dashed|dotted|dashdot)
+        Line style for fault edges. The line style can be any of the following values:
+        ``'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.
+       Parameters in :func:`~networkx.drawing.nx_pylab.draw_networkx`, except for the ``pos`` parameter.
+       If the ``linear_biases`` or ``quadratic_biases`` parameters are specified,
+       the :func:`~networkx.drawing.nx_pylab.draw_networkx` ``node_color``
+       or ``edge_color`` parameters are ignored.
     """
     try:
         assert(G.graph["family"] == "chimera")