SuperTensor/references/api.md

supertensor.sty API

\documentclass[border=10pt]{standalone}
\usepackage[cjk]{supertensor}     % cjk: ctex + fandol (XeLaTeX). en: English rail labels.

Build with ./scripts/build.sh fig.tex — it puts assets/ on TEXINPUTS, so the package does not need to be installed into your texmf tree.

Ledgers

\stsetrole{q}{stTeal}      % role -> color. Macros take a ROLE, never a color.
\stdim{T}{6}               % symbolic axis -> physical edge length in cells
\stsetauthor{...}          % default 五道口纳什
\stsetlabels{A}{O}{M}      % override the three meaning-box rail labels
\stsetrail{3.2em}          % width of the bold label rail

Colors: stTeal stOrange stCoral stViolet stGray stInk. An unknown role falls back to gray and emits a package warning, which build.sh turns into a failed build.

Lengths: \stunit (one cell, 4.6 mm) and \sttilegap (white gutter, 0.5 mm).

Faces

\stface[keys]{name}{(coord)}{rows}{cols}
\ststack[keys]{name}{(coord)}{rows}{cols}{sheets}
\stindexface[keys]{name}{(coord)}{rows}{cols}{entries}

rows/cols accept a declared axis name or a raw integer. (coord) must include its own parentheses — {(0,0)}, {($(A.east)+(1.5,0)$)}. name becomes a TikZ node you can anchor against; \ststack also defines name-front.

Keys:

key	default	meaning
role=	neutral	hue, via \stsetrole
pattern=	dense	solid dense diag band lower upper causal empty data
data=	—	with pattern=data: comma-separated rows, one digit per cell, 0–3 = level
level=	2	level for pattern=solid and the flat level of a mask
bracket=	false	thin neutral matrix brackets
border=	true	outer black!60 border
tiles=	true	false = one flat filled rectangle

\stindexface entries are row-major, rows*cols of them; . leaves a cell blank. It deliberately has no lightness ramp — see semantics.md.

\stface[role=w, pattern=data, level=3,
        data={3300,0330,0033,3003,3030,0303}]{D}{(0,0)}{T}{E}
\stindexface[role=idx]{I}{(b)}{T}{k}{0,1, 1,2, 2,3, 3,0, 0,2, 1,3}

Captions

\node[inner sep=0pt, fit=(A)(B)(C)] (rowA) {};
\stlane{rowA}
\stcaption{A}{$\mathbf A$}{$T\times d$}     % symbol lane, shape lane
\stnolane
\stcaptiontop{A}{\stshapefont{token}}       % occasional label above a face

\stcaption defines name-sym and name-shape nodes; anchor the next stage heading against name-shape.south.

Operators, connectors, nodes

\node[st op, right=6mm of A] (m) {$\times$};
\node[st comm, right=9mm of P] (ar) {All-Reduce};
\starrow{P.east}{ar.west}
\starrowlabel{M.east}{A.west}{softmax}

Styles: st sym st shape st stage st op st note st arrow st comm st brace. Text helpers: \stformula \ststagelabel \stoperator \stsymfont \stshapefont \stprose. Connectors route on the background layer automatically.

Bottom

\node[inner sep=0pt, fit=(F)(rowA)(rowB)(Y-shape)] (all) {};
\stmeaningbox{mb}{16.6cm}{all}{axes text}{objects text}{mechanism text}
\stsignature{因果多头注意力（掩码 + 拼接投影）}{mb}

Arg 2 is the total box width; arg 3 is the node it hangs below — include every caption and top label in that fit or the box will overlap them. An empty {} row is dropped.

Gotchas

• \ststack never re-enters \stface; if you extend the package, do not pass role=\st@role back through pgfkeys — it defines the macro in terms of itself and hangs.
• A coordinate expression inside fit= needs braces: fit={(a) ($(b)+(1,0)$)}.
• \foreach {\macro,...,1} cannot infer its direction from an unexpanded macro.
• \strole is expandable on purpose (it is used inside \edef); the warning lives in \stcheckrole.