dela
7b59c81d02
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.
98 lines
5.9 KiB
Markdown
98 lines
5.9 KiB
Markdown
---
|
||
name: supertensor
|
||
description: Create or refine clean, shape-aware figures for tensor/matrix/vector formulas or tensor code — matrix-block diagrams, entry heatmaps, row/column shard stripes, stacked 3D/4D tensors, attention, tensor/expert parallelism, broadcasting, reductions, contractions, gather/scatter and routing. Use whenever tensor shapes or axis meanings must be visually aligned with the computation. Not for plotting numeric data (loss curves, benchmark bars, scatter plots), architecture block diagrams without shapes, or generic flowcharts.
|
||
---
|
||
|
||
# supertensor
|
||
|
||
Turn a formula or a tensor-code path into one dense, slide-ready figure with three zones:
|
||
|
||
1. **Top — formula.** The clean mathematical definition. No shape underbraces.
|
||
2. **Middle — computation.** Colored faces, shards, stacks, operators, collectives.
|
||
3. **Bottom — meaning.** Axes, object semantics, mechanism. One box, three rows.
|
||
|
||
The `assets/supertensor.sty` package enforces most of the geometry and style rules
|
||
by construction. **Draw with the package; do not hand-roll `\draw` rectangles.**
|
||
A figure built from raw TikZ has to re-earn every invariant by hand and usually fails one.
|
||
|
||
## Workflow
|
||
|
||
1. **Preflight.** `./scripts/preflight.sh`. Exit 0 = TikZ+CJK path. Exit 1 = degraded
|
||
(say so in the delivery). Exit 2 = no LaTeX; fall back to SVG/matplotlib and say
|
||
explicitly that the figure is not TikZ.
|
||
2. **Reduce** the input to one primary computation path. Drop equivalent objectives,
|
||
diagnostics, and secondary metrics unless asked for.
|
||
3. **Build two ledgers** before drawing anything:
|
||
- *shape & semantics* — per symbol: semantic kind, dtype/domain, global and local
|
||
shape, axis meanings, producer/consumer, contracted/broadcast/reduced axes.
|
||
See `references/semantics.md`.
|
||
- *geometry* — one `\stdim{axis}{cells}` per symbolic axis, one `\stsetrole{role}{color}`
|
||
per tensor role. Declaring these makes the invariants automatic.
|
||
See `references/geometry.md`.
|
||
4. **Pick the smallest grammar** that exposes the mechanism (see below), then draw with the
|
||
flow layout — `\ststage` / `\strow` … `\strowend`, empty coordinate arguments, gaps
|
||
declared once. Reach for an absolute coordinate only when no band can express the
|
||
placement. See `references/api.md` and `references/layout.md`.
|
||
5. **Build and audit.** `./scripts/build.sh fig.tex`. A clean build only proves TeX was
|
||
happy; then run the visual audit in `references/checklist.md` against the PNG at full
|
||
size and at thumbnail size. Redraw on any mandatory-invariant violation.
|
||
|
||
For code input, trace the concrete `matmul`, `einsum`, `reshape/view`, `transpose/permute`,
|
||
concat, broadcast, and collective calls. Keep code variable names where useful; state any
|
||
shape or convention you inferred.
|
||
|
||
## Choose the visual grammar
|
||
|
||
| Fact to expose | Grammar | Package |
|
||
|---|---|---|
|
||
| mask, sparsity, causal structure, elementwise roles | entry cells | `\stface[pattern=causal/lower/band/diag/data]` |
|
||
| sharding, device ownership, channel groups | adjacent faces tiling a parent | two `\stface` calls, one role each |
|
||
| leading axes (`B`, `h`) | depth | `\ststack{...}{sheets}` |
|
||
| discrete choices (indices, token ids, expert ids) | symbols in cells, no ramp | `\stindexface` |
|
||
| data movement, collectives, non-linear ops | arrows and nodes | `\stlink`, `\stcomm` |
|
||
| a split along the contracted axis | a vertical pair inside one band slot | `\stcol` … `\stcolend` |
|
||
|
||
Combine grammars only when each one adds information. Known zeros stay unfilled; masks,
|
||
diagonals, sparsity and partitions must encode their exact structure.
|
||
|
||
## Non-negotiables
|
||
|
||
These are the rules that make the figure *true* rather than merely pretty. Each has a
|
||
reference file with the full statement and the failure it prevents.
|
||
|
||
- **Geometry** (`references/geometry.md`) — one symbolic axis, one physical edge length,
|
||
everywhere. `a×a` is a square. A transpose swaps the face, not the label. Both
|
||
occurrences of a contracted `k` are the same length. Shards tile their parent exactly.
|
||
- **Semantics** (`references/semantics.md`) — one block, one semantic object. Scores,
|
||
indices and masks are three different grammars, never one heatmap. Close the chain
|
||
from continuous score to discrete index to gathered value.
|
||
- **Layout** (`references/layout.md`) — everything is a bounding box; tangency counts as
|
||
collision. Reserved lanes for stage heading / tensors / symbols / shapes. Connectors on
|
||
the background layer, text on the foreground layer. Place by cursor, not by hand-tuned
|
||
coordinate: a magic-number offset is only valid for the content it was tuned against.
|
||
- **Style** (`references/style.md`) — muted palette, one hue per role, ≤4 active hues per
|
||
row plus gray, three separated lightness levels, non-periodic texture, no decoration.
|
||
|
||
`references/antipatterns.md` shows what each violation looks like in a rendered figure —
|
||
read it once before your first figure.
|
||
|
||
## Output
|
||
|
||
Default to editable TikZ. `scripts/build.sh` emits PDF, SVG, white-background PNG,
|
||
transparent PNG and a thumbnail. Deliver: the PNG preview, a short mechanism explanation,
|
||
and the `.tex` source plus vector artifact.
|
||
|
||
- **Chinese figures:** `\usepackage[cjk]{supertensor}` (XeLaTeX + portable Fandol). Do not
|
||
select an OS-specific CJK font unless the user asks and accepts the portability cost.
|
||
- **English figures:** `\usepackage[en]{supertensor}` — same geometry, English rail labels.
|
||
- Keep math in LaTeX, not raw Unicode.
|
||
- The identification line is `\stsignature{<subject>}{<box>}`; it renders
|
||
`<subject>@五道口纳什`. Change the handle with `\stsetauthor{...}` only when asked.
|
||
|
||
## Iterating
|
||
|
||
When the user asks for a change, do not restart the figure. Edit the ledger or the one
|
||
call that owns the offending object, rebuild, and re-audit. If a fix requires shrinking
|
||
type, closing the gutter, or covering another object, the layout is wrong — move the stage
|
||
to another row instead. Ask before dropping a stage or an object the user named.
|