cottax.consumers.visualization

Pictures of a graph: XDSM, N2, node-link, and a page framing them.

class Style(name: str, surface: str, ink: str, muted: str, model: Pair, variable: Pair, variable_ink: str, boundary: Pair, edge: str, chip: Pair, ground: Ground, stated: Pair, unanswered: str, bands: tuple[str, ...], band_stroke: str, dashed: bool, run_ring: str | None, undriven: str, tint: float, driven_tint: float, cut_em: float, bold: bool, font: str | None, ring_gap: float, nest_em: float, ring_radius_em: float, groups: tuple[str, ...])[source]

Bases: Frozen

The colours and marks of every drawing in this package. A problem’s hue is its category’s; value is structure; fill and contour are how far a problem is decided.

surface is the ground, ink a box’s label, muted a boundary label or a key entry. model, variable and boundary are (fill, stroke) for a box that runs, a coupling and the two boxes standing for the world outside; variable_ink a variable’s name. edge a coupling line. chip is a condition slot’s (fill, stroke), drawn translucent over its problem.

A category’s colour is its own (Kind.colour), and ground paints it (paint): the hexagon of a problem of that category, and the contour of the ring it answers. A renderer holding a category’s name takes the colour from its struct. stated is a condition that determines nothing and whose type is unknown; one whose type is known is drawn hollow in that type’s stroke. unanswered is the contour of a ring no driver answers (a bare cycle, or several problems with nothing nested).

bands fills a solve ring, one entry per nesting depth (cycling); empty draws the ring as a contour alone. band_stroke is the contour of a band’s key sample, dashed whether a solve ring’s contour is dashed. run_ring is the contour of a block merely run in order, None to draw none.

undriven says how a problem without a driver is drawn: ‘tint’ fills it tint of the way to its type’s fill (driven_tint once driven) and cuts its contour, and a ring nothing answers, open by cut_em in the middle of top and bottom; ‘solid’ draws every problem alike. bold sets every name in a heavier weight. font is a CSS family list, None for the renderer’s own. ring_gap is a solve ring’s clearance as a fraction of the gap between two boxes, nest_em what a nested ring and a driver’s chevron stand off a ring (in ems, floored at that clearance), ring_radius_em a ring’s corner.

groups is the categorical palette a drawing colours groups of nodes with; it keeps clear of the categories’ hues.

name: str
surface: str
ink: str
muted: str
model: Pair
variable: Pair
variable_ink: str
boundary: Pair
edge: str
chip: Pair
ground: Ground
stated: Pair
unanswered: str
bands: tuple[str, ...]
band_stroke: str
dashed: bool
run_ring: str | None
undriven: str
tint: float
driven_tint: float
cut_em: float
bold: bool
font: str | None
ring_gap: float
nest_em: float
ring_radius_em: float
groups: tuple[str, ...]
paint(colour: Pair | None)[source]

The (fill, stroke) of a problem of a category coloured colour, or stated’s for none.

Return type:

Pair

fill(colour: Pair | None, driven: bool)[source]

What a problem of a category coloured colour is filled with, driven or not; stated’s grey, tinted as any, for none.

Return type:

str

band(depth: int)[source]

The fill of a solve ring at depth, or None for a contour alone.

Return type:

str | None

property cuts: bool

Whether a problem without a driver has its contour cut open.

class PlainFormat(notation: Notations | None = None)[source]

Bases: Formatter

Every name by spell_plain, a minted one in its purpose’s notation (notation keyed by the Mint class, else its MintDrawing), else as <spelling>(·) – what a drawing writes unless told otherwise.

spell(path: Label)[source]
Return type:

str

set(source: str)[source]
Return type:

str

label(text: str)[source]
Return type:

str

text(text: Text)[source]
Return type:

str

outright(path: Label)[source]
Return type:

bool

notation(m: Mint)[source]
Return type:

Notation

render_xdsm_svg(graph: NestingGraph | ExecutableGraph | Plan | dict, *, blocks: bool | ExecutableGraph = False, file_name: str = 'xdsm', outdir: str = '.', style: Style | str = TERRACOTTA, follow_system: bool = False, css: str = '', input_label: str | None = None, output_label: str | None = None, write: bool = False, legend: bool = True, font: str | None = None, font_size: float | None = None, names: bool = True, edges: bool = False, thick_blocks: bool | float = False, line_scale: float = 1.0, line_weights: Mapping[str, float] | None = None, box_scale: float = 1.0, var_box_scale: float = 1.0, condition_slots: bool | str = False, problem_first: bool = True, stack_inputs: bool = False, collapse_names: bool = False, inline_names: bool = False, square_names: bool = False, gap: float | None = None, gap_y: float | None = None, ring_gap: float | None = None, nest_gap: float | None = None, head_gap: float | None = None, cell: tuple[float, float] | None = None, canvas: tuple[float, float] | None = None, align: str = 'center', formatter: Formatter = PlainFormat(), measure: Measure | None = None)[source]

graph as a self-contained XDSM in SVG: the steps on the diagonal, a coupling’s box at (producer’s row, consumer’s column), a free input entering from the top-left box and a result leaving to the bottom-right one. Returns an SvgDoc, whose .cell is the widest step column and tallest row used and .size the drawing’s (width, height).

graph: a NestingGraph, a Plan (its graph), a proof (its graph, ringed as proved) or an xdsm_struct already built. blocks: ring every solve, and order the diagonal to run order (an ExecutableGraph: ring as that proof has it); otherwise the diagonal is binding order. file_name, outdir, write: with write=True, also write <outdir>/<file_name>.svg (.path). style: a Style or a name in STYLES. follow_system: add DARK under the viewer’s prefers-color-scheme (the default style only); a hexagon and a ring’s contour keep the light ground’s colours. css: appended to the stylesheet. input_label, output_label: the boundary boxes’ text (None: ‘Coor’, ‘Out’). legend: draw the key beneath the matrix. font: the face, a CSS family list (None: the style’s). font_size: a step label’s size in px; every other size and distance follows it. names: draw the text; off, the boxes keep the size of the names they would hold. edges: also draw the line from producer through a coupling box to its consumer, and with no boundary variable the labelled arrows in and out. thick_blocks: rings at RING_THICK px and solid, or at the number given. line_scale: multiplies every line weight. line_weights: merged over LINE_WEIGHTS before line_scale, per class. box_scale: the air around a step’s label and its row’s floor, times this. var_box_scale: the air around a coupling box’s names, times this. condition_slots: a condition node’s reads in a column per kind (min, = 0, ≤ 0, = û, ≤ u, g ≤ g_max); True for optimise and feasibility problems and every requirement (what it requires), ‘all’ for every condition node. problem_first: a problem at the head of the block it drives; off keeps the graph’s order within a block. stack_inputs: the free inputs on one row, not one row each. collapse_names: a coupling box shows a count, N vars, its names in its <title>. inline_names: a coupling box’s names on one line. square_names: a coupling box’s names in the fewest lines keeping it about square. gap: px between neighbouring boxes, both ways (CELL_GAP); gap_y: the vertical one alone. ring_gap: px from a ring to the boxes and rings beside it (gap / 2). nest_gap, head_gap: px from a ring to a ring nested in it and to its problem’s hexagon (ring_gap). cell: (w, h) in px, every step column and every row at this pitch (another drawing’s .cell), so two drawings share a grid. canvas: (w, h) in px to pad the drawing to (another’s .size), so two share a scale; a smaller canvas is ignored. align: where the drawing sits in canvas: ‘center’, ‘top-left’, ‘top’, ‘left’. formatter: how a name is written; markup (MARKUP) is measured as it is set. measure: (label, size, bold) -> (ink_left, ink_width) in px, replacing the width estimate (latex.xdsm.CairoMeasure).

Return type:

SvgDoc

render_matrix_svg(graph, *, order: str | Sequence[Label] = 'structure', groups: Grouping | None = None, grouped: bool = False, names: bool = True, colour: bool = True, legend: bool = True, bands: bool = True, name_column: float | None = None, cell: float | None = None, font_size: float = 9.0, problem_mark: float = 0.0, colours: Mapping[str, str] | None = None, font: str | None = None, style: Style | str = TERRACOTTA, formatter: Formatter = PlainFormat(), write: bool = False, file_name: str = 'matrix', outdir: str = '.')[source]

The N2 matrix of graph (a NestingGraph, an ExecutableGraph or a Plan) as a self-contained SVG; .size, .names_width and .struct (matrix_struct) beside it.

order: ‘structure’ (run order at every level, each solve contiguous and boxed), ‘binding’, ‘grouped’ (structure, regrouped so each group is contiguous) or a permutation of the nodes. groups: a mapping of group to nodes, or a function of a node (by_namespace). grouped: draw the groups themselves, a cell counting the variables between two. names, colour, legend: the row names, the group colours, the key. bands: the group bars beside and over the matrix. name_column: the names’ column width in px, flush left, so several matrices line up (default: their own width, flush right). cell: a row’s pitch in px (CELL_EM * font_size). font_size, font: the type (font default: the style’s). problem_mark: the least width of a problem’s hexagon in px, drawn over its neighbours. colours: an outermost group’s hue by name, to colour several graphs alike. style, formatter: as every picture’s. write, file_name, outdir: with write=True, also write <outdir>/<file_name>.svg.

Return type:

SvgDoc

by_namespace(depth: int | None = None)[source]

The grouping a graph’s own names declare (PlaceDrawing.namespace_of: its leading names without its own, a minted one read through its namespace), depth levels deep.

Return type:

Callable[[Label], tuple[str, ...]]

render_html(graph: NestingGraph | ExecutableGraph | Plan, *, views: Sequence[str] = ('xdsm', 'n2'), names: bool = True, colour: bool = True, blocks: bool | ExecutableGraph = False, style: Style | str = TERRACOTTA, formatter: Formatter = PlainFormat(), xdsm: Mapping[str, Any] | None = None, n2: Mapping[str, Any] | None = None, write: bool = False, file_name: str = 'graph', outdir: str = '.')[source]

graph as an interactive page: drag to pan, Ctrl+scroll to zoom, Fit; hover a step or a coupling to name it and light its row and column. A Plan is a frame per prefix under a slider, labelled by its op, what the op changed haloed.

views: the pictures each frame carries, ‘xdsm’ and / or ‘n2’, the first opened. names, colour: the Names and (with an N2) Colour toggles’ starting state. blocks: ring the XDSM’s solves (an ExecutableGraph: as that proof has them). xdsm: render_xdsm_svg’s own arguments for the XDSM view. n2: the N2 view’s (cell, font_size, order, groups – by_namespace() unless said –, grouped, colours). write=True also writes <outdir>/<file_name>.html, filling the window.

Return type:

HtmlDoc

draw(graph: NestingGraph | ExecutableGraph | Plan | DiGraph, ax=None, *, boundary: bool = True, collapse_boundary: bool = False, input_label: str | None = None, output_label: str | None = None, pos: dict | None = None, layout: str = 'auto', names: bool = True, node_size: int = 2400, font_size: int = 8, style: Style | str = TERRACOTTA, formatter: Formatter = PlainFormat())[source]

Draw a NestingGraph, a Plan, a proof (each as graph_drawn reads it) or an already-built nx.DiGraph onto a matplotlib axis (a new one if ax is None); returns the axis.

boundary, collapse_boundary, input_label, output_label, style, formatter: as to_dot. A vertex that is not a place (a caller’s nx.DiGraph) is written as str. pos: positions given; else layout, ‘dot’ (needs graphviz), ‘layered’ (layered_pos) or ‘auto’ (dot when installed). names: the variable names on the edges. node_size, font_size: matplotlib’s.

render(graph: NestingGraph | ExecutableGraph | Plan | DiGraph, **kw)[source]

to_dot(graph, **kw) as a graphviz.Source, which Jupyter displays inline as SVG.

to_dot(graph: NestingGraph | ExecutableGraph | Plan | DiGraph, *, boundary: bool = True, collapse_boundary: bool = False, input_label: str | None = None, output_label: str | None = None, rankdir: str = 'LR', style: Style | str = TERRACOTTA, blocks: bool = False, formatter: Formatter = PlainFormat(), font: str | None = None, font_size: int = 10, edge_font_size: int = 9, nodesep: float = 0.35, ranksep: float = 0.6, node_margin: str = '0.14,0.08', margin: float | None = None)[source]

graph as Graphviz DOT source (producing it needs nothing installed). graph is read as draw reads it.

boundary: a vertex per boundary variable. collapse_boundary: those merged into two boxes, one every free input comes from and one every result goes into, labelled input_label / output_label through formatter.label (None: ‘In’ / ‘Out’). rankdir: graphviz’s. style: a Style or a name in STYLES. blocks: every solve a cluster, nested as the solves nest, in its band and ring colours. formatter: how a name is written; a marked-up label becomes an HTML-like one. font: the face (the style’s, else Helvetica); font_size, edge_font_size: a vertex’s and an edge’s type. nodesep, ranksep: the spacing; node_margin: a vertex’s (“x,y”, inches); margin: the drawing’s (none by default).

Return type:

str

Subpackages

Submodules