Files

T

dela 7b59c81d02 Add flow layout: cursor placement, left rail, declared band heights

Figures were positioned by hand-written offsets. Every gap was a magic
number tuned against the content that happened to be there, so a label
that grew two characters landed on the next tensor, and two stages
started from two different x shared no rail. Both failures compile
cleanly.

Replace it with a cursor. Objects placed with an empty coordinate
argument reserve their own width -- including a stack's offset sheets
and a bracket's overhang -- and gaps are declared once (\stgutter,
\strowgap, \stblockgap). The gap belongs to the object that follows it
and the first object in a band gets none, so every band starts flush on
a shared rail and gap=0pt states that two shards tile exactly.

\stlink makes a connector's label a flow object, which is what removes
the label-wider-than-its-arrow failure entirely. \stcol is a vertical
sub-flow for a split along the contracted axis. \strow declares its
height, so an object that does not fit -- or a column that does not add
up to what it declared, and is therefore drawn off-center -- becomes a
package warning, which build.sh fails on.

Absolute placement is unchanged: passing a coordinate takes the original
code path, and \sttrack folds a hand-placed node back into the cursor.

All three golden examples and the new tests/flow.tex are converted and
build clean.

2026-08-05 15:55:21 +08:00

4.3 KiB

Raw Blame History

supertensor

A shape-aware toolkit for drawing tensor formulas: a LaTeX/TikZ macro package, a build pipeline that fails on silent corruption, worked examples, and an agent skill that ties them together.

It exists because figures of this kind fail in a specific way — they compile, they look clean, and they tell the reader something false. A face captioned Kᵀ that was never transposed; shards that do not tile their parent; an index tensor drawn with a lightness ramp. The package's job is to make the correct thing the easy thing.

SKILL.md              the skill entry point (lean; loads references on demand)
references/           geometry, semantics, layout, style, api, checklist, antipatterns
assets/supertensor.sty  the macro package
scripts/preflight.sh  is the TikZ + CJK path available?
scripts/build.sh      compile, audit the log, export pdf/svg/png/thumb
examples/             three golden examples + an anti-pattern gallery

Quick start

./scripts/preflight.sh                       # 0 = full path, 1 = degraded, 2 = no LaTeX
./scripts/build.sh examples/mha-causal.tex   # -> examples/build/mha-causal.{pdf,svg,png}

A minimal figure:

\documentclass[border=10pt]{standalone}
\usepackage[cjk]{supertensor}

\stsetrole{act}{stTeal}      % one hue per tensor role, held across every stage
\stsetrole{w}{stOrange}
\stdim{T}{6}                 % one symbolic axis -> one physical edge length
\stdim{d}{4}

\begin{document}\begin{tikzpicture}
  \ststage{S1}{one band, placed by cursor}
  \strow{row}{T}                            % band height, declared once
    \stface[role=act, bracket=true]{X}{}{T}{d}   % empty coord = at the cursor
    \stglyph{m}{$\times$}
    \stface[role=w]{W}{}{d}{d}
  \strowend
  \stcaption{X}{$\mathbf X$}{$T\times d$}
  \stcaption{W}{$\mathbf W$}{$d\times d$}
\end{tikzpicture}\end{document}

Because T and d come from the ledger, the contracted axis is automatically one edge length in both operands, d×d is automatically square, and any other face of shape T×d in the figure is automatically identical to X.

Because the coordinates are empty, each object reserves its own width and the gap between them is \stgutter, declared once. Nothing here is a tuned offset, so growing a label can only push its neighbours apart — it can never land on top of one. And the band declares its height, so an object that does not fit is a failed build rather than something the reader discovers.

See references/api.md for the full macro list.

Examples

file	shows
`tp-ffn-allreduce.tex`	column-then-row sharding, exact tiling, one hue per TP rank, a collective as a real node, a `\stcol` split along the contracted axis
`mha-causal.tex`	leading axes as stack depth, a physically swapped `Kᵀ`, a mask in a different grammar from the scores it gates
`moe-topk-gather.tex`	scores → indices → Boolean support → gather, with all three cell grammars side by side
`antipatterns.tex`	four figures that compile cleanly and still teach something false

Using it as an agent skill

SKILL.md is the entry point; the references/ files are loaded on demand. Point your agent runtime at this directory (for Claude Code, symlink or copy it under ~/.claude/skills/). The skill assumes scripts/ and assets/ sit beside it.

Why the build script fails on warnings

Two LaTeX warnings produce a figure that is quietly wrong rather than visibly broken: Missing character (a CJK glyph silently dropped — the label just is not there) and Overfull \hbox (text escaping its reserved lane and landing on a tensor). build.sh greps for both and exits non-zero. A Package supertensor Warning — an undeclared role falling back to gray — is treated the same way.

The flow layout adds two of its own: an object that overflows its band, and a \stcol whose contents do not add up to the height it declared (which means it is drawn off-center). Both are things a reader would have to notice for you.

A clean build still proves nothing about collisions, hue budget or whether the math is right. That is what references/checklist.md is for.

Provenance

Extracted from the tensor-formula-viz skill in wdkns-skills, which remains in place unchanged. The prose rules that could be enforced mechanically became macros; the rest became references/.

4.3 KiB Raw Blame History Unescape Escape