XY-pic User’s Guide

Kristoffer H. Rose hkrisrose@tug.orgi×

Version 3.8.4, October 11, 2010

Abstract Contents
XY-pic is a package for typesetting graphs and diagrams Preface 2
using Knuth’s TEX typesetting system. XY-pic works with
most of the many formats available; e.g., plain TEX, 1 Basics 2
LATEX, and AMS-TEX. Several styles of input for various
1.1 Loading . . . . . . . . . . . . . . . . . . . 2
diagram types are supported; they all share a mnemonic
notation based on the logical composition of visual com- 1.2 Entries . . . . . . . . . . . . . . . . . . . . 2
ponents. This guide concentrates on how to typeset 1.3 Arrows . . . . . . . . . . . . . . . . . . . . 3
“matrix-like” diagrams, such as commutative diagrams, 1.4 Labels . . . . . . . . . . . . . . . . . . . . 3
in the following style: 1.5 Breaks . . . . . . . . . . . . . . . . . . . . 3
1.6 Curving . . . . . . . . . . . . . . . . . . . 4
U 1.7 Speeding up typesetting . . . . . . . . . . 4
x
(x,y)
# %/ 2 More Arrows and Labels 4
X ×Z Y p
X 2.1 Explicit label positioning . . . . . . . . . 4
y
q f
2.2 Labeling with any object . . . . . . . . . . 5
  2.3 More arrow styles . . . . . . . . . . . . . . 6
Y
g
/Z 2.4 Sliding arrows sideways . . . . . . . . . . 6
2.5 More targets . . . . . . . . . . . . . . . . 7
was typeset by the XY-pic input lines
2.6 Changing the target . . . . . . . . . . . . 7
\xymatrix{ 2.7 Arrows passing under . . . . . . . . . . . 7
U \ar@/_/[ddr]_y \ar@/^/[drr]^x 2.8 More bending arrows . . . . . . . . . . . . 8
\ar@{.>}[dr]|-{(x,y)} \\
2.9 Defining new arrow types . . . . . . . . . 8
& X \times_Z Y \ar[d]^q \ar[r]_p
& X \ar[d]_f \\
3 More Entries 9
& Y \ar[r]^g & Z }
3.1 Manual entry formatting . . . . . . . . . . 9
Such diagrams have the following characteristics: 3.2 Extra entries outside the matrix . . . . . 9
• Specified as a matrix of entries that are automati- 3.3 Spacing and rotation . . . . . . . . . . . . 10
cally aligned in rows and columns. 3.4 Entry style . . . . . . . . . . . . . . . . . 10
• Any entry may be connected to any other en- 3.5 Naming for later use as targets . . . . . . 10
try using a variety of arrow styles all rotated and 3.6 Grouping objects . . . . . . . . . . . . . . 11
stretched as required.
4 Availability and Further Information 11
• Arrows may be decorated with labels that are tied 4.1 Getting XY-pic . . . . . . . . . . . . . . . . 11
to a specified point along the arrow and extend in
4.2 Backwards compatibility . . . . . . . . . . 11
a particular direction; and arrows may be paired,
cross, and visit/bend around other entries “on the 4.3 Further reading . . . . . . . . . . . . . . . 12
way.” 4.4 Credits . . . . . . . . . . . . . . . . . . . . 13

Several other styles of input are supported; a short survey A Answers to all exercises 13
of the possibilities is included last at the end along with
information on how XY-pic can be obtained. References 14

Index 15
× IBM Thomas J. Watson Research Center, P.O. Box 704, Yorktown Heights, NY 10598, USA.

1
Preface non-standard facilities like the v2 backwards compat-
ibility mode2 then this is also possible as described in
This guide explains some features of XY-pic that are the reference manual [4]; in addition the driver you
relevant to typesetting of “matrix-like diagrams” as wish to use should be explicitly requested, for exam-
used in, for example, category theory; please refer to ple with \xyoption{pdf}.
the reference manual [4] for complete information on
the described constructions. The guide assumes that
you have some experience in using TEX for typeset- 1.2 Entries
ting mathematics, e.g., have studied [2, ch. 16–19], [3,
sec. 3.3], or [5], and that XY-pic is installed on your A diagram is created by the command
TEX system as described in the INSTALL file accom-
panying the distribution. \xymatrix{ . . . }
The first section describes what you need to get
started, in particular all that is needed to typeset where the “. . . ” should be replaced by entries to be
the diagram in the abstract. Section 2 and 3 explain aligned in rows and columns where
advanced use of arrows and entries, respectively. Fi-
nally, section 4 explains where and under what condi- • entries in a row are separated by &,3 and
tions XY-pic is available, gives the relation of version
3.8.4 to previous versions, and lists further sources of • entire rows are separated by \\.
information.
Throughout we give exercises that you should be For example,
able to solve as you go along; all exercises are an-
Pm
swered at the end just prior to the references and A i2
i=n c
index.

1 Basics • D

This section explains the XY-diagram construction was typeset by

concepts needed to get started with typesetting \xymatrix{
matrix-like diagrams. A &*+[F]{\sum_{i=n}^m {i^2}} \\
& {\bullet} & D \ar[ul] }
1.1 Loading Notice the following:
With LATEX 2ε , used by most users, XY-pic is loaded
• entries are typeset as mathematics (using “text
with
style”); entries should not start with a macro
\usepackage[all]{xy} (as illustrated by the use of {} around \bullet .

in the preamble of the document; this also automat- • all entries are centered and the separation be-
ically loads an appropriate “backend driver” for gen- tween rows and columns is usually quite large
erating graphics in either PDF or PostScript1 for- in a diagram,
mat, when possible (by checking for document class
options like pdftex, dvipdfm, or dvips), to ensure • empty entries at the end of rows may be omit-
the highest output quality (and usually results in ted,
smaller files).
When not using LATEX 2ε , or for portability, XY-pic • “XY-decorations” (here \ar[ul]) in entries al-
can be loaded with the commands low drawing of arrows and such relative to the
\input xy entries without changing the overall layout, and
\xyoption{all}
• “XY-modifiers” (here *+[F]) first in entries al-
in the definitions part of your document. If you wish low changing the format and shape in many
to load only the features you use, or you wish to use ways.
1 PostScript is a registered Trademark of Adobe, Inc. [1].
2 If
you use the version 2 loading command \input xypic (or the xypic document style option) then the v2 option described in
section 4.2 will be loaded automatically.
3 Thus when using X -constructions involving & inside other tabular constructions then enclose the X -pic construction in an extra
Y Y
pair of braces!

2
1.3 Arrows will set X
a /Y o B
Z (the @1 is a special code
b A
An “arrow” in an XY-pic diagram is a generic term that can be used for “one-line” diagrams to improve
for the drawn decorations between the entries of the the placement on the line; more such spacing codes
basic matrix structure. In XY-pic all arrows must be are described in section 3.3).
specified along with the entry in which they start; this It is possible to use labels that are not single let-
is called their base entry. Each particular arrow com- ters, digits, or control sequences: if a simple math
mand then refers explicitly to its target entry. This formula in the default style (script style) is desired
is obtained using the \ar command which accepts then simply enclose in {. . . }. In practice anything
many options of which we will describe a few here can be used as a label as described in section 2.2.
and some more in section 2. In its simplest form an Each label is placed perpendicular to the arrow at
arrow is entered as \ar[hop] where hop is a sequence the point halfway between the centers of the base and
of single letters: u for up, d for down, l for left, and target objects. This is usually the most æsthethic,
r for right, e.g., the arrow \ar[ur] reads “typeset an however, in diagrams where the sizes of the entries
arrow from the current entry to that one up and one vary much it is sometimes nicer to place the label
right.” at the center of the actual arrow. This behaviour is
requested by inserting a - (minus) right after the ^
Exercise 1: Which entry does [] refer to? (p.13) or _: A × B × C × D
+
/ B was typeset by
The relative coordinates specified in this way are $\xymatrix@1{
purely logical, e.g., if the diagram contains very wide A\times B\times C\times D \ar[r]^-{+} &B
entries then “diagonal” arrows will be nearly horizon- }$
tal. The constructed arrows are aligned along the line
(it becomes A × B × C × D
+
/ B without the -).
between the centers of the base and target entries;
they will not automatically disappear under entries In fact - is in just one of the may possible placings
that they cross (we discuss how this is achieved in of labels described in section 2.1.
section 2.7).
The arrow style kan be changed by writing the Exercise 3: Typeset the second axiom of category
command as \ar@style[hop]. This will be described theory as
in more detail in section 2.3; here we just list the most A
f
/B
common @styles (obvious variations also work): g;h
g
f ;g
 
@{=>} @{.>} @{:>} @{~>} @{-->} @{-} @{}
C /D
h

     (p.13)

1.5 Breaks
Exercise 2: Typeset
It is also possible to “break” an arrow with a label us-
• • ing the | character: $\xymatrix@1{A\ar[r]|f&B}$
will set A f / B .
If you just want an empty break you should
•o • use the special \hole break: the arrow A /B
was typeset by including $\xymatrix@1{
(p.13)
A\ar[r]|\hole & B }$ in the text.
A different use of breaks is to place a label some-
1.4 Labels where in a diagram outside the normal matrix mesh:
this is accomplished by “breaking” an invisible arrow
You can put labels on arrows. Labels are conceptual-
obtained using the @{} arrow style: the square
ized as sub- and superscripts on arrows such that they
are placed in the usual positions (as “limits”), i.e., ^ A /B
reads “above” and _ “below” on an arrow pointing
right. Notice that the positions depend only on the =
 
direction of the arrow, the absolute notions of “up,” B /C
“down,” etc. are not important. For example,
$\xymatrix@1{ was typeset by
X\ar[r]^a_b & Y & Z\ar[l]^A_B }$ \xymatrix{\ar @{} [dr] |{=}

3
 A \ar[d] \ar[r] & B \ar[d] \\ 1.7 Speeding up typesetting
B \ar[r] & C }
One thing that you will notice is that XY-pic is some-
There is more on breaks in section 2.7. times slow in typesetting diagrams (this is to be ex-
pected considering the number of drawing operations
Exercise 4: Typeset the first axiom of category performed as reflected by the number last in each
theory as the display xymatrix message). If you follow the rule of start-
ing all entries with a (nonexpandable) character or {
A
f
/B then you can insert the declaration
f iB g \CompileMatrices
 ~ 
B /C
g in the preamble of your document: this will create
temporary files4 containing compiled versions of each
(p.13) matrix that can be loaded very quickly; they are au-
tomatically recreated when a matrix is changed.
1.6 Curving If this causes some diagrams to not work, then
such compilation can be explicitly switched off by
Arrows can be made to curve, for example to avoid
using \xymatrixnocompile in place of \xymatrix.
going through another entry, using the special style
Compilation can be switched off completely with
@/curving/. The simplest styles of curving are the
\NoCompileMatrices (which respects TEX grouping
following, shown applied to an arrow from A to B:
as does \CompileMatrices, by the way).
) And if you are still not satisfied with the speed
@/^/ A B
then you can add the following:
@/_/ A 5B
\OnlyOutlines
@/_1pc/ A ?B
which will omit all compiled pictures; the additional
As the last example shows a dimension can be in-
command \ShowOutlines will add a dotted rectangle
serted just after ^ or _ if more or less curving is de-
outlining the size of the picture.
sired.
In case it is easier to specify the in- and out-going
directions of the curving then that is also possible: 2 More Arrows and Labels
use
In this section we explain a number of variations of
@(in,out) the arrow commands that are useful in commutative
diagrams.
where in and out are one of the following directions:
uO 2.1 Explicit label positioning
ul _ ?
ur
The label commands explained in section 1.4 place
lo /r the label text near the point along the arrow halfway
between the centers of the base and target entries.
  This, however, may be changed by inserting a place
dl  dr
d between the ^, _, or |, and the actual label (in fact -
is a place). In general you may insert the following:
In this case the curving is computed such that the
curve begins at the base entry in the in direction • < will place the label at the point where the
and ends at the target entry from the out direction actual arrow begins, i.e., “appears from under”
(this means that @(d1 ,d2 ) and @(d2 ,d1 ) are mirror the base, so $\xymatrix@1{A\ar[r]^<{+}&B}$
images. See section 2.6 for more directions). will typeset A
+
/B .

• Similarly, > will place the label at

Exercise 5: Typeset
the point where the actual arrow ends,
f , i.e., “disappears below” the target,
id 9xk f −1
f (x)
so $\xymatrix@1{A\ar[r]^>{+}&B}$ will
(p.13) typeset A
+
/B .
4 The temporary files are named the same as your document but .tex is replaced by -n.xyc where n is a sequence number.

4
 • << and >> will place the following la- where modifiers can be used to change the shape
bel at a point just a bit5 further from and size of the constructed object. The following are
the beginning and end of the arrow, the most common, the full list of possibilities can be
so $\xymatrix@1{A\ar[r]^>>{+}&B}$ will found in the reference manual [4, fig. 3]:
typeset A
+
/ B . Using more <s or >s will
move the label further in. + grow
+<dimen> grow by dimen
• A factor in ()s: (a) indicates that the
+= grow to enclosing square
label should be “tied” to the point a of
- shrink
the way from the center of the base en-
-<dimen> shrink by dimen
try (called (0)) to the center of the tar-
-= shrink to contained square
get (called (1)) instead of in the middle,
! do not center
so $\xymatrix@1{A\ar[r]^(.3){+}&B}$ will
[o] round
typeset A
+
/B . [l] [r] [u] [d] adjust left, right,. . .
[F] [F=] frame double
• A factor can be given after some < or
>s, in which case the place is computed [F.] [F--] dotted dashed
as if the base was specified by the <s [F-,] [F-:<3pt>] shaded rounded
and target specified by the >s. Hence
$\xymatrix@1{A\ar[r]^<(0){+}&B}$ will
+
/B . Since objects specified this way start with no mar-
typeset A
gin, a single + is usually included to get the default
• Finally, there is a simple way to denote the spacing.
place on an arrow where it intersects with a
straight line between two points: the place x
!{t1 ;t2 } places the label relative to the point Exercise 7: Typeset A /B . (p.13)
on the arrow where the line from the target t1
to the target t2 crosses it. Bug: Only works There can only be one boxing. This can be any
for straight arrows at present. box generation command. The following are the most
As usual more possibilities can be found in the refer- useful boxing{text} combinations:
ence manual [4, fig. 2].
@variant{tip} tip (or shaft) object
Exercise 6: Typeset \txt{. . . } ordinary text
\composite{. . . *. . . } combined objects
1
1000000x / 1000000
4 \frm{} repeat last object
2000x x 2

#
1000 / 2000 (the possibilities for variant and tip are given in the
2x following section). Finally, \hbox{. . . }6 is a quick
way to ensure text-mode interpretation of a single ob-
(p.13)
ject. However, \txt allows the use of \\ in text to cre-
ate a line break, and the special form \txt<6pc>{. . . }
2.2 Labeling with any object will constrain the text to a centered 6pc wide column.
XY-pic supports a general format for entering any TEX By the way, \txt can be used outside of XY-pic con-
text as labels (as well as entries to be explained later). structions.
The character * is reserved for this: in its simplest Finally, several objects can be combined using the
form *{math} will typeset the math material as an last form; the *s serve to separate the composed ob-
object. This is like {math} except that the default ject.
style is ignored and there is no added blank margin.
However, in general the following form of *object
is available: High
*modifiers{text} label
Exercise 8: Typeset A +
×+×+×+×+ ×B .
×+ (p.13)
5 “A bit” is in fact a TEX \jot which is usually 3pt.
6 The plain TEX command \hbox corresponds to \mbox in LATEX and \text in the AMS variants.

5
2.3 More arrow styles Here are some arrows where this is required:
The arrow styles described in section 1.3 are all ex-  /B
@{^{(}->} A
amples of the general arrow style constructions
@{|-_{>}} A /B
@variant{tail shaft head }
@variant{head } Notice that there is no distinction between shafts and
tips using this form, thus it is necessary to include all
that in describes arrows with the indicated tail, shaft, three of tail, shaft, and head, when using it. The ad-
and head (on the first form the tail and head can be vantage is that it is possible then to “fill with a tip.”
omitted; the second style defaults to having no tail Furthermore, the following additional possibilities are
and a standard shaft). available when using this notation:
The following possibilities exist for head and tail
which we will denote tips (here shown as heads): '
{|-} ^{|-} ' _{|-} ''
s 3 L {|=}
%
3{|-}

< > x •
ss 33 ' {*} ^{‘} _{‘}
<< >> + E e
's '3 ' ^{’} _{’}
|< 's s >| |
|<< >>| 3 '3 ||
''
( % ) Ee o ◦

/  //  The even more general form *object can be used,

where object refers to any of the constructions de-
and the shaft should be one of the following: scribed in section 2.2.

- -- v )
Exercise 9: Typeset A •0 6 ?HN• B . (p.13)
4t 4t
~ ~~ 4t

. 2.4 Sliding arrows sideways

The variant should be empty or one of the follow- It is often desirable to have several parallel arrows
ing: between two objects. This can be done by sliding ei-
ther or both arrows sideways a distance given as a
^ “above” variant TEX dimension enclosed in @<>s: it specifies how far
_ “below” variant “sideways” the arrow should be moved, e.g.,
2 “double” variant \xymatrix{
3 “triple” variant A \ar@<1ex>[dr]^a_{.} \\
& B \ar@<1ex>[ul]^b \ar@<1ex>[r]^c
Here are some standard arrows in this notation, all & C \ar@<1ex>[l]^d_{.} }
from A to B as usual:
will typeset
@{<->} Ao /B
A
@^{<->} Ao /B _ a
@_{<->} Ao /B .

b c /
@2{<->} A ks +3 B Bo . C
@3{<->} A jt *4 B d

As a special convenience = and : are provided as ab- A positive distance will slide the arrow in the “^-
breviations for - and . with variant forced to 2. direction,” e.g., the two arrows above are slid in the
As it can be seen, the variant will affect the entire direction of the labels a, b, c, and d, respectively;
arrow. Sometimes this is not what is wanted. In that a negative distance in the “_-direction.” The dis-
case a local variant can be used by entering any of tance <@1ex> is often appropriate since it corresponds
the tail, shaft, and head, on the following form: roughly to the height of letters like “x,” in the type
size being used.
variant{tip}
variant{shaft} ''
Exercise 10: Typeset A B . (p.13)

6
2.5 More targets • <Dx ,Dy > , where Dx , Dy are TEX dimensions,
is the vector with those coordinates, and
The target address can be given in a large number
of formats called positions. The full range of possi-
• /d dimen/ is the vector going dimen in the par-
bilities is described in the reference manual [4, fig. 1];
ticular direction d which can be either the eight
here is a number of useful ones in addition to the hop
simple ones in section 1.6, empty to denote that
format described in section 1.3:
the current direction (the last direction of an
• [r,c], where r, c are integers, denotes the rela- arrow) should be used, or one of the following:
tive entry found r rows below and c columns to
the right of the current entry (the current entry va(α) absolute angle
itself is thus [0,0]). This always corresponds d:a(α) relative angle in degrees
to a [hop], e.g., [1,2] is the same as [drr] d:(x,y) relative vector
and [-2,0] is the same as [uu]. d^ / d_ short for :a(90) / :a(-90)
• "r,c", where r, c are positive integers, denotes
the absolute entry found in the rth row and cth where the d in the last four may be empty to
column of the diagram. The top left entry is denote the “current direction.”
"1,1".
• The “corner offsets” of a target are vectors as
• t0 ;t , where t0 is any target, changes the base shown:
entry of the present arrow to t0 and then sets U
the target to t relative to the original base en- UL f O 8 UR
try. For example,
L o / R
\xymatrix{ A \\
x  &
B & C \ar@<1ex>[ul] DL DR
\ar@<1ex>[ul];[] } D
(they must be specified in upper case),
typesets
A
_ Many, many more possibilities are described in the
reference manual [4].

B C
i.e., the second \ar[ul] arrow starts at the Exercise 11: What is the difference between a tar-
[ul] entry and ends in the current entry. get t and the target t+0? (p.13)

See section 3.5 for how to use a label as a target.

2.7 Arrows passing under
2.6 Changing the target Arrows can pass under (or via) any other entry: Just
It is possible to overwrite a target with another by insert ’t, i.e., a quote (apostrophe) character followed
appending something of the form *object to it. This by a target, for each entry that should be visited ex-
has the effect of typesetting the object at the current cept the last, “ordinary & final” entry:
position, thus effectively on top of the target, and \xymatrix{
then use what was typeset as the target. {\circ}
A target may also have its position changed by \ar@{|-->} ’[dr] ^a
one of the following constructions: ’[rr]+D*{\bullet} ^b
• +vector or -vector which changes the target to [drrr] ^c
be a zero-sized one at the position obtained by & {\circ} & {\circ} & {\circ} \\
adding or subtracting the vector to its center, {\circ} & {\circ} & {\circ} & {\circ} }
or typesets
• !vector which moves the center of the target by ◦ ◦ ◦ ◦
•
the vector ; a b c
"
where a vector should have one of the following forms: ◦ ◦ ◦ ◦

• 0 is the zero vector, As you see, labels are set separately on each segment.

7
Exercise 12: Typeset the “lambda cube” • If the segment can not be made as short as re-
quired then it will point “past” the target. This
λω λC is useful for “going around” entries.
• There is one ‘ per turn thus each target ap-
λ2 λP 2
pears as many times as there are turns towards
it, except the last target that appears one more
λω λP ω
time namely both with ‘ for each turn towards
it and once as an “ordinary” target to set the
λ→ λP
final stretch.
Hint: “going under” an empty entry leaves a small • The sizes of the intermediate targets are ig-
gap at that location. The compactness is achieved nored.
using a trick described in section 3.3. (p.13)

Exercise 13: Typeset A OO

B . (p.14)
2.8 More bending arrows
Finally, arrows can bend around entries: just insert 2.9 Defining new arrow types
‘d t, i.e., a backquote and a direction d followed by
a target t, for each “turn” that starts out in the d- Last in this treatment of arrows we will explain how
direction and ends in a quarter turn towards the tar- new arrows can be defined. The crucial fact is that
get t. This is different from the curving described the characters used for tips and shafts are restricted
earlier in that all turns consist of a straight part end- to the following:
ing in a turn which is a multiple of 1/8 circle segments,
><|ox+/()[] tip characters
and each segment allows separate labels.
-.~:= shaft characters
The possible directions are those of section 1.6
and 2.6, and the possible targets include all those When an arrow is interpreted by XY-pic it is first split
discussed above. Actually the direction is only re- into the three components and then each component
quired for the first in a series of turns since the final is looked up in a library of so-called “directionals.”
direction of one turn is the obvious choice for the fol- It is possible to add new such directionals using the
lowing turn. Furthermore, turns can be changed from command
the default by adding either ^d for anticlockwise turn
\newdir{ directional }{ composite }
to d or _d for clockwise turn to d, where d is the “exit
direction” of the turn. where directional should be a sequence either of
Finally, the turns will have radius 10pt by default, tip characters or of shaft characters, and composite
but this can be changed to any dimension R from a should be a list of objects separated with * just like
particular turn and onwards by inserting /R imme- the argument to \composite described in section 2.2.
diately after the ‘ of the turn. Here is an example If arrows of a particular variant (always one of the let-
involving all of these features: ters ^_23) needs an alternate definition then another
\xymatrix{ declaration can be given with the variant inserted be-
{\circ} \ar ‘r[d] ^a tween \newdir and the first {.
‘[rr] ^b There is one object modifier which is very useful
‘/4pt[rr] ^c in this context, in addition to those of section 2.2:
‘[rrr] ^d !vector shift object vector
‘_dl[drrr]^e
[drrr]^f (where the possibilities for vector are described in
& {\circ} & {\circ} & {\circ} \\ section 2.6). Combined with the direction code this
{\circ} & {\circ} & {\circ} & {\circ} } is very powerful, for example,
typesets \newdir{|>}{%
!/4.5pt/@{|}*:(1,-.2)@^{>}*:(1,+.2)@_{>}}
a e
◦ ◦ ◦ ◦ defines a new tip that makes
b d
c \xymatrix{ A \ar @{=|>} [r] & B }
 f  ,2 B . Notice how the “relative di-
◦ ◦ ◦ ◦ typeset A
rection” is used here to rotate some of the composed
The example illustrates the following points: components.

8
Exercise 14: Often tips used as “tails” have their *\txt{A very long and stupid\\program}
ink on the wrong side of the point where they are \ar[rr]^-{\txt{weird\\arrow}}
placed. Fortunately space ( ) is also a tip charac- &&*\txt<2pc>{Com\-pli\-cated\\Code}}
ter so we can define the directional > to generate a
will typeset
“tail-spaced” arrow. Do this such that
\xymatrix{ A \ar @{>->} @< 2pt> [r] weird Com-
\ar @{ >->} @<-2pt> [r] & B } A very long and stupid arrow / pli-
program cated
typesets
A// // B Code

(p.14)
Finally, when XY-pic diagrams are used in con- Exercise 16: Typeset
junction with Knuth’s computer modern fonts then
the declaration •
2 3
1
\SelectTips {cm}{} '
! x
 x
will change the tips to some that look similar, e.g., x x
x
x
$\SelectTips{cm}{}
\xymatrix@1{A\ar@{->>|}[r]&B}$ (p.14)
typesets A / / B . The second argument (here {})
can be used to specify a point size {10}, {11}, or 3.2 Extra entries outside the matrix
{12}, if desired (the default is {10}7 ); {cm} can be
replaced by {eu}, {lu}, and {xy}, to get tips in “Eu- It is possible to put extra entries in your diagrams
ler,” “Lucida,” and the default technical style, re- that are not part of any “entry” of the matrix cre-
spectively. The declaration respects TEX grouping. ated by & and \\. This is done with the excursion
command
Exercise 15: Typeset A / / / B . Hint: With the
construction \object object one can typeset an XY-pic \save t \restore
object (anything that could follow a * in section 2.2)
in any context. (p.14) where t should be a target in one of the formats de-
scribed in sections 2.5–2.6. t can do any kind of type-
setting desired, for example,
3 More Entries \xymatrix{
This section explains what can go in an entry and A \ar@{-}[dr]
how the general form of the entries is changed. &{}\save[]+<3cm,0cm>*\txt<8pc>{%
This is a very big commentary
but it does not otherwise affect
3.1 Manual entry formatting the diagram.}
All the entries we have seen thus far have been simple \ar[l] \ar[d] \restore \\
math objects. However, it is possible to change the & B \ar@{-}[r] & C \ar@{-}[r] & D
format of an individual entry by using the form: }
will typeset
*object arrows
This is a very big
commentary but it
This allows complete control over what object is Ao
placed in the entry, overriding any spacing and other does not otherwise
conventions for the entry. This was how the frame affect the diagram.
was obtained in the figure in section 1.2. v
B C D
A simple use of this is to insert text in entries us-
ing \txt objects just like labels as described above in It illustrates how a “down” arrow does not necessar-
section 2.2: ily have to point particularly straight down – in this
\xymatrix{ case because it is based in the displaced pseudo entry.
7 Except when XY-pic is loaded as a LATEX 2ε package where the default size is used.

9
3.3 Spacing and rotation \def\objectstyle{\scriptstyle}
\def\labelstyle{\scriptstyle}
The *object form described above can be used to
\vcenter{\xymatrix @-1.2pc @ur {
space individual objects differently, however, it is also
A \ar[r]^{a} & B \ar[d]^{b} \\
possible to change the overall spacing of a matrix by
A’\ar[u]^{a’} & B’\ar[l]^{b’} }}
inserting the following codes between \xymatrix and
\right)$
the following {:  
a ?
B
b
  
@=dimen set spacing in a paragraph will typeset “
A_ B0 .”

@R=dimen set row spacing 
a0 A0 b0
@C=dimen set column spacing
@M=dimen set entry default margin You can even abandon the use of math mode en-
@W=dimen set entry default width tirely: the command \def \objectstyle {\hbox}
@H=dimen set entry default height will change the format of entries to plain text.
@L=dimen set label margin Similarly, all entries are rectangular by default,
but it is possible to change this to round by declaring
= can be replaced by any of +, +=, -, and -= of sec- the default modifiers to be applied to all entries that
tion 2.2 with the same meaning, i.e., replace “set” do not override them (cf. section 2.2):
with “increase,” “increase to at most,” “decrease,” \entrymodifiers={++[o][F-]}
and “decrease to at least,” respectively. For exam- \SelectTips{cm}{}
ple, $\xymatrix@1@=0pt@M=0pt{A&B\\C&D}$ in the \xymatrix @-1pc {
text typesetsAB . *\txt{start} \ar[r]
CD
In case uniform spacing is desired, several alter- & 0 \ar@(r,u)[]^b \ar[r]_a
native forms exist. & 1 \ar[r]^b \ar@(r,d)[]_a
& 2 \ar[r]^b
@! force all spaces equal \ar ‘dr_l[l] ‘_ur[l] _(.2)a [l]
@!0 — and ignore entry sizes &*++[o][F=]{3}
@!R force equal row spacing \ar ‘ur^l[lll]‘^dr[lll]^b [lll]
@!C force equal column spacing \ar ‘dr_l[ll] ‘_ur[ll] [ll] }

Finally a special notation allows rotation of an entire will typeset

matrix: b

b
start / 0 / 1 b / 2 b / 3
@ d rotate towards d a ? T a
a
Only the matrix grid will rotate, however, not the
actual contents. Notice how we obtain the double ring using the
*object form which then has to include all the desired
Exercise 17: Typeset the “strip lemma” modifiers (and how the use of computer modern tips
is nice for diagrams as these).
a
 3.5 Naming for later use as targets
 a0
b If you build an entry with a long and complicated
  excursion then you might wish to be able to refer to
b0 it later. XY-pic provides a mechanism for this: there
(p.14) is a special target form which we haven’t discussed
yet:

3.4 Entry style t ="name"

As mentioned above, the entries of a diagram are set This will introduce the new target "name" which will
in math mode in text style. You may change this refer to the target just before the =. This is particu-
by redefinining the macro \objectstyle, and the la- larly useful inside excursions, of course, and can also
bel style by redefining \labelstyle. We can combine be used after labels.
this with the above to get “small diagrams,” e.g., typ-
(
ing Exercise 18: Typeset A
a /B b /C.
$\left( (p.14)

10
3.6 Grouping objects 4 Availability and Further In-
Sometimes you wish to frame or otherwise treat a formation
rectangle of objects as a single object. This is pos-
sible with the last two target position forms that we Below we describe how to and the conditions for ob-
will mention: taining XY-pic version 3.8.4, the compatibility with
previous versions, and we conclude with a few ap-
t.s merge t with simple s petisers to lure the reader into reading more about
{t} make t simple XY-pic.

The first will enlarge t to also “cover” the “simple”

s (simple means that it cannot have changes etc. at-
4.1 Getting XY-pic
tached unless encapsulated in {}s). Here is an exam- The easiest way to retrieve XY-pic is to get it from
ple where we merge and frame: CTAN8 or the “pictures” collection of TEX Live.9
\xymatrix @R=1pc { The latest version of XY-pic can furthermore be ob-
1,1 & 1,2 & 1,3 & 1,4 & 1,5 \\ tained from the XY-pic home page.10
2,1 & 2,2 & 2,3 & 2,4 & 2,5
\save "1,2"."2,4"*[F.]\frm{} License: XY-pic is free software in the sense that it
\ar"1,1" \ar"2,1" \ar"1,5" \ar"2,5" is available under the following license conditions:
\restore }
XY-pic: Graphs and Diagrams with TEX
will typeset
c 1991–2010 Kristoffer H. Rose
1, 1 o 1, 2 1, 3 1, 4 / 1, 5
c 1994–2010 Ross Moore

y , 2, 5
The XY-pic package is free software; you can redis-
2, 1 2, 2 2, 3 2, 4 tribute it and/or modify it under the terms of the
GNU General Public License as published by the Free
As you can see, the center of the merged object is the Software Foundation; either version 2 of the License,
same as the one of the target before the “..” or (at your option) any later version.
Finally a more advanced example where we create The XY-pic package is distributed in the hope that
two merged objects with center in their “real” center, it will be useful, but without any warranty; without
name them and then connect to them. It also shows even the implied warranty of merchantability or fit-
how macros can be used inside diagrams: they should ness for a particular purpose. See the GNU General
always expand to “commands” like \ar. . . , etc.: Public License for more details.
/B /2 B 0 You should have received a copy of the GNU Gen-
AO AO 0 eral Public License along with this package; if not, see
2 http://www.gnu.org/licenses/.
 
In practice this means that you are free to use
Co D C0 o D0
XY-pic for your documents but if you distribute any
can be typeset by part of XY-pic (including modified versions) to some-
one then you are obliged to ensure that the full source
\def\g#1{\save
text of XY-pic is available to them (the full text of the
[].[dr]!C="g#1"*[F]\frm{}\restore}%
license in the file COPYING explains this in somewhat
\xymatrix{
more detail ^¨ ).
\g1 A\ar[r]&B\ar[d]&\g2 A’\ar[r]&B’\ar[d]\\
C\ar[u]&D\ar[l]& C’\ar[u]&D’\ar[l]
\ar @{.>} "g1" ;"1,4" 4.2 Backwards compatibility
\ar @{-->} "2,1";"g2" }
The first widely distributed version of XY-pic was ver-
Then we can make arrows from/to the two frames by sion 2 (from release 1.40 to release 2.6). A special
using the two new targets "g1" and "g2" as shown. compatibility mode is used automatically if the old
style of loading is used (using files named xypic.tex
Exercise 19: Change the lambda cube of exer- and xypic.sty). You can also mix old and new di-
cise 12 such it is enclosed in a transparent (i.e., dot- agrams in a document if you load as described in
ted) cube. (p.14) section 1.1 and add the declaration \xyoption{v2}.
8 http://ctan.org/tex-archive/macros/generic/diagrams/xypic
9 http://www.tug.org/texlive/, included with most modern systems such as Ubuntu GNU/Linux.
10 http://xy-pic.sourceforge.net.

11
This provides almost full backwards compatibility: • The “2cell” feature provides special support for
the following are the only known exceptions: categorical twocells like
• Automatic “shortening” of arrow tails by |<< ζ
break was a bug and has been “fixed” so it does 1B (
 γ 6C
not work any more. Fix : Put a |<\hole break α (
before it as described in section 2.3. !) ξ
v~
• The release 2.6 * position operator is not avail- 
able. Fix : Use the : and :: operators (de- A 8D

scribed in detail in the reference manual [4]).
• Using t1 ;t2 :(x,y) as the target of an arrow
command does not work. Fix : Enclose it in • The “poly” feature allows polygon-like struc-
braces, i.e., write {t1 ;t2 :(x,y)}. tures:
• The old \pit, \apit, and \bpit commands are
not defined. Fix : Use *@{>} (or \tip) with
variants and rotation.
• The even older notation where an argument in
braces to \rto and the others was automati-
cally taken to be a “tail” is not supported. Fix : • The “web” feature allows composition in lat-
Use the supported |<. . . notation. tices such as
Finally note that sometimes the spacing with ver- σ (2)O .
sion 3.8.4 is “improved” relative to earlier ver- . .
. • .
sions
^¨ . Please report all other things that do not . .
.
. . .
work the same in version 3.8.4 and an earlier version . . .
. . .
to the author. . .
. • . .
. • • / (1)
4.3 Further reading . . • .σ
. • . .
. .
. . . .
The reference manual [4] describes several more in- .
. .
put modes that are useful when the diagram is not . • . .
organised as a matrix. We’ll give some examples of
such diagrams but refer to the reference manual for • The “arc” feature is suitable for effects like
the details.
p
• The “graph” feature allows input of data struc- •
tured as directed graphs to make it easy to pro-
duce such pictures as
•
w c

 x1
s
O z  O
+
 x2
? In each case the figure is produced with relatively few
y
lines using techniques documented in the respective
• The “knot” feature allows drawing of mathe- sections of the reference manual together with the de-
matical knots and links like tails of the XY-pic kernel and extensions, “arrow,” and
“matrix” features as used in this guide; further exten-
 sions provide support for use of colour, PostScript
2 effects, and much more.
For further documentation, the XY-pic home
J 
M page11 links to a number of tutorials on XY-pic with
g focus on different things (and in different languages).
Finally, we maintain a collection of examples in
simple link figure-8 knot cinquefoil the xysamples directory on CTAN.12
11 http://xy-pic.sourceforge.net.
12 http://ctan.org/tex-archive/macros/generic/diagrams/xypic/xysamples/.

12
4.4 Credits && 1000000 \\
1000 \ar[r] _{2x}
XY-pic version 2 was a small package created by the
\ar[urr] _>>>>{x^2}
author. Version 3 is been the result of more than
& 2000 }
ten years of active collaboration with Ross Moore.13
Most recently, version 3.8 was released to permit in- In particular notice how the break was specified to
clusion of Daniel Müllner’s14 impressive xypdf back- happen exactly where the two arrows cross. For an
end, which permits high quality graphics also when easier but not so general method see exercise 12 last
generating PDF files. The release furthermore in- in section 2.7.
cludes fonts by Y&Y Inc. and Jeremy Gibbons, as
well as macros by George Necula. Answer to exercise 7 (p.5): The author typed
\xymatrix@1{ A \ar[r]^*+[o][F-]{x} & B }
A Answers to all exercises
Answer to exercise 8 (p.5): The author did
Answer to exercise 1 (p.3): The target [] is the
current entry itself. \xymatrix@1{
A \ar @{/*\composite{{+}*{\times}}/} [rr]
^*+\txt{High\\label}
Answer to exercise 2 (p.3): The author did
&& B}
\xymatrix{
{\bullet} \ar@{--}[d]\ar@{=}[dr]\ar@{-}[r]
& {\bullet} \ar@{.}[d] \\ Answer to exercise 9 (p.6): The author entered
{\bullet} & {\bullet} \ar[l] } \xymatrix{
Notice how • has been enclosed in {} since it is an A \ar @/^/ @{^{<}-_{>}} [r]
“expandable” entity, i.e., a defined macro: this is rec- \ar @/_/ @{{*}{x}{*}} [r] & B }
ommended.
Answer to exercise 10 (p.6): The author typed
Answer to exercise 3 (p.3): The author used
\xymatrix@1{
\xymatrix{ A \ar@/^/[r] \ar@/^/@<-1ex>[r] & B }
A \ar[r]^f \ar[dr]_{f;g}
& B \ar[d]^g \ar[dr]^{g;h} \\
& C \ar[r]_h & D } Answer to exercise 11 (p.7): The size: t+0 al-
ways has zero size.

Answer to exercise 4 (p.4): The author entered

Answer to exercise 12 (p.7): The author con-
\xymatrix{ structed
A \ar[d]_f \ar[r]^f
\xymatrix@!0{
& B \ar[dl]|{i_B} \ar[d]^g \\
& \lambda\omega \ar@{-}[rr]\ar@{-}’[d][dd]
B \ar[r]_g & C }
& & \lambda C \ar@{-}[dd]
\\
Answer to exercise 5 (p.4): The author did \lambda2 \ar@{-}[ur]\ar@{-}[rr]\ar@{-}[dd]
& & \lambda P2 \ar@{-}[ur]\ar@{-}[dd]
\xymatrix{
\\
x \ar@(ul,dl)[]|{id} \ar@/^/[rr]|f
& \lambda\underline\omega \ar@{-}’[r][rr]
&& f(x) \ar@/^/[ll]|{f^{-1}} }
& & \lambda P\underline\omega
Note that both arrows are curved “above” relative to \\
their direction. \lambda{\to} \ar@{-}[rr]\ar@{-}[ur]
& & \lambda P \ar@{-}[ur]
Answer to exercise 6 (p.5): The author used the }
display A special thing is added: @! forces rows and
\xymatrix{ columns to be equally spaced as discussed in sec-
1 \ar[rr] ^-{1000000x} tion 3.3; @!0 furthermore makes the spacing ignore
\ar[dr] _(.2){2000x} |!{[d];[rr]}\hole the entry sizes, giving a completely fixed grid. The
13 Mathematics Department, Macquarie University, Sydney, Australia 2109; e-mail: ross.moore@mq.edu.au.
14 http://www.math.uni-bonn.de/people/muellner/

13
gaps could also be made with the !. . . crossing nota- \ar@{.} +UL;"back"+UL \ar@{.} +UR;"back"+UR
tion of exercise 6 last in section 2.1 but the above is \ar@{.} +DL;"back"+DL \ar@{.} +DR;"back"+DR
shorter. \restore
in the entry with λ2 to produce
Answer to exercise 13 (p.8): The author typed
λω λC
\xymatrix@1{
A \ar@<-2pt> ‘d[r] ‘[r] [r]
λ2 λP 2
\ar@<+2pt> ‘d[r] ‘[r] [r] & B }
λω λP ω
Answer to exercise 14 (p.8): The author used
λ→ λP
\newdir{ >}{{}*!/-5pt/@{>}}

Answer to exercise 15 (p.9): The author typed References

\xymatrix@1{
A \ar[r] |-{\SelectTips{cm}{}\object@{>>}} [1] Adobe Systems Incorporated. PostScript Lan-
|>{\SelectTips{eu}{}\object@{>}} guage Reference Manual, second edition, 1990.
& B } [2] Donald E. Knuth. The TEXbook. Addison-Wesley,
1984.
Answer to exercise 16 (p.9): The author typed [3] Leslie Lamport. LATEX—A Document Preparation
\xymatrix{ System. Addison-Wesley, 2nd edition, 1994.
*=0{\bullet}
\ar@/^/[dr]!U|1 [4] Kristoffer H. Rose and Ross R. Moore. XY-pic Ref-
\ar@/^/[drr]!U|2 erence Manual. DIKU, University of Copenhagen,
\ar@/^/[drrr]!U|3 Universitetsparken 1, DK–2100 København Ø,
\\ 3.0 edition, June 1995. Latest version is available
&*+[F]\txt{x} from http://xy-pic.sourceforge.net/.
&*+[F]\txt{x\\x} [5] Michael D. Spivak. The Joy of TEX—A Gourmet
&*+[F]\txt{x\\x\\x} Guide to Typesetting with the AMS-TEX Macro
} Package. American Mathematical Society, second
edition, 1990.
Answer to exercise 17 (p.10): The author en-
tered the display
\xymatrix@dr@C=1pc{
a \ar[r]\ar@{->>}[d] & a’ \ar@{.>>}[d] \\
b \ar@{.>>}[r] & b’ }

Answer to exercise 18 (p.10): The author typed

\xymatrix{
A \ar[r] ^a="a" & B \ar[r] ^b="b" & C
\ar @/^/ "a";"b" }
Notice the use of both explicit base and target in the
arrow between the labels.

Answer to exercise 19 (p.11): The author added

the XY-code
\save [].[dd].[ddrr].[rr]*[F.]\frm{}="back"
\restore
in the entry with λω, and
\save [].[dd].[ddrr].[rr]*[F.]\frm{}

14
Index
!, 5, 7, 8 [u], 5 coordinates, 3
!{;}, 5 \\, 2, 5 COPYING, 11
&, 2 ^, 3, 4, 6–8 copyright, 11
’, 7 ^{’}, 6 cover, 11
(, 6 ^{‘}, 6 crossing arrows, 5, 8
(), 5 ^{|-}, 6 cube, 8
(0), 5 _, 3, 4, 6–8 current direction, 7
(1), 5 _{’}, 6 current entry, 7
), 6 _{‘}, 6 curve, 4, 8
*, 5, 7–9, 12 _{|-}, 6 d, 3
+, 5–7, 10 ‘, 8 dashed arrow, 6
+=, 5, 10 {*}, 6 dashed frame, 5
-, 3, 5–7, 10 {|-}, 6 default modifier, 10
--, 6 {|=}, 6 default spacing, 5
-=, 5, 10 |, 3, 4, 6 defining arrows, 8
., 6 |<, 6 degrees, 7
/, 6–8 |<<, 6, 12 directed graphs, 12
//, 6 ||, 6 direction, 4, 7, 8
:(), 7 ~, 6 directionals, 8
:a(), 7 ~~, 6 dotted arrow, 6
;, 7 2cell, 12 dotted frame, 5
<, 4, 6 3{|-}, 6 double arrow, 6
<<, 5, 6
0, 7 double frame, 5
=, 10
>, 4, 6 absolute angle, 7 elliptical, 10
>>, 5, 6 absolute entry, 7 entries outside matrix, 9
>>|, 6 adjust, 5 entries with text, 9
>|, 6 adjusting position, 7 entry, 2, 9
@, 3, 5, 6, 10 \apit , 12 entry format, 9
@!, 10 \ar , 3, 4 entry outside matrix, 3
@(, 4 arc, 12 entry style, 10
@/^/, 4 arrow, 3, 4 excursion, 9
@/_/, 4 arrow head, 6 explicit positioning, 4
@1, 3 arrow passing under, 7 extra entries, 9
@<>, 6 arrow shaft, 6 format, 9
@=, 10 arrow style, 3, 6 frame, 5
@C=, 10 arrow tail, 6 free software, 11
@H=, 10 \frm , 5
base entry, 3, 7
@L=, 10
bend, 8 GNU General Public License, 11
@M=, 10
\bpit , 12 going around, 8
@R=, 10
break, 3 graph, 12
@W=, 10
centered, 5 grouping, 11
@{}, 3
changing position, 7 grow, 5
[F-,], 5
[F--], 5 changing turn radius, 8 half arrow, 6
[F-:<3pt>], 5 circle segments, 8 \hbox , 5
[F.], 5 circular, 10 head, 6
[F=], 5 columns, 2, 7 \hole , 3
[F], 5 combined objects, 5, 8 hop, 3, 7
[], 3, 7 commutative diagrams, 1, 4 intersects, 5
[d], 5 compatibility, 11 invisible arrow, 3
[l], 5 \CompileMatrices , 4
[o], 5 \composite , 5, 8 \jot , 5
[r], 5 computer modern fonts, 9 knot, 12

15
l, 3 quarter turn, 8 text, 5
label, 3, 4, 8 r, 3 text in entries, 9
label centered on arrow, 3 radius, 8 text label, 5
label style, 10 relative angle, 7 text style, 2
label with any object, 5 relative entry, 7 tip, 5, 8
labels as targets, 10 tip characters, 8
relative vector, 7
labels with text, 9 tip in shaft, 6
repeat last object, 5
\labelstyle , 10 triple arrow, 6
retrieving XY-pic, 11
license, 11 turn, 8
rotation, 8, 10
line break, 5 twocells, 12
round, 10
links, 12 \txt , 5, 9
round shape, 5
merge, 11 rounded frame, 5 u, 3
moving target, 7 rows, 2, 7 uniform spacing, 10
name, 11 segment, 7 \usepackage , 2
new arrows, 8 \SelectTips {cm}{}, 9 v2, 2
\newdir , 8 shaded frame, 5 va(), 7
\NoCompileMatrices , 4 shaft, 5, 6, 8 variant, 6, 8
o, 6 shaft as tip, 6 vector, 7
object, 5 shaft characters, 8 vector coordinates, 7
\object , 9 shape, 5
vector in direction, 7
object modifier, 5, 8, 10 \ShowOutlines , 4
vector to corner, 7
\objectstyle , 10 shrink, 5
version 2, 11
old style of loading, 11 sideways, 6
\OnlyOutlines , 4 size, 5 warranty, 11
overwrite, 7 sliding, 6 web, 12
spacing, 10 x, 6
parallel, 6
\pit , 12 square, 5 \xymatrix , 2
plain text entries, 10 squiggly arrow, 6 \xymatrixnocompile , 4
poly, 12 tail, 6 \xyoption , 2, 11
polygon-like, 12 target, 7, 10 xypic.sty, 11
position, 7 target entry, 3 xypic.tex, 11

16