11.3 Matrix-like environments

The amsmath package offers a number of matrix-like environments, all of which are similar to array in syntax and layout. Thinking of complex mathematical layouts in this way is a useful exercise, as quite a wide variety of two-dimensional mathematical structures and table-like layouts can be described like this.

Three of these environments replace old commands that are kept well hidden in standard LaTEX: matrix and pmatrix (discussed in the next section) and cases

(discussed in the section after that). Because these old command forms use a totally different notation inherited from plain TEX, they are not truly part of LaTEX, and they cannot be mixed with the environment forms described here. Indeed, amsmath produces an explanatory error message if one of the old commands is used (see page 735). If, contrariwise, you make the mistake of using the amsmath environment forms without loading that package, then you most probably get this error message: “Misplaced alignment tab character &”.

With delarray and bigdelim, two further packages are described that allow placing various delimiters around and within matrix-like structures. The section concludes with a discussion of two commutative diagram packages: amscd and tikz-cd.

11.3.1 amsmath, mathtools — The matrix environments

The matrix environments are similar to LaTEX’s array, except that they do not have an argument specifying the formats of the columns. Instead, a default format is provided: up to ten centered columns. Also, the spacing differs slightly from the default in array. The example below illustrates the matrix environments matrix, pmatrix, bmatrix, Bmatrix, vmatrix, and Vmatrix1:

11.3.2 amsmath, mathtools, cases — Some case environments

Constructions like the following, where a single equation has a few variants, are very common in mathematics. To handle these constructions, amsmath provides the cases environment. It produces a decorated array with two columns, both left aligned.

11.3.3 delarray — Delimiters surrounding an array

This section describes a useful general extension to the array package (see Section 6.2 on page →I 437) that allows the user to specify opening and closing extensible delimiters (see Section 11.5.6) to surround a mathematical array environment. The delarray package was written by David Carlisle, and its use is illustrated in the next, rather odd-looking, example (note that the delarray package is independent of amsmath, but it automatically loads the array package if necessary).

The delimiters are placed on either side of the “preamble declaration” (here {cc}). They must be delimiters from Table 11.5 on page 190.

The most useful feature of this package is also illustrated in the preceding example: the use of the [t] and [b] optional arguments, which are not available with amsmath’s matrix environments. These show that the use of the delarray syntax is not equivalent to surrounding the array environment with and , because the delimiters are raised as well as the array itself.

11.3.4 bigdelim — Delimiters around and inside arrays

A different way of adding braces or other delimiters to arrays (or tabular structures) is provided by Pieter van Oostrum with the bigdelim package, which is based on his multirow package. In contrast to delarray where the delimiters are specified as part of the overall array specification or the matrix environment from amsmath where the environment name defines the used delimiters, this package requires dedicated array cells to be reserved for receiving the delimiters. Thus, if you want to build a three-column matrix surrounded by parentheses, you need to specify a five-column array, in which the first and last columns are there just to receive the delimiters.

If you think this is more work than with the other approaches, then this is a correct observation. However, while slightly more work, it also offers you more freedom in placement; e.g., you can let the delimiter embrace only some of the rows or even put a delimiter right in the middle of your array. Furthermore, you can attach material at the outside of the delimiter centered on its height, which is sometimes useful.

The two commands provided by the package are and . Their first argument is the delimiter to be placed, which can be any delimiter from Table 11.5 on page 190 that can vertically grow to arbitrary sizes.

In rows you specify how many rows this delimiter should span. The delimiter is placed starting in the cell where the command is used and extending the specified number of rows downwards. If the rows value is negative, it extends upwards. This can be useful in conjunction with colored tables (e.g., when using the colortbl package) because the delimiter is then placed on top of the already colored rows. Otherwise, color in later rows would come on top of the delimiter and thus effectively hide it.

With the optional vmove argument you can fine-tune the vertical position. If your rows are unusually high, you may have to slightly enlarge the row value (which can take fractional values) above the nominal number of rows to span.

In width you specify the space the delimiter and any text (if present) can take up. If you make that too small, you get an overfull box warning, and the material sticks out to the right; if you make it larger than the needed space, you will effectively produce white space at the right side of the delimiter. In some cases, that can be useful, but usually it is best to simply put a * into this argument, which tells the command to use the natural width.1 Finally, there is an optional text argument. If present, the text is placed vertically centered next to the delimiter, for on the left and for on the right.

In the next example we place two delimiters on the right, each covering only some of the rows. Note that we horizontally shifted one to the right so that they do not overprint each other. The brace on the left is printed starting from the last row to show how this is done. Also interesting is the array preamble where we used @, between the data columns and the columns for the delimiters. This suppresses the usual separation between array rows and instead inserts only a tiny space.

11.3.5 Commutative diagrams with standard LATEX

Simple commutative diagrams can in principle be produced by using an array environment and placing elements and arrows into appropriate cells. Of course, this allows only for horizontal and vertical connectors, and as you see in the next example, the results are only modestly satisfying, while the input is rather complex and difficult to read.

The picture environment could in theory be used for more complex commutative diagrams, but in practice this is the wrong tool as any changes in the diagram would require extensive manual recalculations of coordinates.

Fortunately, there are a number of specialized packages for producing sophisticated and beautiful diagrams, among them Kristoffer Rose’s (1965–2016) XY-pic system and its extension [10] by Michael Barr (see [55, Chapter 7]).

For this book we selected two packages. One is the amscd package for producing simple commutative diagrams like the one from the previous example. The other package that allows for arbitrarily complex diagrams is tikz-cd, discussed at the end of the section.

11.3.6 amscd — Commutative diagrams a là AMS

Being based on the array environment, the amscd package allows only for horizontal and vertical connectors. It provides some useful shorthand forms for specifying the decorated arrows and other connectors, which makes the input easier and the results nicer, but otherwise it does not offer new features compared to standard LaTEX.

In the CD environment the notations @>>>, @<<<, @VVV, and @AAA give right, left, down, and up arrows, respectively. The following examples also show the use of the command \DeclareMathOperator (see Section 11.6.2):

Decorations on the arrows are specified as follows. For the horizontal arrows, material between the first and second > or < symbols is typeset as a superscript, and material between the second and third is typeset as a subscript. Similarly, material between the first and second, or second and third, As or Vs of vertical arrows is typeset as left or right “side-scripts”; this format is used in the next example to place the operator EndP to the right of the arrow. The notations @= and @| give horizontal and vertical double lines. A “null arrow” (produced by @.) can be used instead of a visible arrow to fill out an array cell where needed.

If you compare this to Example 11-3-10, it shows clearly how much better the results are with the amscd package: the notation is enormously easier and, for example, the package produces longer horizontal arrows and much improved spacing between elements of the diagram. The more specialized packages enable you to get even more beautiful results, as we see exemplified in the next section.

11.3.7 tikz-cd — Commutative diagrams based on tikz

The tikz-cd package by Augusto Stoffel is one of the more recent additions in the area of specialized packages for drawing and enables you to easily prepare arbitrarily complex commutative diagrams. It is based on the powerful tikz system for drawing1 and is able to harness all of its powers if needed. Nevertheless, its input syntax is easy to learn, and the diagram sources are understandable, even without knowing the details of the package syntax as you will see below.

The package provides the environment tikzcd for producing diagrams. Inside, elements are laid out in a grid separated by &, and rows are separated by \ as usual. For specifying “arrows” between different element there is the command or its short form if you do not like typing long command names.

While the options argument is specified in brackets, it is not optional, because you need to specify at least the target direction through a combination of l, r, u, or d characters (for left, right, up, or down). For example, to have an arrow from the first element in the first row to the third element in the second row, you would specify rrd. Specifying labels for the arrows is done by surrounding their text with “⟨math⟩” (typeset in math mode), and if you require a special arrow form, there is a multitude of keywords to adjust the shape, etc.

These basic features are exhibited in the next example where we reimplement Example 11-3-10 once more.