Arrow theoretic diagrams
************************

This chapter describes definitions for producing commutative diagrams.

Steven Smith wrote this documentation (and the macros).

Slanted lines and vectors
=========================

The macros \drawline and \drawvector provide the capability found in LaTeX's picture mode to draw slanted lines and vectors of certain directions. Both of these macros take three arguments: two integer arguments to specify the direction of the line or vector, and one argument to specify its length.  For example, \drawvector(-4,1){60pt} produces the vector

(A vector in the 2d quadrant of length 60 pt appears here.)

which lies in the 2d quadrant, has a slope of minus 1/4, and a width of 60 pt.

Note that if an \hbox is placed around \drawline or \drawvector, then the width of the \hbox will be the positive dimension specified in the third argument, except when a vertical line or vector is specified, e.g., \drawline(0,1){1in}, which has zero width.  If the specified direction lies in the 1st or 2d quadrant (e.g., (1,1) or (-2,3)), then the \hbox will have positive height and zero depth.  Conversely, if the specified direction lies in the 3d or 4th quadrant (e.g., (-1,-1) or (2,-3)), then the \hbox will have positive depth and zero height.

There are a finite number of directions that can be specified.  For \drawline, the absolute value of each integer defining the direction must be less than or equal to six, i.e., (7,-1) is incorrect, but (6,-1) is acceptable. For \drawvector, the absolute value of each integer must be less than or equal to four. Furthermore, the two integers cannot have common divisors; therefore, if a line with slope 2 is desired, say (2,1) instead of (4,2).  Also, specify (1,0) instead of, say, (3,0) for horizontal lines and likewise for vertical lines.

Finally, these macros depend upon the LaTeX font line10.  If your site doesn't have this font, ask your system administrator to get it.  Future enhancements will include macros to draw dotted lines and dotted vectors of various directions.

Commutative diagrams
====================

The primitive commands \drawline and \drawvector can be used to typeset arrow theoretic diagrams.  This section describes (1) macros to facilitate typesetting arrows and morphisms, and (2) macros to facilitate the construction of commutative diagrams.  All macros described in this section must be used in math mode.

Arrows and morphisms
--------------------

The macros \mapright and \mapleft produce right and left pointing arrows, respectively.  Use superscript (^) to place a morphism above the arrow, e.g., \mapright^\alpha; use subscript (_) to place a morphism below the arrow, e.g., \mapright_{\tilde l}.  Superscripts and subscripts may be used simulataneously, e.g., \mapright^\pi_{\rm epimor.}.

Similarly, the macros \mapup and \mapdown produce up and down pointing arrows, respectively.  Use \rt to place a morphism to the right of the arrow, e.g., \mapup\rt{\rm id}; use \lft to place a morphism to the left of the arrow, e.g., \mapup\lft\omega. \lft and \rt may be used simultaneously, e.g., \mapdown\lft\pi\rt{\rm monomor.}.

Slanted arrows are produced by the macro \arrow, which takes a direction argument (e.g., \arrow(3,-4)).  Use \rt and \lft to place morphisms to the right and left, respectively, of the arrow.  A slanted line (no arrowhead) is produced with the macro \sline, whose syntax is identical to that of \arrow.

The length of these macros is predefined by the default TeX dimensions \harrowlength, for horizontal arrows (or lines), \varrowlength, for vertical arrows (or lines), and \sarrowlength, for slanted arrows (or lines).  To change any of these dimensions, say, e.g., \harrowlength=40pt.  As with all other TeX dimensions, the change may be as global or as local as you like.  Furthermore, the placement of morphisms on the arrows is controlled by the dimensions \hmorphposn, \vmorphposn, and \morphdist. The first two dimensions control the horizontal and vertical position of the morphism from its default position; the latter dimension controls the distance of the morphism from the arrow.  If you have more than one morphism per arrow (i.e., a ^/_ or \lft/\rt construction), use the parameters \hmorphposnup, \hmorphposndn, \vmorphposnup, \vmorphposndn, \hmorphposnrt, \hmorphposnlft, \vmorphposnrt, and \vmorphposnlft. The default values of all these dimensions are provided in the section on parameters that follows below.

There is a family of macros to produce horizontal lines, arrows, and adjoint arrows.  The following macros produce horizontal maps and have the same syntax as \mapright:

\mapright
     $X\mapright Y$ = (a right arrow).

\mapleft
     $X\mapleft Y$ = (a left arrow).

\hline
     $X\hline Y$ = (horizontal line)

\bimapright
     $X\bimapright Y$ = (two right arrows).

\bimapleft
     $X\bimapleft Y$ = (two left arrows)

\adjmapright
     $X\adjmapright Y$ = (two adjoint arrows; left over right)

\adjmapleft
     $X\adjmapleft Y$ = (two adjoint arrows; right over left)

\bihline
     $X\bihline Y$ = (two horizontal lines)

There is also a family of macros to produce vertical lines, arrows, and adjoint arrows.  The following macros produce vertical maps and have the same syntax as \mapdown:

\mapdown
     (a down arrow)

\mapup
     (an up arrow)

\vline
     (vertical line)

\bimapdown
     (two down arrows)

\bimapup
     (two up arrows)

\adjmapdown
     (two adjoint arrows; down then up)

\adjmapup
     (two adjoint arrows; up then down)

\bivline
     (two vertical lines)

Finally, there is a family of macros to produce slanted lines, arrows, and adjoint arrows.  The following macros produce slanted maps and have the same syntax as \arrow:

\arrow
     (a slanted arrow)

\sline
     (a slanted line)

\biarrow
     (two straight arrows)

\adjarrow
     (two adjoint arrows)

\bisline
     (two straight lines)

The width between double arrows is controlled by the parameter \channelwidth. The parameters \hchannel and \vchannel, if nonzero, override \channelwidth by controlling the horizontal and vertical shifting from the first arrow to the second.

There are no adornments on these arrows to distinguish inclusions from epimorphisms from monomorphisms.  Many texts, such as Lang's book Algebra, use as a tasteful alternative the symbol `inc' (in roman) next to an arrow to denote inclusion.

Future enhancements will include a mechanism to draw curved arrows found in, e.g., the Snake Lemma, by employing a version of the \path macros of Appendix D of The TeXbook.

Construction of commutative diagrams
------------------------------------

There are two approaches to the construction of commutative diagrams described here.  The first approach, and the simplest, treats commutative diagrams like fancy matrices, as Knuth does in Exercise 18.46 of The TeXbook.  This case is covered by the macro \commdiag, which is an altered version of the Plain TeX macro \matrix. An example suffices to demonstrate this macro.  The following commutative diagram (illustrating the covering homotopy property; Bott and Tu, Differential Forms in Algebraic Topology)

(A commutative diagram appears here in the printed output.)

is produced with the code

     $$\commdiag{Y&\mapright^f&E\cr \mapdown&\arrow(3,2)\lft{f_t}&\mapdown\cr
     Y\times I&\mapright^{\bar f_t}&X}$$

Of course, the parameters may be changed to produce a different effect. The following commutative diagram (illustrating the universal mapping property; Warner, Foundations of Differentiable Manifolds and Lie Groups)

(A commutative diagram appears here in the printed output.)

is produced with the code

     $$\varrowlength=20pt
     \commdiag{V\otimes W\cr \mapup\lft\phi&\arrow(3,-1)\rt{\tilde l}\cr
     V\times W&\mapright^l&U\cr}$$

A diagram containing isosceles triangles is achieved by placing the apex of the triangle in the center column, as shown in the example (illustrating all constant minimal realizations of a linear system; Brockett, Finite Dimensional Linear Systems)

(A commutative diagram appears here in the printed output.)

which is produced with the code

     $$\sarrowlength=.42\harrowlength
     \commdiag{&R^m\cr &\arrow(-1,-1)\lft{\bf B}\quad \arrow(1,-1)\rt{\bf G}\cr
     R^n&\mapright^{\bf P}&R^n\cr
     \mapdown\lft{e^{{\bf A}t}}&&\mapdown\rt{e^{{\bf F}t}}\cr
     R^n&\mapright^{\bf P}&R^n\cr
     &\arrow(1,-1)\lft{\bf C}\quad \arrow(-1,-1)\rt{\bf H}\cr
     &R^q\cr}$$

Other commutative diagram examples appear in the file commdiags.tex, which is distributed with this package.

In these examples the arrow lengths and line slopes were carefully chosen to blend with each other.  In the first example, the default settings for the arrow lengths are used, but a direction for the arrow must be chosen.  The ratio of the default horizontal and vertical arrow lengths is approximately the golden mean gamma=1.618...; the arrow direction closest to this mean is (3,2). In the second example, a slope of -1/3 is desired and the default horizontal arrow length is 60 pt; therefore, choose a vertical arrow length of 20 pt.  You may affect the interline glue settings of \commdiag by redefining the macro \commdiagbaselines. (cf. Exercise 18.46 of The TeXbook and the section on parameters below.)

The width, height, and depth of all morphisms are hidden so that the morphisms' size do not affect arrow positions.  This can cause a large morphism at the top or bottom of a diagram to impinge upon the text surrounding the diagram.  To overcome this problem, use TeX's \noalign primitive to insert a \vskip immediately above or below the offending line, e.g., $$\commdiag{\noalign{\vskip6pt}X&\mapright^\int&Y\cr ...}.

The macro \commdiag is too simple to be used for more complicated diagrams, which may have intersecting or overlapping arrows.  A second approach, borrowed from Francis Borceux's Diagram macros for LaTeX, treats the commutative diagram like a grid of identically shaped boxes.  To compose the commutative diagram, first draw an equally spaced grid, e.g.,

. . . . . .
. . . . . .
. . . . . .
. . . . . .

on a piece of scratch paper.  Then draw each element (vertices and arrows) of the commutative diagram on this grid, centered at each grid point.  Finally, use the macro \gridcommdiag to implement your design as a TeX alignment.  For example, the cubic diagram

(A commutative diagram appears here.)

that appears in Francis Borceux's documentation can be implemented on a 7 by 7 grid, and is achieved with the code

     $$\harrowlength=48pt \varrowlength=48pt \sarrowlength=20pt
     \def\cross#1#2{\setbox0=\hbox{$#1$}%
       \hbox to\wd0{\hss\hbox{$#2$}\hss}\llap{\unhbox0}}
     \gridcommdiag{&&B&&\mapright^b&&D\cr
     &\arrow(1,1)\lft a&&&&\arrow(1,1)\lft d\cr
     A&&\cross{\hmorphposn=12pt\mapright^c}{\vmorphposn=-12pt\mapdown\lft f}
     &&C&&\mapdown\rt h\cr\cr
     \mapdown\lft e&&F&&\cross{\hmorphposn=-12pt\mapright_j}
     {\vmorphposn=12pt\mapdown\rt g}&&H\cr
     &\arrow(1,1)\lft i&&&&\arrow(1,1)\rt l\cr
     E&&\mapright_k&&G\cr}$$

The dimensions \hgrid and \vgrid control the horizontal and vertical spacing of the grid used by \gridcommdiag. The default setting for both of these dimensions is 15 pt.  Note that in the example of the cube the arrow lengths must be adjusted so that the arrows overlap into neighboring boxes by the desired amount.  Hence, the \gridcommdiag method, albeit more powerful, is less automatic than the simpler \commdiag method. Furthermore, the ad hoc macro \cross is introduced to allow the effect of overlapping arrows.  Finally, note that the positions of four of the morphisms are adjusted by setting \hmorphposn and \vmorphposn.

One is not restricted to a square grid.  For example, the proof of Zassenhaus's Butterfly Lemma can be illustrated by the diagram (appearing in Lang's book Algebra)

(A commutative diagram appears here.)

This diagram may be implemented on a 9 by 12 grid with an aspect ratio of 1/2, and is set with the code

     $$\hgrid=16pt \vgrid=8pt \sarrowlength=32pt
     \def\cross#1#2{\setbox0=\hbox{$#1$}%
       \hbox to\wd0{\hss\hbox{$#2$}\hss}\llap{\unhbox0}}
     \def\l#1{\llap{$#1$\hskip.5em}}
     \def\r#1{\rlap{\hskip.5em$#1$}}
     \gridcommdiag{&&U&&&&V\cr &&\bullet&&&&\bullet\cr
     &&\sarrowlength=16pt\sline(0,1)&&&&\sarrowlength=16pt\sline(0,1)\cr
     &&\l{u(U\cap V)}\bullet&&&&\bullet\r{(U\cap V)v}\cr
     &&&\sline(2,-1)&&\sline(2,1)\cr
     &&\cross{=}{\sline(0,1)}&&\bullet&&\cross{=}{\sline(0,1)}\cr\cr
     &&\l{^{\textstyle u(U\cap v)}}\bullet&&\cross{=}{\sline(0,1)}&&
      \bullet\r{^{\textstyle(u\cap V)v}}\cr
     &\sline(2,1)&&\sline(2,-1)&&\sline(2,1)&&\sline(2,-1)\cr
     \l{u}\bullet&&&&\bullet&&&&\bullet\r{v}\cr
     &\sline(2,-1)&&\sline(2,1)&&\sline(2,-1)&&\sline(2,1)\cr
     &&\bullet&&&&\bullet\cr &&u\cap V&&&&U\cap v\cr}$$

Again, the construction of this diagram requires careful choices for the arrow lengths and is facilitated by the introduction of the ad hoc macros \cross, \r, and \l.  Note also that superscripts were used to adjust the position of the vertices u(U intersection v) and (u intersection V)v. Many diagrams may be typeset with the predefined macros that appear here; however, ingenuity is often required to handle special cases.

Commutative diagram parameters
------------------------------

The following is a list describing the parameters used in the commutative diagram macros.  These dimensions may be changed globally or locally.

\harrowlength
     (Default: 60 pt) The length of right or left arrows.

\varrowlength
     (Default: 0.618\harrowlength) The length of up or down arrows.

\sarrowlength
     (Default: 60 pt) The horizontal length of slanted arrows.

\hmorphposn
     (Default: 0 pt) The horizontal position of the morphism with respect to its default position.  There are also the dimensions \hmorphposnup, \hmorphposndn, \hmorphposnrt, and \hmorphposnlft for ^/_ or \lft/\rt constructions.

\vmorphposn
     (Default: 0 pt) The vertical position of the morphism with respect to its default position. There are also the dimensions \vmorphposnup, \vmorphposndn, \vmorphposnrt, and \vmorphposnlft for ^/_ or \lft/\rt constructions.

\morphdist
     (Default: 4 pt) The distance of morphisms from slanted lines or arrows.

\channelwidth
     (Default: 3 pt) The distance between double lines or arrows.

\hchannel, \vchannel
     (Defaults: 0 pt) Overrides \channelwidth. The horizontal and vertical shifts between double lines or arrows.

\commdiagbaselines
     (Default: \baselineskip=15pt \lineskip=3pt \lineskiplimit=3pt ) The parameters used by \commdiag for setting interline glue.

\hgrid
     (Default: 15 pt) The horizontal spacing of the grid used by \gridcommdiag.

\vgrid
     (Default: 15 pt) The vertical spacing of the grid used by \gridcommdiag.