quimb.tensor.drawing

Functionailty for drawing tensor networks.

Attributes

HAS_FA2

Functions

draw_tn(tn[, color, show_inds, show_tags, ...])	Plot this tensor network as a networkx graph using matplotlib,
parse_dict_to_tids_or_inds(spec, tn[, default])	Parse a dictionary possibly containing a mix of tags, tids and inds, to
_add_legend_matplotlib(ax, colors, legend, ...)
_draw_matplotlib(edges, nodes, *[, colors, ...])
_linearize_graph_data(G[, multi_tag_style])
_draw_matplotlib3d(G, **kwargs)
_draw_plotly(G, **kwargs)
_normalize_positions(pos)
_rotate(xy, theta)	Return a rotated set of points.
_span(xy)	Return the vertical span of the points.
_massage_pos(pos[, nangles, flatten])	Rotate a position dict's points to cover a small vertical span
phyllotaxis_points(n)
layout_single_tensor(tn[, dim])	Manually layout indices around a tensor either in a circle or sphere.
layout_networkx(G[, layout, pos0, fixed, dim])
layout_pygraphviz(G[, layout, pos0, fixed, dim, ...])
get_positions(tn, G, *[, dim, fix, layout, ...])
get_colors(color[, custom_colors, alpha])	Generate a sequence of rgbs for tag(s) color.
to_rgba_str(color[, alpha])
auto_color_html(s)	Automatically hash and color a string for HTML display.
visualize_tensor(tensor, **kwargs)	Visualize all entries of a tensor, with indices mapped into the plane
choose_squarest_grid(x)
visualize_tensors(tn[, mode, r, r_scale, figsize])	Visualize all the entries of every tensor in this network.

Module Contents

quimb.tensor.drawing.HAS_FA2

quimb.tensor.drawing.draw_tn(tn, color=None, *, show_inds=None, show_tags=None, output_inds=None, highlight_inds=(), highlight_tids=(), highlight_inds_color=(1.0, 0.2, 0.2), highlight_tids_color=(1.0, 0.2, 0.2), custom_colors=None, legend='auto', dim=2, fix=None, layout='auto', initial_layout='auto', refine_layout='auto', iterations='auto', k=None, pos=None, node_color=None, node_scale=1.0, node_size=None, node_alpha=1.0, node_shape='o', node_outline_size=None, node_outline_darkness=0.9, node_hatch='', edge_color=None, edge_scale=1.0, edge_alpha=1 / 2, multi_edge_spread=0.1, multi_tag_style='auto', show_left_inds=True, arrow_opts=None, label_color=None, font_size=10, font_size_inner=7, font_family='monospace', isdark=None, title=None, backend='matplotlib', figsize=(6, 6), margin=None, xlims=None, ylims=None, adjust_lims=True, get=None, return_fig=False, ax=None)

Plot this tensor network as a networkx graph using matplotlib, with edge width corresponding to bond dimension.

Parameters:

• color (sequence of tags or True, optional) – If given, color all tensor with each of these tags with a unique color. If True, do this for all tags in the tensor network.

• output_inds (sequence of str, optional) – For hyper tensor networks explicitly specify which indices should be drawn as outer indices. If not set, the outer indices are assumed to be those that only appear on a single tensor.

• highlight_inds (iterable, optional) – Highlight these edges.

• highlight_tids (iterable, optional) – Highlight these nodes.

• highlight_inds_color – What color to use for highlight_inds nodes.

• highlight_tids_color (tuple[float], optional) – What color to use for highlight_tids nodes.

• show_inds ({None, False, True, 'all', 'bond-size'}, optional) – Explicitly turn on labels for each tensors indices.

• show_tags ({None, False, True}, optional) – Explicitly turn on labels for each tensors tags.

• custom_colors (sequence of colors, optional) – Supply a custom sequence of colors to match the tags given in color.

• title (str, optional) – Set a title for the axis.

• legend ("auto" or bool, optional) – Whether to draw a legend for the colored tags. If "auto" then only draw a legend if there are less than 20 tags.

• dim ({2, 2.5, 3}, optional) – What dimension to position the graph nodes in. 2.5 positions the nodes in 3D but then projects then down to 2D.

• fix (dict[tags_ind_or_tid], (float, float)], optional) – Used to specify actual relative positions for each tensor node. Each key should be a sequence of tags that uniquely identifies a tensor, a tid, or a ind, and each value should be a (x, y) coordinate tuple.

• layout (str, optional) –

  How to layout the graph. Can be any of the following:

  • 'auto': layout the graph using a networkx method then relax the layout using a force-directed algorithm.

  • a networkx layout method name, e.g. 'kamada_kawai': just layout the graph using a networkx method, with no relaxation.

  • a graphviz method such as 'dot', 'neato' or 'sfdp': layout the graph using pygraphviz.

• initial_layout ({'auto', 'spectral', 'kamada_kawai', 'circular', ) – ‘planar’, ‘random’, ‘shell’, ‘bipartite’, …}, optional If layout == 'auto' The name of a networkx layout to use before iterating with the spring layout. Set layout directly or iterations=0 if you don’t want any spring relaxation.

• iterations (int, optional) – How many iterations to perform when when finding the best layout using node repulsion. Ramp this up if the graph is drawing messily.

• k (float, optional) – The optimal distance between nodes.

• pos (dict, optional) – Pre-computed positions for the nodes. If given, this will override layout. The nodes shouuld be exactly the same as the nodes in the graph returned by draw(get='graph').

• node_color (tuple[float], optional) – Default color of nodes.

• node_scale (float, optional) – Scale the node sizes by this factor, in addition to the automatic scaling based on the number of tensors.

• node_size (None, float or dict, optional) – How big to draw the tensors. Can be a global single value, or a dict containing values for specific tags or tids. This is in absolute figure units. See node_scale simply scale the node sizes up or down.

• node_alpha (float, optional) – Transparency of the nodes.

• node_shape (None, str or dict, optional) – What shape to draw the tensors. Should correspond to a matplotlib scatter marker. Can be a global single value, or a dict containing values for specific tags or tids.

• node_outline_size (None, float or dict, optional) – The width of the border of each node. Can be a global single value, or a dict containing values for specific tags or tids.

• node_outline_darkness (float, optional) – Darkening of nodes outlines.

• edge_color (tuple[float], optional) – Default color of edges.

• edge_scale (float, optional) – How much to scale the width of the edges.

• edge_alpha (float, optional) – Set the alpha (opacity) of the drawn edges.

• multi_edge_spread (float, optional) – How much to spread the lines of multi-edges.

• show_left_inds (bool, optional) – Whether to show tensor.left_inds as incoming arrows.

• arrow_closeness (float, optional) – How close to draw the arrow to its target.

• arrow_length (float, optional) – The size of the arrow with respect to the edge.

• arrow_overhang (float, optional) – Varies the arrowhead between a triangle (0.0) and ‘V’ (1.0).

• arrow_linewidth (float, optional) – The width of the arrow line itself.

• label_color (tuple[float], optional) – Color to draw labels with.

• font_size (int, optional) – Font size for drawing tags and outer indices.

• font_size_inner (int, optional) – Font size for drawing inner indices.

• font_family (str, optional) – Font family to use for all labels.

• isdark (bool, optional) – Explicitly specify that the background is dark, and use slightly different default drawing colors. If not specified detects automatically from matplotlib.rcParams.

• figsize (tuple of int, optional) – The size of the drawing.

• margin (None or float, optional) – Specify an argument for ax.margin, else the plot limits will try and be computed based on the node positions and node sizes.

• xlims (None or tuple, optional) – Explicitly set the x plot range.

• xlims – Explicitly set the y plot range.

• adjust_lims (bool or "auto", optional) – Whether to automatically adjust the axes limits as elements are added. If “auto” (the default), then this is True if ax is None, else False, i.e. only adjust limits if we own the figure.

• get ({None, 'pos', 'graph'}, optional) –

  If None then plot as normal, else if:

  • 'pos', return the plotting positions of each tid and ind drawn as a node, this can supplied to subsequent calls as fix=pos to maintain positions, even as the graph structure changes.

  • 'graph', return the networkx.Graph object. Note that this will potentially have extra nodes representing output and hyper indices.

• return_fig (bool, optional) – If True and ax is None then return the figure created rather than executing pyplot.show().

• ax (matplotlib.Axis, optional) – Draw the graph on this axis rather than creating a new figure.

quimb.tensor.drawing.parse_dict_to_tids_or_inds(spec, tn, default='__NONE__')

Parse a dictionary possibly containing a mix of tags, tids and inds, to a dictionary with only sinlge tids and inds as keys. If a tag or set of tags are given as a key, all matching tensor tids will receive the value.

quimb.tensor.drawing._add_legend_matplotlib(ax, colors, legend, node_outline_darkness, label_color, font_family)

quimb.tensor.drawing._draw_matplotlib(edges, nodes, *, colors=None, node_outline_darkness=0.9, title=None, legend=True, multi_edge_spread=0.1, multi_tag_style='auto', arrow_opts=None, label_color=None, font_family='monospace', figsize=(6, 6), margin=None, xlims=None, ylims=None, adjust_lims=True, return_fig=False, ax=None)

quimb.tensor.drawing._linearize_graph_data(G, multi_tag_style='auto')

quimb.tensor.drawing._draw_matplotlib3d(G, **kwargs)

quimb.tensor.drawing._draw_plotly(G, **kwargs)

quimb.tensor.drawing._normalize_positions(pos)

quimb.tensor.drawing._rotate(xy, theta)

Return a rotated set of points.

quimb.tensor.drawing._span(xy)

Return the vertical span of the points.

quimb.tensor.drawing._massage_pos(pos, nangles=360, flatten=False)

Rotate a position dict’s points to cover a small vertical span

quimb.tensor.drawing.phyllotaxis_points(n)

J. Kogan, “A New Computationally Efficient Method for Spacing Points on a Sphere,” Rose-Hulman Undergraduate Mathematics Journal, 18(2), 2017 Article 5. scholar.rose-hulman.edu/rhumj/vol18/iss2/5.

quimb.tensor.drawing.layout_single_tensor(tn, dim=2)

Manually layout indices around a tensor either in a circle or sphere.

quimb.tensor.drawing.layout_networkx(G, layout='kamada_kawai', pos0=None, fixed=None, dim=2, **kwargs)

quimb.tensor.drawing.layout_pygraphviz(G, layout='neato', pos0=None, fixed=None, dim=2, iterations=None, k=None, **kwargs)

quimb.tensor.drawing.get_positions(tn, G, *, dim=2, fix=None, layout='auto', initial_layout='auto', refine_layout='auto', iterations='auto', k=None)

quimb.tensor.drawing.get_colors(color, custom_colors=None, alpha=None)

Generate a sequence of rgbs for tag(s) color.

quimb.tensor.drawing.to_rgba_str(color, alpha=None)

quimb.tensor.drawing.auto_color_html(s)

Automatically hash and color a string for HTML display.

quimb.tensor.drawing.visualize_tensor(tensor, **kwargs)

Visualize all entries of a tensor, with indices mapped into the plane and values mapped into a color wheel.

Parameters:

• tensor (Tensor) – The tensor to visualize.

• skew_factor (float, optional) – When there are more than two dimensions, a factor to scale the rotations by to avoid overlapping data points.

• size_map (bool, optional) – Whether to map the tensor value magnitudes to marker size.

• size_scale (float, optional) – An overall factor to scale the marker size by.

• alpha_map (bool, optional) – Whether to map the tensor value magnitudes to marker alpha.

• alpha_pow (float, optional) – The power to raise the magnitude to when mapping to alpha.

• alpha (float, optional) – The overall alpha to use for all markers if not alpha_map.

• show_lattice (bool, optional) – Show a small grey dot for every ‘lattice’ point regardless of value.

• lattice_opts (dict, optional) – Options to pass to maplotlib.Axis.scatter for the lattice points.

• linewidths (float, optional) – The linewidth to use for the markers.

• marker (str, optional) – The marker to use for the markers.

• figsize (tuple, optional) – The size of the figure to create, if ax is not provided.

• ax (matplotlib.Axis, optional) – The axis to draw to. If not provided, a new figure will be created.

Returns:

• fig (matplotlib.Figure) – The figure containing the plot, or None if ax was provided.

• ax (matplotlib.Axis) – The axis containing the plot.

quimb.tensor.drawing.choose_squarest_grid(x)

quimb.tensor.drawing.visualize_tensors(tn, mode='network', r=None, r_scale=1.0, figsize=None, **visualize_opts)

Visualize all the entries of every tensor in this network.

Parameters:

• tn (TensorNetwork) – The tensor network to visualize.

• mode ({'network', 'grid', 'row', 'col'}, optional) –

  How to arrange each tensor’s visualization.

  • 'network': arrange each tensor’s visualization according to the

    automatic layout given by draw.

  • 'grid': arrange each tensor’s visualization in a grid.

  • 'row': arrange each tensor’s visualization horizontally.

  • 'col': arrange each tensor’s visualization vertically.

• r (float, optional) – The absolute radius of each tensor’s visualization, when mode='network'.

• r_scale (float, optional) – A relative scaling factor for the radius of each tensor’s visualization, when mode='network'.

• figsize (tuple, optional) – The size of the figure to create, if ax is not provided.

• visualize_opts – Supplied to visualize_tensor.