Debian Codegraph @

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

raw
1 \documentclass{ltxdoc}
2 \usepackage[T1]{fontenc}
3 \usepackage{lmodern}
4 \usepackage{morefloats}
5 \usepackage{tikz}
6 \usepackage[nowarning]{braids}
7 \usetikzlibrary{
8 braids,
9 calc,
10 decorations.markings
11 }
12 \usepackage[numbered]{hypdoc}
13 \definecolor{lstbgcolor}{rgb}{0.9,0.9,0.9}
14
15 \usepackage{listings}
16 \lstloadlanguages{[LaTeX]TeX}
17 \lstset{
18 gobble=2,
19 breakatwhitespace=true,
20 breaklines=true,
21 language=[LaTeX]TeX,
22 basicstyle=\small\ttfamily,
23 keepspaces=true,
24 columns=fullflexible
25 }
26
27 \usepackage{fancyvrb}
28
29 \newenvironment{example}
30 {\VerbatimEnvironment
31 \begin{VerbatimOut}{example.out}}
32 {\end{VerbatimOut}
33 \begin{center}
34 \setlength{\parindent}{0pt}
35 \fbox{\begin{minipage}{.9\linewidth}
36 \lstinputlisting[]{example.out}
37 \end{minipage}}
38
39 \fbox{\begin{minipage}{.9\linewidth}
40 \centering
41 \input{example.out}
42 \end{minipage}}
43 \end{center}
44 }
45
46 \newenvironment{justexample}
47 {\VerbatimEnvironment
48 \begin{VerbatimOut}{example.out}}
49 {\end{VerbatimOut}
50 \begin{center}
51 \setlength{\parindent}{0pt}
52 \fbox{\begin{minipage}{.9\linewidth}
53 \lstinputlisting[]{example.out}
54 \end{minipage}}
55 \end{center}
56 }
57
58 \usepgfmodule{nonlineartransformations}
59 \makeatletter
60 \def\polartransformation{%
61 % \pgf@x will contain the radius
62 % \pgf@y will contain the distance
63 \pgfmathsincos@{\pgf@sys@tonumber\pgf@x}%
64 % pgfmathresultx is now the cosine of radius and
65 % pgfmathresulty is the sine of radius
66 \pgf@x=\pgfmathresultx\pgf@y%
67 \pgf@y=\pgfmathresulty\pgf@y%
68 }
69 \makeatother
70
71
72 \providecommand*{\url}{\texttt}
73 \GetFileInfo{tikzlibrarybraids.code.tex}
74
75 \title{The \textsf{braids} Package: Documentation}
76 \author{Andrew Stacey \\ \texttt{[email protected]}}
77 \date{\fileversion~from \filedate}
78
79 \begin{document}
80
81 \maketitle
82
83 \begin{center}
84 \begin{tikzpicture}
85 \pic[
86 line width=1.5pt,
87 red,
88 line cap=round,
89 braid/.cd,
90 width=.75cm,
91 crossing height=.5cm,
92 strand 3/.style={gray,line width=1pt},
93 strand 6/.style={gray,line width=1pt},
94 strand 7/.style={gray,line width=1pt},
95 strand 10/.style={gray,line width=1pt},
96 strand 14/.style={gray,line width=1pt},
97 strand 15/.style={gray,line width=1pt},
98 strand 16/.style={gray,line width=1pt},
99 strand 18/.style={gray,line width=1pt},
100 ] {braid={s_1-s_4-s_8-s_{12}-s_{16} s_2-s_5-s_7-s_9-s_{13}-s_{15} s_2-s_5-s_7-s_9-s_{15} s_1-s_4-s_8-s_{16} s_1-s_4-s_7-s_9-s_{17} s_2-s_5-s_{17} s_2-s_{13}-s_{16} s_1-s_{12}-s_{15}}};
101 \end{tikzpicture}
102 \end{center}
103
104 \section{Introduction}
105
106 This is a package for drawing braid diagrams using PGF/TikZ.
107 An example follows.
108
109 \begin{example}
110 \begin{center}
111 \begin{tikzpicture}
112 \pic[
113 rotate=90,
114 braid/.cd,
115 every strand/.style={ultra thick},
116 strand 1/.style={red},
117 strand 2/.style={green},
118 strand 3/.style={blue},
119 ] {braid={s_1 s_2^{-1} s_1 s_2^{-1} s_1 s_2^{-1}}};
120 \end{tikzpicture}
121 \end{center}
122 \end{example}
123
124 This is actually the documentation for two packages: a \emph{package} and a TikZ \emph{library}.
125 If your preamble contains \Verb+\usepackage{braids}+ then you are using the package, if \Verb+\usetikzlibrary{braids}+ then the library.
126
127 The package was the original version, and then with the advent of \Verb+pic+s I rewrote it as a TikZ library.
128 If you are starting afresh then you should use the library, but I recognise that people might have figured out how to get what they want with the old package and don't need to switch.
129 So although the original package should be considered \emph{depreciated}, it is not (yet) obsolete.
130 I will continue to fix bugs for the original package, but new features only go in the TikZ library.
131
132 The best place to report bugs or make suggestions for improvements is on \href{https://github.com/loopspace/braids}{github}.
133 There have been several excellent suggestions made there, and for v2.3 I am particularly indebted to \href{https://github.com/nilesjohnson}{Niles Johnson} who not only contributed ideas but also helped considerably with clarifying the documentation.
134
135 \section{TikZ Library Usage}
136
137 Version 2.0 changed the implementation to use the TikZ \Verb+pic+ syntax.
138 It also converted it to a TikZ library, so to use it put the following in the preamble.
139
140 \begin{verbatim}
141 \usetikzlibrary{braids}
142 \end{verbatim}
143
144 (Or add it to the copious list of TikZ libraries that you are already using.)
145
146 \bigskip
147
148 \DescribeMacro{braid}
149 A braid is specified by the pic name \Verb+braid+.
150 The usual syntax for this is as follows:
151
152 \Verb+\pic[options] at (coordinate) {braid={braid-word}};+
153
154 \DescribeMacro{braid-word}
155 The \Verb+braid-word+ is an expression in the braid group, such as \Verb+s_1 s_2^{-1} s_{3,5}+.
156 The generator labels are not significant.
157
158 The subscript and superscript determine how the strands cross.
159 The following describes the default behaviour and is written from the viewpoint that the braid flows down the page.
160 This default behaviour can be altered by using the \Verb+crossing convention+ or \Verb+flip crossing convention+ keys (described in a moment).
161 %
162 \begin{enumerate}
163 \item If the subscript is a single number, as in \Verb+s_2+, the crossing goes from that number over the next.
164 \item If the subscript is two or more numbers separated by a comma, as in \Verb+s_{2,4}+ or \Verb+s_{1,3,5}+, imagine holding the numbered strands and moving each to the position of the next with the last strand moving under the others to where the first stands.
165 Any intermediate non-specified strand is behind all those involved in the crossing.
166 \item If the subscript is hyphenated, as in \Verb+s_{1-5}+, this is equivalent to \Verb+s_{1,2,3,4,5}+.
167 This can be used as part of a list, as in \Verb+s_{1-3,5}+.
168 \end{enumerate}
169
170 All of these crossings take place in the same amount of vertical space.
171 Be advised that crossings involving a lot of strands can get quite squashed.
172
173 The exponent can be \Verb+1+, \Verb+{-1}+, or missing (in which case it defaults to \Verb+1+, note also that the exponent is read as a \TeX-token so \Verb+{1}+ is also legal).
174 If the exponent is \(-1\) then the braid element represented by the crossing is inverted.
175
176 \begin{itemize}
177 \item \Verb+s_1+ is strand \(1\) over strand \(2\).
178 \item \Verb+s_1^{-1}+ is strand \(2\) over strand \(1\).
179 \item \Verb+s_{1,3}+ is strand \(1\) over strand \(3\), and both are over strand \(2\).
180 \item \Verb+s_{1-3}+ is strand \(3\) under strand \(2\) and then under strand \(1\).
181 \end{itemize}
182
183 Certain other symbols are allowed in the \Verb+braid-word+ which control the rendering of the braid.
184 These extras are as follows.
185
186 \begin{enumerate}
187 \item To get crossings to render at the same height, separate them with a hyphen (note: no check is made to ensure that the crossings can legally be put at the same height; \emph{caveat emptor}).
188 For example, \Verb+s_1-s_3+.
189
190 \item To draw a \emph{floor} -- which is a rectangle behind the braid occupying some number of levels (the default being one level) -- precede the braid element by a vertical line, as in \Verb+s_1 | s_2+.
191 The floor is itself a pic which, by default, consists of a rectangle and two horizontal lines.
192 The rectangle picks up any \Verb+fill+ options and the lines any \Verb+draw+ options that are set in the \Verb+braid/every floor+ and \Verb+braid/floor <n>+ styles, which are documented below (with an example of changing the pic).
193 The \Verb+n+ is the level number, starting at \(1\).
194
195 More general floors can be drawn using the key \Verb+braid/add floor+.
196 This takes one argument which is a comma separated list of parameters that specifies the position and size of the floor:
197 %
198 \begin{verbatim}
199 braid/add floor={x,y,width,height,name}
200 \end{verbatim}
201 %
202 The units used are the ``natural'' units of the braid: strand separation and level height.
203 The \Verb+name+ is optional and if given can be used to style the floor in that the style \Verb+braid/floor <name>+ is applied to that floor.
204
205 Replacing the floor pic will change how it is drawn.
206 The coordinate system is set up for the floor pic so that the floor is a unit square with lower left corner at the origin.
207 The default definition is:
208
209 \begin{lstlisting}
210 floor/.pic={
211 \path[pic actions, draw=none] (0,0) rectangle (1,1);
212 \path[pic actions, fill=none] (0,0) -- (1,0) (0,1) -- (1,1);
213 }
214 \end{lstlisting}
215
216 \item The identity element can occur in the braid-word.
217 It is represented by \Verb+1+.
218 This inserts the identity which corresponds to no crossing.
219 However, it takes the same amount of space as if there were a crossing.
220
221 \end{enumerate}
222
223 The crossing behaviour can be modified by use of one of the following keys.
224 All are in the \Verb+/tikz/braid/+ namespace.
225
226 \DescribeMacro{crossing convention, flip crossing convention, set symbols, flip symbols} These keys determine the behaviour of the braid symbols.
227 Both \Verb+crossing convention+ and \Verb+set symbols+ take an option, which is one of \Verb+over+, \Verb+under+, \Verb+down+, or \Verb+up+; in this list \Verb+over+ and \Verb+down+ are synonyms for each other, as are \Verb+under+ and \Verb+up+.
228 The default for both is \Verb+over+.
229 Then \Verb+flip crossing convention+ and \Verb+flip symbols+ reverses the current behaviour of the corresponding setting key.
230
231 These have similar but not identical behaviours.
232 The \Verb+crossing convention+ keys set whether the standard crossings are over or under (the alternatives, \Verb+down+ and \Verb+up+, are based on visualising the braid as travelling down or up the page).
233 The \Verb+set symbols+ keys can be used to invert the braid element represented by each symbol.
234
235 For the generators, such as \(s_1\), these have the same effect since \(s_1^{-1}\) is obtained from \(s_1\) by swapping the crossing type.
236 But for the other symbols, such as \(s_{1-3}\), then these achieve different things.
237 With the \Verb+crossing convention+ set to \Verb+under+ then \(s_{1-3}\) still moves strands \(1\) and \(2\) to the right.
238 But with \Verb+set symbols+ set to \Verb+under+ then these strands now move to the left.
239
240 To see the effect of these options, consider \(s_{1-3}\).
241 The equivalences of this, as a braid element, under the various options is in Table~\ref{tab:overunder}.
242 In this table each row corresponds to a different setting while the central column gives how to achieve the same result as \(s_{1-3}\) but with the default settings.
243
244 \begin{table}
245 \begin{center}
246 \begin{tabular}{lcc}
247 Defaults & \(s_2 s_1\) & \tikz[baseline=(defaults.east)]{ \pic[scale=.5,draw,thin] (defaults) {braid={s_{1-3}}}; \path (defaults.south) +(0,-.1); } \\
248 \Verb+crossing convention=under+ & \(s_2^{-1} s_1^{-1}\) & \tikz[baseline=(convention.east)]{ \pic[scale=.5,draw,thin,braid/crossing convention=under] (convention) {braid={s_{1-3}}}; \path (convention.south) +(0,-.1); } \\
249 \Verb+set symbols=under+ & \(s_1^{-1} s_2^{-1}\) & \tikz[baseline=(symbols.east)]{ \pic[scale=.5,draw,thin,braid/set symbols=under] (symbols) {braid={s_{1-3}}}; \path (symbols.south) +(0,-.1); }\\
250 Both & \(s_1 s_2\) & \tikz[baseline=(symbols.east)]{ \pic[scale=.5,draw,thin,braid/set symbols=under, braid/crossing convention=under] (symbols) {braid={s_{1-3}}}; \path (symbols.south) +(0,-.1); }\\
251 \end{tabular}
252 \caption{Equivalences of \(s_{1-3}\)}
253 \label{tab:overunder}
254 \end{center}
255
256 \end{table}
257
258
259 Any strands not involved in the crossing, for example strands \(2\) and \(3\) in \(s_{1,4}\), stay behind the crossing regardless of these settings.
260 This is partially because implementing them as over strands is more complicated to code, and partially because the idea of \(s_{1,4}\) is that strands \(2\) and \(3\) are not involved.
261
262 \begin{example}
263 \begin{tikzpicture}[
264 braid/.cd,
265 strand 1/.style={red},
266 strand 2/.style={green},
267 strand 3/.style={blue},
268 strand 4/.style={magenta},
269 ]
270 \pic at (0,0) {braid={s_1 s_{1-4} s_{1,3,4}}};
271 \pic[braid/crossing convention=under] at (4,0) {braid={s_1 s_{1-4} s_{1,3,4}}};
272 \pic[braid/set symbols=under] at (8,0) {braid={s_1 s_{1-4} s_{1,3,4}}};
273 \end{tikzpicture}
274 \end{example}
275
276 \subsection{Style Options}
277 \label{sec:picstyleopts}
278
279 There are various keys that change the behaviour or rendering of the braid.
280 All of these are in the \Verb+/tikz/braid/+ namespace.
281 Many of the examples use the key \Verb+braid/.cd+ to switch to this namespace, meaning that multiple \Verb+braid+ keys can be given without the \Verb+braid+ prefix.
282 Any unknown keys are dropped back to the \Verb+tikz+ namespace.
283 See the TikZ/pgf documentation for more details on key handling.
284
285 \DescribeMacro{number of strands} The key \Verb+number of strands+ sets the minimum number of strands for the braid.
286 The number of strands will grow according to the terms in the braid word so this merely sets a lower bound.
287 If not set, the number of strands will be determined by the terms in the braid word.
288
289 \DescribeMacro{height}
290 The key \Verb+height+ is used to set the height of the piece of the braid corresponding to a single element in the group.
291 This can be negative, and indeed the default value is negative because the default is for a braid to flow down the page.
292
293 This key is depreciated and is only kept for backwards compatibility, the fact that the default is negative proved confusing.
294 Therefore the following key should be used in its place.
295
296 \DescribeMacro{crossing height}
297 The key \Verb+crossing height+ also sets the height of the piece of the braid corresponding to an element in the group.
298 The sign of this is ignored.
299
300 The correct way to get a braid to flow in a different direction to the default is to use a transformation on the \Verb+pic+, such as in the following example.
301
302 \begin{example}
303 \begin{tikzpicture}[
304 every braid/.style={
305 ultra thick,
306 braid/strand 1/.style=red,
307 braid/strand 2/.style=green,
308 braid/strand 3/.style=blue,
309 braid/anchor=center,
310 }
311 ]
312 \pic {braid={s_1 s_2^{-1}}};
313 \pic[rotate=90] at (3,0) {braid={s_1 s_2^{-1}}};
314 \pic[rotate=180] at (6,0) {braid={s_1 s_2^{-1}}};
315 \pic[yscale=-1] at (9,0) {braid={s_1 s_2^{-1}}};
316 \end{tikzpicture}
317 \end{example}
318
319 The \Verb+crossing height+ and \Verb+height+ keys shouldn't be used together.
320 If they are then a message will be printed on the console and the value for \Verb+crossing height+ will be used.
321
322 \DescribeMacro{width}
323 The key \Verb+width+ sets the separation of the strands in the braid.
324 This can be negative (though the effect of a negative width would be better achieved with a transformation of `xscale=-1`).
325
326 \DescribeMacro{border height}
327 The key \Verb+border height+ adds a little extra length to the strands at the start and end of the braid.
328
329 \DescribeMacro{gap}
330 The key \Verb+gap+ is used to determine how much of a gap to leave in the under strand at a crossing.
331 This should be a number strictly between 0 and .5.
332 The curve is drawn using a cubic b\'ezier and the gap is in terms of the time parameter, so the gap will not increase exactly proportionally to the value given by this key, though that is a reasonable approximation.
333
334 \DescribeMacro{control factor}
335 As just said, the parts of the strands involved in a crossing are drawn using a cubic b\'ezier curve.
336 The control points are vertically above or below their respective end point.
337 This key determines that vertical separation.
338 It is multiplied by the \Verb+height+ so that it scales properly.
339 It can be set to 0 whereupon the strands in the crossing are straight lines.
340 The default is 0.5.
341
342 \DescribeMacro{nudge factor}
343 The crossings are not quite placed one after another.
344 There is a small ``nudge'' between the end of one crossing and the start of another.
345 Due to the way that the strands are lengthened, if there is no ``nudge'' then some PDF renderers produce slightly strange results at certain magnifications.
346 This key controls how much that ``nudge'' is, as a factor of the \Verb+height+.
347 For the aforementioned reason, it should not be set to 0 (the default is 0.05).
348 Note that this does not change the height of a crossing.
349 Rather, it nudges the height at which the strands start to cross over.
350
351 \bigskip
352
353 The following example illustrates the above keys.
354
355 \begin{example}
356 \begin{tikzpicture}
357 \pic[
358 draw,
359 ultra thick,
360 magenta,
361 braid/.cd,
362 border height=3mm,
363 nudge factor=.2,
364 gap=.3
365 ] (lengths) {braid={s_1 s_2}};
366 \draw (lengths-1-s) -- +(-1,0) coordinate (a);
367 \draw (lengths-1-0) -- +(-1,0) coordinate (b);
368 \draw (lengths-3-1) -- +(1,0) coordinate (c);
369 \draw (lengths-1-2) -- +(1,0) coordinate (d);
370 \draw (lengths-1-s) -- +(0,1) coordinate (e);
371 \draw (lengths-2-s) -- +(0,1) coordinate (f);
372 \draw (lengths-2-1) -- +(-1,0) coordinate (g);
373 \draw ($(lengths-2-1)!.2!(lengths-1-0)$) -- +(-1,0) coordinate (h);
374 \draw (lengths-1-1) -- +(.5,0) coordinate (i);
375 \draw ($(lengths-1-1)!.5!(lengths-2-0)$) -- +(.5,0) coordinate (j);
376 \draw[|<->|] (a) -- node[left] {border height} (b);
377 \draw[|<->|] (c) -- node[right] {crossing height} (d);
378 \draw[|<->|] (e) -- node[above] {width} (f);
379 \draw[|<->|] (g) -- node[left] {nudge factor} (h);
380 \draw[|<->|] (i) -- node[right] {control factor} (j);
381 \end{tikzpicture}
382 \end{example}
383
384 \DescribeMacro{every braid}
385 This style is invoked on a scope that surrounds the actual braid.
386 It can be used to set defaults for a group of braids.
387
388 \DescribeMacro{every strand, strand <n>}
389 The style of the strands are controlled by two types of option.
390 Style options that are set on the \Verb+pic+ are passed to every strand.
391 It is also possible to add style options to individual strands using the keys \Verb+every strand+ and \Verb+strand <n>+.
392 The strands are numbered by their starting position.
393
394 \DescribeMacro{every floor, floor <n>}
395 When a floor is requested behind a crossing, it is rendered as a pic.
396 These keys control how the floor is styled.
397 They can even be used to change the \Verb+pic+ used to draw individual floors.
398 The \Verb+n+ is the level number, starting at \(1\).
399
400 \begin{example}
401 \begin{tikzpicture}
402 \pic[
403 braid/floor 3/.style={
404 floor/.pic={
405 \path[pic actions, draw=none] (.5,.5) circle[x radius=.5, y radius=.5];
406 \path[pic actions, fill=none, dashed] (0,0) -- (1,0);
407 \path[pic actions, fill=none, dotted] (0,1) -- (1,1);
408 },
409 },
410 braid/every floor/.style={
411 fill=yellow,
412 draw=black
413 }
414 ] {braid={| s_1 s_2 | s_1^{-1}}};
415 \end{tikzpicture}
416 \end{example}
417
418 \subsection{Coordinates and Anchors}
419 \label{sec:coords}
420
421 The braid is littered with coordinates.
422 Each strand gets a coordinate at each end, and at every level between crossings.
423 These are labelled and numbered by the initial strand position and the crossing level.
424 They are also labelled and numbered by the final strand position with the prefix \Verb+rev+.
425 If the braid has been named, the coordinate names look like the following:
426 %
427 \begin{lstlisting}
428 <braid name>-<strand number>-<crossing number>
429 <braid name>-rev-<strand number>-<crossing number>
430 \end{lstlisting}
431 %
432 The crossing number can also be either \Verb+s+ or \Verb+e+ for the start and end of the strand.
433 Note that \Verb+-1-0+ and \Verb+-1-s+ are slightly different in that \Verb+s+ includes the border height.
434
435 \begin{example}
436 \begin{tikzpicture}
437 \pic[draw,braid/strand 1/.style={red}] (coords) {braid={s_1}};
438 \node[at=(coords-1-s),pin=west:strand 1 start] {};
439 \node[at=(coords-1-e),pin=east:strand 1 end] {};
440 \end{tikzpicture}
441 \end{example}
442
443 See Section~\ref{sec:picexamples} for more examples using these anchors.
444
445 In addition, if the braid is named then a rectangular node is defined that fits around the whole braid.
446 This node is not defined in the standard way, so -- for example -- it can't directly be used to draw a border, but TikZ behaves afterwards as if it were.
447 In particular its anchors can be used to define locations around the edge of the braid.
448
449 \begin{example}
450 \begin{tikzpicture}[ultra thick]
451 \pic (anchors) at (1,2) {braid={s_1 s_2}};
452 \draw[<-,cyan] (anchors.east) -- +(1,0) node[right] {east};
453 \draw[<-,cyan] (anchors.west) -- +(-1,0) node[left] {west};
454 \draw[<-,cyan] (anchors.north) -- +(0,1) node[above] {north};
455 \draw[<-,cyan] (anchors.south) -- +(0,-1) node[below] {south};
456 \end{tikzpicture}
457 \end{example}
458
459 \DescribeMacro{anchor}
460 The key \Verb+anchor+ (in the \Verb+braid+ name space) can be used to shift the braid so that a different part of it is at the specified location.
461 If the argument contains a hyphen then it is assumed to refer to a point on a strand with the same interpretation as the coordinates.
462 If the argument does not contain a hyphen then it is taken to be an anchor of a surrounding rectangular node (the node might not itself exist -- if the braid isn't named -- but that doesn't affect the positioning).
463 In the following example, the braid is shifted so that where the third strand starts the second level is at the position \Verb+(1,1)+.
464
465 \begin{example}
466 \begin{center}
467 \begin{tikzpicture}
468 \fill[purple] (1,1) circle[radius=3mm];
469 \pic[
470 rotate=90,
471 braid/anchor=3-2,
472 braid/strand 3/.style={red},
473 ] at (1,1) {braid={s_2 s_1 s_2 s_1}};
474 \end{tikzpicture}
475 \end{center}
476 \end{example}
477
478
479 \subsection{Examples}
480 \label{sec:picexamples}
481
482 Here are more detailed examples.
483
484 \begin{example}
485 \begin{center}
486 \begin{tikzpicture}
487 \pic[
488 braid/every floor/.style={fill=yellow},
489 braid/floor 1/.style={draw=black,dashed,fill=yellow!50!green},
490 line width=2pt,
491 braid/strand 1/.style={red},
492 braid/strand 2/.style={blue},
493 braid/strand 3/.style={green},
494 braid/add floor={2,4,3,2,a},
495 braid/floor a/.style={fill=pink},
496 name=coordinates,
497 ] at (2,0) {braid={| s_1-s_3-s_5 | s_2^{-1}-s_4| s_1-s_4 s_2^{-1} s_1-s_3 s_2^{-1}-s_4^{-1}}};
498 \fill[yellow] (2,0) circle (4pt);
499 \node[at=(coordinates-3-s),pin=north west:strand 3 start] {};
500 \node[at=(coordinates-3-e),pin=south west:strand 3 end] {};
501 \node[at=(coordinates-rev-3-s),pin=north east:strand 3 (from bottom) start] {};
502 \node[at=(coordinates-rev-3-e),pin=south east:strand 3 (from bottom) end] {};
503 \end{tikzpicture}
504 \end{center}
505 \end{example}
506
507 \begin{example}
508 \begin{center}
509 \begin{tikzpicture}
510 \pic[
511 braid/.cd,
512 number of strands=3,
513 line width=8pt,
514 strand 1/.style={red},
515 strand 2/.style={green},
516 strand 3/.style={blue},
517 gap=0.1,
518 control factor=0,
519 nudge factor=0,
520 name=symbols,
521 ] {braid={a_2 a_1 a_2^{-1} a_1}};
522 \node[circle,draw,fill=white,inner sep=0pt] at (symbols-2-1) {\(+\)};
523 \node[circle,draw,fill=white,inner sep=0pt] at (symbols-3-1) {\(-\)};
524 \node[circle,draw,fill=white,inner sep=0pt] at (symbols-2-3) {\(+\)};
525 \end{tikzpicture}
526 \end{center}
527
528 \end{example}
529
530 \begin{example}
531 \begin{center}
532 \begin{tikzpicture}
533 \pic[
534 braid/.cd,
535 number of strands=3,
536 ultra thick,
537 strand 1/.style={red},
538 strand 2/.style={green},
539 strand 3/.style={blue},
540 gap=0.1,
541 ] {braid={a_{1-3} a_{1,3}}};
542 \end{tikzpicture}
543 \end{center}
544
545 \end{example}
546
547 The next example uses the nonlinear transformations pgf module with the following definition.
548
549 \begin{lstlisting}
550 \usepgfmodule{nonlineartransformations}
551 \makeatletter
552 \def\polartransformation{%
553 % \pgf@x will contain the radius
554 % \pgf@y will contain the distance
555 \pgfmathsincos@{\pgf@sys@tonumber\pgf@x}%
556 % pgfmathresultx is now the cosine of radius and
557 % pgfmathresulty is the sine of radius
558 \pgf@x=\pgfmathresultx\pgf@y%
559 \pgf@y=\pgfmathresulty\pgf@y%
560 }
561 \makeatother
562 \end{lstlisting}
563
564 \begin{example}
565 \begin{tikzpicture}[scale=.5]
566 \begin{scope}
567 \pgftransformnonlinear{\polartransformation}% see above
568 \pic[
569 rotate=90,
570 braid/.cd,
571 every strand/.style={line width=6pt,magenta!67},
572 border height=0cm,
573 crossing height=15.7pt,
574 gap=.2,
575 nudge factor=0.01,
576 ] at (0,5) {braid=%
577 s_2^{-1} s_3 s_1 s_3 s_2^{-1} s_3 s_1 s_3
578 s_2^{-1} s_3 s_1 s_2^{-1} s_3 s_1 s_2^{-1}
579 s_1 s_3 s_1 s_2^{-1} s_1 s_3 s_1 s_2^{-1}
580 };
581 \end{scope}
582
583 \end{tikzpicture}
584 \end{example}
585
586 \newpage
587
588 Here's an example using a decoration library to style the strands.
589
590 \begin{justexample}
591 \begin{tikzpicture}[remember picture, overlay]
592 \pic[
593 decoration={
594 markings,
595 mark=between positions 2mm and 1 step 5mm with {
596 \draw[black,thick] (-2mm,-1.5mm) .. controls +(4mm,0) and +(-4mm,0) .. (2mm,1.5mm);
597 }
598 },
599 braid/number of strands=10,
600 braid/gap=.15,
601 braid/every strand/.style={
602 line width=3mm,
603 draw,
604 brown!50,
605 postaction={
606 decorate,
607 },
608 preaction={
609 draw,
610 black,
611 line width=3.3mm,
612 }
613 },
614 braid/every floor/.style={
615 draw
616 },
617 braid/height=-3cm,
618 braid/width=2cm,
619 braid/anchor=1-0,
620 ]
621 at ([shift={(2,-2)}]current page.north west)
622 {braid={
623 s_1-s_3-s_5^{-1}-s_7^{-1}
624 s_1-s_3-s_5^{-1}-s_7^{-1}
625 s_1-s_3-s_5^{-1}-s_7^{-1}
626 s_1-s_3-s_5^{-1}-s_7^{-1}
627 s_1-s_3-s_5^{-1}-s_7^{-1}
628 s_1-s_3-s_5^{-1}-s_7^{-1}
629 s_1-s_3-s_5^{-1}-s_7^{-1}
630 s_1-s_3-s_5^{-1}-s_7^{-1}
631 }};
632 \begin{scope}[shift={([shift={(1,-2)}]current page.north west)}]
633 \draw (0,0) grid[xstep=4cm,ystep=3cm] ++(20,-24.1);
634 \draw (18,0) -- +(0,-24.1);
635 \end{scope}
636 \end{tikzpicture}
637 \end{justexample}
638
639 \newpage
640
641 \begin{tikzpicture}[remember picture, overlay]
642 \pic[
643 decoration={
644 markings,
645 mark=between positions 2mm and 1 step 5mm with {
646 \draw[black,thick] (-2mm,-1.5mm) .. controls +(4mm,0) and +(-4mm,0) .. (2mm,1.5mm);
647 }
648 },
649 braid/number of strands=10,
650 braid/gap=.15,
651 braid/every strand/.style={
652 line width=3mm,
653 draw,
654 brown!50,
655 postaction={
656 decorate,
657 },
658 preaction={
659 draw,
660 black,
661 line width=3.3mm,
662 }
663 },
664 braid/every floor/.style={
665 draw
666 },
667 braid/height=-3cm,
668 braid/width=2cm,
669 braid/anchor=1-0,
670 ]
671 at ([shift={(2,-2)}]current page.north west)
672 {braid={
673 s_1-s_3-s_5^{-1}-s_7^{-1}
674 s_1-s_3-s_5^{-1}-s_7^{-1}
675 s_1-s_3-s_5^{-1}-s_7^{-1}
676 s_1-s_3-s_5^{-1}-s_7^{-1}
677 s_1-s_3-s_5^{-1}-s_7^{-1}
678 s_1-s_3-s_5^{-1}-s_7^{-1}
679 s_1-s_3-s_5^{-1}-s_7^{-1}
680 s_1-s_3-s_5^{-1}-s_7^{-1}
681 }};
682 \begin{scope}[shift={([shift={(1,-2)}]current page.north west)}]
683 \draw (0,0) grid[xstep=4cm,ystep=3cm] ++(20,-24.1);
684 \draw (18,0) -- +(0,-24.1);
685 \end{scope}
686 \end{tikzpicture}
687
688 \newpage
689
690 \section{Original Package Usage (Depreciated)}
691
692 The original version was as a separate package.
693 This is still included for backwards compatibility.
694 To use this package, you need to put the following in the preamble.
695
696 \begin{verbatim}
697 \usepackage{braids}
698 \end{verbatim}
699
700 This will generate a warning saying that it is preferable to use the TikZ library version.
701 To suppress this warning use the \Verb+nowarning+ option:
702
703 \begin{verbatim}
704 \usepackage[nowarning]{braids}
705 \end{verbatim}
706
707
708 \DescribeMacro{\braid}
709 A braid is specified by the command \Verb+\braid+.
710 The syntax for this command is as follows:
711
712 \Verb+\braid[style options] (name) at (coordinate) braid-word;+
713
714 \DescribeMacro{braid-word}
715 The \Verb+braid-word+ is an expression in the braid group, such as \Verb+s_1 s_2^{-1}+.
716 The generator labels are not significant.
717 The exponent can be \Verb+1+, \Verb+{-1}+, or missing (in which case it defaults to \Verb+1+, note also that the exponent is read as a \TeX-token so \Verb+{1}+ is also legal).
718 Certain other symbols are allowed in the \Verb+braid-word+ which control the rendering of the braid.
719 These extras are as follows.
720
721 \begin{enumerate}
722 \item To get crossings to render at the same height, separate them with a hyphen (note: no check is made to ensure that the crossings can legally be put at the same height; \emph{caveat emptor}).
723
724 \item To draw a \emph{floor}, precede the braid element by a vertical line.
725 What happens then is that when the braid is rendered, the coordinates of the rectangle behind that crossing (wide enough to encompass all the strands) is passed to a command.
726 The intention is that this command draw something behind the braid.
727 The command is configurable by a key (see \ref{sec:styleopts}).
728
729 \item The identity element can occur in the braid-word.
730 It is represented by \Verb+1+.
731 This inserts the identity which corresponds to no crossing.
732 However, it takes the same amount of space as if there were a crossing.
733
734 \item Strands can be labelled between crossings.
735 To do this, the commands \Verb+\label+, \Verb+\olabel+, and \Verb+\clabel+ are provided.
736 These take three arguments, the first is optional.
737 The result of this command is to place a node on top of a particular strand between the crossings where the command is given.
738 The first (optional) argument can be used to pass style options to this node.
739 The second argument is the strand number.
740 The third argument is the label text.
741
742 The three commands differ as to how they interpret the strand number.
743 For \Verb+\olabel+, the strand number is taken to mean the strand that starts at that position.
744 For \Verb+\clabel+, the strand number is taken to mean the strand that is currently at that position.
745 The behaviour of \Verb+\label+ is to choose one or other of these depending on whether the key \Verb+strand label by origin+ is true or false.
746 This key only has an effect at the start of the braid-word; it cannot be reset in the middle.
747
748 \item Style options can be given in the middle of a braid-word by enclosing them in square brackets.
749 There are not many style options that it makes sense to change in the middle of the braid-word, since the strands are rendered all in one go at the end.
750
751 \item Scoping is handled by using braces.
752 Thus to change a style only briefly, enclose the desired scope in braces.
753 \end{enumerate}
754
755 \DescribeMacro{name}
756 The (optional) \Verb+name+ acts a little like the \Verb+name+ of a TikZ node.
757 When it is specified, the routine that renders the braid also saves certain coordinates as if they were node anchors.
758 Specifically, \Verb+coordinate+ nodes are placed at the centre of the braid diagram and at the ends of each strand.
759 The centre has the label \Verb+name+, the strands are labelled \Verb+name-number-end+ and \Verb+name-rev-number-end+, where \Verb+name+ is the name given to the braid, \Verb+number+ is the number of the strand counting from the left, and \Verb+end+ is either \Verb+s+ for the start or \Verb+e+ for the end.
760 If the version with \Verb+rev+ is used then the numbers correspond to the \emph{final} positions of the braids.
761 The name can also be specified with the \Verb+name+ key.
762
763 \DescribeMacro{at}
764 The (optional) \Verb+at (coordinate)+ syntax positions the braid at the \Verb+coordinate+ in the current picture.
765 Due to the implementation, the coordinate has to be known at the start, but the width and height of the braid are only known at the end.
766 Therefore, the braid is positioned so that the start of the first strand is at \Verb+(coordinate)+.
767 This can also be specified using the \Verb+at+ key.
768
769 \DescribeMacro{style options}
770 The \Verb+style options+ set the style for the braid strands.
771 They can be grouped into three types: options that set up the main parameters for the braid, options that set the default style for the strands, and options that set up styles for individual strands.
772 The options are as follows.
773
774 \subsection{Style Options}
775 \label{sec:styleopts}
776
777 \DescribeMacro{number of strands} The key \Verb+number of strands+ sets the minimum number of strands for the braid.
778 The number of strands will grow according to the terms in the braid word so this merely sets a lower bound.
779 If not set, the number of strands will be determined by the terms in the braid word.
780
781 \DescribeMacro{height}
782 The key \Verb+height+ sets the height of the piece of the braid corresponding to an element in the group.
783
784 \DescribeMacro{width}
785 The key \Verb+width+ sets the separation of the strands in the braid.
786
787 \DescribeMacro{border height}
788 The key \Verb+border height+ adds a little extra length to the strands at the start and end of the braid.
789
790 \DescribeMacro{gap}
791 The key \Verb+gap+ is used to determine how much of a gap to leave in the under strand at a crossing.
792 This should be a number strictly between 0 and .5.
793 The curve is drawn using a cubic b\'ezier and the gap is in terms of the time parameter, so the gap will not increase exactly proportionally to the value given by this key, though that is a reasonable approximation.
794
795 \DescribeMacro{control factor}
796 As just said, the parts of the strands involved in a crossing are drawn using a cubic b\'ezier curve.
797 The control points are vertically above or below their respective end point.
798 This key determines that vertical separation.
799 It is multiplied by the \Verb+height+ so that it scales properly.
800 It can be set to 0 whereupon the strands in the crossing are straight lines.
801 The default is 0.5.
802
803 \DescribeMacro{nudge factor}
804 The crossings are not quite placed one after another.
805 There is a small ``nudge'' between the end of one crossing and the start of another.
806 Due to the way that the strands are lengthened, if there is no ``nudge'' then some PDF renderers produce slightly strange results at certain magnifications.
807 This key controls how much that ``nudge'' is, as a factor of the \Verb+height+.
808 For the aforementioned reason, it should not be set to 0 (the default is 0.05).
809 Note that this does not change the height of a crossing.
810 Rather, it nudges the height at which the strands start to cross over.
811
812 \DescribeMacro{style strands}
813 The style of the strands are controlled by two types of option.
814 Style options that are set on the \Verb+\braid+ command are passed to every strand.
815 It is also possible to add style options to individual strands using the key \Verb+style strands+.
816 This takes two options, a comma-delimited list of strand numbers (which could be just a single number) and a list of options to be applied to that strand.
817 Thus, the syntax is \Verb+style strands={n,m,...}{options}+.
818 The strands are numbered by their starting position.
819 Not all of the standard TikZ style options are possible due to the way that the strands are constructed.
820 Basically, the options that are allowed are those that do not require changing the path or drawing it more than once.
821
822 \DescribeMacro{floor command}
823 When a floor is requested behind a crossing, the actual way to render it is determined by a command.
824 This key allows the user to define that command.
825 The argument to this key should be the code that should be executed for each floor.
826 To avoid the hassle of getting the number of hashes right, the command should take no arguments.
827 Rather, the coordinates of the rectangle are saved in to macros \Verb+\floorsx+, \Verb+\floorsy+, \Verb+\floorex+, \Verb+\floorey+ (these macros will expand to something like \Verb+10pt+) and the command should use these to position the drawing.
828 The default is to draw a line at the top and at the bottom of the rectangle.
829
830 \DescribeMacro{style floors}
831 \DescribeMacro{style all floors}
832 In the spirit of separating \emph{style} and \emph{content}, the style options for the floors can be specified separately to the command (of course, they could be built in to the command).
833 One advantage of this over building them in to the command is to allow them to be overridden for individual floors.
834 The \Verb+style all floors+ sets up options to be used for \emph{all} floors, whilst the \Verb+style floors={n,m,...}{options}+ sets up options to be used only for the listed floor.
835 Anything specified in the \Verb+floor command+ will take precedence over both of these.
836
837 Any other style options are passed to the underlying TikZ/PGF system and so may influence how the braid is drawn (but note that not all keys make sense due to the implementation).
838
839
840 \subsection{Examples}
841 \label{sec:pkgexamples}
842
843 Here are more detailed examples.
844
845 \begin{example}
846 \begin{center}
847 \begin{tikzpicture}
848 \braid[
849 style all floors={fill=yellow},
850 style floors={1}{dashed,fill=yellow!50!green},
851 floor command={%
852 \fill (\floorsx,\floorsy) rectangle (\floorex,\floorey);
853 \draw (\floorsx,\floorsy) -- (\floorex,\floorsy);
854 },
855 line width=2pt,
856 style strands={1}{red},
857 style strands={2}{blue},
858 style strands={3}{green}
859 ] (strands) at (2,0) | s_1-s_3-s_5 | s_2^{-1}-s_4| s_1-s_4 s_2^{-1} s_1-s_3 s_2^{-1}-s_4^{-1};
860 \fill[yellow] (2,0) circle (4pt);
861 \fill[purple] (strands) circle (4pt);
862 \node[at=(strands-3-s),pin=north west:strand 3] {};
863 \node[at=(strands-3-e),pin=south west:strand 3] {};
864 \node[at=(strands-rev-3-s),pin=north east:strand 3 (from bottom)] {};
865 \node[at=(strands-rev-3-e),pin=south east:strand 3 (from bottom)] {};
866 \end{tikzpicture}
867 \end{center}
868 \end{example}
869
870 \begin{example}
871 \begin{center}
872 \begin{tikzpicture}
873 \braid[
874 number of strands=3,
875 line width=8pt,
876 style strands={1}{red},
877 style strands={2}{green},
878 style strands={3}{blue},
879 gap=0.1,
880 control factor=0,
881 nudge factor=0,
882 strand label by origin=true,
883 strand label/.style={circle,draw,fill=white,inner sep=0pt},
884 yscale=1] (braid_1) a_2 \label{2}{\(+\)} \clabel{2}{\(-\)} a_1 a_2^{-1} \olabel{2}{\(+\)} a_1;
885 \end{tikzpicture}
886 \end{center}
887
888 \end{example}
889
890 \end{document}
891 % Local Variables:
892 % tex-output-type: "pdf18"
893 % End: