szcharlesji/tikz-dl-visualizer

TikZ深層学習ビジュアライザ

あなたは基本（MLP、バックプロパゲーション、CNN、トランスフォーマーとは何か）をすでに知っていて、そのなぜを知りたい学生のために図を描いています。ここでの良い図とは、飾り立てた箱の図ではなく、一目で一つのアイデアが明らかになり、見返すとさらに発見があるものです。スタイルはAlfredo CanzianiのNYU深層学習の本に従います：暗い灰色のページ、ColorBrewer Set3パステルカラー、そして色は常に同じ意味を持ちます。

必要なものはすべてバンドルされています：

• assets/dlviz.sty：パレット（ダークとライト）、表記マクロ、ノードスタイル、pgfplotsの見た目、ヘルパー。常にこれをベースに構築し、ゼロからスタイルを再設定しないでください。それによってすべての図が一つのビジュアル言語で統一されます。
• assets/examples/*.tex（各ファイルの.pngプレビュー付き）：コンパイル済みでレビュー済みの6つの図。それぞれが一つのアーキタイプを表します。PNGを見て目標の品質を確認してください。最も近いものから始めてください。
• scripts/render.py：PDFとPNGにコンパイルし、最初のエラーのみを表示します。
• references/visual-language.md：色の役割、要素の語彙、表記法、タイポグラフィ、レイアウトルール。セッションで最初の図を描く前に読んでください。
• references/archetypes.md：どの概念にどの図が適しているか、さらに図でよくある間違いの表。自分の概念に対応する行を読んでください。
• references/tikz-gotchas.md：私たちが遭遇したコンパイルエラーとレイアウトの落とし穴、その修正方法。コンパイルできない場合や見た目がおかしい場合に読んでください。

ワークフロー

1. 一つのアイデアを見つける

TikZに触る前に、その図が伝えるべき洞察を一文で書き留めてください。学生が見るものとして表現します。例えば：

• 「アテンションの各出力行は、値の行の重み付き平均であり、重みはソフトマックス化されたスコア行列の一行である。」
• 「モーメンタムは振動する勾配成分を打ち消し、一貫した成分を蓄積する。」
• 「残差ブロックは、xがそのまま通過するため、補正F(x)だけを学習すればよい。」

この文が書けないなら、まだ何を描くべきかわかっていません。学生が最も誤解しやすい点は何かを自問し、そこを狙った図にしてください。概念が広い場合（例：「トランスフォーマー」）、最も示唆に富む一つのスライスを選んでそう伝え、残りはフォローアップの図として提供し、一つに詰め込まないでください。

2. アーキタイプを選ぶ

references/archetypes.mdを開き、その文を視覚化できる形を選んでください。主なもの：

アーキタイプ	示すもの	サンプルファイル
パイプライン/計算グラフ	データの流れ、何が何に供給されるか	autoencoder.tex
行列/ヒートマップレイアウト	テンソルの形状と積、重み	attention.tex
グリッド+受容野	局所的、スライド、共有操作	convolution.tex
パラメータ空間の幾何学	最適化経路、損失の輪郭	momentum.tex
小さなプロットの並列	関数や設定の比較	activations.tex
前後の空間変形	層が入力空間に何をするか	linear-map.tex

二つのアーキタイプを組み合わせるのは問題ありませんが（例えばパイプラインに小さなヒートマップをインセット）、一つが支配的であるべきです。

3. 具体的にする

抽象化は直感の敵です。小さく具体的なサイズ（4トークン、d_k=3、5x5入力、2次元パラメータ）を使い、それらが何を表すかを言ってください。実数はプレースホルダーより優れています：合計が1になる重み、出力を検証できる畳み込み、オプティマイザが実際に行う軌跡。

数値はPythonで計算し、手計算や暗算は絶対にしないでください。 短いスクリプト（uv run --with numpy python - または通常のPython）を実行し、その座標や値を.texに貼り付けてください。どのように生成したかをコメントとして残してください。手作りの「説明用」の数値は間違った図の原因です：合計が1.1になるソフトマックス行、入力と一致しない畳み込み出力など。

4. 図を書く

出力フォルダ（ユーザーが指定した場合はそのフォルダ、そうでなければカレントディレクトリ）に <concept>.tex を作成し、以下から始めます：

% Caption: <2-3文：何を見て、何を示しているか>
\documentclass[tikz,border=8pt]{standalone}
\usepackage[dark]{dlviz}   % [light]は白い論文・スライド用
\begin{document}
\begin{tikzpicture}
  ...
\end{tikzpicture}
\end{document}

テーマは図が置かれる場所から選んでください：ダーク（本の見た目）はスライド、スクリーン、およびユーザーが本に合わせるよう求めた場合。ライトは論文、学位論文、講義ノートPDF、宿題、印刷などの紙のような出力先向け、または要求された場合。どちらのヒントもない場合はダークを使用し、[light]について言及してください。色の役割は両方のテーマで保持されるので、切り替えは一言で済みます。

最も重要な原則（詳細は references/visual-language.md）：

• 色＝役割、一貫して。 入力xはピンク、隠れhは緑、予測ỹは紫、ターゲットyは青、潜在zはオレンジ、コスト/損失/エネルギーは赤、エンコーダーはラベンダー、デコーダーはアクア、予測器は黄色、パラメータはゴールド。図、ラベル、数式（\pink{\vx}）で同じ記号に同じ色を使ってください。これにより、目は読まずに絵と数式を結びつけられます。図あたり最大5色程度。構造的なものはすべて白/グレー。
• 対比には二つの色相が必要。 図が二つの条件を比較する場合（プレーン vs 残差、SGD vs モーメンタム、BatchNorm vs LayerNorm）、それぞれに固有の色相を与え、その条件の曲線、ラベル、ハイライト全体でそれらの色相を使用してください。両方とも勾配だからといって両方を赤で描かないでください。赤は共通のもの（損失、逆伝播方向）を示し、比較は一目で読み取れるままになります。
• 大きさを可視化する。 量が増減する場合（勾配ノルム、アテンション重み、分散）、印刷された数字だけでなく、図自体にそれを符号化してください：段階的に細くなる線幅、塗りつぶしの濃淡、矢印の長さ、ドットのサイズ。対応関係もインクを使う価値があります：各サンプルからそれが着地する場所への細い線は、二つの別々のクラウドよりも変換を示すのに優れています。
• 数式を色分けして表示する。 定義式を図の中に、通常は下部に配置し、各項を視覚的な対応物と同じ色で着色してください。
• あらゆるものに形状を。 テンソルにはその形状を控えめな dim スタイルでラベル付けしてください（\(\R^{n\times d_k}\)）。形状の管理はDL操作を理解する上で半分を占めます。
• 一つの例を追跡する。 一つの行、一つのパッチ、一つのステップを（hl スタイル、赤い枠線）それが現れるすべての場所でハイライトし、学生が単一の計算を最初から最後まで追跡できるようにしてください。
• 注釈は控えめに、適所に。 短い斜体の注釈（annot）を細いリーダー線で、説明するものの隣に配置してください。凡例ボックスではなく、直接ラベルを使用してください。全体的なタイトルはなし（キャプションがその役割を果たします）ただし、マルチパネル図には短いパネルラベル、例えば「(a) プレーン: (\vx_l = F_l(\vx_{l-1}))」を annot スタイルで、各パネルの上に明確なスペースを空けて配置します。
• 最小限のインク。 影、グラデーション、それ自体のための3D、装飾的なアイコンはなし。塗りつぶしはストロークカラーの薄い色合い（cell=colorX でこれを行います）。
• 標準表記。 太字小文字ベクトル、太字大文字行列、プレーンスカラー；マクロ（\vx、\mW、\vytld、\softmax）を使用してください。行方向と列方向の規則は、印刷する数式と一致させる必要があります（アテンションはVaswani et al.と同様にトークンごとの行方向Q、K、Vを使用します）。

5. コンパイルして確認する

python <skill-dir>/scripts/render.py path/to/concept.tex

これにより、dlviz.styが図の隣にコピーされ（フォルダをどこでも再コンパイル可能に）、concept.pdfとconcept.pngが書き出されます。コンパイルが失敗した場合は最初のエラーを表示します；references/tikz-gotchas.mdを確認してください。パッケージがない場合はtlmgrコマンドを表示します；ユーザーのマシンにインストールを実行するよう求めずにユーザーに伝えてください。

その後、PNGを開いてレビュアーのように批評してください。 コンパイルは完了ではありません；assets/examplesのすべての図は、確認後少なくとも一ラウンドの修正を必要としました。以下をチェック：

1. 重なりや接触はないか：線上のテキスト、ラベルを通る矢印、ノードの境界に触れるテキスト、軸やパネルの端でクリップされるラベル、一つのパネルの注釈が隣のパネルのラベルにかぶっていないか？密集した領域は拡大して確認してください（magick in.png -crop WxH+X+Y out.png でPNGを切り取る）、サムネイルを信用しないでください。
2. 3秒以内に一つのアイデアが見えますか？目は最初にどこに留まりますか？それは正しいものですか？
3. すべての色が役割を果たしており、各役割がどこでも同じ色で塗られていますか？
4. すべての数値、形状、数式は正しいですか（references/archetypes.mdの事実テーブルを参照）？
5. スペースは均等で、配置は意図的ですか？

修正して再コンパイルし、すべての答えが「はい」になるまで繰り返してください。2、3回の反復は普通です。

6. 成果物を渡す

ユーザーに以下を提供します：

1. PNG（ファイルを表示または送信できる場合はインライン表示）、および.tex、.pdf、dlviz.styへのパス。
2. 読み方ガイド：4〜8文で、図を読む順に目を誘導し（「Qのハイライトされた行から始めて...」）、各視覚要素を数式に結びつけ、最後に要点を述べます。中級の学生向けに書いてください：ニューロンが何かを再説明する必要はありませんが、メカニズムがなぜ機能するかを説明してください。
3. 適応方法についての一文：[light]への切り替え、サイズ変更、または自然なフォローアップ図（例：「次はマルチヘッド版？」）。

.texの先頭にある% Caption:コメントを図と同期させてください；それはユーザーがドキュメントの下に貼り付けるキャプションです。

関連スキル

このスキルは静的な図を作成します：アイデアごとに一つのPDF/PNGを、スライド、論文、印刷用に。二つの関連スキルが同じdlviz.styとビジュアル言語を共有します：

• tikz-live：同じ種類の図をインタラクティブ（ドラッグ、スライド、ホバー、再生）にした自己完結型のWebページ。読者が何かを変更してメカニズムの応答を見る必要がある場合、またはユーザーがインタラクティブで探索可能、ブラウザ内でアニメーションする図を求める場合に使用します。
• tikz-explorer-book：コースや分野全体のWebブックで、概念マップと図の章を持つ；このスキルを静的図に、tikz-liveを動的図に使用します。

要求が特殊な場合

• ユーザー自身のLaTeX文書やプリアンブル。 ユーザーの表記や色がある場合はそれに合わせてください；それでもdlviz.styからスタイルを\inputしたり、必要な部分だけをコピーすることができます。ページの色を上書きしないでください。
• スライド（Beamer）。 スタンドアロンの図を作成し、\includegraphicsの使用方法を示してください；ステップバイステップのビルドには、\only<n> / \visible<n>をレイヤーに配置するか、複数のスタンドアロンファイル（step-1、step-2...）を作成してください。
• アニメーションや時間経過のプロセス。 印刷やスライドには、一つの図に小さな多重図（t = 0、1、2、...、T）を優先してください；パネルのシーケンスはアニメーションが隠す傾向を示します。画面で読まれ、読者がステップまたはスクラブする場合は、代わりにtikz-liveを使用してください。
• PowerPoint / Keynote。 PNG（200 dpiでレンダリング、スライド幅いっぱいでシャープ）またはPDFを挿入してください；白いスライドテンプレートには[light]を使用します。
• 論文の図。 [light]を使用し、論文に記載されている場合は図内の数式を削除し、フォントは論文のものに合わせてください（dlvizはフォントパッケージを読み込まないため、ドキュメントのフォントが使用されます）。
• 3Dサーフェス。 pgfplotsの\addplot3[surf]をview={...}と控えめなカラーマップ（colormap name=dlheat）で使用し、等高線プロットの方が説明に適しているかどうかを尋ねてください。通常は等高線の方が適しています。