diff --git a/docs/reference/drawing.rst b/docs/reference/drawing.rst index 1434d36a..7f042b97 100644 --- a/docs/reference/drawing.rst +++ b/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 `_ and/or - `Matplotlib `_\ . - 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. diff --git a/dwave_networkx/drawing/chimera_layout.py b/dwave_networkx/drawing/chimera_layout.py index 598f0332..89db7f4d 100644 --- a/dwave_networkx/drawing/chimera_layout.py +++ b/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`_. 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") diff --git a/dwave_networkx/drawing/pegasus_layout.py b/dwave_networkx/drawing/pegasus_layout.py index e540b4d4..3f9d3e2d 100644 --- a/dwave_networkx/drawing/pegasus_layout.py +++ b/dwave_networkx/drawing/pegasus_layout.py @@ -13,7 +13,7 @@ # limitations under the License. """ -Tools to visualize Pegasus lattices and weighted graph problems on them. +Tools to visualize :term:`Pegasus` lattices and weighted :term:`graph` problems on them. """ import networkx as nx @@ -32,31 +32,29 @@ def pegasus_layout(G, scale=1., center=None, dim=2, crosses=False): - """Positions the nodes of graph G in a Pegasus topology. - - `NumPy `_ is required for this function. + """Positions the nodes of graph ``G`` in a Pegasus topology. Parameters ---------- G : NetworkX graph - A Pegasus graph or a subgraph of a Pegasus graph, as produced by + :term:`Pegasus` :term:`graph` or a :term:`subgraph` of a Pegasus graph as produced by the :func:`dwave_networkx.pegasus_graph` function. scale : float (default 1.) - Scale factor. A setting of ``scale = 1`` fits all positions within + 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. crosses: boolean (optional, default False) If True, :math:`K_{4,4}` subgraphs are shown in a cross - rather than L configuration. Ignored if G is defined with - ``nice_coordinates=True``. + rather than an L configuration. If ``G`` is defined with + ``nice_coordinates=True``, this parameter is ignored. Returns ------- @@ -102,29 +100,29 @@ def pegasus_node_placer_2d(G, scale=1., center=None, dim=2, crosses=False): Parameters ---------- G : NetworkX graph - A Pegasus graph or a subgraph of a Pegasus graph, as produced by + :term:`Pegasus` :term:`graph` or a :term:`subgraph` of a Pegasus graph as produced by the :func:`dwave_networkx.pegasus_graph` function. scale : float (default 1.) - Scale factor. A setting of ``scale = 1`` fits all positions within + 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. crosses: boolean (optional, default False) If True, :math:`K_{4,4}` subgraphs are shown in a cross - rather than L configuration. + rather than an L configuration. Returns ------- - xy_coords : function - A function that maps a Pegasus index (u, w, k, z) in a - Pegasus lattice to plottable x,y coordinates. + xy_coords : Function + Function that maps a Pegasus index ``(u, w, k, z)`` in a + Pegasus lattice to plottable x- and y-coordinates. """ import numpy as np @@ -176,36 +174,35 @@ def _xy_coords(u, w, k, z): def draw_pegasus(G, crosses=False, **kwargs): - """Draws graph G in a Pegasus topology. - - If ``linear_biases`` and/or ``quadratic_biases`` are provided, these - are visualized on the plot. + """Draws graph ``G`` in a Pegasus topology. Parameters ---------- G : NetworkX graph - A Pegasus graph or a subgraph of a Pegasus graph, as produced by + :term:`Pegasus` :term:`graph` or a :term:`subgraph` of a Pegasus graph as produced by the :func:`dwave_networkx.pegasus_graph` function. linear_biases : dict (optional, default {}) - Biases as a dict, of form {node: bias, ...}, where keys are - nodes in G and biases are numeric. + Linear biases as a dict of the form ``{node: bias, ...}``, where keys are + nodes in ``G`` and biases are numeric. + If specified, the linear biases are visualized on the plot. quadratic_biases : dict (optional, default {}) - Biases as a dict, of form {edge: bias, ...}, where keys are - edges in G and biases are numeric. Self-loop + Quadratic biases as a dict of the form ``{edge: bias, ...}``, where keys are + edges in ``G`` and biases are numeric. Self-loop edges (i.e., :math:`i=j`) are treated as linear biases. + If specified, the quadratic biases are visualized on the plot. crosses: boolean (optional, default False) If True, :math:`K_{4,4}` subgraphs are shown in a cross - rather than L configuration. Ignored if G is defined with - ``nice_coordinates=True``. + rather than an L configuration. If ``G`` is defined with + ``nice_coordinates=True``, this parameter is ignored. 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 -------- @@ -224,89 +221,90 @@ def draw_pegasus(G, crosses=False, **kwargs): def draw_pegasus_embedding(G, *args, **kwargs): - """Draws an embedding onto Pegasus graph G. + """Draws an embedding onto Pegasus graph ``G``. Parameters ---------- G : NetworkX graph - A Pegasus graph or a subgraph of a Pegasus graph, as produced by + :term:`Pegasus` :term:`graph` or a :term:`subgraph` of a Pegasus graph as produced by the :func:`dwave_networkx.pegasus_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. + Chains as a dict of the form ``{qubit: chain, ...}``, where qubits are + nodes in ``G`` and chains 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) their keys are connected - by an edge in this graph. If given, only couplers between chains + Graph that contains all keys of the ``emb`` parameter as nodes. If specified, + edges of ``G`` are considered interactions if and only if (1) they + exist between two chains of the ``emb`` parameter and (2) their keys are connected + by an edge in this graph. If given, only the couplers between chains based on this graph are displayed. interaction_edges : list (optional, default None) - A list of edges used as interactions. If given, + Interactions as a list of edges. If specified, only these couplers are displayed. show_labels: boolean (optional, default False) - If True, 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) - Colors as a dict of form {node: rgba_color, ...} associated with - each key in ``emb``, where colors are length-4 tuples of floats - between 0 and 1 inclusive. If None, each chain is assigned a + Colors as a dict of the form ``{node: rgba_color, ...}`` associated with + each key in the ``emb`` parameter, where colors are 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)) - Color for nodes of G that are not part of chains, and edges - that are neither chain edges nor interactions. If None, these - nodes and edges are not shown. + Color for graph ``G``'s nodes that are not part of chains, and edges + that are neither chain edges nor interactions. If None, + these nodes and edges are not shown. crosses: boolean (optional, default False) If True, :math:`K_{4,4}` subgraphs are shown in a cross - rather than L configuration. Ignored if G is defined with + rather than an L configuration. Ignored, if ``G`` is defined with ``nice_coordinates=True``. overlapped_embedding: boolean (optional, default False) - If True, chains in ``emb`` may overlap (contain the same vertices - in G), and these overlaps are displayed as concentric circles. + If True, chains in the ``emb`` parameter may overlap (contain the same vertices + 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. + 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. """ crosses = kwargs.pop("crosses", False) draw_embedding(G, pegasus_layout(G, crosses=crosses), *args, **kwargs) def draw_pegasus_yield(G, **kwargs): - """Draws the given graph G with highlighted faults, according to layout. + """Draws graph ``G`` with highlighted faults. Parameters ---------- G : NetworkX graph - 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 absent from the 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`_. 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"] == "pegasus") diff --git a/dwave_networkx/drawing/zephyr_layout.py b/dwave_networkx/drawing/zephyr_layout.py index 7f22d6eb..eb3e34a2 100644 --- a/dwave_networkx/drawing/zephyr_layout.py +++ b/dwave_networkx/drawing/zephyr_layout.py @@ -13,7 +13,7 @@ # limitations under the License. """ -Tools to visualize Zephyr lattices and weighted graph problems on them. +Tools to visualize :term:`Zephyr` lattices and weighted :term:`graph` problems on them. """ import networkx as nx @@ -31,25 +31,23 @@ def zephyr_layout(G, scale=1., center=None, dim=2): - """Positions the nodes of graph G in a Zephyr topology. - - `NumPy `_ is required for this function. + """Positions the nodes of graph ``G`` in a Zephyr topology. Parameters ---------- G : NetworkX graph - A Zephyr graph or a subgraph of a Zephyr graph, as produced by + :term:`Zephyr` :term:`graph` or a :term:`subgraph` of a Zephyr graph as produced by the :func:`dwave_networkx.zephyr_graph` function. scale : float (default 1.) - Scale factor. A setting of ``scale = 1`` fits all positions within + 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 @@ -90,25 +88,25 @@ def zephyr_node_placer_2d(G, scale=1., center=None, dim=2): Parameters ---------- G : NetworkX graph - A Zephyr graph or a subgraph of a Zephyr graph, as produced by + :term:`Zephyr` :term:`graph` or a :term:`subgraph` of a Zephyr graph as produced by the :func:`dwave_networkx.zephyr_graph` function. scale : float (default 1.) - Scale factor. A setting of ``scale = 1`` fits all positions within + 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 Zephyr index (u, w, k, j, z) in a - Zephyr lattice to plottable x,y coordinates. + xy_coords : Function + Function that maps a Zephyr index ``(u, w, k, j, z)`` in a + Zephyr lattice to plottable x- and y-coordinates. """ import numpy as np @@ -148,32 +146,30 @@ def _xy_coords(u, w, k, j, z): def draw_zephyr(G, **kwargs): - """Draws graph G in a Zephyr topology. - - If ``linear_biases`` and/or ``quadratic_biases`` are provided, these - are visualized on the plot. + """Draws graph ``G`` in a Zephyr topology. Parameters ---------- G : NetworkX graph - A Zephyr graph or a subgraph of a Zephyr graph, as produced by + :term:`Zephyr` :term:`graph` or a :term:`subgraph` of a Zephyr graph as produced by the :func:`dwave_networkx.zephyr_graph` function. linear_biases : dict (optional, default {}) - Biases as a dict, of form {node: bias, ...}, where keys are - nodes in G and biases are numeric. + Linear biases as a dict of the form ``{node: bias, ...}``, where keys are + nodes in ``G`` and biases are numeric. + If specified, the linear biases are visualized on the plot. quadratic_biases : dict (optional, default {}) - Biases as a dict, of form {edge: bias, ...}, where keys are - edges in G and biases are numeric. Self-loop + Quadratic biases as a dict of the form ``{edge: bias, ...}``, where keys are + edges in ``G`` and biases are 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 :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. + 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 -------- @@ -192,87 +188,84 @@ def draw_zephyr(G, **kwargs): def draw_zephyr_embedding(G, *args, **kwargs): - """Draws an embedding onto Zephyr graph G. + """Draws an embedding onto a Zephyr graph ``G``. Parameters ---------- G : NetworkX graph - A Zephyr graph or a subgraph of a Zephyr graph, as produced by + :term:`Zephyr` :term:`graph` or a :term:`subgraph` of a Zephyr graph as produced by the :func:`dwave_networkx.zephyr_graph` function. emb : dict - Minor-embedding as a dict of form {node: chain, ...}, where ``node`` are - nodes in G and ``chain`` are iterables of qubit labels. + Minor-embedding as a dict of the form ``{node: chain, ...}``, where ``node`` is + nodes in ``G`` and ``chain`` is 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 the given graph. - If given, only couplers between chains based on this graph are displayed. + Graph that contains all keys of the ``emb`` parameter as nodes. If specified, + the edges of ``G`` are considered interactions if and only if (1) they + exist between two chains of the ``emb`` parameter and (2) the keys of the + corresponding chains are connected by an edge in the given graph. + If given, only the couplers between chains based on this graph are displayed. interaction_edges : list (optional, default None) - A list of edges used as interactions. If given, + Interactions as a list of edges. If specified, only these couplers are displayed. show_labels: boolean (optional, default False) - If True, 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) - Colors as a dict of form {node: rgba_color, ...} associated with - each key in ``emb``, where colors are length-4 tuples of floats - between 0 and 1 inclusive. If None, each chain is assigned a + Colors as a dict of the form ``{node: rgba_color, ...}`` associated with + each key in the ``emb`` parameter, where colors are 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)) - Color for nodes of G that are not part of chains, and edges + Color for graph ``G``'s nodes 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 True, chains in ``emb`` may overlap (contain the same vertices - in G), and these overlaps are displayed as concentric circles. + If True, chains in the ``emb`` parameter may overlap (contain the same vertices + in ``G``), and these overlaps are displayed as concentric circles. kwargs : optional keywords - 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. + 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, zephyr_layout(G), *args, **kwargs) def draw_zephyr_yield(G, **kwargs): - """Draws the given graph G with highlighted faults, according to layout. + """Draws graph ``G`` with highlighted faults, according to the Zephyr layout. Parameters ---------- G : NetworkX graph - 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 nodes and edges of ``G`` 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 absent from the 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 for - `Matplotlib's markers `_; - for example "o" (circle), "^" (triangle)", "s" (square) and many more - options. + Shape of the fault nodes. The shapes are the same as those specified for + `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 :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. + 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"] == "zephyr")