szcharlesji/tikz-dl-visualizer

Visualizador TikZ para deep learning

Estás dibujando para un estudiante que ya conoce los fundamentos (MLPs, backprop, CNN, qué es un transformer) y quiere el por qué. Una buena figura aquí no es un diagrama decorado de cajas; hace que una idea sea obvia de un vistazo y luego recompensa una segunda mirada. El estilo sigue el libro de Deep Learning de NYU de Alfredo Canziani: página gris oscura, pasteles ColorBrewer Set3, y colores que siempre significan lo mismo.

Todo lo que necesitas está incluido:

• assets/dlviz.sty: paleta (oscuro y claro), macros de notación, estilos de nodos, apariencias de pgfplots, ayudantes. Siempre construye sobre esto en lugar de reestilizar desde cero; eso mantiene cada figura en un solo lenguaje visual.
• assets/examples/*.tex (con una vista previa .png de cada uno): seis figuras compiladas y revisadas, una por arquetipo. Mira el PNG para ver la calidad objetivo. Comienza desde el más cercano.
• scripts/render.py: compila a PDF y PNG e imprime solo el primer error.
• references/visual-language.md: roles de color, vocabulario de elementos, notación, reglas de tipografía y maquetación. Léelo antes de tu primera figura en una sesión.
• references/archetypes.md: qué imagen encaja con qué concepto, más una tabla de hechos de DL que las figuras suelen representar incorrectamente. Lee la fila para tu concepto.
• references/tikz-gotchas.md: errores de compilación y trampas de diseño que hemos encontrado, con soluciones. Léelo cuando algo no compile o se vea raro.

Flujo de trabajo

1. Encuentra la idea única

Antes de tocar TikZ, escribe en una oración la visión que la figura debe transmitir, formulada como algo que el estudiante verá, por ejemplo:

• "Cada fila de salida de la atención es un promedio ponderado de las filas de valor, y los pesos son una fila de una matriz de puntuaciones softmaxeada."
• "Momentum cancela la componente del gradiente que oscila y acumula la consistente."
• "Un bloque residual solo tiene que aprender la corrección F(x), porque x se pasa sin modificar."

Si no puedes escribir esa oración, todavía no sabes qué dibujar. Pregúntate qué concepto erróneo es más probable que tenga el estudiante y apunta la figura hacia él. Si el concepto es amplio (ej. "transformers"), elige la porción más iluminadora y dilo; ofrece una figura de seguimiento para el resto en lugar de meter todo en una.

2. Elige el arquetipo

Abre references/archetypes.md y elige la forma visual que haga visible la oración. Los principales:

Arquetipo	Muestra	Archivo de ejemplo
pipeline / grafo de cómputo	cómo fluyen los datos, qué alimenta a qué	autoencoder.tex
diseño de matriz / mapa de calor	formas de tensores y productos, pesos	attention.tex
rejilla + campo receptivo	operaciones locales, deslizantes, compartidas	convolution.tex
geometría del espacio de parámetros	rutas de optimización, contornos de pérdida	momentum.tex
múltiples gráficos pequeños	comparar funciones o configuraciones	activations.tex
antes/después deformación del espacio	lo que una capa hace al espacio de entrada	linear-map.tex

Combinar dos arquetipos está bien (un pipeline con un pequeño recuadro de mapa de calor), pero uno debe dominar.

3. Hazlo concreto

La abstracción es enemiga de la intuición. Usa tamaños pequeños y específicos (4 tokens, d_k = 3, una entrada 5x5, parámetros 2-D) y di qué representan. Los números reales vencen a los marcadores de posición: pesos que suman 1, una convolución cuya salida puedes verificar, una trayectoria que es realmente lo que hace el optimizador.

Calcula los números en Python, nunca a mano o mentalmente. Ejecuta un script corto (numpy mediante uv run --with numpy python - o Python puro), luego pega las coordenadas o valores en el .tex. Deja un comentario diciendo cómo se produjeron. Los números "ilustrativos" hechos a mano son de donde vienen las figuras incorrectas: una fila softmax que suma 1.1, una salida de convolución que no coincide con su entrada.

4. Escribe la figura

Crea <concepto>.tex en la carpeta de salida (la carpeta del usuario si nombró una, si no, el directorio de trabajo actual) comenzando desde:

% Título: <2-3 oraciones: qué mirar y qué muestra>
\documentclass[tikz,border=8pt]{standalone}
\usepackage[dark]{dlviz}   % [light] para documentos / diapositivas blancos
\begin{document}
\begin{tikzpicture}
  ...
\end{tikzpicture}
\end{document}

Elige el tema según dónde vivirá la figura: oscuro (el aspecto del libro) para diapositivas, pantallas y cualquier cosa que el usuario diga que debe coincidir con el libro; claro para destinos tipo papel (artículos, tesis, apuntes de clase en PDF, tareas, impresión) o cuando se solicite. Si nada indica una dirección, usa oscuro y menciona [light]. Los roles de color se mantienen en ambos temas, así que cambiar es una palabra.

Principios más importantes (detalles en references/visual-language.md):

• Color = rol, consistentemente. Entrada x rosa, oculta h verde, predicción ỹ violeta, objetivo y azul, latente z naranja, costo/pérdida/energía rojo, codificador lavanda, decodificador aguamarina, predictor amarillo, parámetros dorado. Usa el mismo color para un símbolo en el dibujo, en las etiquetas y en la ecuación (\pink{\vx}). Esto permite que el ojo vincule imagen y matemáticas sin leer. Máximo ~5 tonos por figura; todo lo estructural es blanco/gris.
• El contraste necesita dos tonos. Cuando la figura compara dos condiciones (simple vs residual, SGD vs momentum, BatchNorm vs LayerNorm), dale a cada una su propio tono y usa esos tonos para las curvas, etiquetas y resaltados de esa condición en toda la figura. No dibujes ambas en rojo solo porque ambas son gradientes; el rojo entonces marca lo compartido (la pérdida, la dirección hacia atrás), y la comparación sigue siendo legible de un vistazo.
• Haz la magnitud visible. Si una cantidad crece o decrece (norma del gradiente, peso de atención, varianza), codifícala en el dibujo mismo, no solo en un número impreso: grosor de línea que se reduce paso a paso, tinte de relleno, longitud de flecha, tamaño de punto. La correspondencia también merece tinta: líneas finas desde cada muestra hasta donde aterriza muestran una transformación mejor que dos nubes separadas.
• Muestra las matemáticas, con código de colores. Pon la ecuación definitoria en la figura, generalmente debajo, con cada término coloreado como su contraparte visual.
• Formas en todo. Etiqueta los tensores con su forma en el estilo dim atenuado (\(\R^{n\times d_k}\)). El mantenimiento de formas es la mitad de la comprensión de una operación de DL.
• Sigue un ejemplo a lo largo. Resalta una fila, un parche o un paso (estilo hl, contorno rojo) en todas partes donde aparezca, para que el estudiante pueda rastrear un solo cómputo de principio a fin.
• Anota con moderación y en su lugar. Dos o tres notas cortas en cursiva (annot) con líneas guía finas, junto a lo que explican. Etiquetas directas en lugar de una leyenda. Sin título general (el título lo hace), pero las figuras de múltiples paneles obtienen etiquetas cortas como "(a) plano: (\vx_l = F_l(\vx_{l-1}))" en estilo annot, con espacio claro sobre cada panel.
• Mínima tinta. Sin sombras, degradados, 3-D por sí mismo ni iconos decorativos. Los rellenos son tintes claros del color del trazo (cell=colorX hace esto).
• Notación estándar. Vectores en negrita minúscula, matrices en negrita mayúscula, escalares normales; usa las macros (\vx, \mW, \vytld, \softmax). Las convenciones de fila vs columna deben coincidir con la ecuación que imprimes (la atención usa Q, K, V por fila por token como en Vaswani et al.).

5. Compila y míralo

python <directorio-del-skill>/scripts/render.py ruta/hacia/concepto.tex

Esto copia dlviz.sty junto a la figura para que la carpeta pueda recompilarse en cualquier lugar, luego escribe concepto.pdf y concepto.png. Si la compilación falla, imprime el primer error; consulta references/tikz-gotchas.md. Si falta un paquete, imprime el comando tlmgr; informa al usuario en lugar de ejecutar instalaciones en su máquina sin preguntar.

Luego abre el PNG y critícalo como un revisor. Compilar no es terminar; cada figura en assets/examples necesitó al menos una ronda de correcciones después de mirarla. Verifica:

1. ¿Algo se superpone o toca: texto sobre líneas, flechas a través de etiquetas, texto tocando un borde de nodo, etiquetas recortadas en un borde de eje o panel, notas de un panel apiñando la etiqueta del siguiente? Acerca en áreas densas (recorta el PNG con magick in.png -crop WxH+X+Y out.png) en lugar de confiar en una miniatura.
2. ¿Puedes ver la idea única en tres segundos? ¿Dónde aterriza el ojo primero? ¿Es eso lo correcto?
3. ¿Cada color está haciendo un trabajo, y cada rol está coloreado igual en todas partes?
4. ¿Cada número, forma y fórmula es correcta (consulta la tabla de hechos en references/archetypes.md)?
5. ¿El espaciado es uniforme y la alineación deliberada?

Corrige y recompila hasta que las respuestas sean todas sí. Dos o tres iteraciones son normales.

6. Entrega

Dale al usuario:

1. El PNG, mostrado en línea si puedes mostrar o enviar archivos, más las rutas al .tex, .pdf y dlviz.sty.
2. Una guía de lectura: 4-8 oraciones que guían el ojo a través de la figura en el orden en que debe leerse ("Empieza en la fila resaltada de Q..."), conectan cada elemento visual con las matemáticas y terminan con la conclusión. Escribe para un estudiante intermedio: no reexpliques qué es una neurona, pero sí explica por qué funciona el mecanismo.
3. Una línea sobre cómo adaptarla: cambiar a [light], cambiar tamaños, o una figura de seguimiento natural (ej. "¿versión multi-cabeza después?").

Mantén el comentario % Título: al inicio del .tex sincronizado con la figura; es el título que el usuario pegará debajo en su documento.

Skills hermanos

Este skill produce figuras estáticas: un PDF/PNG por idea, para diapositivas, artículos e impresión. Dos hermanos comparten el mismo dlviz.sty y lenguaje visual:

• tikz-live: el mismo tipo de figura hecha interactiva (arrastrar, deslizar, pasar el ratón, reproducir) como una página web autónoma. Úsalo cuando el lector deba cambiar algo y ver cómo responde el mecanismo, o cuando el usuario pida una figura interactiva, explorable o animada en el navegador.
• tikz-explorer-book: un libro web completo de un curso o campo, con un mapa conceptual y capítulos de figuras; usa este skill para figuras estáticas y tikz-live para las interactivas.

Cuando la solicitud es inusual

• El propio documento o preámbulo LaTeX del usuario. Coincide con su notación y colores si los tiene; aún puedes \input los estilos de dlviz.sty o copiar solo las partes que necesiten. No sobrescribas su color de página.
• Diapositivas (Beamer). Produce la figura independiente y muestra el uso de \includegraphics; para construcciones paso a paso, pon \only<n> / \visible<n> en capas, o haz varios archivos independientes (paso-1, paso-2...).
• Animación o un proceso a lo largo del tiempo. Para impresión y diapositivas, prefiere múltiples imágenes pequeñas (t = 0, 1, 2, ..., T) en una figura; una secuencia de paneles muestra la tendencia que una animación oculta. Si se leerá en pantalla y el lector debe avanzar o desplazarse, usa tikz-live en su lugar.
• PowerPoint / Keynote. Inserta el PNG (renderizado a 200 ppp, nítido a ancho completo de diapositiva) o el PDF; para una plantilla de diapositiva blanca usa [light].
• Figura de artículo. Usa [light], elimina la ecuación dentro de la figura si el artículo la expresa, y mantén las fuentes del artículo (dlviz no carga paquetes de fuentes, por lo que se usa la fuente del documento).
• Superficies 3-D. Usa \addplot3[surf] de pgfplots con view={...} y un mapa de colores atenuado (colormap name=dlheat), y pregunta si un gráfico de contorno lo explicaría mejor. Generalmente lo hace.