WarpWeaver is a lightweight C++20 tool for inspecting tensor layouts, bitwise swizzles, thread ownership, and shared-memory bank behavior.
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build
ctest --test-dir build --output-on-failureThe first version intentionally has no third-party runtime dependencies. The core library is separated from the CLI so a future TUI or Dear ImGui frontend can reuse the same layout and analysis APIs.
WarpWeaver is most useful when a layout is treated as an experiment. The following examples are deliberately small enough to run, inspect, and modify. Run them from the repository root after building.
Start with eight lanes reading one column of an 8x64 f16 tile:
./build/warpweaver analyze \
--shape 8x64 --dtype f16 \
--access column:0 --lanes 8 --vector-bytes 16 --no-colorThe baseline is intentionally bad: unique_banks=4 and
max_transactions_per_bank=8. Now add a 128-byte TMA swizzle:
./build/warpweaver analyze \
--shape 8x64 --dtype f16 --swizzle tma-128b \
--access column:0 --lanes 8 --vector-bytes 16 --no-colorThe same logical column becomes unique_banks=32 with
max_transactions_per_bank=1. This is an address-mapping experiment, not a
claim about a particular GPU's full execution time, but it makes the reason
for a swizzle visible immediately.
./build/warpweaver show \
--shape 8x16 --tile 4x8 --max-rows 4 --max-cols 8 --no-colorThe command inserts the coordinate stages
(row,col) -> (tile-row,tile-col,local-row,local-col) before the affine
mapping. Try changing 4x8 to 2x4 and compare the physical offsets. The
same transformation can be written as a split followed by a permutation:
./build/warpweaver show \
--shape 8x16 --split 1:8 --permute 1,0,2 \
--max-rows 4 --max-cols 8 --no-color./build/warpweaver owners \
--shape 8x8 --threads-per-warp 8x4 \
--ownership-order 1,0 --no-colorRead each cell as cta:warp:lane:register. Swap the ownership order to
0,1 and the lane pattern rotates: the tensor stays the same, but the
thread-to-coordinate relationship changes.
./build/warpweaver layout \
--expr "(2,(3,3)):(21,(6,1))" \
--dtype f16 --colors 2This renders two top-level blocks, each containing a nested 3x3 mode. The
summary exposes the flattened view as leaf-shape=2x3x3 and
leaf-stride=21,6,1, while the cells retain their source index and logical
coordinate. For a sliding-window view over a 6x6 grid, try:
./build/warpweaver layout \
--expr "(16,(3,3)):(1,(6,1))" \
--grid-shape 6x6 --colors 16The CLI already emits ANSI colors when stdout is a terminal. Force them for a pipe or a captured session with:
./build/warpweaver layout \
--expr "(2,(3,3)):(21,(6,1))" --color alwaysREADME Markdown cannot portably express arbitrary text colors. GitHub-flavored
Markdown supports basic inline HTML, but CSS such as
<span style="color: red">...</span> is sanitized or ignored by common
renderers. ANSI escape sequences are likewise shown as plain text in a
Markdown code block. For documentation that must work everywhere, use code
labels, tables, and a generated image; for a local terminal, use
--color always.
The detailed documentation is organized under docs/:
docs/architecture.md: core data model and mapping pipeline.docs/cli.md: command reference and reproducible examples.docs/swizzles.md: XOR/TMA conventions and analysis models.docs/development.md: C++20 development and testing workflow.docs/nested-layout-design.md: nested shape/stride design and template API.
./build/warpweaver show --shape 8x64 --dtype f16 --swizzle xor:b=3,m=3,s=3
./build/warpweaver analyze --shape 8x64 --dtype f16 --swizzle tma-128b \
--access column:0 --lanes 8 --vector-bytes 16
./build/warpweaver owners --shape 8x8 \
--threads-per-warp 8x4 --ownership-order 1,0
./build/warpweaver layout \
--expr "(2,(3,3)):(21,(6,1))" --dtype f16 --no-color
./build/warpweaver layout \
--expr "(2,(3,3)):(21,(6,1))" --grid-shape 6x6 --no-color
./build/warpweaver layout \
--expr "(16,(3,3)):(1,(6,1))" --grid-shape 6x6 --colors 16show emits a two-dimensional map whose cells are
physical-element-offset|shared-memory-bank. analyze builds a single warp
access trace and reports the distinct 4-byte bank words served by each bank.
--vector-bytes gives each lane a contiguous physical byte range; the command
also reports a global-memory coalescing estimate using 32-byte sectors and
128-byte segments. It is an address-transaction model, not a cache-state or
instruction-scheduling simulation. Use --color always to retain bank colors
when output is not connected to a TTY.
The canonical XOR syntax is xor:b=BIT_COUNT,m=LOW_BITS,s=SHIFT_BITS and uses
the high-to-low form, requiring S >= B. Explicit positional import forms are
also available: xor:bms:B,M,S and xor:cute:M,B,S; the older bare
xor:M,B,S spelling remains accepted for compatibility.
TMA presets additionally validate the 128-byte shared-memory base alignment and
the CUDA requirement that the inner tensor dimension fit inside the selected
32B, 64B, or 128B swizzle width.
Coordinate stages execute in their CLI order before the affine layout:
# Reorder 8x16 logical elements into 4x8 physical tiles.
./build/warpweaver show --shape 8x16 --tile 4x8
# Split the logical column axis and then make the outer column tile major.
./build/warpweaver show --shape 8x16 --split 1:8 --permute 1,0,2--permute AXES accepts a complete axis order, --split AXIS:FACTOR replaces
one axis with outer/inner axes, and --merge AXIS combines one axis with its
next neighbor. --tile ROWSxCOLS is a rank-2 shorthand that produces
(outer_row, outer_col, inner_row, inner_col). Stage factors must divide the
respective dimensions; partial tiles are deliberately not inferred yet.
owners uses a blocked distribution to show logical ownership as
cta-coordinate:warp:lane:register. Configure its hierarchy with
--size-per-thread, --threads-per-warp, --warps-per-cta, and
--ownership-order; the thread tile must multiply to 32 lanes.
layout displays a nested Shape:Stride view. The example above has two
top-level rows and a nested 3x3 column mode, so it prints a 2x9 view whose
element offsets are 0..14 and 21..35. Tuple nesting is preserved in the
summary (leaf-shape=2x3x3, leaf-stride=21,6,1), while each cell shows the
source Grid index and logical view coordinate as
G<index>@<logical-coordinate>.
The command is one-shot and exits after rendering; the interactive session will
build on this same model.
Add --grid-shape 6x6 to see the same mapping over the original grid. The
command then prints every G<linear>@<logical-coordinate> mapping at each
selected original-matrix location; mappings are separated by ;, and .
marks an unselected element. --grid-stride R,C overrides the default
row-major grid stride when the original grid is padded, transposed, or
otherwise non-contiguous.
The view topology still controls coloring: in an (a,(b,c)) view, the a
sub-blocks receive distinct colors. For a flat rank-3 (a,b,c) view, colors
use (a*b*c) % C; configure C with --colors (1 to 256).
When the layout has the sliding-window form (N,(R,C)):(1,(W,1)), the first
mode is interpreted as a row-major window ordinal over a source width W.
For example, ordinal 4 in a 6-column source starts at global index 6, not 4.
The explicit form ((A,B),(R,C)) is rendered as an (A*R)x(B*C) mosaic, so
((4,4),(3,3)) displays 4x4 colored 3x3 windows in a 12x12 table.
The CLI defaults to Torch-style linear indexing, where the last leaf mode is
fastest. Use --order cute to select CuTe's colexicographical indexing and
match the ordering used by CuTe's idx2crd and print_layout conventions.
AffineTransform(Layoutalias): integer coordinate to linear element offset mapping. The first layouts are row-major, column-major, and padded leading-dimension variants.NestedLayout: C++20 template model for recursive shape/stride tuples, with static and dynamic integer leaves plus flattening intoAffineTransform.RuntimeLayout: parser-friendly runtime tuple model used by the CLI to render nested shape/stride expressions without losing their topology. The CLI can enumerate it with Torch or CuTe linear-index order.ComposedLayout: lazyA o Bview with domain validation and optional affine reconstruction throughtry_flatten().BitTransform: a GF(2) bit matrix with composition and invertibility checks.SwizzleTransform: identity or named XOR transform; it can expose its GF(2) bit-matrix representation for visualization and testing.LayoutPipeline: applies affine mapping, then swizzle, then dtype/base address conversion. It also owns the validated coordinate-stage chain: permute, split, merge, and 2D tile. Both terminal and future GUI frontends consume this API.BankAnalyzer: maps vector byte ranges to shared-memory bank words and estimates global-memory sector/segment demand.BlockedOwnershipLayout: maps logical coordinates to CTA, warp, lane, and per-thread register ownership using a configurable blocked hierarchy.warpweaver: ANSI terminal frontend. It has no layout logic and can later be joined by an ImGui frontend that consumes the same core results.
