Diagrammes commutatifs (tikz-cd / amscd)

Un diagramme commutatif place des objets comme des points et les applications entre eux comme des flèches, afin de montrer d’un coup d’œil que « tous les chemins de compositions donnent le même résultat ». LaTeX propose deux outils principaux : le puissant tikz-cd, bâti sur TikZ, et le paquet AMS plus simple amscd. Cette page compose un carré commutatif, le diagramme de base, avec chacun d’eux, explique comment donner direction, étiquettes et style aux flèches, puis compare les cas d’usage.

Ce qu’est un diagramme commutatif

Les diagrammes commutatifs sont employés en algèbre, théorie des catégories et topologie pour faire voir des relations immédiatement. Le plus petit exemple est le carré commutatif : objets A, B, C, D aux quatre coins, avec une application f sur le bord supérieur de A vers B, g sur le bord inférieur de C vers D, une application vers le bas à gauche de A vers C, et une autre à droite de B vers D. Dire que « le carré commute » signifie simplement que les deux chemins de A vers D, par le haut puis la droite ou par la gauche puis le bas, donnent la même application.

Un diagramme est lui-même un morceau de mathématiques ; on le place donc normalement dans un environnement mathématique hors texte, comme \[ … \] ou equation. De nombreux paquets ont existé pour cela, notamment xy/xypic, diagrams et d’autres, mais le standard de fait actuel est tikz-cd, qui trace facilement courbes, flèches diagonales et diagrammes complexes à plusieurs lignes. Quand un simple diagramme rectangulaire suffit, le paquet AMS amscd est l’option légère. Nous les examinons successivement.

tikz-cd : le choix moderne

tikz-cd adapte le paquet de dessin généraliste TikZ aux diagrammes commutatifs. Il a été écrit par Florêncio Neves et est désormais maintenu par Augusto Stoffel ; la version CTAN actuelle est la 1.0 (mai 2021). Chargez-le dans le préambule avec \usepackage{tikz-cd} ou, après avoir chargé TikZ, avec \usetikzlibrary{cd}, et vous disposez de l’environnement tikzcd. Son contenu s’écrit comme une matrice, à la manière de tabular en LaTeX : les cellules sont séparées par & et les lignes par \\. Chaque cellule est un nœud où placer un « objet », le tout étant automatiquement composé en mode mathématique.

Les flèches entre objets se tracent avec la commande \arrow ; l’alias court \ar fait exactement la même chose. Dans la cellule d’origine de la flèche, on écrit \arrow[…] et l’on indique la cible et la décoration entre crochets. La cible se donne par touches de direction : r pour droite, l pour gauche, u pour haut, d pour bas. On les combine en chaîne ; par exemple [rd] pointe vers la cellule située une colonne à droite et une ligne plus bas, en diagonale.

Pour mettre une étiquette, le nom d’une application, sur une flèche, écrivez une chaîne entre guillemets parmi les options. \arrow[r, "f"] signifie « une flèche vers la cellule de droite, étiquetée f ». Par défaut, l’étiquette se place à gauche de la flèche par rapport à sa direction ; ajouter une apostrophe ' juste après l’étiquette la déplace de l’autre côté, comme dans "g"'. Une même flèche peut porter plusieurs étiquettes, et leur position se précise avec des options comme "f" near start. Voici un court exemple d’usage typique.

\[
\begin{tikzcd}
  A \arrow[r, "\phi"] \arrow[rd] & B \\
  & C
\end{tikzcd}
\]

On obtient A en haut à gauche, B en haut à droite et C en bas à droite : une flèche horizontale va de A vers B à droite avec l’étiquette φ, tandis qu’une flèche diagonale descend de A vers C en bas à droite. Remarquez que \arrow[r, "\phi"] et \arrow[rd] sont écrites l’une après l’autre dans la même cellule A ; une cellule peut émettre autant de flèches que nécessaire.

Avec cela, composons le carré commutatif décrit au début. Plaçons les quatre coins A, B, C, D comme une matrice 2×2, puis traçons quatre flèches : f de A vers la droite, le côté gauche de A vers le bas, le côté droit de B vers le bas, et g de C vers la droite.

\[
\begin{tikzcd}
  A \arrow[r, "f"] \arrow[d, "\alpha"] & B \arrow[d, "\beta"] \\
  C \arrow[r, "g"]                      & D
\end{tikzcd}
\]

On obtient ainsi un carré avec A, B, C, D aux quatre coins : f vers la droite en haut, g vers la droite en bas, α vers le bas à gauche et β vers le bas à droite. Chaque étiquette est placée du côté par défaut, à gauche de la direction de la flèche. Pour envoyer le β de droite de l’autre côté, vers l’extérieur, écrivez par exemple \arrow[d, "\beta"']. Comme l’intérieur de tikzcd est en mode mathématique, utilisez \text{…} d’amsmath dans l’option d’étiquette si vous voulez y mettre des mots ordinaires.

La grande force de tikz-cd est de permettre de modifier finement l’apparence des flèches. Style de ligne, pointe de flèche et courbure se changent simplement en ajoutant des clés de style aux options de \arrow. Le tableau ci-dessous rassemble les plus courantes. On peut en donner plusieurs à la fois, comme dans \arrow[r, tail, two heads, dashed], et les combiner librement.

Il est courant de placer un symbole d’isomorphisme comme \sim ou \simeq sur une flèche comme étiquette. Par exemple, \arrow[r, dashed, "\simeq"] place le signe ≃ au-dessus d’une flèche tiretée. Pour tracer deux arcs distincts entre les mêmes objets, utilisez bend left et bend right. Comme tikz-cd accepte aussi directement les clés TikZ (color=…, dotted, in=…/out=…, etc.), son domaine d’expression est en pratique celui de tout TikZ.

Une réserve : les diagrammes tikzcd ne s’affichent pas correctement dans les visualiseurs DVI. Compilez avec pdflatex, lualatex ou xelatex, qui produisent directement du PDF, ou passez par une conversion DVI vers PDF/PS. Notez aussi que \arrow possède une ancienne forme antérieure à la syntaxe avec guillemets, \arrow[…]{direction}labels, par exemple \arrow{r}{f}. Elle reste disponible pour compatibilité, mais la syntaxe avec guillemets est plus lisible et recommandée pour les nouveaux documents.

amscd : l’environnement CD simple d’AMS

amscd transpose en LaTeX la fonctionnalité de diagrammes commutatifs d’AMS-TeX ; on le charge dans le préambule avec \usepackage{amscd}. Il fournit un seul environnement CD. Comme avec tikz-cd, le contenu s’écrit comme une matrice avec & et \\, mais amscd ne dépend d’aucun paquet externe, pas de TikZ, et fonctionne avec la seule composition TeX : il est donc léger. Sa conception est toutefois volontairement sobre : il ne trace que des flèches horizontales et verticales.

Chaque flèche s’écrit comme un jeton spécial commençant par @. Les flèches horizontales sont @>>> vers la droite et @<<< vers la gauche ; les flèches verticales sont @VVV vers le bas, V pour vertical, et @AAA vers le haut, le A étant lu comme une flèche montante. L’égalité, ligne double, est @= horizontalement et @| ou @\vert verticalement. Pour un point de grille sans flèche, placez @., un point. Les flèches horizontales vont entre les objets, à la position & de la même ligne ; les verticales se placent sur la ligne directement sous leur objet.

Les étiquettes s’écrivent entre les caractères qui forment la flèche. Le @>>> horizontal possède trois séparateurs > et donc deux emplacements : le texte du premier emplacement, juste après @>, va au-dessus de la flèche ; celui du second va au-dessous. Ainsi @>f>> met f au-dessus, @>>g> met g au-dessous, et @>f>g> met f au-dessus et g au-dessous. Le @VVV vertical suit le même principe : @VfVV place f à gauche d’une flèche descendante, @VVfV à droite ; @AAA obéit à la même règle.

Voici l’exemple de carré commutatif du manuel AMS de amscd. Il suppose que \End a été défini comme nom d’opérateur, comme avec \operatorname.

\[
\begin{CD}
  S^{{\mathcal{W}}_\Lambda}\otimes T  @>j>>  T \\
  @VVV                                @VV{\End P}V \\
  (S\otimes T)/I                     @=  (Z\otimes T)/J
\end{CD}
\]

Dans ce diagramme, la ligne du haut trace une flèche horizontale de l’objet de gauche vers T à droite, avec l’étiquette j au-dessus. La ligne du milieu, @VVV et @VV{\End P}V, crée les flèches verticales : une flèche descendante sans étiquette dans la colonne de gauche, et une flèche descendante avec l’étiquette End P à droite dans la colonne de droite. La ligne du bas relie les deux objets par @=, une égalité à double trait. Les accolades de {\End P} groupent une étiquette de plusieurs jetons en une seule unité.

Le carré commutatif f/g/α/β du début de la page s’écrit ainsi avec amscd. Les étiquettes des flèches verticales de gauche et de droite sont placées dans le premier emplacement, donc à gauche, comme expliqué plus haut.

\[
\begin{CD}
  A    @>f>>    B \\
  @VV\alpha V   @VV\beta V \\
  C    @>g>>    D
\end{CD}
\]

On obtient un carré avec A, B, C, D aux coins : une flèche f vers la droite en haut, une flèche g vers la droite en bas, une flèche α vers le bas à gauche et une flèche β vers le bas à droite. C’est exactement le même diagramme que l’exemple tikz-cd ; seule la notation en @ change. Comme l’environnement CD d’amscd est en mode mathématique, on le place lui aussi dans une formule hors texte ; ci-dessus, nous utilisons \[ … \].

Lequel utiliser

Les deux paquets ont des domaines clairement différents. L’environnement CD d’amscd ne traite que les diagrammes en grille, rectangulaires ; le manuel AMS indique explicitement qu’il vise seulement les diagrammes rectangulaires simples, sans flèches diagonales ni fonctions plus élaborées. C’est sa principale limite. Si vous avez besoin de flèches diagonales, de courbes ou de diagrammes complexes à plusieurs lignes, amscd ne peut pas les dessiner : il faut passer à tikz-cd, ou à la famille xy.

• Besoin de flèches diagonales ou de courbes → tikz-cd. amscd ne trace que l’horizontal et le vertical.
• Contrôle fin des pointes et styles de ligne souhaité, injection hook, surjection two heads, tirets, doubles lignes, etc. → tikz-cd.
• Un diagramme rectangulaire simple suffit / dépendances légères → amscd. Il ne charge pas TikZ, il est léger et rapide.
• Goût de notation : l’écriture @>>> d’amscd est concise mais particulière ; \arrow[r, "f"] de tikz-cd est plus longue mais claire pour le lecteur.
• Chaîne de sortie : tikz-cd ne s’affiche pas correctement dans les visualiseurs DVI, il suppose donc un moteur produisant du PDF, comme pdfLaTeX ; amscd n’a pas cette contrainte.

Règle pratique : si votre article contient seulement quelques diagrammes rectangulaires, amscd suffit largement, sans dépendance supplémentaire et rapide à composer. Si les diagrammes sont centraux et que vous utilisez des applications obliques, des courbes ou des pointes élaborées, choisissez tikz-cd. Et pour quelque chose d’aussi simple que « A → B », un environnement de diagramme est souvent inutile : une commande en ligne comme \xrightarrow{f} d’amsmath suffit.