tensor-formula-viz

Tensor Formula Viz

将公式或张量代码路径转化为一张密集、适合幻灯片展示的图，分为三个区域：

1. 顶部 — 公式： 清晰的数学定义，不使用形状下括号。
2. 中部 — 计算： 彩色区块、条纹、切片、运算符和通信。
3. 底部 — 含义： 简要说明每个形状维度和不显而易见的操作。

工作流

1. 将输入精简为一条主要计算路径。除非用户另有要求，否则省略等价目标、诊断信息和次要指标。
2. 建立形状与语义清单：符号／代码名称、语义类型、数据类型／取值域、全局和本地形状、轴的含义、有意义时的取值范围、形状等价类、生产者／消费者，以及收缩／广播／归约的轴。
3. 选择能清楚呈现机制的最精简视觉语法。
4. 预留互不重叠的阶段通道和对象边界框，然后绘制三段式布局。
5. 渲染并检查，修正数学和视觉对齐。

对于代码输入，追踪具体的 matmul、einsum、reshape/view、transpose/permute、拼接、广播和集合通信操作。在适用时保留代码变量名；注明推断出的形状或约定。

选择视觉语法

• 元素色块： 用于掩码、稀疏性、因果结构、逐元素操作，或小矩阵中的行／列角色。
• 行／列条纹： 用于分片、设备所有权、张量并行、通道组，或关键在于整个轴如何分区的操作。
• 堆叠切片或头部面板： 用于 (B\times T\times d) 或 (B\times h\times T\times d_h) 等 3D／4D 张量。让深度／面板直观地表示额外的轴。
• 箭头和设备／集合通信节点： 用于 AllReduce、AllGather、ReduceScatter、转置、重塑、拆分、拼接或数据移动。

仅在每种视觉语法都能提供额外信息时才组合使用。单元格的变化可以为稠密张量提供视觉层次，但已知为零的元素应保持未填充；掩码、对角线、稀疏性和分区必须精确呈现其结构。

公式和形状规则

• 让每个展示的公式保持简洁。代数式中绝不使用形状下括号；仅在中部对应区块下方标注形状。
• 将符号居中放在区块正下方；在下一行居中标注形状。
• 在底部解释维度含义，而不是重复形状列表。
• 明确展示收缩维度： [ (m\times k)(k\times n)\rightarrow(m\times n). ]
• 对于作用于最后一个维度的线性层，保留前导轴： [ (B\times T\times d_{\mathrm{in}}) (d_{\mathrm{in}}\times d_{\mathrm{out}}) \rightarrow B\times T\times d_{\mathrm{out}}. ]
• 区分全局形状和每个 rank 的本地形状。
• 明确标示转置、广播、归约、重塑、拆分和拼接的轴顺序。
• 让颜色承载语义：整张图中，每种张量角色、头部或 TP rank 使用一种固定颜色。

符号语义与离散对象

• 将每个不明显的符号归类为值、分数／logit、概率、索引／坐标、排名／顺序、计数、ID、掩码／支持集、排列或形状参数。说明其数据类型／取值域，以及每个条目代表什么；仅给出形状是不够的。
• 一个区块只表示一个语义对象。切勿将分数、索引列表和掩码合并为 (M/S) 之类的标签；每次转换都要用显式运算符和箭头表示。
• 对于选择或路由，要完整展示整个链路：连续分数 (\rightarrow) 离散索引／ID (\rightarrow) 收集、散布、掩码或路由 (\rightarrow) 选出的值。区分 TopKValues 与 TopKIndices；如果两者都用到，要同时展示两个输出。
• 首次使用时定义索引记法和范围，例如 (S_t=(s_{t,1},\ldots,s_{t,k}))，(s_{t,r}\in{0,\ldots,t})。区分源位置轴 (s) 与选中槽位／排名轴 (r)，并说明顺序、重复、填充或基数可变性是否重要。
• 仅展示一次地址映射，例如 (G[b,t,r,:]=X[b,S[b,t,r],:])。如果同时展示掩码，要说明 (M[b,t,s]=\mathbf 1[s\in S_{b,t}])；不要暗示整数索引张量和布尔掩码是同一个对象。
• 将整数索引可视化为有序槽位、位置标签或收集连线；将掩码可视化为二值结构支持；将分数和值可视化为用颜色表示幅度的色块。不要用相同的热力图样式表示这三者。
• 当多个头、排名或分支共享索引时，只绘制一次共享选择器，并明确标出广播／复用的轴。

强制几何不变量

• 将每个矩阵面 (a\times b) 映射为高度 (a)、宽度 (b)。对于批处理或堆叠张量，矩阵面使用最后两个矩阵轴，前导轴仅用于表示深度或重复面板。
• 根据形状清单推导一份几何清单。为每个符号轴值分配一个标称物理边长，并在整张图中重复使用。形状相同的对象属于同一等价类，在不同阶段、排名和语义角色中必须具有相同的面宽和面高。
• 将 (a\times a) 绘制为正方形。绘制转置时必须在物理上交换面的高度和宽度；仅更改标签无效。
• 在 ((m\times k)(k\times n)) 中，两处收缩维度 (k) 都必须使用相同的物理边长。einsum 收缩和注意力轴也适用同一规则。
• 保持分区几何不变。显式分片必须沿拆分轴完整平铺其父对象；大小相同的分片必须尺寸相同；拼接必须还原拆分。根据声明的形状确定拼接部分的尺寸——只有当输出形状相同时，Q/K/V 才是等长分段。如果省略中间分片，要显示省略号，绝不能拉伸可见分片来冒充完整父对象。
• 仅在显式的重塑、展平、转置、拆分或拼接运算处改变几何形状。说明轴的身份，例如 ((h/p)d_h=d/p)；轴发生变化前后，不得悄然复用同一个通用矩形。
• 示意图中的单元格数量不必与实际张量维度相符，但这不能豁免形状相等、正方形、转置、收缩或分区不变量。

强制布局不变量

• 将每个张量、完整偏移量堆栈、括号、运算符、箭头标签、注释、符号、形状标签、阶段标题和释义框都视为边界框。定义一个基础间距 (g\geq1,\mathrm{em})；无关边界框之间至少保持 (g) 的间距，阶段带之间至少保持 (1.5g) 的间距。相切也算碰撞。
• 仅允许在一个已声明的组合体内部重叠：矩阵内的分块、平铺父块的分片、同一堆栈中的轮廓片、包围张量的括号，或位于源/目标边界上的连接器端点。禁止任何其他相交或遮挡。
• 为阶段标题、连接器注释、张量/运算符行、符号和形状分别预留垂直区域。说明性文字放在阶段副标题、底部框或连接器上方；除非浮动说明卡是真实的运算节点，否则不得将其插在操作数之间。
• 将连接器置于背景层，张量和运算符置于主层，文字置于前景层。连接器不得穿过非端点边界框；标签的白色底衬只能遮盖其自身的连接器，不得遮盖张量或其他标签。
• 将堆栈中的所有偏移片都计入堆栈的边界框。后置片使用仅描边或极浅的填充，不包含隐藏的语义内容；如果需要单独阅读切片，请使用独立面板，而不是重叠显示。
• 内容放不下时，依次缩短或删除次要注释、扩大自然裁切范围、增加行间距，或将整个阶段移至另一行。切勿通过缩小字体至低于排版层级要求、压缩间距或遮盖其他对象来解决拥挤问题。

对于分片矩阵乘法，请在顶部公式和相关的中间面板中展开分块代数：

[ \mathbf X\mathbf W

[\mathbf X\mathbf W^{(1)}|\cdots|\mathbf X\mathbf W^{(p)}]

[\mathbf H^{(1)}|\cdots|\mathbf H^{(p)}], ]

[ [\mathbf H^{(1)}|\cdots|\mathbf H^{(p)}] \begin{bmatrix} \mathbf W^{(1)}\ \vdots\ \mathbf W^{(p)} \end{bmatrix}

\sum_r\mathbf H^{(r)}\mathbf W^{(r)}

\sum_r\mathbf P^{(r)}. ]

风格指南

• 当入门级矩阵块是重点，或用户要求采用类似 Kimi 的风格时，绘制前请用图像查看器检查 assets/kimi-matrix-style-reference.png。仅将其用于校准单元间距、圆角、中性括号、克制的色相、明度区分和结构留白；不要照搬其公式或内容，也不要将该资源嵌入输出。
• 使用白色背景和自然的 standalone 裁切。除非用户要求，否则不要强制使用 16:9 画布。
• 默认不添加标题。顶部最多放两行紧凑公式：主链，以及仅在确有必要时添加的一条补充定义。
• 每个阶段都排成一条水平代数行，并共享视觉基线。在保留主路径的前提下尽量减少阶段；不要创建无关分支或仪表板面板。
• 沿用以下字体层级：\large 公式、居中的 \small\bfseries 柔和阶段标签、\Large 运算符、\small 符号、\scriptsize 柔和形状标注，以及 \small 底部说明文字。
• 将入门级矩阵拆分为独立单元，单元间留出细窄的白色间隙，圆角轻微，约为 (0.5)–(1) pt。使用细窄的中性括号或 black!55–black!70 外边框；避免高饱和的张量色轮廓和连续的电子表格网格。增加维度时使用浅层堆叠或重复面板。
• 先编码支撑结构，再编码数值大小：所有已知零值保持白色或不填充，所有展示的非零值都着色。对于对角、分块对角、三角、掩码或稀疏矩阵，精确填充结构支撑区域；对角矩阵应一眼看出是白色区域上的彩色对角单元。
• 以柔和、中等色度的纸感色彩为起点，而非直接使用高饱和原色。安全的默认调色板为青绿 #4F8FA5、橙色 #EE995B、珊瑚红 #C95B5B、紫色 #8A74B5 和中性灰 #85898F。
• 为每种张量角色指定一种语义颜色，并在各阶段复用。同一代数行默认最多使用四种活跃色相系列，另加中性灰；添加新色相前，先调整明度或复用相关的输入／输出颜色系列。若正负号有意义，用色相表示符号，用强度表示大小。
• 通过明度区分维持清晰对比，不要一味追求高饱和度。白色或近白色仅用于表示零值／缺失；数值变化时，至少使用三档彼此有明显区分的活跃明度。role!30、role!55 和 role!80 是实用的默认值。不要将所有数据单元都填充为 role!5–role!15 的浅色。
• 对示意性稠密张量，使用两到三档非周期性明度。除非用于表达真实结构，否则不要生成棋盘格、规则条纹或对称图案。
• 将符号置于对应矩阵块正下方居中，形状标注放在下一行。
• 底部使用一个通栏、低对比度的说明框，采用单列布局，最多包含三行固定标签：轴表示维度含义，对象表示语义类型／定义域／值域，机制表示最多两个必要的映射、缩并、广播或边界；这些标签应使用图示所用的语言。标签栏应窄且加粗，内容使用左对齐、右侧参差的 \small 字体；内边距为 (8)–(10) pt，行间距为 (0.4)–(0.6) em。每行保持紧凑；优先说明符号语义，而非数值配置或次要评论。如需精简，应删减内容，而不是添加卡片、列或缩小字号。
• 在底部说明框外、其下方居中放置一行图示标识，使用低对比度中性灰和 \scriptsize 或更小字号。格式为 <简洁的可视化主题>@五道口纳什，将尖括号内的占位文本替换为图示内容，并省略尖括号；保持单行，与上方留出较小但清晰可见的垂直间距。例如：TP-FFN（GeLU + All-Reduce）@五道口纳什。
• 避免添加主公式中未包含的图表或指标插图、装饰性胶囊标签、横幅、阴影、重复分隔线和说明卡片。
• 让示意单元数量在视觉上保持一致；只需说明一次这些单元表示轴结构，而非实际维度，不要因此弱化必须遵守的几何规则。
• 中文图示使用简洁的中文标签，并可在适当时保留标准英文术语。

渲染与验证

对于公式密集型图示，默认使用可编辑的 TikZ。对于中文 TikZ，要求使用 XeLaTeX 和便携式 TeX Live 字体集：

\usepackage[UTF8,fontset=fandol]{ctex}

默认不要选择特定操作系统的 CJK 字体。只有当用户明确要求使用品牌字体或系统字体，并接受可移植性降低时，才覆盖 Fandol。数学符号使用 LaTeX，而非原始 Unicode。如果环境支持，请同时导出源文件、PDF、SVG、透明 PNG 和白底 PNG。

交付前：

1. 独立重新计算每个形状。
2. 审核语义台账：每个离散符号或多义符号都只有一个类型／定义域／值域；分数、索引和掩码对象彼此不同；生产者到消费者的映射完整闭合。
3. 审核几何台账：边界框形状相等、正面和转置面为正方形、收缩后的边长，以及拆分／拼接守恒。
4. 验证矩阵块乘法、广播、归约和分片代数。
5. 渲染为 PNG，并目视检查最新输出。
6. 在完整尺寸下，审核每个边界框、间距、堆叠范围、连接线走向和图层，确保不存在禁止的交叉、相切、裁切或遮挡。
7. 检查顶部的紧凑布局、逐行的代数阶段、符号／形状对齐、自然裁切、底部三行框、居中的标识行以及精确的结构支撑。确认标识行准确说明实际可视化内容，位于含义框之外，且既未被裁切，也不会在视觉上喧宾夺主。在缩略图尺寸下，依据设计规范或提供的参考，审核色相数量及其复用、柔和的基础色、不同活跃级别之间的区分、中性的边框，以及非周期性纹理。
8. 如果图示违反任何强制性的语义、几何或布局不变量，则拒绝并重新绘制。
9. 交付预览、简短的机制说明，以及可编辑／矢量制品的链接。

不要交付仅在语法上有效的图示；数学正确性和清晰的视觉对齐都必须达标。