diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/braids/braids.tex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/braids/braids.tex | 481 |
1 files changed, 481 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/braids/braids.tex b/Master/texmf-dist/doc/latex/braids/braids.tex new file mode 100644 index 00000000000..7dab9f08738 --- /dev/null +++ b/Master/texmf-dist/doc/latex/braids/braids.tex @@ -0,0 +1,481 @@ +\documentclass{ltxdoc} +\usepackage[T1]{fontenc} +\usepackage{lmodern} +\usepackage{morefloats} +\usepackage{tikz} +\usepackage{braids} +\usetikzlibrary{braids} +\usepackage[numbered]{hypdoc} +\definecolor{lstbgcolor}{rgb}{0.9,0.9,0.9} + +\usepackage{listings} +\lstloadlanguages{[LaTeX]TeX} +\lstset{breakatwhitespace=true,breaklines=true,language=TeX} + +\usepackage{fancyvrb} + +\newenvironment{example} + {\VerbatimEnvironment + \begin{VerbatimOut}{example.out}} + {\end{VerbatimOut} + \begin{center} + \setlength{\parindent}{0pt} + \fbox{\begin{minipage}{.9\linewidth} + \lstset{breakatwhitespace=true,breaklines=true,language=TeX,basicstyle=\small} + \lstinputlisting[]{example.out} + \end{minipage}} + + \fbox{\begin{minipage}{.9\linewidth} + \input{example.out} + \end{minipage}} +\end{center} +} + +\providecommand*{\url}{\texttt} +\GetFileInfo{tikzlibrarybraids.code.tex} + +\title{The \textsf{braids} Package: Documentation} +\author{Andrew Stacey \\ \texttt{loopspace@mathforge.org}} +\date{\fileversion~from \filedate} + +\begin{document} + +\maketitle + +\begin{center} + \begin{tikzpicture} + \pic[ + line width=1.5pt, + red, + line cap=round, + braid/.cd, + width=.75cm, + height=.5cm, + strand 3/.style={gray,line width=1pt}, + strand 6/.style={gray,line width=1pt}, + strand 7/.style={gray,line width=1pt}, + strand 10/.style={gray,line width=1pt}, + strand 14/.style={gray,line width=1pt}, + strand 15/.style={gray,line width=1pt}, + strand 16/.style={gray,line width=1pt}, + strand 18/.style={gray,line width=1pt}, + ] {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}}}; +\end{tikzpicture} +\end{center} + +\section{Introduction} + +This is a package for drawing braid diagrams using PGF/TikZ. +An example follows. + +\begin{example} +\begin{center} +\begin{tikzpicture} +\pic[ + rotate=90, + braid/.cd, + every strand/.style={ultra thick}, + strand 1/.style={red}, + strand 2/.style={green}, + strand 3/.style={blue}, +] {braid={s_1 s_2^{-1} s_1 s_2^{-1} s_1 s_2^{-1}}}; +\end{tikzpicture} +\end{center} +\end{example} + +\section{TikZ Library Usage} + +Version 2.0 changed the implementation to use the TikZ \Verb+pic+ syntax. +It also converted it to a TikZ library, so to use it put the following in the preamble. + +\begin{verbatim} +\usetikzlibrary{braids} +\end{verbatim} + +(Or add it to the copious list of TikZ libraries that you are already using.) + +\bigskip + +\DescribeMacro{braid} +A braid is specified by the pic name \Verb+braid+. +The usual syntax for this is as follows: + +\Verb+\pic[options] at (coordinate) {braid={braid-word}};+ + +\DescribeMacro{braid-word} +The \Verb+braid-word+ is an expression in the braid group, such as \Verb+s_1 s_2^{-1} s_{3,5}+. +The generator labels are not significant. +If the subscript is a single number, as in \Verb+s_2+, the crossing goes from that number over the next. +If the subscript is two numbers, as in \Verb+s_{2,4}+, the crossing goes from the first over the second, with both the crossing strands passing over all of the intervening strands. +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). +If the exponent is \(-1\) then the over and under strands swap. + +\begin{itemize} +\item \Verb+s_1+ is strand \(1\) over strand \(2\). +\item \Verb+s_1^{-1}+ is strand \(2\) over strand \(1\). +\item \Verb+s_{1,3}+ is strand \(1\) over strand \(3\), and both are over strand \(2\). +\end{itemize} + +Certain other symbols are allowed in the \Verb+braid-word+ which control the rendering of the braid. +These extras are as follows. + +\begin{enumerate} +\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}). +For example, \Verb+s_1-s_3+. + +\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+. +The floor is itself a pic which, by default, consists of a rectangle and two horizontal lines. +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. +The \Verb+n+ is the level number, starting at \(1\). + +More general floors can be drawn using the key \Verb+braid/add floor+. +This takes one argument which is a comma separated list of parameters that specifies the position and size floor: +% +\begin{verbatim} +braid/add floor={x,y,width,height,name} +\end{verbatim} +% +The units used are the ``natural'' units of the braid: strand separation and level height. +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. + +Replacing the floor pic will change how it is drawn. +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. + +\item The identity element can occur in the braid-word. +It is represented by \Verb+1+. +This inserts the identity which corresponds to no crossing. +However, it takes the same amount of space as if there were a crossing. + +\end{enumerate} + +\subsection{Style Options} +\label{sec:picstyleopts} + +There are various keys that change the behaviour or rendering of the braid. +All of these are in the \Verb+/tikz/braid/+ namespace. + +\DescribeMacro{number of strands} The key \Verb+number of strands+ sets the minimum number of strands for the braid. +The number of strands will grow according to the terms in the braid word so this merely sets a lower bound. +If not set, the number of strands will be determined by the terms in the braid word. + +\DescribeMacro{height} +The key \Verb+height+ sets the height of the piece of the braid corresponding to an element in the group. +This can be negative. + +\DescribeMacro{width} +The key \Verb+width+ sets the separation of the strands in the braid. +This can be negative. + +\DescribeMacro{border height} +The key \Verb+border height+ adds a little extra length to the strands at the start and end of the braid. + +\DescribeMacro{gap} +The key \Verb+gap+ is used to determine how much of a gap to leave in the under strand at a crossing. +This should be a number strictly between 0 and .5. +The curve is drawn using a cubic bezier 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. + +\DescribeMacro{control factor} +As just said, the parts of the strands involved in a crossing are drawn using a cubic bezier curve. +The control points are vertically above or below their respective end point. +This key determines that vertical separation. +It is multiplied by the \Verb+height+ so that it scales properly. +It can be set to 0 whereupon the strands in the crossing are straight lines. +The default is 0.5. + +\DescribeMacro{nudge factor} +The crossings are not quite placed one after another. +There is a small ``nudge'' between the end of one crossing and the start of another. +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. +This key controls how much that ``nudge'' is, as a factor of the \Verb+height+. +For the aforementioned reason, it should not be set to 0 (the default is 0.05). +Note that this does not change the height of a crossing. +Rather, it nudges the height at which the strands start to cross over. + +\DescribeMacro{every strand, strand <n>} +The style of the strands are controlled by two types of option. +Style options that are set on the \Verb+pic+ are passed to every strand. +It is also possible to add style options to individual strands using the keys \Verb+every strand+ and \Verb+strand <n>+. +The strands are numbered by their starting position. + +\DescribeMacro{every floor, floor <n>} +When a floor is requested behind a crossing, it is rendered as a pic. +These keys control how the floor is styled. + +\subsection{Coordinates and Anchors} + +The braid is littered with coordinates. +Each strand gets a coordinate at each end, and at every level between crossings. +These are labelled and numbered by the initial strand position and the crossing level. +They are also labelled and numbered by the final strand position with the prefix \Verb+rev+. +With a \Verb+name prefix+, the coordinate names look like the following: +% +\begin{verbatim} +<name prefix>-<strand number>-<crossing number> +<name prefix>-rev-<strand number>-<crossing number> +\end{verbatim} +% +The crossing number can also be either \Verb+s+ or \Verb+e+ for the start and end of the strand. +Note that \Verb+-1-0+ and \Verb+-1-s+ are slightly different in that \Verb+s+ includes the border height. + +\DescribeMacro{anchor} +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. +It uses the same syntax as the coordinates, except without the \Verb+<name prefix>-+. +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)+ + +\begin{example} +\begin{center} +\begin{tikzpicture} +\fill[purple] (1,1) circle[radius=3mm]; +\pic[braid/anchor=3-2,rotate=90] at (1,1) {braid={s_2 s_1 s_2 s_1}}; +\end{tikzpicture} +\end{center} +\end{example} + + +\section{Examples} + +Here are more detailed examples. + +\begin{example} +\begin{center} +\begin{tikzpicture} +\pic[ + braid/every floor/.style={fill=yellow}, + braid/floor 1/.style={draw=black,dashed,fill=yellow!50!green}, + line width=2pt, + braid/strand 1/.style={red}, + braid/strand 2/.style={blue}, + braid/strand 3/.style={green}, + braid/add floor={2,4,3,2,a}, + braid/floor a/.style={fill=pink}, + name prefix=braid, +] 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}}}; +\fill[yellow] (2,0) circle (4pt); +\node[at=(braid-3-s),pin=north west:strand 3 start] {}; +\node[at=(braid-3-e),pin=south west:strand 3 end] {}; +\node[at=(braid-rev-3-s),pin=north east:strand 3 (from bottom) start] {}; +\node[at=(braid-rev-3-e),pin=south east:strand 3 (from bottom) end] {}; +\end{tikzpicture} +\end{center} +\end{example} + +\begin{example} +\begin{center} +\begin{tikzpicture} +\pic[ + braid/.cd, + number of strands=3, + line width=8pt, + strand 1/.style={red}, + strand 2/.style={green}, + strand 3/.style={blue}, + gap=0.1, + control factor=0, + nudge factor=0, + name prefix=braid, +] {braid={a_2 a_1 a_2^{-1} a_1}}; +\node[circle,draw,fill=white,inner sep=0pt] at (braid-2-1) {\(+\)}; +\node[circle,draw,fill=white,inner sep=0pt] at (braid-3-1) {\(-\)}; +\node[circle,draw,fill=white,inner sep=0pt] at (braid-2-3) {\(+\)}; +\end{tikzpicture} +\end{center} + +\end{example} + +\newpage + +\section{Original Package Usage (Depreciated)} + +The original version was as a separate package. +This is still included for backwards compatibility. +To use this package, you need to put the following in the preamble. + +\begin{verbatim} +\usepackage{braids} +\end{verbatim} + +\DescribeMacro{\braid} +A braid is specified by the command \Verb+\braid+. +The syntax for this command is as follows: + +\Verb+\braid[style options] (name) at (coordinate) braid-word;+ + +\DescribeMacro{braid-word} +The \Verb+braid-word+ is an expression in the braid group, such as \Verb+s_1 s_2^{-1}+. +The generator labels are not significant. +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). +Certain other symbols are allowed in the \Verb+braid-word+ which control the rendering of the braid. +These extras are as follows. + +\begin{enumerate} +\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}). + +\item To draw a \emph{floor}, precede the braid element by a vertical line. +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. +The intention is that this command draw something behind the braid. +The command is configurable by a key (see \ref{sec:styleopts}). + +\item The identity element can occur in the braid-word. +It is represented by \Verb+1+. +This inserts the identity which corresponds to no crossing. +However, it takes the same amount of space as if there were a crossing. + +\item Strands can be labelled between crossings. +To do this, the commands \Verb+\label+, \Verb+\olabel+, and \Verb+\clabel+ are provided. +These take three arguments, the first is optional. +The result of this command is to place a node on top of a particular strand between the crossings where the command is given. +The first (optional) argument can be used to pass style options to this node. +The second argument is the strand number. +The third argument is the label text. + +The three commands differ as to how they interpret the strand number. +For \Verb+\olabel+, the strand number is taken to mean the strand that starts at that position. +For \Verb+\clabel+, the strand number is taken to mean the strand that is currently at that position. +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. +This key only has an effect at the start of the braid-word; it cannot be reset in the middle. + +\item Style options can be given in the middle of a braid-word by enclosing them in square brackets. +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. + +\item Scoping is handled by using braces. +Thus to change a style only briefly, enclose the desired scope in braces. +\end{enumerate} + +\DescribeMacro{name} +The (optional) \Verb+name+ acts a little like the \Verb+name+ of a TikZ node. +When it is specified, the routine that renders the braid also saves certain coordinates as if they were node anchors. +Specifically, \Verb+coordinate+ nodes are placed at the centre of the braid diagram and at the ends of each strand. +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. +If the version with \Verb+rev+ is used then the numbers correspond to the \emph{final} positions of the braids. +The name can also be specified with the \Verb+name+ key. + +\DescribeMacro{at} +The (optional) \Verb+at (coordinate)+ syntax positions the braid at the \Verb+coordinate+ in the current picture. +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. +Therefore, the braid is positioned so that the start of the first strand is at \Verb+(coordinate)+. +This can also be specified using the \Verb+at+ key. + +\DescribeMacro{style options} +The \Verb+style options+ set the style for the braid strands. +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. +The options are as follows. + +\subsection{Style Options} +\label{sec:styleopts} + +\DescribeMacro{number of strands} The key \Verb+number of strands+ sets the minimum number of strands for the braid. +The number of strands will grow according to the terms in the braid word so this merely sets a lower bound. +If not set, the number of strands will be determined by the terms in the braid word. + +\DescribeMacro{height} +The key \Verb+height+ sets the height of the piece of the braid corresponding to an element in the group. + +\DescribeMacro{width} +The key \Verb+width+ sets the separation of the strands in the braid. + +\DescribeMacro{border height} +The key \Verb+border height+ adds a little extra length to the strands at the start and end of the braid. + +\DescribeMacro{gap} +The key \Verb+gap+ is used to determine how much of a gap to leave in the under strand at a crossing. +This should be a number strictly between 0 and .5. +The curve is drawn using a cubic bezier 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. + +\DescribeMacro{control factor} +As just said, the parts of the strands involved in a crossing are drawn using a cubic bezier curve. +The control points are vertically above or below their respective end point. +This key determines that vertical separation. +It is multiplied by the \Verb+height+ so that it scales properly. +It can be set to 0 whereupon the strands in the crossing are straight lines. +The default is 0.5. + +\DescribeMacro{nudge factor} +The crossings are not quite placed one after another. +There is a small ``nudge'' between the end of one crossing and the start of another. +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. +This key controls how much that ``nudge'' is, as a factor of the \Verb+height+. +For the aforementioned reason, it should not be set to 0 (the default is 0.05). +Note that this does not change the height of a crossing. +Rather, it nudges the height at which the strands start to cross over. + +\DescribeMacro{style strands} +The style of the strands are controlled by two types of option. +Style options that are set on the \Verb+\braid+ command are passed to every strand. +It is also possible to add style options to individual strands using the key \Verb+style strands+. +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. +Thus, the syntax is \Verb+style strands={n,m,...}{options}+. +The strands are numbered by their starting position. +Not all of the standard TikZ style options are possible due to the way that the strands are constructed. +Basically, the options that are allowed are those that do not require changing the path or drawing it more than once. + +\DescribeMacro{floor command} +When a floor is requested behind a crossing, the actual way to render it is determined by a command. +This key allows the user to define that command. +The argument to this key should be the code that should be executed for each floor. +To avoid the hassle of getting the number of hashes right, the command should take no arguments. +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. +The default is to draw a line at the top and at the bottom of the rectangle. + +\DescribeMacro{style floors} +\DescribeMacro{style all floors} +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). +One advantage of this over building them in to the command is to allow them to be overridden for individual floors. +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. +Anything specified in the \Verb+floor command+ will take precedence over both of these. + +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). + + +\section{Examples} + +Here are more detailed examples. + +\begin{example} +\begin{center} +\begin{tikzpicture} +\braid[ + style all floors={fill=yellow}, + style floors={1}{dashed,fill=yellow!50!green}, + floor command={% + \fill (\floorsx,\floorsy) rectangle (\floorex,\floorey); + \draw (\floorsx,\floorsy) -- (\floorex,\floorsy); + }, + line width=2pt, + style strands={1}{red}, + style strands={2}{blue}, + style strands={3}{green} +] (braid) 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}; +\fill[yellow] (2,0) circle (4pt); +\fill[purple] (braid) circle (4pt); +\node[at=(braid-3-s),pin=north west:strand 3] {}; +\node[at=(braid-3-e),pin=south west:strand 3] {}; +\node[at=(braid-rev-3-s),pin=north east:strand 3 (from bottom)] {}; +\node[at=(braid-rev-3-e),pin=south east:strand 3 (from bottom)] {}; +\end{tikzpicture} +\end{center} +\end{example} + +\begin{example} +\begin{center} +\begin{tikzpicture} +\braid[ + number of strands=3, + line width=8pt, + style strands={1}{red}, + style strands={2}{green}, + style strands={3}{blue}, + gap=0.1, + control factor=0, + nudge factor=0, + strand label by origin=true, + strand label/.style={circle,draw,fill=white,inner sep=0pt}, + yscale=1] (braid_1) a_2 \label{2}{\(+\)} \clabel{2}{\(-\)} a_1 a_2^{-1} \olabel{2}{\(+\)} a_1; +\end{tikzpicture} +\end{center} + +\end{example} + +\end{document} +% Local Variables: +% tex-output-type: "pdf18" +% End: |