Debian Codegraph @

texmf-dist/doc/latex/tqft/tqft.tex

raw
1 \documentclass{ltxdoc}
2 \usepackage[T1]{fontenc}
3 \usepackage{lmodern}
4 \usepackage{morefloats}
5 \usepackage[svgnames]{xcolor}
6 \usepackage{tikz}
7 \usepackage{tqft}
8 \usetikzlibrary{tqft}
9 \usepackage[numbered]{hypdoc}
10 \definecolor{lstbgcolor}{rgb}{0.9,0.9,0.9}
11
12 \usepackage{listings}
13 \lstloadlanguages{[LaTeX]TeX}
14 \lstset{breakatwhitespace=true,breaklines=true,language=TeX}
15
16 \usepackage{fancyvrb}
17
18 \newenvironment{example}
19 {\VerbatimEnvironment
20 \begin{VerbatimOut}{example.out}}
21 {\end{VerbatimOut}
22 \begin{center}
23 \setlength{\parindent}{0pt}
24 \fbox{\begin{minipage}{.9\linewidth}
25 \lstset{breakatwhitespace=true,breaklines=true,language=TeX,basicstyle=\small}
26 \lstinputlisting[]{example.out}
27 \end{minipage}}
28
29 \fbox{\begin{minipage}{.9\linewidth}
30 \centering
31 \input{example.out}
32 \end{minipage}}
33 \end{center}
34 }
35
36 \providecommand*{\url}{\texttt}
37 \GetFileInfo{tikzlibrarytqft.code.tex}
38 \pdfstringdefDisableCommands{%
39 \def\\{}%
40 \def\url#1{<#1>}%
41 }
42
43
44 \title{The \textsf{tqft} Ti\emph{k}Z Library: Documentation}
45 \author{Andrew Stacey \\ \url{[email protected]}}
46 \date{\fileversion~from \filedate}
47
48 \begin{document}
49
50 \maketitle
51
52 \begin{center}
53 \begin{tikzpicture}[
54 scale=.5,
55 every tqft/.style={
56 transform shape
57 },
58 tqft/cobordism/.style={
59 fill=DarkMagenta,
60 draw,
61 ultra thick},
62 ]
63 \pic[
64 name=a,
65 tqft,
66 incoming boundary components=0,
67 outgoing boundary components=3,
68 ];
69 \pic[
70 name=b,
71 at=(a-outgoing boundary 2),
72 tqft cylinder,
73 anchor=incoming boundary 1,
74 ];
75 \pic[
76 at=(a-outgoing boundary 3),
77 name=c,
78 tqft,
79 incoming boundary components=0,
80 outgoing boundary components=2,
81 anchor={(0,1)},
82 ];
83 \pic[
84 at=(c-outgoing boundary 1),
85 name=d,
86 tqft,
87 incoming boundary components=3,
88 outgoing boundary components=1,
89 offset=2.5,
90 anchor=incoming boundary 1,
91 boundary separation=1cm,
92 cobordism height=2.5cm,
93 ];
94 \pic[
95 at=(c-outgoing boundary 2),
96 name=e,
97 tqft,
98 rotate=90,
99 incoming boundary components=0,
100 outgoing boundary components=3,
101 anchor={(2,-.5)}
102 ];
103 \pic[
104 at=(e-outgoing boundary 3),
105 name=f,
106 tqft cylinder,
107 rotate=90,
108 anchor=incoming boundary 1,
109 ];
110 \pic[
111 at=(e-outgoing boundary 2),
112 name=g,
113 tqft cylinder,
114 rotate=90,
115 anchor=incoming boundary 1,
116 ];
117 \pic[
118 at=(g-outgoing boundary 1),
119 name=h,
120 tqft,
121 anchor={(0,1)},
122 incoming boundary components=0,
123 outgoing boundary components=3,
124 ];
125 \pic[
126 at=(h-outgoing boundary 2),
127 name=i,
128 tqft cylinder,
129 anchor=incoming boundary 1,
130 ];
131 \end{tikzpicture}
132 \end{center}
133
134 \section{Introduction}
135 This package defines some Ti\emph{k}Z/PGF picture shapes that can be used to construct the diagrams common in Topological Quantum Field Theory (TQFT).
136 An example follows:
137
138 \begin{example}
139 \begin{tikzpicture}[tqft/cobordism/.style={draw}]
140 \pic[tqft/pair of pants,name=a];
141 \pic[tqft/cylinder to next,anchor=incoming boundary 1,name=c,at=(a-outgoing boundary 1)];
142 \pic[tqft/reverse pair of pants, anchor=incoming boundary 1,at=(a-outgoing boundary 2)];
143 \end{tikzpicture}
144 \end{example}
145
146 \tableofcontents
147
148 \section{History}
149
150 This is the second version of the TQFT package.
151 The first version used nodes to draw the shapes.
152 However, with the advent of Ti\emph{k}Z3.0 came the ability to define subdrawings called \Verb+pic+s which were a bit like nodes but were geared more towards drawings than containers for text.
153 This seems a much more suitable mechanism for drawing these diagrams and so the package has been rewritten to make use of this new facility.
154
155 The second version is designed to be similar to the first, but with some improvements.
156 The original version was distributed as a \Verb+.sty+ file and so is loaded using \Verb+\usepackage{tqft}+.
157 The newer version is a Ti\emph{k}Z library and so is loaded using \Verb+\usetikzlibrary{tqft}+.
158 This makes it possible to use both in the same document.
159 This is not recommended, but an attempt has been made to make it possible to switch between the two methods (mainly to stop this documentation file complaining every time I compile it).
160 This hasn't been extensively tested so use with caution.
161 To make the switch use the key \Verb+/tikz/tqft/use nodes=<true|false>+.
162 By default, the one loaded last should be in effect at the start of the document.
163
164 \section{Keys}
165
166 Before giving any details, a word is in order about the keys involved in this package.
167 There are many options and keys that can be set via the \Verb+\pgfkeys+ system (which is used for setting options in Ti\emph{k}Z).
168 Such keys live in a ``directory'' but often that can be omitted.
169 For example, in the Ti\emph{k}Z command \Verb+\draw[red] (0,0) -- (1,0);+ the key \Verb+red+ is actually in the ``directory'' \Verb+/tikz+ but it is not necessary to specify that as it is assumed.
170 Defining a ``directory'' helps separate keys and ensure that there is no conflict.
171 The keys in this library are (mostly) defined in the directories \Verb+/tikz/tqft+ (the newer version) and \Verb+/pgf/tqft+ (the old version).
172
173 Invoking \Verb+/tikz/tqft+ itself sets the ``current directory'' to whichever directory is right for the current version in force and so all subsequent keys do not need prefixing.
174 Moreover, any unknown keys are passed on to the \Verb+/tikz+ directory so there is (or should be!) no harm in mixing \Verb+tqft+ specific keys with ordinary Ti\emph{k}Z keys.
175 Some examples take advantage of this switch so when copying and modifying examples from this document, it is important to remember that the first \Verb+tqft+ specific key needs an explicit \Verb+tqft/+ prefix.
176
177
178 \section{Version 2: Pics via a TikZ Library}
179 \label{sec:pic}
180
181 \subsection{The Shapes}
182
183 There is only one picture shape: \Verb+cobordism+.
184 This is a cobordism between a number of incoming circles and a number of outgoing circles, where the numbers of boundary components can be specified as options to the shape.
185 There are certain common shapes that are predefined as aliases to the main shape with specified boundaries.
186 The list of predefined shapes follows.
187 The names are all in the \Verb+tqft+ family, but an alias is made so that \Verb+tqft <shape>+ will work without any further qualification.
188
189 \begin{enumerate}
190 \item \Verb+pair of pants+
191
192 \begin{tikzpicture}
193 \pic[draw,tqft/pair of pants];
194 \end{tikzpicture}
195
196 \item \Verb+reverse pair of pants+
197
198 \begin{tikzpicture}
199 \pic[draw,tqft/reverse pair of pants];
200 \end{tikzpicture}
201
202 \item \Verb+cylinder to prior+
203
204 This is a cylinder that has been skewed to one side, thus following the same path as the \Verb+pair of pants+ cobordism but with only one outgoing boundary component.
205 The name \Verb+to prior+ is because it goes towards the lower-numbered component on the \Verb+pair of pants+.
206
207 \begin{tikzpicture}
208 \pic[draw,tqft/cylinder to prior];
209 \end{tikzpicture}
210
211 \item \Verb+cylinder to next+
212
213 This is a cylinder that has been skewed to one side, thus following the same path as the \Verb+pair of pants+ cobordism but with only one outgoing boundary component.
214 The name \Verb+to next+ is because it goes towards the higher-numbered component on the \Verb+pair of pants+.
215
216 \begin{tikzpicture}
217 \pic[draw,tqft/cylinder to next];
218 \end{tikzpicture}
219
220 \item \Verb+cylinder+
221
222 This is a straight cylinder.
223
224 \begin{tikzpicture}
225 \pic[draw,tqft/cylinder];
226 \end{tikzpicture}
227
228 \item \Verb+cap+
229
230 This is a cap.
231
232 \begin{tikzpicture}
233 \pic[draw,tqft/cap];
234 \end{tikzpicture}
235
236 \item \Verb+cup+
237
238 This is a cup (an upside-down cap).
239
240 \begin{tikzpicture}
241 \pic[draw,tqft/cup];
242 \end{tikzpicture}
243
244 \end{enumerate}
245
246 The general shape is controlled by the following keys:
247
248 \begin{itemize}
249 \item \DescribeMacro{view from} To get a simulated 3D effect, the cobordism is drawn as if viewed from a slight angle.
250 The value of this key determines whether the cobordism is viewed from the direction of the incoming boundary components or the outgoing ones.
251 This key can take the values \Verb+incoming+ and \Verb+outgoing+.
252 The default is \Verb+outgoing+.
253 \item \DescribeMacro{cobordism height} This is the height of the cobordism (``height'' interpreted in its own internal coordinate system).
254 With no offset (q.v.), this would be the distance between the centres of the first incoming and first outgoing boundary components.
255
256 \item \DescribeMacro{boundary separation} This is the distance between the centres of the boundary components of the same type.
257
258 \item \DescribeMacro{circle x radius} This is the half-width of the boundary circles.
259
260 \item \DescribeMacro{circle y radius} This is the half-depth of the boundary circles (``depth'' since, in the internal coordinate system, this corresponds to the \(z\)-axis out of the page).
261
262 \item \DescribeMacro{incoming boundary components} The number of incoming boundary components (can be zero).
263
264 \item \DescribeMacro{skip incoming boundary components} A list of incoming boundary components to be skipped.
265
266 \item \DescribeMacro{outgoing boundary components} The number of outgoing boundary components (can be zero).
267
268 \item \DescribeMacro{skip outgoing boundary components} A list of outgoing boundary components to be skipped.
269
270 \item \DescribeMacro{offset} This offsets the first outgoing boundary component horizontally relative to the first incoming boundary component.
271 It is a dimensionless number (not necessarily an integer) and is interpreted so that a value of \(1\) aligns the first outgoing boundary component with the second incoming boundary component.
272
273 \item \DescribeMacro{genus} This defines the number of holes in the shape.
274 These are spread out in a horizontal line in the middle of the shape.
275
276 \item \DescribeMacro{twisted} This is a boolean that, if set, makes the cobordism \emph{twisted} in that the edges cross as they pass from the incoming to outgoing boundaries.
277 This probably won't look good with a non-zero genus, but there's nothing stopping you doing it.
278 \end{itemize}
279
280 \subsection{Styling}
281
282 There are various options for styling the diagrams.
283 To understand how they work, it is important to know the order in which a cobordism is drawn and how many pieces it decomposes into.
284 This is the following list, with the corresponding keys:
285
286 \begin{enumerate}
287 \item The boundary circles are drawn.
288 These are actually elliptical nodes (and thus can be individually styled).
289 Applicable styles:
290
291 \begin{itemize}
292 \item \Verb+every boundary component+,
293 \item \Verb+every incoming boundary component+,\\
294 or \Verb+every outgoing boundary component+,
295 \item \Verb+incoming boundary component <n>+,\\
296 or \Verb+outgoing boundary component <n>+
297 \end{itemize}
298
299 \item The lower edges of the boundary circles are redrawn.
300 These are individual arcs.
301
302 \begin{itemize}
303 \item \Verb+every lower boundary component+,
304 \item \Verb+every incoming lower boundary component+,\\or \Verb+every outgoing lower boundary component+,
305 \item \Verb+incoming lower boundary component <n>+,\\or \Verb+outgoing lower boundary component <n>+
306 \end{itemize}
307
308 \item The full edge of the cobordism is drawn.
309 This is a closed path so can be sensibly filled.
310 It is clipped against a path defined by the genus of the cobordism which results in holes if it is filled (or shaded or anything else that goes in to the interior).
311
312 \begin{itemize}
313 \item \Verb+cobordism+,
314 \item also, any actions specified on the \Verb+pic+ are applied here (specifically, the \Verb+pic actions+ key is invoked; see the Ti\emph{k}Z manual for full details on this),
315 \item \Verb+cobordism outer path+.
316 \end{itemize}
317
318 \item Any holes specified by the genus are now drawn.
319 These are styled to give the 3D impression, and this follows the direction specified by the \Verb+view from+ key.
320 The paths are split so that each can be individually styled.
321
322 \begin{itemize}
323 \item \Verb+cobordism+, this style is applied because the curves defined by the genus can be thought of as part of the edge of the cobordism shape.
324 \item \Verb+pic actions+, for the same reason as above.
325
326 However, following this key then \Verb+fill=none,shade=none+ is issued.
327 This is because even if the main shape is filled or shaded, the paths drawing the holes should almost certainly not be.
328 \item \Verb+cobordism edge+, the same logic applies to the edge path (q.v.).
329 \item \Verb+genus style+,
330 \item \Verb+genus upper+ or \Verb+genus lower+,
331 \item \Verb+hole <n>+,
332 \item \Verb+hole <n> upper+ or \Verb+hole <n> lower+.
333 \end{itemize}
334
335 \item The non-boundary edge of the cobordism is redrawn.
336 This is split in to pieces to allow for individual styling.
337
338 \begin{itemize}
339 \item \Verb+cobordism edge+,
340 \item \Verb+cobordism outer edge+,
341 \item \Verb+between incoming+, or \Verb+between outgoing+, or \Verb+between incoming and outgoing+.
342 The latter is for the two sides, but note that if the cobordism has no incoming or no outgoing components then it also applies to the ``over the top'' edge.
343 \item \Verb+<anchor>+, where the \Verb+<anchor>+ is the name of the anchor that lies on the midpoint of the curve, so it will be one of:
344 %
345 \begin{itemize}
346 \item \Verb=between incoming <n> and <n+1>=,
347 \item \Verb=between outgoing <n> and <n+1>=,
348 \item \Verb+between first incoming and first outgoing+,
349 \item \Verb+between last incoming and last outgoing+,
350 \item \Verb+between first and last incoming+,
351 \item \Verb+between first and last outgoing+.
352 \end{itemize}
353 \end{itemize}
354
355 \item The upper edges of the boundary circles are redrawn.
356 These are arcs.
357
358 \begin{itemize}
359 \item \Verb+every upper boundary component+,
360 \item \Verb+every incoming upper boundary component+,\\or \Verb+every outgoing upper boundary component+,
361 \item \Verb+incoming upper boundary component <n>+,\\or \Verb+outgoing upper boundary component <n>+
362 \end{itemize}
363 \end{enumerate}
364
365 The fact that there are so many is to allow different style to be applied to different pieces and to give as much control as possible, whilst still making it fairly straightforward to draw a simple cobordism.
366 The duplication of paths is to allow certain composite pieces to be \emph{filled}.
367 Here is a progressively built up cobordism.
368
369 \begin{example}
370 \begin{tikzpicture}[tqft/view from=incoming]
371 \begin{scope}[tqft/every boundary component/.style={fill=green,fill opacity=1}]
372 \pic[tqft/cylinder,at={(1,0)}];
373 \begin{scope}[tqft/every lower boundary component/.style={draw=purple,thick}]
374 \pic[tqft/cylinder,at={(2,0)}];
375 \begin{scope}[tqft/cobordism/.style={fill=yellow,fill opacity=.7}]
376 \pic[tqft/cylinder,at={(3,0)}];
377 \begin{scope}[tqft/cobordism edge/.style={draw,thick,blue}]
378 \pic[tqft/cylinder,fill=yellow,fill opacity=.7,at={(4,0)}];
379 \begin{scope}[tqft/every upper boundary component/.style={draw,thick,orange}]
380 \pic[tqft/cylinder,fill=yellow,fill opacity=.7,at={(5,0)}];
381 \end{scope}
382 \end{scope}
383 \end{scope}
384 \end{scope}
385 \end{scope}
386 \end{tikzpicture}
387 \end{example}
388
389 Here's an example with lots of styling.
390
391 \begin{example}
392 \begin{tikzpicture}
393 \pic[
394 tqft,
395 incoming boundary components=3,
396 outgoing boundary components=3,
397 offset=1,
398 genus=3,
399 hole 3/.style={ultra thick, purple,solid},
400 genus lower/.style={dashed},
401 fill=red!50,
402 cobordism edge/.style={draw},
403 between incoming and outgoing/.style={dotted},
404 between outgoing 2 and 3/.style={ultra thick},
405 ];
406 \end{tikzpicture}
407 \end{example}
408
409 \subsection{Anchors}
410
411 The cobordism is a \Verb+pic+ so does not have any native anchors.
412 Nevertheless, a multitude of coordinates are defined that simulate the anchors associated with nodes.
413 There is also support for specifying the shape to be located relative to a particular anchor.
414
415 The \Verb+\pic+ should be named via the \Verb+name=<prefix>+ key, whereupon the anchors are prefixed by this value.
416 The pseudo-anchors defined have the naming convention \Verb+<prefix>-<anchor name>+ (at the moment, it doesn't check to see if the \Verb+name+ key has been specified so if it isn't then the pseudo-anchors are still defined but with an empty prefix).
417 They are:
418 %
419 \begin{itemize}
420 \item \Verb+incoming boundary <n>+, these are in fact elliptical nodes and so also define actual anchors.
421 \item \Verb+incoming boundary+ is an alias for \Verb+incoming boundary 1+.
422 \item \Verb+outgoing boundary <n>+, same.
423 \item \Verb+outgoing boundary+ is an alias for \Verb+outgoing boundary 1+.
424 \item \Verb=between incoming <n> and <n+1>=, this lies on the midpoint of the curve between successive boundary components.
425 \item \Verb=between outgoing <n> and <n+1>=, this lies on the midpoint of the curve between successive boundary components.
426 \item \Verb=between first incoming and first outgoing= is on the edge between the first incoming and first outgoing boundary components; note that this is only defined if there are both incoming and outgoing boundary components.
427 \item \Verb=between last incoming and last outgoing= is on the edge between the last incoming and last outgoing boundary components; note that this is only defined if there are both incoming and outgoing boundary components.
428 \item \Verb=between first and last incoming=; this is only defined if there are no outgoing components.
429
430 This is also available via the alias \Verb=between first incoming and last incoming=.
431 \item \Verb=between first and last outgoing=; this is only defined if there are no incoming components.
432
433 This is also available via the alias \Verb=between first outgoing and last outgoing=.
434 \item \Verb=hole <n>=; if the genus is non-zero, this points to the centre of the \(n\)th hole.
435 \end{itemize}
436
437 To place the shape relative to an anchor, use the \Verb+tqft/anchor+ key.
438 The argument should be just the name of the anchor without the leading \Verb+<prefix>-+.
439 The \Verb+anchor+ key can also take another type of argument.
440 If its argument is of the form \Verb+(x,y)+ then this is taken as a pseudo-coordinate\footnote{Note that due to the presence of the comma, this type of argument must be protected by braces.}.
441 It is interpreted as being \(x\) boundary components across and \(y\) times the cobordism height down.
442 However, if an \Verb+offset+ is specified then the resulting \(x\) value is shifted so that if \(y < 0\) then \((1,y)\) is in line with the first incoming boundary component and if \(y > 1\) then \((1,y)\) is in line with the first outgoing boundary component.
443 If \(0 < y < 1\) then \((1,y)\) linearly interpolates between the first incoming and first outgoing boundary components.
444 Thus \((1,0)\) is the first incoming boundary component, \((1,1)\) the first outgoing boundary component, \((0,0)\) is one unit to the left of the first incoming, and \((1,2)\) one unit below the first outgoing.
445 Note that the picture is shifted to put this point at the current coordinate.
446
447 \begin{example}
448 \begin{tikzpicture}
449 \pic[tqft, incoming boundary components=2,outgoing boundary components=4,offset=-1,draw,name=a];
450 \foreach \anchor/\placement in
451 {
452 between first incoming and first outgoing/left,
453 between last incoming and last outgoing/right,
454 between outgoing 2 and 3/above,
455 incoming boundary 1/above left,
456 incoming boundary 2/above right,
457 outgoing boundary 1/below left,
458 outgoing boundary 4/below right}
459 \draw[overlay,shift=(a-\anchor)] plot[mark=x] coordinates{(0,0)} node[\placement] {\scriptsize\texttt{(a-\anchor)}};
460 \path (a-incoming boundary) +(0,.5) (a-outgoing boundary) +(0,-1);
461 \end{tikzpicture}
462 \end{example}
463
464 \subsection{Notes}
465
466 \begin{enumerate}
467 \item Like \Verb+node+s, \Verb+pic+s need the \Verb+transform shape+ key to be set to take note of external transformations (other than shifts).
468 The tqft pic uses nodes internally and those nodes have \Verb+transform shape+ automatically set so this should \emph{just work}.
469 \item There is an additional \Verb+every tqft+ key which is run when the \Verb+tqft+ key is invoked (which might be via some other key).
470 This is better placed than the \Verb+every pic+ key since that applies to a surrounding scope rather than to the \Verb+pic+ itself.
471 \item If the \Verb+tqft+ key is invoked, either implicitly or explicitly, then the \Verb+pic type+ is set to \Verb+cobordism+.
472 This has the side effect that the invoking syntax has to be completely set by keys; so the \Verb+pic (<name>) at (<coord>) {<type>}+ cannot be used.
473 Rather, the \Verb+name+ and \Verb+at+ have to be specified by keys and the \Verb+type+ omitted.
474
475 \item If upgrading from the previous version of TQFT, as well as shifting from a \Verb+node+ to a \Verb+pic+, the following changes have been made in the implementation:
476
477 \begin{itemize}
478 \item The \Verb+flow+ key has not made it across to the new version.
479 Use \Verb+transform shape+ and apply your own transformation.
480
481 \item The \Verb+circle width+ and \Verb+circle depth+ are now \Verb+circle x radius+ and \Verb+circle y radius+ (the old names weren't correct anyway).
482
483 \item The bounding box is a little better, particularly for cobordisms with only one type of boundary component.
484 \end{itemize}
485 \end{enumerate}
486
487 \subsection{More Examples}
488
489 \begin{example}
490 \begin{tikzpicture}[tqft/cobordism height=1.5cm,tqft/boundary separation=1.5cm]
491 \foreach \coord/\style in {
492 {(0,0)}/{tqft/view from=outgoing,fill},
493 {(5,0)}/{tqft/view from=incoming,draw},
494 {(0,-8)}/{fill=orange,fill opacity=.5,tqft/every lower boundary component/.style={draw,blue,ultra thin,dashed},tqft/every upper boundary component/.style={draw,green},tqft/cobordism edge/.style={draw,purple},tqft/every boundary component/.style={fill=yellow}},
495 {(5,-8)}/{fill=orange,fill opacity=.5,tqft/cobordism edge/.style={draw,purple},tqft/every boundary component/.style={fill=yellow,draw=green}}
496 } {
497 \begin{scope}[every tqft/.style/.expand once=\style]
498 \pic[tqft/cap,name=h,at=\coord];
499 \pic[tqft/pair of pants,anchor=incoming boundary 1,name=a,at=(h-outgoing boundary 1)];
500 \pic[tqft/cylinder to next,anchor={(0,1)},name=d,at=(a-outgoing boundary 2)];
501 \pic[tqft/reverse pair of pants,anchor=incoming boundary 1,name=b,at=(a-outgoing boundary 2)];
502 \pic[tqft/cylinder to prior,anchor=incoming boundary 1,name=c,at=(b-outgoing boundary 1)];
503 \pic[tqft/cylinder,twisted,anchor=incoming boundary 1,name=e,at=(a-outgoing boundary 1)];
504 \pic[tqft/cylinder,anchor=incoming boundary 1,name=f,at=(e-outgoing boundary 1)];
505 \pic[tqft/reverse pair of pants,anchor=incoming boundary 1,name=g,at=(f-outgoing boundary 1)];
506 \pic[tqft/cup,anchor=incoming boundary 1,name=i,at=(g-outgoing boundary 1)];
507 \end{scope}
508 }
509 \end{tikzpicture}
510 \end{example}
511
512 \begin{example}
513 \begin{tikzpicture}[every tqft/.append style={transform shape}]
514 \foreach \ang in {0,90,180,270} {
515 \begin{scope}[rotate=\ang]
516 \pic[draw,tqft/pair of pants,name=a,at={(3,3)}];
517 \pic[draw,tqft/cap,anchor=outgoing boundary 1,at=(a-incoming boundary 1)];
518 \pic[fill,tqft/cup,anchor=incoming boundary 1,at=(a-outgoing boundary 1)];
519 \pic[draw,tqft/cup,anchor=incoming boundary 1,at=(a-outgoing boundary 2)];
520 \end{scope}
521 }
522 \end{tikzpicture}
523 \end{example}
524
525 \begin{example}
526 \begin{tikzpicture}[
527 tqft,
528 every outgoing boundary component/.style={fill=blue!50},
529 outgoing boundary component 3/.style={fill=none,draw=red},
530 every incoming boundary component/.style={fill=green!50},
531 every lower boundary component/.style={draw,ultra thick, dashed},
532 every upper boundary component/.style={draw,purple},
533 cobordism/.style={fill=red!50},
534 cobordism edge/.style={draw},
535 genus=3,
536 hole 2/.style={ultra thick, blue},
537 view from=incoming,
538 anchor=between incoming 1 and 2
539 ]
540 \pic[rotate=90,
541 %every node/.style={transform shape},
542 name=a,tqft,incoming boundary components=5,skip incoming boundary components={2,4},outgoing boundary components=7,skip outgoing boundary components={2,3,5},offset=-.5];
543
544 \begin{scope}[every pin edge/.style={<-}]
545 \foreach \anchor/\ang in {
546 hole 1/-90,
547 hole 2/90,
548 hole 3/-90,
549 incoming boundary 3/180,
550 outgoing boundary 4/0,
551 between last incoming and last outgoing/90,
552 between first incoming and first outgoing/-90,
553 between incoming 1 and 3/180,
554 between outgoing 1 and 4/0,
555 between outgoing 4 and 6/0
556 } {
557 \node[pin=\ang:\anchor,at=(a-\anchor),inner sep=0pt] {};
558 }
559 \draw[<-] (0,0) -- ++(-2,0) node[left] {origin};
560 \end{scope}
561 \end{tikzpicture}
562 \end{example}
563
564 %\begin{example}
565 \begin{tikzpicture}
566 \pic[
567 tqft,
568 incoming boundary components=2,
569 outgoing boundary components=2,
570 genus=2,
571 draw,
572 name=a
573 ];
574 \pic[
575 tqft,
576 incoming boundary components=2,
577 outgoing boundary components=1,
578 draw,
579 at=(a-outgoing boundary 1),
580 offset=.5,
581 cobordism height=1cm,
582 name=b
583 ];
584 \pic[tqft,
585 incoming boundary components=1,
586 outgoing boundary components=3,
587 draw,
588 at=(b-outgoing boundary 1),
589 offset=-1,
590 name=c
591 ];
592 \pic[tqft,
593 incoming boundary components=2,
594 outgoing boundary components=1,
595 draw,
596 at=(c-outgoing boundary 1),
597 anchor=incoming boundary 2,
598 name=d,
599 boundary separation=1.6cm,
600 ];
601 \pic[tqft,
602 incoming boundary components=1,
603 outgoing boundary components=1,
604 draw,
605 at=(c-outgoing boundary 3),
606 offset=.5,
607 name=e,
608 every outgoing lower boundary component/.style={draw}
609 ];
610 \pic[tqft,
611 incoming boundary components=1,
612 outgoing boundary components=1,
613 draw,
614 at=(c-outgoing boundary 2),
615 name=f
616 ];
617 \pic[tqft,
618 incoming boundary components=1,
619 outgoing boundary components=2,
620 draw,
621 at=(f-outgoing boundary),
622 name=g,
623 offset=-.5,
624 ];
625 \pic[tqft,
626 incoming boundary components=1,
627 outgoing boundary components=1,
628 draw,
629 at=(g-outgoing boundary 1),
630 name=h,
631 offset=-.25,
632 ];
633 \pic[tqft,
634 incoming boundary components=1,
635 outgoing boundary components=1,
636 draw,
637 at=(g-outgoing boundary 2),
638 name=i,
639 offset=.25,
640 ];
641 \pic[tqft,
642 incoming boundary components=1,
643 outgoing boundary components=1,
644 draw,
645 at=(h-outgoing boundary),
646 name=j,
647 every outgoing lower boundary component/.style={draw}
648 ];
649 \pic[tqft,
650 incoming boundary components=1,
651 outgoing boundary components=1,
652 draw,
653 at=(i-outgoing boundary),
654 name=k,
655 every outgoing lower boundary component/.style={draw}
656 ];
657 \pic[tqft,
658 incoming boundary components=1,
659 outgoing boundary components=1,
660 draw,
661 at=(d-outgoing boundary),
662 name=l
663 ];
664 \pic[tqft,
665 incoming boundary components=1,
666 outgoing boundary components=0,
667 draw,
668 at=(l-outgoing boundary),
669 name=m
670 ];
671 \pic[tqft,
672 incoming boundary components=1,
673 outgoing boundary components=1,
674 draw,
675 at=(d-incoming boundary),
676 anchor=outgoing boundary,
677 name=n
678 ];
679 \pic[tqft,
680 incoming boundary components=1,
681 outgoing boundary components=1,
682 draw,
683 at=(n-incoming boundary),
684 anchor=outgoing boundary,
685 name=o
686 ];
687 \pic[tqft,
688 incoming boundary components=3,
689 outgoing boundary components=3,
690 draw,
691 at=(o-incoming boundary),
692 anchor={(2,1)},
693 name=p,
694 boundary separation=1.25cm,
695 outgoing lower boundary component 1/.style={draw},
696 outgoing lower boundary component 3/.style={draw}
697 ];
698 \pic[tqft,
699 incoming boundary components=5,
700 outgoing boundary components=5,
701 genus=3,
702 at=(k-outgoing boundary),
703 anchor={(4,-1)},
704 draw,
705 name=q,
706 every outgoing lower boundary component/.style={draw}
707 ];
708 \path (q-incoming boundary 3) ++(0,1) node {\Huge \(=\)};
709 \end{tikzpicture}
710 %\end{example}
711
712 \section{Version 1: Nodes via a Style File}
713
714 \tikzset{tqft/use nodes=true}
715
716 As mentioned in the introduction, this is the original method of drawing cobordism diagrams using nodes and is no longer updated (though I will fix bugs if I can).
717 If drawing a new diagram, use the pic method from Section~\ref{sec:pic}.
718
719 \subsection{The Node Shapes}
720
721 There are only two shapes, \Verb+tqft cobordism+ and \Verb+tqft boundary circle+.
722 The first, which is the main shape, is a cobordism between a number of incoming circles and a number of outgoing circles, where the numbers of boundary components can be specified as options to the shape.
723 The second is just the boundary circle.
724 It is used as a sub-node of the first to add extra anchors, but can be used by itself.
725 There are certain common shapes that are predefined as aliases to the main shape with specified boundaries.
726 The list of predefined shapes follows.
727 The names are all in the \Verb+tqft+ family, but an alias is made so that \Verb+tqft nodeshape+ will work without any further qualification.
728
729 \begin{enumerate}
730 \item \Verb+pair of pants+
731
732 \begin{tikzpicture}
733 \node[draw,tqft/pair of pants] (a) {};
734 \end{tikzpicture}
735
736 \item \Verb+reverse pair of pants+
737
738 \begin{tikzpicture}
739 \node[draw,tqft/reverse pair of pants] (a) {};
740 \end{tikzpicture}
741
742 \item \Verb+cylinder to prior+
743
744 This is a cylinder that has been skewed to one side, thus following the same path as the \Verb+pair of pants+ cobordism but with only one outgoing boundary component.
745 The name \Verb+to prior+ is because it goes towards the lower-numbered component on the \Verb+pair of pants+.
746
747 \begin{tikzpicture}
748 \node[draw,tqft/cylinder to prior] (a) {};
749 \end{tikzpicture}
750
751 \item \Verb+cylinder to next+
752
753 This is a cylinder that has been skewed to one side, thus following the same path as the \Verb+pair of pants+ cobordism but with only one outgoing boundary component.
754 The name \Verb+to next+ is because it goes towards the higher-numbered component on the \Verb+pair of pants+.
755
756 \begin{tikzpicture}
757 \node[draw,tqft/cylinder to next] (a) {};
758 \end{tikzpicture}
759
760 \item \Verb+cylinder+
761
762 This is a straight cylinder.
763
764 \begin{tikzpicture}
765 \node[draw,tqft/cylinder] (a) {};
766 \end{tikzpicture}
767
768 \item \Verb+cap+
769
770 This is a cap.
771
772 \begin{tikzpicture}
773 \node[draw,tqft/cap] (a) {};
774 \end{tikzpicture}
775
776 \item \Verb+cup+
777
778 This is a cup (an upside-down cap).
779
780 \begin{tikzpicture}
781 \node[draw,tqft/cup] (a) {};
782 \end{tikzpicture}
783
784 \end{enumerate}
785
786 The general shape is controlled by the following keys:
787
788 \begin{itemize}
789 \item \DescribeMacro{flow} A cobordism ``flows'' from its incoming to its outgoing boundaries.
790 This key controls the direction of that flow.
791 The shape is transformed so that the incoming-outgoing axis aligns with the argument.
792 However, the transformation may be more than just a rotation as the shape is set up so that the numbering of the boundary components is always left-to-right or top-to-bottom (as appropriate).
793 Currently, this key can take the values \Verb+north+, \Verb+south+ (default), \Verb+east+, and \Verb+west+.
794
795 \item \DescribeMacro{view from} To get a simulated 3D effect, the cobordism is drawn as if viewed from a slight angle.
796 The value of this key determines whether the cobordism is viewed from the direction of the incoming boundary components or the outgoing ones.
797 This key can take the values \Verb+incoming+ and \Verb+outgoing+.
798 The default is \Verb+outgoing+.
799 \item \DescribeMacro{cobordism height} This is the height of the cobordism (``height'' interpreted in its own internal coordinate system).
800 With no offset (q.v.), this would be the distance between the centres of the first incoming and first outgoing boundary components.
801
802 \item \DescribeMacro{boundary separation} This is the distance between the centres of the boundary components of the same type.
803
804 \item \DescribeMacro{circle width} This is the half-width of the boundary circles.
805
806 \item \DescribeMacro{circle depth} This is the half-depth of the boundary circles (``depth'' since, in the internal coordinate system, this corresponds to the \(z\)-axis out of the page).
807
808 \item \DescribeMacro{incoming boundary components} The number of incoming boundary components (can be zero).
809
810 \item \DescribeMacro{outgoing boundary components} The number of outgoing boundary components (can be zero).
811
812 \item \DescribeMacro{offset} This offsets the first outgoing boundary component horizontally relative to the first incoming boundary component.
813 It is a dimensionless number (not necessarily an integer) and is interpreted so that a value of \(1\) aligns the first outgoing boundary component with the second incoming boundary component.
814 \end{itemize}
815
816 \subsection{Styling}
817
818 There are various options for styling the diagrams.
819 To understand how they work, it is important to know the order in which a cobordism is drawn and how many pieces it decomposes into.
820 This is the following list, with the corresponding key:
821
822 \begin{enumerate}
823 \item The boundary circles are drawn.
824 \Verb+boundary style+
825 \item The lower edges of the boundary circles are redrawn.
826 \Verb+boundary lower style+
827 \item The cobordism itself is drawn.
828 \item The non-boundary edge of the cobordism is redrawn.
829 \Verb+cobordism style+
830 \item The upper edges of the boundary circles are redrawn.
831 \Verb+boundary upper style+
832 \end{enumerate}
833
834 The fact that there are so many is to allow different style to be applied to different pieces.
835 The duplication is to allow certain composite pieces to be \emph{filled}.
836 All of these items can be styled separately.
837 The style given to the node itself is passed on to the third item in that list, the cobordism itself.
838 The styles of the others are controlled by a series of keys, each of should be a list of styles to be applied to that component.
839 Not all options make sense, in particular only the first and third can be filled.
840 (That is, the \Verb+fill+ style is ignored on the other components.)
841 Here is a progressively built up cobordism.
842
843 \begin{example}
844 \begin{tikzpicture}
845 \begin{scope}[tqft/boundary style={fill=purple,fill opacity=1}]
846 \node[tqft/cylinder] at (1,0) {};
847 \begin{scope}[tqft/boundary lower style={draw,dashed,green,thick}]
848 \node[tqft/cylinder] at (2,0) {};
849 \begin{scope}
850 \node[tqft/cylinder,fill=yellow,fill opacity=.7] at (3,0) {};
851 \begin{scope}[tqft/cobordism style={draw,thick,blue}]
852 \node[tqft/cylinder,fill=yellow,fill opacity=.7] at (4,0) {};
853 \begin{scope}[tqft/boundary upper style={draw,thick,orange}]
854 \node[tqft/cylinder,fill=yellow,fill opacity=.7] at (5,0) {};
855 \end{scope}
856 \end{scope}
857 \end{scope}
858 \end{scope}
859 \end{scope}
860 \end{tikzpicture}
861 \end{example}
862
863 \subsection{Anchors}
864
865 As with all PGF node shapes, there are certain anchors defined by the \Verb+tqft+ shape.
866 These are the \Verb+center+ (and \Verb+centre+) anchors and the \Verb+incoming boundary n+, \Verb+outgoing boundary n+ anchors.
867 The positioning of the \Verb+center+ anchor is slightly unusual in that if there are no, say, incoming boundary components then the centre anchor is still at the same height above the outgoing boundary components as if there were incoming boundary components.
868 The reason for this is two-fold: computing the \emph{actual} centre of the shape in such circumstances would be tricky, and when aligning these shapes it is more useful to have the anchors consistent across shapes of varying boundary components.
869
870 There are also the directional anchors \Verb+north+, \Verb+south+, \Verb+east+, \Verb+west+, \Verb+north east+, \Verb+north west+, \Verb+south east+, \Verb+south west+.
871 The \Verb+east+ and \Verb+west+ anchors are placed at the midpoints of the sides.
872 The \Verb+north+ and \Verb+south+ anchors are placed in a vertical line with the \Verb+center+ anchor and vertically aligned with the centres of the corresponding boundary circles.
873 The other four directional anchors are placed at the corners of the cobordism (the placement of these anchors in the case that there are no boundary circles in the corresponding direction may change in future versions).
874
875 The \Verb+incoming boundary n+ and \Verb+outgoing boundary n+ are placed at the centres of the corresponding boundary components, with the numbering starting at the left or the top as appropriate to the flow of the cobordism.
876 A hack borrowed from the \Verb+regular polygon+ shape ensures that there are always enough anchors for the boundary components.
877
878 There are also anchors placed at the midpoint of the cobordism edge between the boundary circles.
879 The names of these are \Verb+after incoming boundary n+ and \Verb+after outgoing boundary n+.
880
881 The above anchors can all be ``floated'' off the cobordism using the keys \Verb+outer sep+, \Verb+outer xsep+, and \Verb+outer ysep+.
882 The last two are the ones actually used, the first is a shortcut for setting both simultaneously.
883
884 There are also ``sub-nodes''.
885 Provding the main node is named, each boundary circle is covered by a \Verb+tqft boundary circle+ node.
886 This means that the anchors of the \Verb+tqft boundary circle+ can be used.
887 These cannot be used for placing the main shape, but can be used afterwards.
888 These are not affected by the \Verb+outer (x/y)sep+ keys.
889 The names of these sub-nodes are of the form \Verb+name incoming n+ and \Verb+name outgoing n+ where \Verb+name+ is the name of the main node.
890 The \Verb+tqft boundary circle+ shape is based on an ellipse and defines a boundary so the syntax \Verb+(name.angle)+ works as expected.
891 It also defines anchors \Verb+next+, \Verb+prior+, \Verb+above+, and \Verb+below+.
892 These correspond to where the boundary circle in the prescribed direction should be placed.
893
894 \begin{example}
895 \begin{tikzpicture}
896 \node[tqft, incoming boundary components=2,outgoing boundary components=4,offset=-1,draw] (a) {};
897 \foreach \anchor/\placement in
898 {
899 north/above,
900 south/below,
901 east/right,
902 west/left,
903 north west/left,
904 south west/left,
905 north east/right,
906 south east/right,
907 incoming boundary 1/above left,
908 incoming boundary 2/above right,
909 outgoing boundary 1/below left,
910 outgoing boundary 4/below right,
911 after outgoing boundary 1/below}
912 \draw[shift=(a.\anchor)] plot[mark=x] coordinates{(0,0)} node[\placement] {\scriptsize\texttt{(a.\anchor)}};
913 \end{tikzpicture}
914 \end{example}
915
916 \begin{example}
917 \begin{tikzpicture}
918 \node[tqft,cylinder, circle width=2cm, circle depth=1cm, cobordism height=4cm,boundary separation=3cm,draw] (b) {};
919 \foreach \anchor/\placement in
920 {
921 prior/left,
922 next/right,
923 above/above,
924 below/below,
925 0/right,
926 60/right,
927 200/left}
928 \draw[shift=(b incoming 1.\anchor)] plot[mark=x] coordinates{(0,0)} node[\placement] {\scriptsize\texttt{(b incoming 1.\anchor)}};
929 \end{tikzpicture}
930 \end{example}
931
932 \subsection{Improvements}
933
934 Here are some ideas for extending this, and some minor ``bugs''.
935
936 \begin{enumerate}
937 \item Make \Verb+incoming boundary+ an alias of \Verb+incoming boundary 1+ so that if there is only one incoming boundary component then we don't need to specify the number (ditto outgoing).
938 \item No thought has been given as to where the text gets placed if it is specified.
939 \item Add the ability to hide certain boundary components.
940 This is useful if the shapes are not specified in their natural order so certain boundary components should be hidden behind earlier drawn shapes.
941 \item Some style options on the main node get passed to the other pieces (\Verb+fill opacity+ being one).
942 This shouldn't happen, or should happen by design not by accident.
943 \item The bounding box isn't as good as it could be.
944 \item Add a way to specify more directions for the flow.
945 \item Add the ability to apply different styles to the incoming and outgoing components.
946 \end{enumerate}
947
948 \subsection{More Examples}
949
950 \begin{example}
951 \begin{tikzpicture}[tqft/cobordism height=1.5cm,tqft/boundary separation=1.5cm]
952 \foreach \coord/\style in {
953 {(0,0)}/{tqft/view from=outgoing,fill},
954 {(5,0)}/{tqft/view from=incoming,draw},
955 {(0,-8)}/{fill=orange,fill opacity=.5,tqft/boundary lower style={draw,blue,ultra thin,dashed},tqft/boundary upper style={draw,green},tqft/cobordism style={draw,purple},tqft/boundary style={fill=yellow}},
956 {(5,-8)}/{fill=orange,fill opacity=.5,tqft/cobordism style={draw,purple},tqft/boundary style={fill=yellow,draw=green}}
957 } {
958 \begin{scope}[every node/.style/.expand once=\style]
959 \node[tqft/cap] (h) at \coord {};
960 \node[tqft/pair of pants,anchor=incoming boundary 1] (a) at (h.outgoing boundary 1) {};
961 \node[tqft/cylinder to next,anchor=incoming boundary 1] (d) at (a.incoming boundary 2) {};
962 \node[tqft/reverse pair of pants,anchor=incoming boundary 1] (b) at (a.outgoing boundary 2) {};
963 \node[tqft/cylinder to prior,anchor=incoming boundary 1] (c) at (b.outgoing boundary 1) {};
964 \node[tqft/cylinder,anchor=incoming boundary 1] (e) at (a.outgoing boundary 1) {};
965 \node[tqft/cylinder,anchor=incoming boundary 1] (f) at (e.outgoing boundary 1) {};
966 \node[tqft/reverse pair of pants,anchor=incoming boundary 1] (g) at (f.outgoing boundary 1) {};
967 \node[tqft/cup,anchor=incoming boundary 1] (i) at (g.outgoing boundary 1) {};
968 \end{scope}
969 }
970 \end{tikzpicture}
971 \end{example}
972
973 \begin{example}
974 \begin{tikzpicture}
975 \node[draw,tqft/pair of pants] (a) {};
976 \node[draw,tqft/cap,anchor=outgoing boundary 1] at (a.incoming boundary 1) {};
977 \node[fill,tqft/cup,anchor=incoming boundary 1] at (a.outgoing boundary 1) {};
978 \node[draw,tqft/cup,anchor=incoming boundary 1] at (a.outgoing boundary 2) {};
979 \begin{scope}[tqft/flow=east]
980 \node[draw,tqft/pair of pants] (a) at (4,0) {};
981 \node[draw,tqft/cap,anchor=outgoing boundary 1] at (a.incoming boundary 1) {};
982 \node[fill,tqft/cup,anchor=incoming boundary 1] at (a.outgoing boundary 1) {};
983 \node[draw,tqft/cup,anchor=incoming boundary 1] at (a.outgoing boundary 2) {};
984 \end{scope}
985 \begin{scope}[tqft/flow=north]
986 \node[draw,tqft/pair of pants] (a) at (0,-4) {};
987 \node[draw,tqft/cap,anchor=outgoing boundary 1] at (a.incoming boundary 1) {};
988 \node[fill,tqft/cup,anchor=incoming boundary 1] at (a.outgoing boundary 1) {};
989 \node[draw,tqft/cup,anchor=incoming boundary 1] at (a.outgoing boundary 2) {};
990 \end{scope}
991 \begin{scope}[tqft/flow=west]
992 \node[draw,tqft/pair of pants] (a) at (4,-4) {};
993 \node[draw,tqft/cap,anchor=outgoing boundary 1] at (a.incoming boundary 1) {};
994 \node[fill,tqft/cup,anchor=incoming boundary 1] at (a.outgoing boundary 1) {};
995 \node[draw,tqft/cup,anchor=incoming boundary 1] at (a.outgoing boundary 2) {};
996 \end{scope}
997 \end{tikzpicture}
998 \end{example}
999
1000 \end{document}