Diagrammes commutatifs (tikz-cd / amscd)

« Ce diagramme commute » est peut-être la phrase la plus courte et la plus portante des mathématiques : elle tient lieu d’un ensemble d’égalités qui prendrait plusieurs lignes. Un diagramme commutatif transforme les objets en points et les applications en flèches, et affirme que deux chemins orientés quelconques reliant le même couple d’objets se composent en la même application. En LaTeX, la façon standard d’en tracer un est aujourd’hui \usepackage{tikz-cd} — l’environnement s’appelle tikzcd, sans trait d’union — tandis que le package AMS amscd suffit encore pour les grilles rectangulaires simples. Cette page construit un carré commutatif à partir de rien, répartit les étiquettes de part et d’autre des flèches, les courbe, et se termine sur le choix du package.

Ce que « le diagramme commute » affirme au juste

Commuter signifie que tout chemin orienté ayant même origine et même but donne la même composée. Dans un carré portant A, B, C, D aux coins — f en haut de A vers B, β à droite de B vers D, α à gauche de A vers C et g en bas de C vers D —, dire qu’il commute revient exactement à l’unique égalité β∘f = g∘α. Un triangle porte une équation, un carré une, un cube six, une par face, toutes repliées dans une seule image. Plus le diagramme grandit, plus l’écart se creuse entre ce que contient le dessin et ce que coûteraient les équations écrites. Un diagramme commutatif n’est pas un ornement : c’est de la notation comprimée.

Cette compression prend tout son sens dans la chasse au diagramme (diagram chasing). Les démonstrations d’algèbre homologique — lemme des cinq, lemme du serpent — consistent à choisir un élément dans un coin et à le pousser le long des flèches, en circulant dans le diagramme. La commutativité est la règle qui garantit, à chaque étape de ce parcours, que les deux routes aboutissent au même endroit. Le diagramme n’est donc pas seulement une image : c’est le plateau sur lequel se joue la démonstration. Ces diagrammes sont entrés dans l’écriture mathématique avec l’article de 1945 qui a fondé la théorie des catégories ; cette histoire, et les symboles de flèche eux-mêmes, sont traités sur la page des flèches.

Un diagramme est lui-même une formule hors texte : il se place donc dans \[ … \] ou dans un environnement equation, qui lui donne une ligne à part, centrée. Toute une étagère de packages a été écrite pour cela — xypic, diagram, kuvio entre autres — mais pour un travail neuf le choix se réduit à deux : tikz-cd, bâti sur le package de dessin généraliste TikZ, et le package AMS amscd. On les examine tour à tour.

\usepackage{tikz-cd} et l’environnement tikzcd

Dans le préambule, \usepackage{tikz-cd} ; dans le corps, le diagramme s’écrit entre \begin{tikzcd} et \end{tikzcd}. Le nom du package porte un trait d’union, celui de l’environnement non. En les intervertissant, on obtient ! LaTeX Error: File 'tikzcd.sty' not found. ; en écrivant l’environnement sans charger le package, ! LaTeX Error: Environment tikzcd undefined. Si TikZ est déjà chargé, \usetikzlibrary{cd} donne exactement la même chose. La version courante sur CTAN est la 1.0, datée du 4 mai 2021, maintenue par Augusto Stoffel. Les pointes de flèche sont livrées dans une bibliothèque à part, dessinées pour s’accorder aux flèches de la fonte Computer Modern — d’où le fait que les flèches du diagramme n’aient pas l’air empruntées à une autre fonte.

À l’intérieur de tikzcd, on écrit exactement ce qu’on écrirait dans tabular ou matrix : cellules séparées par &, lignes par \\. Chaque cellule devient un nœud du diagramme et son contenu est composé automatiquement en mode mathématique ; les $ sont donc inutiles. Ajouter \arrow dans une cellule y fait pousser une flèche ; l’alias court \ar est la même commande. La flèche s’écrit dans la cellule d’où elle part, et sa cible se donne entre crochets par des touches de direction : r droite, l gauche, u haut, d bas. Elles se combinent en chaîne : [rd] va en diagonale vers le bas à droite, [rr] atteint la cellule suivante mais une. Une même cellule peut émettre autant de flèches qu’on veut.

\usepackage{tikz-cd}   % package has a hyphen; environment does not
\[
\begin{tikzcd}
  A \arrow[r, "f"] \arrow[d, "\alpha"'] & B \arrow[d, "\beta"] \\
  C \arrow[r, "g"']                     & D
\end{tikzcd}
\]

Voilà le carré commutatif. A, B, C, D occupent les quatre coins ; f va vers la droite en haut, g vers la droite en bas, α et β descendent à gauche et à droite. & sépare les colonnes et \\ les lignes : la charpente se réduit donc à A & B \\ C & D. Les flèches ne sont que des annotations glissées ensuite dans cette charpente, et la position des objets ne dépend en rien de la façon dont les flèches sont écrites — c’est le trait le plus agréable de la conception de tikzcd.

Étiqueter une flèche au-dessus ou au-dessous : "f" et "f"'

Une chaîne entre guillemets parmi les options devient une étiquette, et une apostrophe ' juste après le guillemet fermant la fait passer de l’autre côté. La règle n’est pas « au-dessus ou au-dessous » mais à gauche du sens de parcours. Pour une flèche vers la droite, la gauche est le haut : \arrow[r, "f"] place donc f au-dessus, \arrow[r, "f"'] au-dessous. Pour une flèche vers le bas, la gauche est bien la gauche : \arrow[d, "\alpha"] place α à gauche, \arrow[d, "\alpha"'] à droite. Inutile de retenir quatre cas ; la seule règle « à gauche du parcours » les explique tous.

Une flèche peut porter autant d’étiquettes qu’on veut, chacune avec ses propres options. "\phi" near start se place près du départ, "\eta" near end près de l’arrivée, et "h" description pose l’étiquette sur la flèche en découpant le trait derrière elle à la couleur du fond — le geste classique lorsqu’une flèche courte doit porter un nom long. Si le texte de l’étiquette ou ses options contiennent une virgule, on les protège par des accolades : "{(x,y)}". L’intérieur étant en mode mathématique, les mots ordinaires demandent \text{…} d’amsmath.

\[
\begin{tikzcd}
  A \arrow[r, "\phi" near start, "\psi"', "\eta" near end] & B \\
  X \arrow[r, "h" description] \arrow[rd] & Y \\
                                          & Z
\end{tikzcd}
\]

Courber les flèches et en tracer deux entre les mêmes objets

On emploie bend left et bend right, avec un angle si besoin : bend left=25. La raison de courber est presque toujours la même — il y a deux applications entre le même couple d’objets. Une adjonction, une équivalence d’homotopie, le couple d’applications d’un conoyau : chacun demande deux flèches, et tracées droites elles se superposent et n’en font plus qu’une. Courbées, les deux se lisent. Pour les vouloir parallèles plutôt que courbes, shift left et shift right (valeur par défaut 0.56ex) décalent latéralement une flèche restée droite. Comme toujours, « gauche » se rapporte au sens de parcours : bend left bombe vers la gauche de la flèche.

Dans les diagrammes en trois dimensions — un cube aplati sur la page — les arêtes du fond croisent celles du premier plan. Ajouter crossing over à une flèche trace d’abord sous elle un trait épais de la couleur du fond, de sorte qu’elle semble passer devant. Les flèches sont dessinées dans l’ordre où elles sont écrites ; si celle qui doit passer dessous vient en premier, on retarde l’autre en la déclarant à rebours depuis une cellule ultérieure, par exemple avec from=uu. La réussite d’un diagramme en cube tient entièrement à ces deux points.

\[
\begin{tikzcd}
  A \arrow[r, bend left=25, "f"] \arrow[r, bend right=25, "g"'] & B
\end{tikzcd}
\qquad
\begin{tikzcd}
  A \arrow[dr] & B \arrow[dl, crossing over] \\
  C            & D
\end{tikzcd}
\]

Les styles de trait et les pointes se changent de la même façon, en ajoutant des clés aux options de \arrow. Les noms forment deux familles : des noms courts et descriptifs comme hook ou two heads, et des noms repris de commandes LaTeX existantes sans la contre-oblique, comme dashrightarrow. Connaître la seconde convention permet de deviner une clé au lieu de la chercher. Les clés se cumulent : \arrow[r, tail, two heads, dashed] produit d’un coup une flèche à queue, à double pointe et en tirets. Les clés courantes sont rassemblées ci-dessous.

Poser un signe d’isomorphisme comme étiquette est un autre usage courant : \arrow[r, dashed, "\simeq"] place ≃ au-dessus d’une flèche tiretée (\sim fonctionne de même). Et comme tikz-cd est bâti sur TikZ, il accepte directement les clés propres à TikZ — color=…, dotted, in=…/out=… et les autres. Son domaine d’expression est en pratique celui de tout TikZ ; ce qui signifie aussi qu’en cas de blocage, le manuel à ouvrir sera peut-être celui de TikZ plutôt que celui de tikz-cd.

Ajuster les espacements et marquer un carré cartésien

Les espacements se règlent dans l’argument optionnel de l’environnement : \begin{tikzcd}[column sep=large, row sep=small]. Les dimensions (2em) comme les noms (tiny, small, large, huge) sont acceptés, et sep règle lignes et colonnes d’un coup. Ne vouloir élargir que la direction qui porte les étiquettes longues est un besoin assez fréquent pour que ces deux clés méritent d’être retenues.

Le petit coin ⌜ qui signale un carré cartésien (produit fibré) n’a pas de clé dédiée. L’usage est de poser une étiquette sur une flèche invisible : \arrow[rd, phantom, "\ulcorner", very near start]. La clé phantom efface la flèche, et l’étiquette restante vient se loger juste à l’intérieur du coin supérieur gauche (pour un cocartésien, \lrcorner près du coin inférieur droit). Un piège guette : \ulcorner n’est pas un symbole du noyau LaTeX mais d’AMSFonts ; sans \usepackage{amssymb}, la compilation s’arrête sur ! Undefined control sequence. Les étiquettes d’une flèche phantom sont en outre ancrées en leur centre et composées en pleine taille \textstyle ; pour les réduire, il faut écrire \scriptstyle.

\usepackage{amssymb}   % \ulcorner comes from AMSFonts, not core LaTeX
\[
\begin{tikzcd}[column sep=large, row sep=large]
  P \arrow[r, "p"] \arrow[d, "q"'] \arrow[rd, phantom, "\ulcorner", very near start]
    & X \arrow[d, "f"] \\
  Y \arrow[r, "g"'] & Z
\end{tikzcd}
\]

Quand amscd suffit encore : l’environnement CD

Quand le diagramme est une grille rectangulaire sans diagonale et qu’on préfère ne pas embarquer TikZ dans la compilation, amscd est la réponse. \usepackage{amscd} n’apporte qu’une chose : l’environnement CD. Il fait partie du lot amsmath, se trouve aujourd’hui en v2.1 (14 avril 2017) et ne dépend que d’amsgen. Le plus savoureux est sa propre documentation : elle explique qu’il reproduit les capacités de diagrammes d’AMS-TeX 2.x, précise sans détour que seuls les diagrammes rectangulaires simples sont pris en charge, sans flèches diagonales ni fonctions plus exotiques, puis ajoute que bien des utilisateurs seraient mieux servis par un package plus puissant — en citant diagram, xypic et kuvio. Peu de packages renvoient ainsi leur lecteur ailleurs dès leur introduction.

Le contenu est une matrice de & et de \\, comme dans tikz-cd, mais chaque flèche s’écrit sous la forme d’un jeton spécial commençant par @. À l’horizontale, @>>> va vers la droite et @<<< vers la gauche ; à la verticale, @VVV descend — le V de « vertical » — et @AAA monte, le A se lisant comme une pointe dirigée vers le haut. L’égalité à double trait est @= en horizontal et @| en vertical. Un point de grille sans flèche reçoit la « flèche nulle » @. pour que les colonnes restent alignées. Les flèches horizontales se placent entre deux objets d’une même ligne, les verticales sur la ligne située juste sous leur objet.

Les étiquettes s’insèrent entre les caractères qui composent la flèche — et voici le fait qui explique d’un coup tout le reste. Selon la documentation AMS, la matière comprise entre le premier et le deuxième > est composée en exposant, et celle comprise entre le deuxième et le troisième en indice. D’où @>f>> qui met f au-dessus, @>>g> qui met g au-dessous, et @>f>g> qui en place un de chaque côté. C’est aussi pourquoi les étiquettes sortent en petit corps : une flèche amscd est au fond un symbole de relation très large muni d’indices. Les flèches verticales suivent la même règle, les indices se plaçant sur les côtés : @VfVV met f à gauche d’une flèche descendante, @VVfV à droite.

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

C’est exactement le même carré que dans l’exemple tikz-cd. À gauche, @V\alpha VV place α à gauche de la flèche ; à droite, @VV\beta V place β à sa droite, de sorte que les deux étiquettes regardent vers l’extérieur du carré. En bas, @>>g> met g sous sa flèche. L’environnement CD est lui aussi en mode mathématique et se place donc, comme tikz-cd, dans une formule hors texte. Vient ensuite l’exemple du manuel AMS, qui suppose \End défini comme nom d’opérateur, à la manière d’\operatorname.

% from the AMS amscd manual; \End must be defined as an operator name
\[
\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}
\]

La ligne du haut trace une flèche de l’objet de gauche vers T à droite, avec j au-dessus. La ligne du milieu crée les deux flèches verticales : sans étiquette dans la colonne de gauche, et avec End P à droite de la flèche dans celle de droite. La ligne du bas relie ses deux objets par le double trait @=. Les accolades de {\End P} groupent une étiquette de plusieurs jetons en une seule unité. Et si le besoin se fait sentir de flèches grasses, tiretées, bidirectionnelles ou colorées tout en restant dans amscd, le package d’extension amscdx (v2.2x, 2019) les ajoute — la restriction à la géométrie rectangulaire demeurant telle quelle.

tikz-cd ou amscd : comment choisir

La décision tient presque à une seule question — faut-il une flèche diagonale ? Si oui, amscd est hors course. Si une grille rectangulaire suffit, amscd est plus léger en dépendances et plus court à écrire. La liste ci-dessous détaille un peu cette unique question.

• Flèches diagonales ou courbes nécessaires → tikz-cd. amscd ne fait qu’horizontal et vertical ; l’oblique n’est pas malcommode, elle est impossible.
• Contrôle fin des pointes et des styles de trait (injections hook/tail, surjections two heads, tirets, doubles lignes) → tikz-cd.
• Un diagramme rectangulaire simple suffit et les dépendances doivent rester légères → amscd. Sans TikZ, la composition est plus rapide et le préambule reste court.
• Affaire de goût : le @>f>> d’amscd est bref mais singulier ; le \arrow[r, "f"] de tikz-cd est plus long mais reste lisible six mois plus tard.
• Chaîne de sortie : les diagrammes tikz-cd ne s’affichent pas correctement dans les visualiseurs DVI. Ils supposent pdflatex, lualatex ou xelatex, des moteurs produisant directement du PDF, ou une conversion de DVI vers PDF/PS. amscd n’a pas cette contrainte.
• Faut-il seulement un diagramme : pour deux objets et une flèche, \xrightarrow{f} d’amsmath dans le fil du texte suffit à tout.

Deux dernières remarques, pour le jour où l’on hérite d’un ancien document. tikz-cd conserve la forme antérieure à la syntaxe avec guillemets — \arrow[options]{direction}{étiquettes}, par exemple \arrow{r}{f} — maintenue par souci de compatibilité. S’y ajoutent les commandes abrégées \rar, \dar, \uar, \lar, ainsi que les diagonales comme \drar ; \rar vaut simplement \arrow{r}. Mieux vaut éviter les deux dans un travail neuf : s’en tenir partout à \arrow[r, "f"] est une amabilité envers soi-même dans six mois.