tensor-formula-viz

Tensor Formula Viz

数式またはテンソルコードの処理経路を、3つのゾーンで構成される、情報量の多いスライド向けの図に変換します。

1. 上段 — 数式： 形状を示す下括弧を使わず、明瞭な数学的定義を示します。
2. 中段 — 計算： 色付きのブロック、ストライプ、スライス、演算子、通信を示します。
3. 下段 — 意味： 各形状次元と、自明でない各演算を簡潔に説明します。

ワークフロー

1. 入力を主要な計算経路1つに絞ります。要求がない限り、等価な目的関数、診断情報、副次的な指標は省略します。
2. 形状と意味の台帳を作成します。記録する項目は、シンボル／コード名、意味上の種類、データ型／値域、グローバル形状とローカル形状、軸の意味、該当する場合は値の範囲、形状の同値類、生成元／消費先、縮約／ブロードキャスト／縮約された軸です。
3. 仕組みが分かる、最小限の視覚表現を選びます。
4. 重複しないステージレーンとオブジェクトのバウンディングボックスを確保してから、3つのゾーンで構成されるレイアウトを描きます。
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}}. ]
• グローバル形状とランクごとのローカル形状を区別します。
• 転置、ブロードキャスト、縮約、形状変更、分割、結合では、軸の順序を明示します。
• 色は意味を表すものとして扱います。図全体を通して、テンソルの役割、ヘッド、またはTPランクごとに色を統一します。

記号の意味と離散オブジェクト

• 自明でない記号はすべて、値、スコア／ロジット、確率、インデックス／座標、順位／順序、カウント、ID、マスク／サポート、置換、または形状パラメーターのいずれかに分類します。その dtype／定義域と、各要素が何を意味するかを明記します。形状だけでは不十分です。
• 1つのブロックには、1つの意味上のオブジェクトだけを割り当てます。スコア、インデックスリスト、マスクを (M/S) のようなラベルの下で決してまとめず、変換ごとに明示的な演算子と矢印を示します。
• 選択やルーティングでは、連続スコア (\rightarrow) 離散インデックス／ID (\rightarrow) gather、scatter、mask、または route (\rightarrow) 選択された値、という一連の流れを最後まで示します。TopKValues と TopKIndices を区別します。両方を使う場合は、両方の出力を示します。
• インデックス表記と範囲は、最初に使用するときに定義します。例：(S_t=(s_{t,1},\ldots,s_{t,k}))、(s_{t,r}\in{0,\ldots,t})。ソース位置軸 (s) と選択スロット／順位軸 (r) を区別し、順序、重複、パディング、可変カーディナリティが重要かどうかを明記します。
• アドレスの対応関係を1回示します。例：(G[b,t,r,:]=X[b,S[b,t,r],:])。マスクも示す場合は、(M[b,t,s]=\mathbf 1[s\in S_{b,t}]) と明記します。整数インデックステンソルとブールマスクが同じオブジェクトであるかのように示してはいけません。
• 整数インデックスは順序付きスロット、位置ラベル、または gather 線で可視化し、マスクは二値の構造的サポートとして可視化します。スコアと値は大きさを表す色ブロックで可視化します。この3つすべてを同じヒートマップの表現で描いてはいけません。
• インデックスを複数のヘッド、順位、または分岐で共有する場合は、共有セレクターを1回だけ描き、ブロードキャスト／再利用される軸を明示します。

必須の幾何学的不変条件

• 各行列面 (a\times b) は、高さ (a)、幅 (b) に対応させます。バッチ化または積み重ねられたテンソルでは、最後の2つの行列軸を面に使用し、先行軸は奥行きまたは反復パネルだけに使用します。
• 形状台帳から幾何台帳を1つ作成します。各記号軸の値に1つの公称物理辺長を割り当て、図全体でその値を再利用します。同じ形状は同値類を形成し、ステージ、順位、意味上の役割が異なっても、面の幅と高さを同一にします。
• (a\times a) は正方形として描きます。転置は、面の高さと幅を物理的に入れ替えて描きます。ラベルだけを変更するのは無効です。
• ((m\times k)(k\times n)) では、縮約される (k) の両方を同じ物理辺長で描きます。einsum の縮約とアテンション軸にも同じ規則を適用します。
• 分割の幾何を維持します。明示的なシャードは分割軸に沿って親を隙間なく正確にタイル状に分割し、同じサイズのシャードは同じ大きさにします。連結は分割を逆にたどります。連結する部分のサイズは、宣言された形状に基づいて決めます。Q/K/V の出力形状が等しい場合に限り、各出力は等しいセグメントです。中間シャードを省略する場合は省略記号を示し、見えているシャードを引き伸ばして親全体に見せかけてはいけません。
• 幾何を変更できるのは、明示的な reshape、flatten、transpose、split、または concat 演算子の箇所に限ります。((h/p)d_h=d/p) のように軸の対応関係を示します。軸の変更前後で、汎用的な同じ長方形を暗黙に使い回してはいけません。
• 説明用のセル数は実際のテンソル次元と一致していなくてもかまいませんが、形状の一致、正方形、転置、縮約、分割に関する不変条件は必ず守ります。

必須のレイアウト不変条件

• すべてのテンソル、オフセットスタック全体、括弧、演算子、矢印ラベル、注釈、記号、形状ラベル、ステージ見出し、意味を示すボックスをバウンディングボックスとして扱います。基準となる余白 (g\geq1,\mathrm{em}) を定め、無関係なボックス同士は少なくとも (g)、ステージ帯同士は少なくとも (1.5g) 離します。接している場合も衝突とみなします。
• 重なりを許可するのは、明示的に定義した複合要素内だけです。具体的には、行列内のタイル、親要素をタイル状に分割するシャード、1つのスタック内の輪郭シート、テンソルを囲む括弧、コネクターの端点が始点または終点の境界に接する場合です。それ以外の交差や隠蔽はすべて禁止します。
• ステージ見出し、コネクター注釈、テンソル／演算子の行、記号、形状には、それぞれ別の縦方向のレーンを確保します。説明文はステージのサブタイトル、下部のボックス、またはコネクターの上に配置し、オペランドの間に浮いた解説カードを挿入しないでください。ただし、実際の演算ノードである場合を除きます。
• コネクターは背景レイヤー、テンソルと演算子はメインレイヤー、テキストは前景レイヤーに配置します。コネクターは、端点以外のボックスを横切ってはいけません。ラベルの白い下地が覆ってよいのは、そのラベル自身のコネクターだけです。テンソルや別のラベルを覆ってはいけません。
• スタックのバウンディングボックスには、すべてのオフセットシートを含めます。背面シートは輪郭のみ、またはごく薄い色で示し、隠れた意味情報は持たせません。スライスを個別に読み取る必要がある場合は、重ねずに別々のパネルを使用します。
• 内容が収まらない場合は、まず二次的な注釈を短縮または削除し、自然な範囲でクロップを広げ、行間を広げ、その後にステージ全体を別の行へ移します。この順序を守ってください。文字階層を下回るまで縮小したり、余白を詰めたり、別のオブジェクトを覆ったりして混雑を解消してはいけません。

シャーディングされた行列積では、トップの式と該当する中央のパネルの両方で、ブロック代数を展開します。

[ \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 のキャンバスを強制しないでください。
• デフォルトではタイトルを追加しないでください。上部には最大 2 行のコンパクトな数式行を配置します。主要なチェーンと、どうしても必要な場合に限り 1 つの補助的な定義です。
• 各ステージは、共通の視覚的ベースラインを持つ 1 つの水平な代数行にしてください。主要なパスを保つ最小限のステージ数を使用し、無関係な分岐やダッシュボードパネルを作成しないでください。
• 次のタイプ階層を再利用してください：\large の数式、中央揃えの \small\bfseries でミュートされたステージラベル、\Large の演算子、\small の記号、\scriptsize でミュートされた図形、\small の下部の文章。
• エントリー行列は、小さな白いガターと控えめな (0.5)–(1) pt の角丸を持つ個別のタイルから構築してください。薄いニュートラルなブラケットまたは black!55–black!70 の外枠を使用し、彩度の高いテンソル色のアウトラインや連続したスプレッドシートグリッドは避けてください。追加の軸には浅いスタックまたは繰り返しパネルを使用してください。
• 大きさの前にサポートをエンコードしてください：既知のすべてのゼロは白/未塗りつぶしのままにし、表示されるすべての非ゼロに色を付けてください。対角、ブロック対角、三角、マスク、またはスパース行列の場合、構造的サポートを正確に塗りつぶしてください。対角行列は、白いフィールド上の色付き対角セルとして即座に読み取れる必要があります。
• 生の彩度の高い原色ではなく、ミュートされた中彩度の紙の色から始めてください。安全なデフォルトパレットは、ティール #4F8FA5、オレンジ #EE995B、コーラル #C95B5B、バイオレット #8A74B5、ニュートラルグレー #85898F です。
• 各テンソルの役割に 1 つのセマンティックカラーを与え、ステージ間で再利用してください。デフォルトでは、代数行ごとに最大 4 つのアクティブな色相ファミリーとニュートラルグレーとします。色相を追加する前に、明度を変化させるか、関連する入力/出力ファミリーを再利用してください。符号が重要な場合は、符号に色相を、大きさに強度を使用してください。
• 最大の彩度ではなく、明度の分離を通じて目に見えるコントラストを維持してください。ゼロ/不在には白またはほぼ白を確保し、値が変化する場合は少なくとも 3 つの分離されたアクティブレベルを使用してください。role!30、role!55、role!80 が実用的なデフォルトです。すべてのデータセルを role!5–role!15 のパステル塗りつぶしでレンダリングしないでください。
• 例示的な密なテンソルの場合、2 つまたは 3 つの非周期的な明度レベルを使用してください。実際の構造をエンコードしない限り、チェッカーボード、規則的なストライプ、対称的なモチーフを生成しないでください。
• 各ブロックのすぐ下に記号を中央揃えし、その形状を次の行に配置してください。
• 全幅で低コントラストの下部ボックスを 1 つ使用し、1 つの読み取り列と最大 3 つの固定ラベル行を配置してください：次元の意味には Axes、セマンティックな種類/ドメイン/範囲には Objects、最大 2 つの必須マッピング、縮約、ブロードキャスト、または境界には Mechanism。これらのラベルは図の言語にローカライズしてください。狭い太字のラベルレール、左揃えで右不揃いの \small コンテンツ、(8)–(10) pt の内部パディング、(0.4)–(0.6) em の行間を使用してください。各行はコンパクトに保ち、数値設定や二次的な解説よりも記号のセマンティクスを優先し、カード、列、またはより小さな文字を追加するのではなくコンテンツを削除してください。
• 下部の意味ボックスの下、ボックスの外側に、低コントラストのニュートラルグレーで \scriptsize 以下のサイズの中央揃えの識別行を 1 つ配置してください。形式は <簡潔な可視化対象>@五道口纳什 とし、山括弧のプレースホルダーを図が可視化するものに置き換え、リテラルの山括弧は省略してください。小さくても目に見える垂直方向の間隔を保ち、1 行に収めてください。例：TP-FFN（GeLU + All-Reduce）@五道口纳什。
• 主要な数式に存在しないチャートやメトリクスのインセット、装飾的なピル、バナー、影、繰り返しのセパレーター、説明的なカードは避けてください。
• 例示的なセル数は視覚的に一貫させてください。これらが文字通りの次元ではなく軸構造を示していることを一度述べ、必須の幾何学的不変条件を弱めないでください。
• 中国語の図の場合、簡潔な中国語ラベルを使用し、役立つ場合は標準的な英語用語を併記してください。

レンダリングと検証

数式が多い図では、編集可能なTikZをデフォルトで使用してください。中国語を含むTikZでは、XeLaTeXとポータブルなTeX Liveフォントセットを必須とします。

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

デフォルトではOS固有のCJKフォントを選択しないでください。ユーザーがブランドフォントまたはシステムフォントを明示的に希望し、移植性が低下することを了承した場合に限り、Fandolを置き換えてください。数学記号は生のUnicodeではなくLaTeXで記述してください。環境が対応している場合は、ソースに加えてPDF、SVG、透過PNG、白背景のPNGを書き出してください。

納品前に、以下を確認してください。

1. すべての図形を個別に再計算します。
2. セマンティクス台帳を監査します。離散記号または多重の意味を持つ記号には、それぞれ型・定義域・値域が1つずつ割り当てられていること、スコア・インデックス・マスクの各オブジェクトが区別されていること、生成元から使用先までの対応関係が閉じていることを確認します。
3. ジオメトリ台帳を監査します。境界ボックスの形状の一致、正方形の面と転置後の面、縮約後の辺の長さ、分割・連結時の総量保存を確認します。
4. ブロック乗算、ブロードキャスト、リダクション、シャーディングの代数を検証します。
5. PNGにレンダリングし、最新の出力を目視で確認します。
6. フルサイズで、すべての境界ボックス、ガター、スタックの範囲、コネクタの経路、レイヤーについて、禁止されている交差、接触、クリッピング、遮蔽がないか監査します。
7. コンパクトな上部、行ごとの代数的処理段階、記号と形状の対応、自然な切り抜き、3行の下部ボックス、中央揃えの識別行、正確な構造的サポートを確認します。識別行が実際の可視化の名称を示し、意味ボックスの外にあり、クリッピングされず、視覚的に目立ちすぎていないことを確認します。サムネイルサイズでは、色相の数と再利用、彩度を抑えたベースカラー、アクティブレベル間の区別、中立的な境界線、ハウススタイルまたは提供された参考資料との一貫性を保つ非周期的なテクスチャを監査します。
8. 必須のセマンティクス、ジオメトリ、レイアウトの不変条件に違反する図は却下し、描き直します。
9. プレビュー、仕組みの簡潔な説明、編集可能またはベクター形式の成果物へのリンクを納品します。

構文的に有効なだけの図は納品しないでください。数学的な正しさと、整然とした視覚的な配置の両方を必須とします。