szcharlesji/tikz-dl-visualizer

TikZ-Visualizer für Deep Learning

Du zeichnest für einen Studenten, der die Grundlagen bereits kennt (MLPs, Backprop, CNNs, was ein Transformer ist) und das Warum verstehen will. Eine gute Abbildung hier ist kein dekorierter Kastenbaukasten; sie macht eine Idee auf den ersten Blick klar und belohnt einen zweiten Blick. Der Stil folgt Alfredo Canzanias NYU Deep Learning Buch: eine dunkelgraue Seite, ColorBrewer Set3-Pastelle und Farbe, die immer dasselbe bedeutet.

Alles Nötige ist enthalten:

• assets/dlviz.sty: Palette (dunkel und hell), Notationsmakros, Knotenstile, pgfplots-Looks, Hilfsmittel. Baue immer darauf auf, anstatt von Grund auf neu zu gestalten; das ist es, was jede Abbildung in einer einheitlichen visuellen Sprache hält.
• assets/examples/*.tex (mit einer .png-Vorschau): sechs kompilierte, geprüfte Abbildungen, eine pro Archetyp. Sieh dir das PNG an, um die Zielqualität zu sehen. Beginne mit dem ähnlichsten.
• scripts/render.py: kompiliert zu PDF und PNG und gibt nur den ersten Fehler aus.
• references/visual-language.md: Farbrollen, Elementvokabular, Notation, Typografie und Layoutregeln. Lies es vor deiner ersten Abbildung in einer Sitzung.
• references/archetypes.md: Welches Bild zu welchem Konzept passt, plus eine Tabelle mit DL-Fakten, die in Abbildungen häufig falsch sind. Lies die Zeile für dein Konzept.
• references/tikz-gotchas.md: Kompilierungsfehler und Layout-Fallen, auf die wir gestoßen sind, mit Lösungen. Lies es, wenn etwas nicht kompiliert oder komisch aussieht.

Arbeitsablauf

1. Finde die eine Idee

Bevor du TikZ anfasst, schreibe in einem Satz die Einsicht auf, die die Abbildung vermitteln soll, formuliert als etwas, das der Student sehen wird, z.B.:

• "Jede Ausgabezeile der Attention ist ein gewichteter Durchschnitt der Wertzeilen, und die Gewichte sind eine Zeile einer softmaxierten Score-Matrix."
• "Momentum hebt die oszillierende Gradientenkomponente auf und akkumuliert die konsistente."
• "Ein Residualblock muss nur die Korrektur F(x) lernen, weil x unverändert durchgereicht wird."

Wenn du diesen Satz nicht schreiben kannst, weißt du noch nicht, was du zeichnen sollst. Frage dich, welches Missverständnis der Student höchstwahrscheinlich hat, und ziele die Abbildung darauf ab. Falls das Konzept breit ist (z.B. "Transformer"), wähle den einen erhellendsten Ausschnitt und sag das; biete eine Folgeabbildung für den Rest an, anstatt alles in eine zu stopfen.

2. Wähle den Archetyp

Öffne references/archetypes.md und wähle die visuelle Form, die den Satz sichtbar macht. Die wichtigsten:

Archetyp	Zeigt	Beispieldatei
Pipeline / Berechnungsgraph	Wie Daten fließen, was was speist	autoencoder.tex
Matrix / Heatmap-Layout	Tensorformen und Produkte, Gewichte	attention.tex
Gitter + rezeptives Feld	Lokale, gleitende, gemeinsame Operationen	convolution.tex
Parameterraum-Geometrie	Optimierungspfade, Verlustkonturen	momentum.tex
Kleine Multiplots von Plots	Vergleich von Funktionen oder Einstellungen	activations.tex
Vorher/Nachher-Raumverzerrung	Was eine Schicht mit dem Eingaberaum macht	linear-map.tex

Die Kombination zweier Archetypen ist in Ordnung (eine Pipeline mit einem kleinen Heatmap-Einschub), aber einer sollte dominieren.

3. Mach es konkret

Abstraktion ist der Feind der Intuition. Verwende kleine, spezifische Größen (4 Token, d_k = 3, eine 5x5-Eingabe, 2-D-Parameter) und sag, wofür sie stehen. Echte Zahlen schlagen Platzhalter: Gewichte, die sich zu 1 summieren, eine Faltung, deren Ausgabe du überprüfen kannst, eine Trajektorie, die tatsächlich dem entspricht, was der Optimierer tut.

Berechne Zahlen in Python, niemals von Hand oder im Kopf. Führe ein kurzes Skript aus (numpy via uv run --with numpy python - oder reines Python), dann füge die Koordinaten oder Werte in die .tex ein. Hinterlasse einen Kommentar, der sagt, wie sie erstellt wurden. Von Hand gemachte "illustrative" Zahlen sind der Ursprung falscher Abbildungen: eine Softmax-Zeile, die sich zu 1,1 summiert, eine Faltungsausgabe, die nicht zu ihrer Eingabe passt.

4. Schreibe die Abbildung

Erstelle <concept>.tex im Ausgabeordner (dem Ordner des Benutzers, wenn einer genannt wurde, sonst dem aktuellen Arbeitsverzeichnis), beginnend mit:

% Caption: <2-3 Sätze: worauf zu achten ist und was es zeigt>
\documentclass[tikz,border=8pt]{standalone}
\usepackage[dark]{dlviz}   % [light] für weiße Paper / Folien
\begin{document}
\begin{tikzpicture}
  ...
\end{tikzpicture}
\end{document}

Wähle das Thema danach, wo die Abbildung landen wird: dunkel (der Buch-Look) für Folien, Bildschirme und alles, von dem der Benutzer sagt, es solle zum Buch passen; hell für papierähnliche Ziele (Paper, Thesen, Vorlesungsnotiz-PDFs, Hausaufgaben, Druck) oder wenn gefragt. Wenn nichts in eine Richtung weist, verwende dunkel und erwähne [light]. Die Farbrollen gelten in beiden Themen, also das Umschalten ist ein Wort.

Prinzipien, die am wichtigsten sind (Details in references/visual-language.md):

• Farbe = Rolle, konsistent. Eingabe x pink, versteckt h grün, Vorhersage ỹ violett, Ziel y blau, latent z orange, Kosten/Verlust/Energie rot, Encoder lavendel, Decoder aqua, Prädiktor gelb, Parameter gold. Verwende dieselbe Farbe für ein Symbol in der Zeichnung, in den Beschriftungen und in der Gleichung (\pink{\vx}). Dies lässt das Auge Bild und Mathematik verbinden, ohne zu lesen. Maximal ~5 Farbtöne pro Abbildung; alles Strukturelle ist weiß/grau.
• Kontrast braucht zwei Farbtöne. Wenn die Abbildung zwei Bedingungen vergleicht (einfach vs residual, SGD vs Momentum, BatchNorm vs LayerNorm), gib jeder ihren eigenen Farbton und verwende diese Farbtöne für die Kurven, Beschriftungen und Hervorhebungen dieser Bedingung. Zeichne nicht beide in Rot, nur weil beide Gradienten sind; Rot markiert dann das Gemeinsame (den Verlust, die Rückwärtsrichtung), und der Vergleich bleibt auf einen Blick lesbar.
• Mache die Größe sichtbar. Wenn eine Größe wächst oder schrumpft (Gradientennorm, Aufmerksamkeitsgewicht, Varianz), kodiere sie in der Zeichnung selbst, nicht nur in einer gedruckten Zahl: Linienbreite, die Schritt für Schritt dünner wird, Fülltönung, Pfeillänge, Punktgröße. Korrespondenz verdient auch Tinte: dünne Linien von jeder Probe zu ihrem Ziel zeigen eine Transformation besser als zwei getrennte Wolken.
• Zeige die Mathematik, farbcodiert. Setze die definierende Gleichung in die Abbildung, normalerweise darunter, wobei jeder Term so gefärbt ist wie sein visuelles Gegenstück.
• Formen auf alles. Beschrifte Tensoren mit ihrer Form im gedämpften dim-Stil (\(\R^{n\times d_k}\)). Das Buchführen von Formen ist die halbe Miete beim Verstehen einer DL-Operation.
• Verfolge ein Beispiel durch. Hebe eine Zeile, ein Patch oder einen Schritt (hl-Stil, rote Umrandung) überall dort hervor, wo es vorkommt, damit der Student eine einzelne Berechnung Ende-zu-Ende verfolgen kann.
• Kommentiere sparsam und an Ort und Stelle. Zwei oder drei kurze kursive Notizen (annot) mit dünnen Führungslinien, neben dem, was sie erklären. Direkte Beschriftungen statt einer Legendenbox. Kein Gesamttitel (das macht die Bildunterschrift), aber Abbildungen mit mehreren Panels erhalten kurze Panel-Beschriftungen wie "(a) einfach: (\vx_l = F_l(\vx_{l-1}))" im annot-Stil, mit deutlichem Abstand über jedem Panel.
• Wenigste Tinte. Keine Schatten, Verläufe, 3-D um seiner selbst willen oder dekorative Symbole. Füllungen sind helle Tönungen der Strichfarbe (cell=colorX macht das).
• Standard-Notation. Fettgedruckte Kleinbuchstaben für Vektoren, fettgedruckte Großbuchstaben für Matrizen, normale Skalare; verwende die Makros (\vx, \mW, \vytld, \softmax). Zeilen-vs-Spalten-Konventionen müssen mit der gedruckten Gleichung übereinstimmen (Attention verwendet zeilenweise Token-Q, K, V wie in Vaswani et al.).

5. Kompiliere und sieh es dir an

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

Es kopiert dlviz.sty neben die Abbildung, sodass der Ordner überall neu kompiliert werden kann, dann schreibt es concept.pdf und concept.png. Wenn die Kompilierung fehlschlägt, gibt es den ersten Fehler aus; überprüfe references/tikz-gotchas.md. Wenn ein Paket fehlt, gibt es den tlmgr-Befehl aus; sag dem Benutzer Bescheid, anstatt Installationen auf seinem Rechner ohne Nachfrage auszuführen.

Öffne dann das PNG und kritisiere es wie ein Reviewer. Kompilieren ist nicht getan; jede Abbildung in assets/examples brauchte mindestens eine Runde Korrekturen nach dem Ansehen. Überprüfe:

1. Überschneidet oder berührt sich etwas: Text auf Linien, Pfeile durch Beschriftungen, Text, der eine Knotengrenze berührt, Beschriftungen, die an einer Achsen- oder Panelkante abgeschnitten sind, Notizen eines Panels, die die Beschriftung des nächsten Panels bedrängen? Zoome in dichte Bereiche (schneide das PNG mit magick in.png -crop WxH+X+Y out.png zu), anstatt einer Miniaturansicht zu vertrauen.
2. Kannst du die eine Idee innerhalb von drei Sekunden sehen? Worauf fällt das Auge zuerst? Ist das das Richtige?
3. Erfüllt jede Farbe eine Aufgabe, und ist jede Rolle überall gleich gefärbt?
4. Sind jede Zahl, Form und Formel korrekt (siehe Fakten-Tabelle in references/archetypes.md)?
5. Ist der Abstand gleichmäßig und die Ausrichtung bewusst?

Korrigiere und kompiliere neu, bis alle Antworten ja sind. Zwei oder drei Iterationen sind normal.

6. Liefere

Gib dem Benutzer:

1. Das PNG, inline gezeigt, wenn du Dateien anzeigen oder senden kannst, plus Pfade zur .tex, .pdf und dlviz.sty.
2. Eine Leseanleitung: 4-8 Sätze, die das Auge in der Reihenfolge, in der gelesen werden sollte, durch die Abbildung führen ("Beginne an der hervorgehobenen Zeile von Q..."), jedes visuelle Element mit der Mathematik verbinden und mit der Erkenntnis enden. Schreibe für einen fortgeschrittenen Studenten: Erkläre nicht noch einmal, was ein Neuron ist, aber erkläre, warum der Mechanismus funktioniert.
3. Einen Satz zur Anpassung: Wechsel zu [light], Größen ändern oder eine natürliche Folgeabbildung (z.B. "Multi-Head-Version als nächstes?").

Halte den % Caption:-Kommentar am Anfang der .tex mit der Abbildung synchron; es ist die Bildunterschrift, die der Benutzer darunter in sein Dokument einfügt.

Verwandte Skills

Diese Skill erstellt statische Abbildungen: eine PDF/PNG pro Idee, für Folien, Paper und Druck. Zwei verwandte Skills teilen dasselbe dlviz.sty und dieselbe visuelle Sprache:

• tikz-live: die gleiche Art von Abbildung interaktiv (ziehen, schieben, schweben, abspielen) als eigenständige Webseite. Verwende es, wenn der Leser etwas ändern und den Mechanismus reagieren sehen soll, oder wenn der Benutzer nach einer interaktiven, erforschbaren oder im Browser animierten Abbildung fragt.
• tikz-explorer-book: ein ganzes Web-Buch eines Kurses oder Fachgebiets mit einer Konzeptkarte und Kapiteln von Abbildungen; es verwendet diese Skill für statische Abbildungen und tikz-live für die interaktiven.

Wenn die Anfrage ungewöhnlich ist

• Das eigene LaTeX-Dokument oder die Präambel des Benutzers. Passe ihre Notation und Farben an, wenn sie welche haben; du kannst immer noch die Stile aus dlviz.sty mit \input einbinden oder nur die Teile kopieren, die sie brauchen. Überschreibe nicht ihre Seitenfarbe.
• Folien (Beamer). Erstelle die eigenständige Abbildung und zeige die Verwendung von \includegraphics; für schrittweise Aufbauten setze \only<n> / \visible<n> auf Ebenen oder erstelle mehrere eigenständige Dateien (schritt-1, schritt-2...).
• Animation oder ein Prozess über die Zeit. Für Druck und Folien bevorzuge kleine Multiplots (t = 0, 1, 2, ..., T) in einer Abbildung; eine Abfolge von Panels zeigt den Trend, den eine Animation verbirgt. Wenn es auf dem Bildschirm gelesen wird und der Leser Schritt für Schritt oder durchkratzen soll, verwende stattdessen tikz-live.
• PowerPoint / Keynote. Füge das PNG (gerendert mit 200 dpi, scharf in voller Folienbreite) oder das PDF ein; für eine weiße Folienvorlage verwende [light].
• Eine Paper-Abbildung. Verwende [light]], lasse die Gleichung in der Abbildung weg, wenn das Paper sie angibt, und behalte die Schriftarten des Papers bei (keine Schriftpakete werden von dlviz` geladen, also wird die Dokumentschriftart verwendet).
• 3-D-Oberflächen. Verwende pgfplots \addplot3[surf] mit view={...} und einer gedämpften Farbkarte (colormap name=dlheat) und frage, ob ein Konturplot es besser erklären würde. Das tut er normalerweise.