dela
de917a2fbd
- Bracket ink is part of the fit: \st@facebody drops -inkw/-inke extreme coordinates and \stface/\ststack register them with the enclosing group/col/row fit, so a group outline can no longer be crossed by a member's bracket arms - \stlink inside \stgroup or \stcol is now a package error: sub-flow members never terminate a pending connector, so the arrow was dropped silently while the label still rendered - \stgroup requires role= (explicit role=neutral for mixed groups) and must bind at least two members or one \stcol partition; a lone stack or face inside a group is a dirty-build warning - lint: default budget is one \stcallout per figure; the allow-multiple-callouts directive relaxes it to one per band - build.sh: clean-build hint no longer names hue budget (lint owns it) - tests/group-callout.tex reworked: multi-member group with a bracketed member as a regression probe, single callout; new negative fixtures group-link, group-norole, group-single, callout-budget - api.md, checklist.md, style.md, layout.md, SKILL.md updated to match
100 lines
6.2 KiB
Markdown
100 lines
6.2 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; read `references/fallback.md` before
|
||
falling back and state explicitly which package guarantees are unavailable.
|
||
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` runs the source linter, TeX checks and
|
||
exports. Then run the remaining visual/semantic audit in `references/checklist.md`
|
||
against the PNG at full size and thumbnail size. Redraw on any mandatory 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` |
|
||
| adjacent objects that are one composite (heads of `q`, shards of `W`) | an outline in their own role hue | `\stgroup` … `\stgroupend` |
|
||
| an aside about a whole band | a side card off its right edge, one per figure | `\stcallout` |
|
||
|
||
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.
|
||
- Add `\stsignature{<subject>}{<box>}` only when the user or house template asks for an
|
||
identification line. It renders only the subject, with no author or handle.
|
||
|
||
## 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.
|