Cyclic topology, figure math and multi-panel figures¶
Four figure tools for theory and benchmark papers on cyclic clusters and periodic models:
a cyclic-topology schematic: the ring or torus of a cyclic cluster or an AICCM torus, drawn beside the unrolled sheet of its cells;
math in figure text: subscripts, superscripts, Greek letters, a few operators, fractions and overbars, without LaTeX;
labelled multi-panel figures: existing figure SVGs in a grid with (a), (b), … labels at a stated physical width, written as one SVG, PDF or PNG;
workflow and taxonomy diagrams: boxes with text and connectors that are computed from the boxes, laid out in layers, as a tree or by hand.
Each one reads the model or the figures it is given and changes nothing. The
same model and options always give the same bytes. PDF and PNG output needs
the publication extra (pip install 'vibesketcher[publication]'); the PDF
embeds the publication font.
The cyclic-topology schematic¶
A cyclic cluster is the input cell repeated N1 × N2 × N3 times with Born–von Kármán boundary conditions: cell N along an axis is cell 0. The schematic shows that identification in two panels.
The unrolled sheet lays the cells flat in the true lattice geometry, with every atom at its fractional position and the bonds between the cells. The identified edges carry matching arrows: one arrow for the edges parallel to the first drawn axis and two for the second. This is the usual notation for gluing a square into a torus. The sheet is to scale.
The cyclic shape is a ring for one drawn axis and a projected torus for two. The cells are a grid on the surface, and the seams u = 0 and v = 0 are drawn in the accent colour with the sheet’s arrow marks. The torus is shaded and drawn back to front, so the far side shows through the hole only where it is visible. It is a schematic and not to scale, and the figure says so.
A bond that crosses a seam is a wrap-around bond. It is drawn dashed in the accent colour in both panels: in the sheet it leaves one edge and re-enters through the identified opposite edge. Bonds are the structure’s stored bonds when it has any, otherwise pairs closer than 1.15 times the sum of the covalent radii, as in the periodic figures.
# A 4 x 3 graphene torus from a document's periodic structure:
vibe-sketcher solid topology cells.vsk --structure graphene --repeats 4,3,1 -o torus.pdf
# The torus an AICCM input was written for, from its convention record:
vibe-sketcher solid topology --record lih-aiccm.aiccm.json --axes 0,1 -o lih-torus.svg
The record is the NAME.aiccm.json file written beside every AICCM input
(AICCM planning). It carries the
cell, the sites and the torus repeats. The figure adds a line with the
variant, the reference and the start of the Hamiltonian digest.
A structure with one periodic axis gives a ring and one with two gives a
torus. A three-dimensional torus cannot be drawn; name the two axes to draw
with --axes 0,1, and the figure states how many images along the third axis
it leaves out. The schematic draws at most 48 cells along an axis and 3000
atoms. Repeats must be 1 along non-periodic axes.
The options are axes, atoms, bonds, seams (the accent colour and the
arrow marks), unrolled (the sheet), cell_labels (cell indices; shown by
default up to 36 cells), elevation_deg (10 to 80), aspect (major over
tube radius, 1.5 to 6), atom_scale, width and font_size in points,
title (math allowed) and caption (the provenance lines).
Math in figure text¶
Figure titles, panel captions and figure math take plain text with math
between dollar signs, for example $E_{\mathrm{coh}}$ per cell or
$N_c = N_1 N_2$. Inside math:
Write |
For |
|---|---|
|
subscripts and superscripts, nested up to three levels |
|
Greek letters ( |
|
operators and relations |
|
symbols |
|
a stacked fraction |
|
a bar over the group, as in |
|
grouping (text is upright anyway) |
|
spaces |
|
the characters themselves |
A hyphen in math is the minus sign. Spaces in math are kept as typed, also after a command; TeX would drop them. Letters stay upright, because the publication font has a single upright face.
Anything else is refused with the reason: an unknown command, an unbalanced
brace or dollar sign, a script without its argument, a doubled script on one
base, a line break, or a character the publication font has no glyph for.
The font has no arrows, so \to and \rightarrow are refused, as are
\equiv, \hbar and \nabla. GET /api/figures/math lists the subset.
Scripts are smaller text runs placed above or below the baseline, never Unicode superscript or subscript characters, and bars are drawn lines, never combining characters. Each run is placed from the font’s advance widths, so SVG, PDF and PNG agree.
vibe-sketcher figure math '$\Delta E_{\mathrm{coh}}$' --check # prints the plain reading
vibe-sketcher figure math '$\frac{1}{N_c}\sum_k \varepsilon_{nk}$' -o label.pdf
Labelled multi-panel figures¶
figure panels composes figure SVGs into one figure. The panels are placed
row by row in the order given and labelled (a), (b), … in that order.
vibe-sketcher figure panels lattice.svg supercell.svg torus.svg -o schematic.pdf \
--columns 3 --column double --caption 'lattice and cluster' \
--caption 'Wigner–Seitz supercell' --caption '$N_c = 12$ torus'
The width is stated. --column single is 85 mm and --column double (the
default) 178 mm. --width-mm gives a journal’s own measure. One SVG unit is
one point, so the PDF page has exactly that width. To keep text at its true
size, draw each panel at the width of one grid column: cell_width_pt(options)
in Python gives it in points.
Each panel is embedded unchanged as a nested SVG and scaled by one factor.
Its identifiers are prefixed per panel, so two panels never share a clip path.
--scale chooses the factor:
fit(the default) makes every panel fill its column;uniformuses one factor for every panel, so relative sizes stay as drawn;angstromshows one angstrom at the same length in every panel. Each panel states its angstrom per SVG unit (--angstrom-per-unit, in order, or the root attributedata-vibe-angstrom-per-unit). A panel without it is refused.--scale-bar 5adds a common 5 Å bar under the grid.
Periodic figures record data-vibe-angstrom-per-unit themselves, so two
periodic figures compose at one angstrom scale with no stated value. A
figure with a Brillouin-zone panel records nothing, because that panel is in
reciprocal angstrom. The cyclic-topology schematic records nothing either,
because its torus is not to scale.
--max-height-mm caps tall panels. --labels chooses (a), a, a),
(A), A or none. --title and each --caption may hold math.
Panel SVG is treated as untrusted and checked before use. A panel is refused
when it has a DOCTYPE or entity, an element outside the drawing subset (no
script, image, foreignObject or animation), an event attribute, an external
reference, or a style sheet other than an @font-face block. An
@font-face block is dropped, because conversion supplies the publication
font.
Workflow and taxonomy diagrams¶
figure diagram draws boxes and connectors from a small spec, written as
JSON or TOML with the schema vibesketcher.diagram/1:
schema = "vibesketcher.diagram/1"
layout = "tree" # layered (the default), tree or manual
direction = "down" # or right
[[nodes]]
id = "all"
label = "pair $(A, B)$ in the\ncyclic cluster" # up to four lines; math allowed
[[nodes]]
id = "one"
label = "one-centre"
group = "local" # optional; a group is a labelled frame
[[groups]]
id = "local"
label = "on-site"
[[edges]]
source = "all"
target = "one"
label = "$A = B$" # optional; also style = "dashed", arrow = false
vibe-sketcher figure diagram classes.toml -o classes.pdf
vibe-sketcher figure diagram flow.json --check # validate and lay out only
A node takes id, label, group, position (its centre in points, y
down), shape (rounded, box or plain), fill, stroke, min_width
and bold. An edge takes source, target, label, style, arrow and
colour. The spec also sets font_size, layer_gap, node_gap,
padding, width_pt (draw the figure this wide; by default one unit is one
point) and title. Colours are #rrggbb.
The layouts:
layered, for workflows, is the layered drawing of Sugiyama, Tagawa and Toda (1981). A cycle, such as an SCF loop, is broken by reversing its back edge for the layout; the edge is still drawn in its stated direction. Every node sits on the layer of its longest path from a start node. An edge that skips layers bends through the gaps between the boxes. A fixed number of barycentre sweeps orders each layer to reduce crossings, and the order with the fewest crossings is kept. The SVG records that count asdata-vibe-crossings.tree, for taxonomies, needs at most one parent per node. Children sit side by side in the order their edges are stated, and each parent is centred over its children (Reingold and Tilford, 1981).manualplaces every node at its statedposition. In the other layouts apositionpins that node and leaves the rest to the layout.
Connectors are computed from the boxes on every draw: each one leaves its source box and ends with its arrow tip on the target box’s edge. When you move a box, its connectors follow. Two edges in opposite directions between the same boxes run side by side. An edge label sits on its connector and slides along it to stay clear of boxes and of other labels. A group frame is drawn around its member boxes, with room left for it between the layers.
The bounds cover every box, connector, arrowhead, label and title, measured with the publication font, so nothing is clipped in SVG, PDF or PNG. The same spec always gives the same bytes.
The diagram is refused, with the reason, when it has more than 120 nodes, 360 edges or 24 groups, or when a label has more than four lines. It is also refused for a duplicate or unknown id, a self-loop, a repeated edge, a missing position in the manual layout, or a second parent in a tree. Unsupported math, two overlapping boxes, a group frame that covers a box outside the group and an edge label with no free place are refused too.
The cyclic-cluster schematic figure¶
The script
cyclic_cluster_schematic.py
builds the schematic figure of a cyclic-cluster article in one run, from the
public Python API only. It writes a double-column (178 mm) figure in four
labelled panels:
(a) the graphene lattice with a 3 × 3 cyclic cluster;
(b) the Wigner–Seitz supercell with the boundary atoms’ weights;
(c) the torus beside its unrolled sheet;
(d) the interaction classes, drawn from
interaction-classes.toml.
python cyclic_cluster_schematic.py schematic.pdf # or .svg, .png
The PDF embeds its font, and the same release always writes the same bytes.
REST, MCP and Python¶
POST /api/documents/{id}/periodic/{structure}/topologytakesrepeats,options,format(svg,pdf,png) anddpi.POST /api/periodic/topologytakesrecord(an AICCM convention record) instead of a structure.POST /api/figures/panelstakespanels([{svg, caption, angstrom_per_unit}]),options,formatanddpi.POST /api/figures/mathtakestext,size,formatanddpi;GET /api/figures/mathlists the subset.POST /api/figures/diagramtakesspec(a diagram spec),formatanddpi;GET /api/figures/diagram/schemareturns the spec’s JSON schema.
A refusal is a 422 with the reasons and a missing publication extra a 503.
The MCP tools are cyclic_topology_figure, compose_figure_panels,
figure_math and figure_diagram; each returns SVG text. In Python,
vibesketcher.render.diagram.load_spec reads a spec and diagram(spec, fmt)
draws it.
from vibesketcher.document import crystal
from vibesketcher.render.cyclic_topology import TopologyOptions, topology_figure
from vibesketcher.render.panels import Panel, PanelOptions, cell_width_pt, compose_panels
from vibesketcher.render.periodic import FigureOptions, periodic_figure_svg
graphene = crystal.prototype("graphene", identifier="graphene")
layout = PanelOptions(columns=2, column="double")
width = cell_width_pt(layout)
lattice = periodic_figure_svg(graphene, FigureOptions(repeat=(4, 3, 1), width=width))
torus = topology_figure(graphene, (4, 3, 1), TopologyOptions(width=width, unrolled=False))
pdf = compose_panels(
[
Panel(svg=lattice.decode(), caption="graphene, 4 × 3 cluster"),
Panel(svg=torus.decode(), caption="$N_c = 12$ torus"),
],
layout,
"pdf",
)
Not yet covered¶
Math in drawn canvas text objects (scene and Ketcher text) is open in the issue tracker. The diagram layouts do not route connectors around boxes: a long edge bends only through the gaps between layers, and a manual layout draws straight connectors.
References¶
K. Sugiyama, S. Tagawa and M. Toda, “Methods for visual understanding of hierarchical system structures”, IEEE Trans. Syst. Man Cybern. SMC-11, 109–125 (1981), doi:10.1109/TSMC.1981.4308636.
E. M. Reingold and J. S. Tilford, “Tidier drawings of trees”, IEEE Trans. Softw. Eng. SE-7, 223–228 (1981), doi:10.1109/TSE.1981.234519.