strdiags.StrDiag

class rewalt.strdiags.StrDiag(diagram)

Bases: object

Class for string diagram visualisations of diagrams and shapes.

A string diagram depicts a top-dimensional “slice” of a diagram. The top-dimensional cells are represented as nodes, and the codimension-1 cells are represented as wires. The inputs of a top-dimensional cell are incoming wires of the associated node, and the outputs are outgoing wires.

The input->node->output order determines an acyclic flow between nodes and wires, which is represented in a string diagram by placing them at different “heights”.

There are two other “flows” that we take into account:

from codimension-2 inputs, to top-dimensional or codimension-1 cell, to codimension-2 outputs (only in dimension > 1);
from codimension-3 inputs, to codimension-1 cells, to codimension-3 outputs (only in dimension > 2).

These are not in general acyclic; however, we obtain an acyclic flow by removing all directed loops. If there is a flow of the first kind between nodes and wires, we place them at different “widths”.

If there is a flow of the second kind between wires, we place them at different “depths”; this is only seen when wires cross each other, in which case the one of lower depth is depicted as passing over the one of higher depth.

Internally, these data are encoded as a triple of NetworkX directed graphs, sharing the same vertices, partitioned into “node vertices” and “wire vertices”. These graphs encode the “main (height) flow”, the “width flow” and the “depth flow” between nodes and wires.

The class then contains a method place_vertices() that places the vertices on a [0, 1]x[0, 1] canvas, taking into account the height and width relations and resolving clashes.

Finally, it contains a method draw() that outputs a visualisation of the string diagram. The visualisation has customisable colours, orientation, and labels, and works with any drawing.DrawBackend; currently available are

a Matplotlib backend, and
a TikZ backend.

Parameters: diagram (diagrams.Diagram | shapes.Shape | shapes.ShapeMap) – A diagram or a shape or a shape map.

Notes

The “main flow” graph is essentially the open graph encoding of the string diagram in the sense of Dixon & Kissinger.

Methods

`draw`(**params)	Outputs a visualisation of the string diagram, using a backend.
`place_vertices`()	Places node and wire vertices on the unit square canvas, and returns their coordinates.

Attributes

`depthgraph`	Returns the "depth" flow graph between wire vertices.
`graph`	Returns the main flow graph between node and wire vertices.
`nodes`	Returns the nodes of the string diagram, together with all the stored associated information.
`widthgraph`	Returns the "width" flow graph between node and wire vertices.
`wires`	Returns the wires of the string diagram, together with all the stored associated information.

property graph

Returns the main flow graph between node and wire vertices.

Returns: graph – The main flow graph.
Return type: networkx.DiGraph

property widthgraph

Returns the “width” flow graph between node and wire vertices.

Returns: widthgraph – The width flow graph.
Return type: networkx.DiGraph

property depthgraph

Returns the “depth” flow graph between wire vertices.

Returns: depthgraph – The depth flow graph.
Return type: networkx.DiGraph

property nodes

Returns the nodes of the string diagram, together with all the stored associated information.

This is a dictionary whose keys are the elements of the diagram’s shape corresponding to nodes. For each node, the object stores another dictionary, which contains

the node’s label (label),
the node’s fill colour (color) and stroke colour (stroke),
booleans specifying whether to draw the node and/or its label (draw_node, draw_label), and
a boolean specifying whether the node represents a degenerate cell (isdegenerate).

Returns: nodes – The nodes of the string diagram.
Return type: dict[dict]

property wires

Returns the wires of the string diagram, together with all the stored associated information.

This is a dictionary whose keys are the elements of the diagram’s shape corresponding to wires. For each node, the object stores another dictionary, which contains

the wire’s label (label),
the wire’s colour (color),
a boolean specifying whether to draw the wire’s label (draw_label), and
a boolean specifying whether the wire represents a degenerate cell (isdegenerate).

Returns: wires – The nodes of the string diagram.
Return type: dict[dict]

place_vertices()

Places node and wire vertices on the unit square canvas, and returns their coordinates.

The node and wire vertices are first placed on different heights and widths, proportional to the ratio between the longest path to the vertex and the longest path from the vertex in the main flow graph and the width flow graph.

In dimension > 2, this may result in clashes, where some vertices are given the same coordinates. In this case, these are resolved by “splitting” the clashing vertices, placing them at equally spaced angles of a circle centred on the clash coordinates, with an appropriately small radius that does not result in further clashes.

The coordinates are returned as a dictionary whose keys are the elements corresponding to nodes and wires.

Returns: coordinates – The coordinates assigned to wire and node vertices.
Return type: dict[tuple[float]]

draw(**params)

Outputs a visualisation of the string diagram, using a backend.

Currently supported are a Matplotlib backend and a TikZ backend; in both cases it is possible to show the output (as a pop-up window for Matplotlib, or as code for TikZ) or save to file.

Various customisation options are available, including different orientations and colours.

Keyword Arguments

tikz (bool) – Whether to output TikZ code (default is False).
show (bool) – Whether to show the output (default is True).
path (str) – Path where to save the output (default is None).
orientation (str) – Orientation of the string diagram: one of 'bt' (bottom-to-top), 'lr' (left-to-right), 'tb' (top-to-bottom), 'rl' (right-to-left) (default is 'bt').
depth (bool) – Whether to take into account the depth flow graph when drawing wires (default is True).
bgcolor (multiple types) – The background colour (default is 'white').
fgcolor (multiple types) – The foreground colour, given by default to nodes, wires, and labels (default is 'black').
infocolor (multiple types) – The colour of additional information displayed in the diagram, such as positions (default is 'magenta').
wirecolor (multiple types) – The default wire colour (default is same as fgcolor).
nodecolor (multiple types) – The default node fill colour (default is same as fgcolor).
nodestroke (multiple types) – The default node stroke colour (default is same as nodecolor).
degenalpha (float) – The alpha factor of wires corresponding to degenerate cells (default is 0.1).
labels (bool) – Whether to display node and wire labels (default is True).
nodelabels (bool) – Whether to display node labels (default is same as labels).
wirelabels (bool) – Whether to display wire labels (default is same as labels).
labeloffset (tuple[float]) – Point offset of labels relative to vertices (default is (4, 4)).
positions (bool) – Whether to display node and wire positions (default is False).
nodepositions (bool) – Whether to display node positions (default is same as positions).
wirepositions (bool) – Whether to display wire positions (default is same as positions).
positionoffset (tuple[float]) – Point offset of positions relative to vertices (default is (4, -16) for Matplotlib, (4, -6) for TikZ).
scale (float) – (TikZ only) Scale factor to apply to output (default is 3).
xscale (float) – (TikZ only) Scale factor to apply to x axis in output (default is same as scale)
yscale (float) – (TikZ only) Scale factor to apply to y axis in output (default is same as scale)