quimb.tensor.drawing ==================== .. py:module:: quimb.tensor.drawing .. autoapi-nested-parse:: Functionailty for drawing tensor networks. Attributes ---------- .. autoapisummary:: quimb.tensor.drawing.HAS_FA2 Functions --------- .. autoapisummary:: quimb.tensor.drawing.draw_tn quimb.tensor.drawing.parse_dict_to_tids_or_inds quimb.tensor.drawing._add_legend_matplotlib quimb.tensor.drawing._draw_matplotlib quimb.tensor.drawing._linearize_graph_data quimb.tensor.drawing._draw_matplotlib3d quimb.tensor.drawing._draw_plotly quimb.tensor.drawing._normalize_positions quimb.tensor.drawing._rotate quimb.tensor.drawing._span quimb.tensor.drawing._massage_pos quimb.tensor.drawing.phyllotaxis_points quimb.tensor.drawing.layout_single_tensor quimb.tensor.drawing.layout_networkx quimb.tensor.drawing.layout_pygraphviz quimb.tensor.drawing.get_positions quimb.tensor.drawing.get_colors quimb.tensor.drawing.to_rgba_str quimb.tensor.drawing.auto_color_html quimb.tensor.drawing.visualize_tensor quimb.tensor.drawing.choose_squarest_grid quimb.tensor.drawing.visualize_tensors Module Contents --------------- .. py:data:: HAS_FA2 .. py:function:: 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, get=None, return_fig=False, ax=None) Plot this tensor network as a networkx graph using matplotlib, with edge width corresponding to bond dimension. :param color: If given, uniquely color any tensors which have each of the tags. If some tensors have more than of the tags, only one color will show. :type color: sequence of tags, optional :param output_inds: 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. :type output_inds: sequence of str, optional :param highlight_inds: Highlight these edges. :type highlight_inds: iterable, optional :param highlight_tids: Highlight these nodes. :type highlight_tids: iterable, optional :param highlight_inds_color: What color to use for ``highlight_inds`` nodes. :param highlight_tids_color: What color to use for ``highlight_tids`` nodes. :type highlight_tids_color: tuple[float], optional :param show_inds: Explicitly turn on labels for each tensors indices. :type show_inds: {None, False, True, 'all', 'bond-size'}, optional :param show_tags: Explicitly turn on labels for each tensors tags. :type show_tags: {None, False, True}, optional :param custom_colors: Supply a custom sequence of colors to match the tags given in ``color``. :type custom_colors: sequence of colors, optional :param title: Set a title for the axis. :type title: str, optional :param legend: Whether to draw a legend for the colored tags. If ``"auto"`` then only draw a legend if there are less than 20 tags. :type legend: "auto" or bool, optional :param dim: What dimension to position the graph nodes in. 2.5 positions the nodes in 3D but then projects then down to 2D. :type dim: {2, 2.5, 3}, optional :param fix: 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. :type fix: dict[tags_ind_or_tid], (float, float)], optional :param layout: 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``. :type layout: str, optional :param initial_layout: '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. :type initial_layout: {'auto', 'spectral', 'kamada_kawai', 'circular', \ :param iterations: How many iterations to perform when when finding the best layout using node repulsion. Ramp this up if the graph is drawing messily. :type iterations: int, optional :param k: The optimal distance between nodes. :type k: float, optional :param pos: 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')``. :type pos: dict, optional :param node_color: Default color of nodes. :type node_color: tuple[float], optional :param node_scale: Scale the node sizes by this factor, in addition to the automatic scaling based on the number of tensors. :type node_scale: float, optional :param node_size: 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. :type node_size: None, float or dict, optional :param node_alpha: Transparency of the nodes. :type node_alpha: float, optional :param node_shape: 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. :type node_shape: None, str or dict, optional :param node_outline_size: The width of the border of each node. Can be a global single value, or a dict containing values for specific tags or tids. :type node_outline_size: None, float or dict, optional :param node_outline_darkness: Darkening of nodes outlines. :type node_outline_darkness: float, optional :param edge_color: Default color of edges. :type edge_color: tuple[float], optional :param edge_scale: How much to scale the width of the edges. :type edge_scale: float, optional :param edge_alpha: Set the alpha (opacity) of the drawn edges. :type edge_alpha: float, optional :param multi_edge_spread: How much to spread the lines of multi-edges. :type multi_edge_spread: float, optional :param show_left_inds: Whether to show ``tensor.left_inds`` as incoming arrows. :type show_left_inds: bool, optional :param arrow_closeness: How close to draw the arrow to its target. :type arrow_closeness: float, optional :param arrow_length: The size of the arrow with respect to the edge. :type arrow_length: float, optional :param arrow_overhang: Varies the arrowhead between a triangle (0.0) and 'V' (1.0). :type arrow_overhang: float, optional :param arrow_linewidth: The width of the arrow line itself. :type arrow_linewidth: float, optional :param label_color: Color to draw labels with. :type label_color: tuple[float], optional :param font_size: Font size for drawing tags and outer indices. :type font_size: int, optional :param font_size_inner: Font size for drawing inner indices. :type font_size_inner: int, optional :param font_family: Font family to use for all labels. :type font_family: str, optional :param isdark: Explicitly specify that the background is dark, and use slightly different default drawing colors. If not specified detects automatically from `matplotlib.rcParams`. :type isdark: bool, optional :param figsize: The size of the drawing. :type figsize: tuple of int, optional :param margin: Specify an argument for ``ax.margin``, else the plot limits will try and be computed based on the node positions and node sizes. :type margin: None or float, optional :param xlims: Explicitly set the x plot range. :type xlims: None or tuple, optional :param xlims: Explicitly set the y plot range. :type xlims: None or tuple, optional :param get: 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. :type get: {None, 'pos', 'graph'}, optional :param return_fig: If True and ``ax is None`` then return the figure created rather than executing ``pyplot.show()``. :type return_fig: bool, optional :param ax: Draw the graph on this axis rather than creating a new figure. :type ax: matplotlib.Axis, optional .. py:function:: 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. .. py:function:: _add_legend_matplotlib(ax, colors, legend, node_outline_darkness, label_color, font_family) .. py:function:: _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, return_fig=False, ax=None) .. py:function:: _linearize_graph_data(G, multi_tag_style='auto') .. py:function:: _draw_matplotlib3d(G, **kwargs) .. py:function:: _draw_plotly(G, **kwargs) .. py:function:: _normalize_positions(pos) .. py:function:: _rotate(xy, theta) Return a rotated set of points. .. py:function:: _span(xy) Return the vertical span of the points. .. py:function:: _massage_pos(pos, nangles=360, flatten=False) Rotate a position dict's points to cover a small vertical span .. py:function:: 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. .. py:function:: layout_single_tensor(tn, dim=2) Manually layout indices around a tensor either in a circle or sphere. .. py:function:: layout_networkx(G, layout='kamada_kawai', pos0=None, fixed=None, dim=2, **kwargs) .. py:function:: layout_pygraphviz(G, layout='neato', pos0=None, fixed=None, dim=2, iterations=None, k=None, **kwargs) .. py:function:: get_positions(tn, G, *, dim=2, fix=None, layout='auto', initial_layout='auto', refine_layout='auto', iterations='auto', k=None) .. py:function:: get_colors(color, custom_colors=None, alpha=None) Generate a sequence of rgbs for tag(s) ``color``. .. py:function:: to_rgba_str(color, alpha=None) .. py:function:: auto_color_html(s) Automatically hash and color a string for HTML display. .. py:function:: visualize_tensor(tensor, **kwargs) Visualize all entries of a tensor, with indices mapped into the plane and values mapped into a color wheel. :param tensor: The tensor to visualize. :type tensor: Tensor :param skew_factor: When there are more than two dimensions, a factor to scale the rotations by to avoid overlapping data points. :type skew_factor: float, optional :param size_map: Whether to map the tensor value magnitudes to marker size. :type size_map: bool, optional :param size_scale: An overall factor to scale the marker size by. :type size_scale: float, optional :param alpha_map: Whether to map the tensor value magnitudes to marker alpha. :type alpha_map: bool, optional :param alpha_pow: The power to raise the magnitude to when mapping to alpha. :type alpha_pow: float, optional :param alpha: The overall alpha to use for all markers if ``not alpha_map``. :type alpha: float, optional :param show_lattice: Show a small grey dot for every 'lattice' point regardless of value. :type show_lattice: bool, optional :param lattice_opts: Options to pass to ``maplotlib.Axis.scatter`` for the lattice points. :type lattice_opts: dict, optional :param linewidths: The linewidth to use for the markers. :type linewidths: float, optional :param marker: The marker to use for the markers. :type marker: str, optional :param figsize: The size of the figure to create, if ``ax`` is not provided. :type figsize: tuple, optional :param ax: The axis to draw to. If not provided, a new figure will be created. :type ax: matplotlib.Axis, optional :returns: * **fig** (*matplotlib.Figure*) -- The figure containing the plot, or ``None`` if ``ax`` was provided. * **ax** (*matplotlib.Axis*) -- The axis containing the plot. .. py:function:: choose_squarest_grid(x) .. py:function:: 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. :param tn: The tensor network to visualize. :type tn: TensorNetwork :param mode: 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. :type mode: {'network', 'grid', 'row', 'col'}, optional :param r: The absolute radius of each tensor's visualization, when ``mode='network'``. :type r: float, optional :param r_scale: A relative scaling factor for the radius of each tensor's visualization, when ``mode='network'``. :type r_scale: float, optional :param figsize: The size of the figure to create, if ``ax`` is not provided. :type figsize: tuple, optional :param visualize_opts: Supplied to ``visualize_tensor``.