Notebooks · lib/graphdraw

The whole program as a graph, drawn by Viv

draw_program(g, title) draws a ProgramGraph (lib/proggraph.viv) with the figure records of a diagram: every def that matters to the run as a box, the steps inside it as boxes in the order they run, the loops that hold steps as dashed boxes around them, the calls between defs as arrows from the step that makes each call, and the values steps hand each other as arrows labeled with the variables. A value that reaches the next pass of a loop is a dashed arrow back up.

Which defs are drawn: <main>, every def with steps that the run can reach, and every def on a call path from <main> to one of them. When no def has steps, every def the run reaches (up to MAX_PLAIN_DEFS). The defs these call and that are not drawn are named at the foot of their caller's box.

The layout is lib/graphlayout.viv, twice: inside each box its children, top to bottom; then the boxes of the defs, left to right, callers before callees. Each box's id is its node's id (hf_scf, hf_scf/fock), so a page can find the box of the def or step a reader is at.

draw_view(g, v, title) draws what a GraphView says: which defs are boxes, how many callees each one hides (written +3 at the right of its header, for a page to open) or whether its callees are open (−), how many times each call ran (written on its arrow when more than once), and where the boxes of an earlier drawing were, so a redrawing after a box is opened moves the others as little as it can. draw_program is draw_view with the defs chosen above and nothing hidden, counted or remembered.

Every mark has an id a page can act on: a box is its node's id; an arrow is call:<step or def>-><def>, data:<step>-><step>, next:<step>-><step> (a value for the next pass) or then:<step>-><step> (the order of two steps); the text of a node is <id>#head, #text, #reads, #foot, its marks #more and #less; an arrow's text is <arrow id>#vars or #count. The figure's x label says which way the defs run, across or down, so a page that asks for a redrawing can keep it.

draw_view_mp(g, v, mp, title) also draws a program's multi-paths: a stage with several implementations of one intent, cross-checked against each other. Open, a multi-path is a fork (a diamond named after the stage), one path per implementation, and a join (a diamond with the agreement they are held to); the call into the fork carries the stage's intent, the default's path is solid and the others are dashed. Closed, it is one box, multi-path ×n, with the intent, the contract and how many implementations are independent and were seen agreeing. An implementation that is a drawn function is its own box on its path. The marks: the closed box is mp:<stage>@<host>; open, mp:<stage>@<host>/fork, /join, /m:<name>, and the arrows mp:<stage>@<host>/in, /to:<name>, /from:<name>.

Used with import graphdraw.

Look inside this program

Atlas
The program’s map: every function and which calls which.
There’s no recorded run of this program yet.

This program declares a record type (GraphView), and records run only in compiled C for now, so the Run buttons here are off. Open it in the workbench and use its C tab to compile it.

Shift+Enter in a cell runs it and moves to the next. Running a cell runs every cell above it too, as one program.

[1]lines 54–1340

from proggraph import node_index, ProgramGraph, reachable
from graphlayout import layered, layout_input, LayoutInput

#| Text sizes, in the drawing's units (a unit is a pixel at full size), and
#| the width of a character as a fraction of the size: the renderers use
#| these sizes, and a monospace character is 0.6 of its size in every font
#| they name. Sans text is estimated.
FONT_SMALL = 11
FONT_NORMAL = 13
FONT_LARGE = 15
MONO_EM = 0.6
SANS_EM = 0.56
#| Space inside a box, around its text and its children.
PAD = 8
#| Space between two lines of text.
LINE_GAP = 3
#| A step's box: least and greatest width.
STEP_MIN_W = 96
STEP_MAX_W = 220
#| A def's or loop's header: the widest it is written.
HEADER_MAX_W = 360
#| The longest variable list written on a value's arrow, in characters.
LABEL_MAX_CHARS = 26
#| Inside a box: space between children, and between ranks.
INNER_NODE_GAP = 22
INNER_RANK_GAP = 6
#| Between the boxes of the defs.
OUTER_NODE_GAP = 34
OUTER_RANK_GAP = 70
#| How much the order of the steps wants to be a straight line.
SEQUENCE_WEIGHT = 8
#| How much of a child's width the arcs meeting it spread over.
PORT_SPREAD = 0.7
#| The most arcs (values that skip a child, or go to the next pass) a box draws.
MAX_ARCS = 5
#| With no steps anywhere: at most this many defs.
MAX_PLAIN_DEFS = 40
#| Left to right unless the drawing would be more than this many times as
#| wide as tall; then top to bottom.
WIDE_RATIO = 2
#| The legend's height, above the drawing.
LEGEND_H = 30
#| Top to bottom, the space between the lanes that take a step's calls down
#| the right side of its def's box.
LANE_GAP = 7
#| Space between a node's header and its `+3` or `−` mark.
MARK_GAP = 10

#| What `draw_view` draws of a graph.
#: shown     per node: 1 for a def drawn as a box (its steps and loops come with it)
#: open      per node: 1 for a def whose callees are shown; its header ends in `−`
#: more      per node: how many callees of the def are not shown; its header ends in `+n`
#: counts    per edge: how many times the call ran; 0 when not known
#: hint_ids  the def boxes of an earlier drawing
#: hint_x    the left side of each, in that drawing
#: hint_y    its top, measured down from the drawing's top
#: dir       0 to choose, 1 for callees to the right of callers, 2 for below them
record GraphView {
    shown: Arr
    open: Arr

from proggraph import node_index, ProgramGraph, reachable
from graphlayout import layered, layout_input, LayoutInput

#| Text sizes, in the drawing's units (a unit is a pixel at full size), and
#| the width of a character as a fraction of the size: the renderers use
#| these sizes, and a monospace character is 0.6 of its size in every font
#| they name. Sans text is estimated.
FONT_SMALL = 11
FONT_NORMAL = 13
FONT_LARGE = 15
MONO_EM = 0.6
SANS_EM = 0.56
#| Space inside a box, around its text and its children.
PAD = 8
#| Space between two lines of text.
LINE_GAP = 3
#| A step's box: least and greatest width.
STEP_MIN_W = 96
STEP_MAX_W = 220
#| A def's or loop's header: the widest it is written.
HEADER_MAX_W = 360
#| The longest variable list written on a value's arrow, in characters.
LABEL_MAX_CHARS = 26
#| Inside a box: space between children, and between ranks.
INNER_NODE_GAP = 22
INNER_RANK_GAP = 6
#| Between the boxes of the defs.
OUTER_NODE_GAP = 34
OUTER_RANK_GAP = 70
#| How much the order of the steps wants to be a straight line.
SEQUENCE_WEIGHT = 8
#| How much of a child's width the arcs meeting it spread over.
PORT_SPREAD = 0.7
#| The most arcs (values that skip a child, or go to the next pass) a box draws.
MAX_ARCS = 5
#| With no steps anywhere: at most this many defs.
MAX_PLAIN_DEFS = 40
#| Left to right unless the drawing would be more than this many times as
#| wide as tall; then top to bottom.
WIDE_RATIO = 2
#| The legend's height, above the drawing.
LEGEND_H = 30
#| Top to bottom, the space between the lanes that take a step's calls down
#| the right side of its def's box.
LANE_GAP = 7
#| Space between a node's header and its `+3` or `−` mark.
MARK_GAP = 10

#| What `draw_view` draws of a graph.
#: shown     per node: 1 for a def drawn as a box (its steps and loops come with it)
#: open      per node: 1 for a def whose callees are shown; its header ends in `−`
#: more      per node: how many callees of the def are not shown; its header ends in `+n`
#: counts    per edge: how many times the call ran; 0 when not known
#: hint_ids  the def boxes of an earlier drawing
#: hint_x    the left side of each, in that drawing
#: hint_y    its top, measured down from the drawing's top
#: dir       0 to choose, 1 for callees to the right of callers, 2 for below them
record GraphView {
    shown: Arr
    open: Arr