cottax.consumers.visualization.latex.xdsm module

XDSM figures for a LaTeX document: render_xdsm_svg set in the document’s face, measured in the face it is drawn in, and written as the PDF the document includes – at a size said as the page does (page=’half’, text_pt=9).

No TeX engine reads SVG, so the drawing becomes a PDF here with cairosvg, which needs no Inkscape and keeps it vector. An SVG unit is 1/96 in and a PDF point 1/72 in, so a figure included at natural size sets its text at font_size px = Layout.body_pt: include it without a `width=`, or use save_figure and the width it hands back.

Needs cairosvg (and cairocffi, which it brings).

class CairoMeasure(font: str)

Bases: Frozen

render_xdsm_svg’s measure: (label, size, bold) -> (ink_left, ink_width) for a label carrying its markup, in font as cairo will draw it. A box is cut to that and the label placed on it – an italic capital’s side bearing is several px.

font: str

INPUTS = '\\mathcal{I}'

what the model is given, and what it produces.

Type:

The two boundary boxes

LATIN_MODERN = 'LMRoman10, serif'

Latin Modern, which is Computer Modern, as fontconfig names it – the converter asks fontconfig, and fc-match ‘Latin Modern Roman’ answers another face entirely.

class Layout(linewidth_pt: float, body_pt: float, font: str)

Bases: Frozen

The page a figure is printed on: linewidth and the body size in TeX points, and the face the body is set in.

linewidth_pt: float

body_pt: float

font: str

OUTPUTS = '\\mathcal{O}'

what the model is given, and what it produces.

Type:

The two boundary boxes

PAGE = {'full': 1.0, 'half': 0.48, 'quarter': 0.24, 'third': 0.32}

A named printed width as a fraction of linewidth – what to write in the includegraphics[width=…]. half is 0.48: two panels need a gutter.

REVTEX = Layout(linewidth_pt=510.0, body_pt=10.0, font='LMRoman10, serif')

REVTeX 4-2, one column, at 10 pt.

font_for(panels, text_pt: float, page='half', *, layout: Layout = REVTEX, start: float = PANEL_FONT_SIZE, **kw)

The font_size to draw at so the labels print at text_pt once scaled to page of the line. The printed type is font_size * printed / drawn width, and the drawn width follows the font, so it is solved for; a size past what the panels asymptote to (the boxes grow with the font, gap does not) raises, naming the way out.

Return type:

float

ink_box(body: str)

(x0, y0, x1, y1) of every box and hexagon in one drawing’s body: where a panel’s ink is, inside the margins the renderer keeps around it.

Return type:

tuple[float, float, float, float]

op_arrow(op: str, xm: float, y: float, gutter: float, size: float, font: str, ink: str = '#000', muted: str = '#444')

An operation between two panels: an arrow across the gutter centred on xm at height y, in muted, the operation named over it in ink (op_label), for labels size px.

Return type:

str

printed_ink(sty: Style)

The ink and muted ink a figure’s own text and arrows are set in: black on a light ground, the style’s on a dark one.

Return type:

tuple[str, str]

save(graph, path, **kw)

to_svg written as the format path’s suffix names: .pdf, .svg or .png.

Return type:

Path

save_figure(panels, *, page='half', text_pt=9.0, align='top-left', match_height=False, layout: Layout = REVTEX, formats=('pdf', 'svg'), **kw)

save_panels told what the figure is for: page (a name in PAGE or a fraction of linewidth) and the text_pt its labels print at there. The font is solved for (font_for), the ink follows it, and the panels share one canvas width – includegraphics scales by width – aligned top-left; match_height pins the height too, for a row that must line up on the page. Returns the paths and the width= to print them at.

save_grid(rows, *, page='half', text_pt=9.0, align='top-left', layout: Layout = REVTEX, formats=('pdf', 'svg'), **kw)

save_figure for panels in several rows: one font over all of them, one width, and each row padded to its own tallest panel only.

save_panels(panels, *, formats=('pdf', 'svg'), **kw)

Several drawings as one figure’s panels, at one zoom: every panel padded to the largest (canvas), so two printed at 0.48linewidth set their type alike. panels is (stem, graph) or (stem, graph, kwargs); kw is to_svg’s for every panel, a panel’s own merged over it. Returns every path written.

Return type:

list[Path]

save_strip(panels, path, *, text_pt=7.0, page='full', gutter_em=1.5, gap_em=None, gap_y_em=None, ring_gap_em=None, labels=None, label_pt=9.0, label_gap_em=0.6, ops=None, sublabels=None, titles=None, layout: Layout = REVTEX, formats=('pdf',), **kw)

Several panels as one drawing, side by side by their ink (ink_box), gutter_em apart and top-aligned, with their labels set into it: labels under each (‘(a)’), titles over each, and either ops – n - 1 operations, one per gutter, as an arrow with the name over it: a chain of states – or sublabels – n, one beside each letter: branches off one graph. One font for the strip, solved so labels print at text_pt at page; with the gaps in ems (gap_em, gap_y_em, ring_gap_em) nothing is left to solve and the printed size is reported instead.

Returns the paths written, the font drawn at, and the size the labels print at.

tex(s: str | None)

A LaTeX string as a label a drawing sets rather than prints.

Return type:

str | None

to_svg(graph, *, layout: Layout = REVTEX, **kw)

render_xdsm_svg with a figure’s defaults over its own: layout’s face at its body size, measured (CairoMeasure), a LatexFormatter, the boundary boxes mathcal{I} and mathcal{O}, and no key (the caption says what a shape means). Every argument is render_xdsm_svg’s.

Return type:

SvgDoc