szcharlesji/tikz-dl-visualizer

Visualiseur TikZ pour l'apprentissage profond

Vous dessinez pour un étudiant qui connaît déjà les bases (MLP, rétropropagation, CNN, ce qu'est un transformer) et veut comprendre le pourquoi. Une bonne figure ici n'est pas un diagramme décoré de boîtes ; elle rend une idée évidente au premier coup d'œil et récompense un second regard. Le style suit le livre d'Alfredo Canziani sur l'apprentissage profond à NYU : fond gris foncé, pastels ColorBrewer Set3, et une couleur qui signifie toujours la même chose.

Tout ce dont vous avez besoin est inclus :

• assets/dlviz.sty : palette (sombre et claire), macros de notation, styles de nœuds, aspects pgfplots, aides. Construisez toujours dessus plutôt que de restyler à partir de zéro ; c'est ce qui maintient chaque figure dans un langage visuel unique.
• assets/examples/*.tex (avec un aperçu .png de chacun) : six figures compilées et révisées, une par archétype. Regardez le PNG pour voir la qualité cible. Partez de la plus proche.
• scripts/render.py : compile en PDF et PNG et n'affiche que la première erreur.
• references/visual-language.md : rôles des couleurs, vocabulaire des éléments, notation, typographie et règles de mise en page. Lisez-le avant votre première figure dans une session.
• references/archetypes.md : quelle image correspond à quel concept, plus un tableau des faits DL que les figures représentent souvent mal. Lisez la ligne correspondant à votre concept.
• references/tikz-gotchas.md : erreurs de compilation et pièges de mise en page que nous avons rencontrés, avec correctifs. Lisez-le quand quelque chose ne compile pas ou semble étrange.

Workflow

1. Trouver l'idée unique

Avant de toucher à TikZ, écrivez en une phrase l'intuition que la figure doit transmettre, formulée comme quelque chose que l'étudiant verra, par exemple :

• "Chaque ligne de sortie de l'attention est une moyenne pondérée des lignes de valeur, et les poids sont une ligne d'une matrice de scores softmaxée."
• "L'impulsion annule la composante oscillante du gradient et accumule la composante cohérente."
• "Un bloc résiduel n'a qu'à apprendre la correction F(x), car x est transmis inchangé."

Si vous ne pouvez pas écrire cette phrase, vous ne savez pas encore quoi dessiner. Demandez-vous quelle est l'idée fausse la plus probable chez l'étudiant et ciblez la figure sur celle-ci. Si le concept est vaste (ex. "transformers"), choisissez la tranche la plus éclairante et dites-le ; proposez une figure complémentaire pour le reste plutôt que de tout entasser dans une seule.

2. Choisir l'archétype

Ouvrez references/archetypes.md et choisissez la forme visuelle qui rend la phrase visible. Les principales :

Archétype	Montre	Fichier exemple
pipeline / graphe de calcul	comment les données circulent, quoi alimente quoi	autoencoder.tex
matrice / heatmap	formes de tenseurs et produits, poids	attention.tex
grille + champ réceptif	opérations locales, glissantes, partagées	convolution.tex
géométrie de l'espace des paramètres	chemins d'optimisation, contours de perte	momentum.tex
petits multiples de tracés	comparaison de fonctions ou de réglages	activations.tex
avant/après déformation d'espace	ce qu'une couche fait à l'espace d'entrée	linear-map.tex

Combiner deux archétypes est acceptable (un pipeline avec un petit encart heatmap), mais un doit dominer.

3. Rendre concret

L'abstraction est l'ennemi de l'intuition. Utilisez des tailles petites et spécifiques (4 jetons, d_k = 3, une entrée 5x5, paramètres 2-D) et dites ce qu'elles représentent. Les chiffres réels battent les espaces réservés : des poids qui totalisent 1, une convolution dont vous pouvez vérifier la sortie, une trajectoire qui est réellement ce que fait l'optimiseur.

Calculez les nombres en Python, jamais à la main ou de tête. Exécutez un court script (numpy via uv run --with numpy python - ou Python simple), puis collez les coordonnées ou valeurs dans le .tex. Laissez un commentaire indiquant comment ils ont été produits. Les nombres "illustratifs" faits à la main sont là d'où viennent les figures erronées : une ligne softmax qui totalise 1,1, une sortie de convolution qui ne correspond pas à son entrée.

4. Écrire la figure

Créez <concept>.tex dans le dossier de sortie (le dossier de l'utilisateur s'il en a nommé un, sinon le répertoire de travail actuel) en commençant par :

% Légende : <2-3 phrases : quoi regarder et ce que cela montre>
\documentclass[tikz,border=8pt]{standalone}
\usepackage[dark]{dlviz}   % [light] pour papiers blancs / diapositives
\begin{document}
\begin{tikzpicture}
  ...
\end{tikzpicture}
\end{document}

Choisissez le thème en fonction de l'endroit où vivra la figure : sombre (l'aspect du livre) pour les diapositives, les écrans et tout ce que l'utilisateur dit devoir correspondre au livre ; clair pour les destinations de type papier (articles, thèses, notes de cours PDF, devoirs, impression) ou sur demande. Si rien n'indique l'un ou l'autre, utilisez sombre et mentionnez [light]. Les rôles de couleur tiennent dans les deux thèmes, donc le passage est d'un mot.

Principes les plus importants (détails dans references/visual-language.md) :

• Couleur = rôle, de manière cohérente. Entrée x rose, cachée h verte, prédiction ỹ violette, cible y bleue, latent z orange, coût/perte/énergie rouge, encodeur lavande, décodeur aqua, prédicteur jaune, paramètres or. Utilisez la même couleur pour un symbole dans le dessin, dans les étiquettes et dans l'équation (\pink{\vx}). Cela permet à l'œil de relier l'image et les maths sans lire. Au maximum ~5 teintes par figure ; tout ce qui est structurel est blanc/gris.
• Le contraste nécessite deux teintes. Lorsque la figure compare deux conditions (simple vs résiduel, SGD vs momentum, BatchNorm vs LayerNorm), donnez à chacune sa propre teinte et utilisez ces teintes pour les courbes, étiquettes et surlignages de cette condition dans toute la figure. Ne dessinez pas les deux en rouge simplement parce que les deux sont des gradients ; le rouge marque alors la chose partagée (la perte, la direction arrière), et la comparaison reste lisible d'un coup d'œil.
• Rendez la magnitude visible. Si une quantité croît ou décroît (norme du gradient, poids d'attention, variance), encodez-la dans le dessin lui-même, pas seulement dans un nombre imprimé : épaisseur de ligne qui s'amincit progressivement, teinte de remplissage, longueur de flèche, taille de point. La correspondance mérite aussi de l'encre : des lignes fines de chaque échantillon à son emplacement d'arrivée montrent une transformation mieux que deux nuages séparés.
• Montrez les maths, en couleurs. Mettez l'équation définissant dans la figure, généralement en dessous, avec chaque terme coloré comme son homologue visuel.
• Formes sur tout. Étiquetez les tenseurs avec leur forme dans le style dim atténué (\(\R^{n\times d_k}\)). La gestion des formes est la moitié de la compréhension d'une opération DL.
• Suivez un exemple. Surlignez une ligne, un patch ou une étape (style hl, contour rouge) partout où il apparaît, afin que l'étudiant puisse tracer un seul calcul de bout en bout.
• Annotez avec parcimonie et sur place. Deux ou trois courtes notes en italique (annot) avec de fines lignes de guidage, à côté de ce qu'elles expliquent. Étiquettes directes plutôt qu'une légende en boîte. Pas de titre général (la légende fait cela), mais les figures multi-panneaux reçoivent de courtes étiquettes de panneau comme "(a) simple : (\vx_l = F_l(\vx_{l-1}))" dans le style annot, avec un espace clair au-dessus de chaque panneau.
• Moins d'encre. Pas d'ombres, dégradés, 3-D pour lui-même ou d'icônes décoratives. Les remplissages sont des teintes claires de la couleur de trait (cell=colorX fait cela).
• Notation standard. Vecteurs minuscules en gras, matrices majuscules en gras, scalaires simples ; utilisez les macros (\vx, \mW, \vytld, \softmax). Les conventions ligne-vs-colonne doivent correspondre à l'équation que vous imprimez (l'attention utilise Q, K, V par jeton comme dans Vaswani et al.).

5. Compiler et regarder

python <skill-dir>/scripts/render.py chemin/vers/concept.tex

Cela copie dlviz.sty à côté de la figure pour que le dossier puisse être recompilé n'importe où, puis écrit concept.pdf et concept.png. Si la compilation échoue, cela affiche la première erreur ; vérifiez references/tikz-gotchas.md. Si un package manque, cela affiche la commande tlmgr ; informez l'utilisateur plutôt que d'exécuter des installations sur sa machine sans demander.

Ensuite, ouvrez le PNG et critiquez-le comme un relecteur. Compiler n'est pas terminé ; chaque figure dans assets/examples a eu besoin d'au moins un cycle de correctifs après inspection. Vérifiez :

1. Quelque chose se chevauche-t-il ou se touche-t-il : texte sur lignes, flèches à travers les étiquettes, texte touchant une bordure de nœud, étiquettes coupées à un bord d'axe ou de panneau, les notes d'un panneau empiétant sur l'étiquette du panneau suivant ? Zoomez sur les zones denses (recadrez le PNG avec magick in.png -crop WxH+X+Y out.png) plutôt que de vous fier à une vignette.
2. Pouvez-vous voir l'idée unique en trois secondes ? Sur quoi l'œil se pose-t-il en premier ? Est-ce la bonne chose ?
3. Chaque couleur fait-elle un travail, et chaque rôle est-il coloré de la même manière partout ?
4. Chaque nombre, forme et formule est-il correct (voir le tableau de faits dans references/archetypes.md) ?
5. L'espacement est-il uniforme et l'alignement délibéré ?

Corrigez et recompilez jusqu'à ce que les réponses soient toutes oui. Deux ou trois itérations est normal.

6. Livrer

Donnez à l'utilisateur :

1. Le PNG, affiché en ligne si vous pouvez afficher ou envoyer des fichiers, plus les chemins vers les fichiers .tex, .pdf et dlviz.sty.
2. Un guide de lecture : 4 à 8 phrases qui guident l'œil à travers la figure dans l'ordre de lecture ("Commencez par la ligne surlignée de Q..."), relient chaque élément visuel aux maths, et se terminent par le message à retenir. Écrivez pour un étudiant intermédiaire : ne réexpliquez pas ce qu'est un neurone, mais expliquez pourquoi le mécanisme fonctionne.
3. Une ligne sur la façon de l'adapter : passer à [light], changer les tailles, ou une figure complémentaire naturelle (ex. "version multi-tête ensuite ?").

Gardez le commentaire % Légende : en haut du .tex synchronisé avec la figure ; c'est la légende que l'utilisateur collera en dessous dans son document.

Compétences sœurs

Cette compétence produit des figures statiques : un PDF/PNG par idée, pour diapositives, articles et impression. Deux compétences sœurs partagent le même dlviz.sty et langage visuel :

• tikz-live : le même type de figure rendue interactive (glisser, faire glisser, survoler, jouer) sous forme de page web autonome. Utilisez-la lorsque le lecteur doit changer quelque chose et regarder le mécanisme répondre, ou lorsque l'utilisateur demande une figure interactive, explorable ou animée dans le navigateur.
• tikz-explorer-book : un livre web complet d'un cours ou d'un domaine, avec une carte conceptuelle et des chapitres de figures ; il utilise cette compétence pour les figures statiques et tikz-live pour les figures en direct.

Lorsque la demande est inhabituelle

• Le propre document LaTeX ou préambule de l'utilisateur. Faites correspondre leur notation et leurs couleurs s'ils en ont ; vous pouvez toujours \input les styles depuis dlviz.sty ou copier uniquement les parties dont ils ont besoin. Ne remplacez pas leur couleur de page.
• Diapositives (Beamer). Produisez la figure autonome et montrez l'utilisation de \includegraphics ; pour les constructions pas à pas, mettez \only<n> / \visible<n> sur les calques, ou créez plusieurs fichiers autonomes (étape-1, étape-2...).
• Animation ou processus dans le temps. Pour l'impression et les diapositives, préférez les petits multiples (t = 0, 1, 2, ..., T) dans une seule figure ; une séquence de panneaux montre la tendance qu'une animation cache. Si la figure sera lue à l'écran et que le lecteur doit passer à travers ou la parcourir, utilisez tikz-live à la place.
• PowerPoint / Keynote. Insérez le PNG (rendu à 200 dpi, net à pleine largeur de diapositive) ou le PDF ; pour un modèle de diapositive blanc, utilisez [light].
• Figure d'article. Utilisez [light], supprimez l'équation dans la figure si l'article l'énonce, et gardez les polices de l'article (aucun package de polices n'est chargé par dlviz, donc la police du document est utilisée).
• Surfaces 3-D. Utilisez pgfplots \addplot3[surf] avec view={...} et une colormap atténuée (colormap name=dlheat), et demandez si un tracé de contour expliquerait mieux. C'est généralement le cas.