summaryrefslogtreecommitdiff
path: root/graphics
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2024-01-13 03:01:12 +0000
committerNorbert Preining <norbert@preining.info>2024-01-13 03:01:12 +0000
commit65fecaf48c4ed6505cb45447a2d7cf1b9d933e3a (patch)
treec56b603d6058668578165093bb5ff98e735e0fe8 /graphics
parent1748d1e662c9618cc16f80d5e67669e9e9d6d4be (diff)
CTAN sync 202401130301
Diffstat (limited to 'graphics')
-rw-r--r--graphics/pgf/contrib/bodeplot/README.md69
-rw-r--r--graphics/pgf/contrib/bodeplot/bodeplot-doc.pdfbin1056779 -> 1085542 bytes
-rw-r--r--graphics/pgf/contrib/bodeplot/bodeplot.dtx321
-rw-r--r--graphics/pgf/contrib/braids/README.txt11
-rw-r--r--graphics/pgf/contrib/braids/braids.pdfbin301271 -> 387688 bytes
-rw-r--r--graphics/pgf/contrib/braids/braids.tex479
-rw-r--r--graphics/pgf/contrib/braids/braids_code.dtx159
-rw-r--r--graphics/pgf/contrib/braids/braids_code.pdfbin456447 -> 463012 bytes
8 files changed, 815 insertions, 224 deletions
diff --git a/graphics/pgf/contrib/bodeplot/README.md b/graphics/pgf/contrib/bodeplot/README.md
index 70ed10b0ee..90284d2e2f 100644
--- a/graphics/pgf/contrib/bodeplot/README.md
+++ b/graphics/pgf/contrib/bodeplot/README.md
@@ -1,11 +1,17 @@
# bodeplot
LaTeX package to plot Bode, Nichols, and Nyquist diagrams.
-
Inspired by the `bodegraph` package.
-*Version 1.0.8 and newer store `gnuplot` temporary files in the working directory. Use class option `declutter` to restore pre-v1.0.8 behavior. Option `declutter` can cause errors if used with a `tikzexternalize` prefix.*
+Author: Rushikesh Kamalapurkar ([rlkamalapurkar@gmail.com](mailto:rlkamalapurkar@gmail.com))
+
+License: [LPPL-1.3c](https://github.com/rlkamalapurkar/bodeplot/blob/main/LICENSE)
-Compilation instructions:
+## Limitations
+ 1. If `bable` is used with the French language option, it needs to be loaded before `bodeplot` is loaded. Also, the `french` option to `babel` has to be passed locally, not via class options.
+ 2. TF commands are wrapped between -180 and 180 degrees in `pgf` mode.
+ 3. Version 1.0.8 and newer store `gnuplot` temporary files in the working directory. Use class option `declutter` to restore pre-v1.0.8 behavior. Option `declutter` can cause errors if used with a `tikzexternalize` prefix.
+
+## Compilation instructions
1) `latex bodeplot.ins` to generate `bodeplot.sty`
2) To compile documentation (needs `gnuplot` on system PATH):
```
@@ -15,8 +21,9 @@ makeindex -s gglo.ist -o bodeplot.gls bodeplot.glo
pdflatex bodeplot.dtx --shell-escape
pdflatex bodeplot.dtx --shell-escape
```
-Added functionality:
+## Added functionality over `bodegraph`
- New `\BodeZPK` and `\BodeTF` commands to generate Bode plots of any transfer function given either poles, zeros, gain, and delay, or numerator and denominator coefficients and delay
+ - All plots are fully customizable using `pgf` options (see package documentation for a full list of commands, environments, and options)
- Support for unstable poles and zeros.
- Support for complex poles and zeros.
- Support for general stable and unstable second order transfer functions.
@@ -25,33 +32,29 @@ Added functionality:
- Support for `deg` (default) and `rad` (package option `rad` or `pgf` key `phase unit=rad` for per-plot change) phase units.
- Support for linear and asymptotic approximation of magnitude and phase plots of any transfer function given poles, zeros, and gain.
-Main Bode/Nyquist/Nichols commands:
-Given Zeros, Poles, Gain, and Delay (Bode plots support asymptotic and linear approximation for systems without delays):
- - `\BodeZPK[object1/type1/{options1},object2/type2/{options2},...]{z/{zeros},p/{poles},k/gain,d/delay}{min-frequency}{max-frequency}`
- - `\NicholsZPK[plot/{options},axes/{options}]{z/{zeros},p/{poles},k/gain,d/delay}{min-frequency}{max-frequency}`
- - `\NyquistZPK[plot/{options},axes/{options}]{z/{zeros},p/{poles},k/gain,d/delay}{min-frequency}{max-frequency}`
-
-Given Numerator and denominator coefficients and delay (does not support approximation yet):
- - `\BodeTF[object1/type1/{options1},object2/type2/{options2},...]{num/{coeff},den/{coeff},d/delay}{min-frequency}{max-frequency}`
- - `\NicholsTF[plot/{options},axes/{options}]{num/{coeff},den/{coeff},d/delay}`
- - `\NyquistTF[plot/{options},axes/{options}]{num/{coeff},den/{coeff},d/delay}`
-
-Other new environments and associated commands:
- - `BodePlot` environment
- - `\addBodeZPKPlots[{approximation1/{plot-options1}},{approximation2/{plot-options2}},...]{plot-type (phase or magnitude)}{z/{zeros},p/{poles},k/gain,d/delay}`
- - `\addBodeTFPlot[plot-options]{plot-type (phase or magnitude)}{num/{coeff},den/{coeff},d/delay}`
- - `\addBodeComponentPlot[plot-options]{basic_component_plot_command}`
- - Basic component plot commands: ***(append `Lin` to get linear approximation and `Asymp` to get asymptotic approximation)*** ***(change `Pole` to `Zero` to get inverse plots)*** ***(change `Mag` to `Ph` to get phase plots)***
- - `\MagK{a}` - Pure gain, G(s) = a.
- - `\MagPole{a}{b}` - Single pole at s = a+bi, G(s) = 1/(s - a-bi).
- - `\MagCSPoles{z}{w}` - Cannonical Second order system, G(s) = 1/(s^2 + 2zws + w^2).
- - `\MagSOPoles{a}{b}` - Second Order system, G(s) = 1/(s^2 + as + b).
- - `\MagDel{T}` - Pure delay, G(s) = exp(-Ts) (does not admit asymptotic approximation).
- - `NicholsChart` environment
- - `\addNicholsZPKChart[plot-options]{z/{zeros},p/{poles},k/gain,d/delay}`
- - `\addNicholsTFChart[plot-options]{num/{coeff},den/{coeff},d/delay}`
- - `NyquistPlot` environment
- - `\addNyquistZPKPlot[plot-options]{z/{zeros},p/{poles},k/gain,d/delay}`
- - `\addNyquistTFPlot[plot-options]{num/{coeff},den/{coeff},d/delay}`
+## Basic Bode/Nyquist/Nichols commands
+*See package documentation for a full list of commands, environments, and options.*
+ - Given Zeros, Poles, Gain, and Delay (asymptotic and linear approximation available for systems without delay):
+```
+\BodeZPK % (OR \NicholsZPK[samples=1000] OR NyquistZPK[samples=1000])
+{%
+ z/{0,{-0.1,-0.5},{-0.1,0.5}}, % zeros at s = 0, s = -0.1 - 0.5j, and s = -0.1 + 0.5j
+ p/{{-0.5,-10},{-0.5,10}}, % poles at s = -0.5 - 10j, and s = -0.5 + 10j
+ k/10, % gain
+ d/0.01, % delay
+}
+{0.01} % frequency range start
+{100} % frequency range end
+```
-Limitation: TF commands are wrapped between 0 and 360 degrees in `pgf` mode.
+ - Given Numerator and denominator coefficients and delay (does not support approximation):
+```
+\BodeTF % (OR \NicholsTF[samples=1000] OR NyquistTF[samples=1000])
+{%
+ num/{10,2,2.6,0}, % numerator coefficients
+ den/{1,1,100.25}, % denominator coefficients
+ d/0.01, % delay
+}
+{0.001} % frequency range start
+{100} % frequency range end
+```
diff --git a/graphics/pgf/contrib/bodeplot/bodeplot-doc.pdf b/graphics/pgf/contrib/bodeplot/bodeplot-doc.pdf
index beef350836..bc4da652f2 100644
--- a/graphics/pgf/contrib/bodeplot/bodeplot-doc.pdf
+++ b/graphics/pgf/contrib/bodeplot/bodeplot-doc.pdf
Binary files differ
diff --git a/graphics/pgf/contrib/bodeplot/bodeplot.dtx b/graphics/pgf/contrib/bodeplot/bodeplot.dtx
index 17c1b53119..c7fcd076e6 100644
--- a/graphics/pgf/contrib/bodeplot/bodeplot.dtx
+++ b/graphics/pgf/contrib/bodeplot/bodeplot.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 2021 by Rushikesh Kamalapurkar <rlkamalapurkar@gmail.com>
+% Copyright (C) 2021-2024 by Rushikesh Kamalapurkar <rlkamalapurkar@gmail.com>
% -----------------------------------------------------------
%
% This file may be distributed and/or modified under the conditions of
@@ -20,7 +20,7 @@
%<package>\ProvidesPackage{bodeplot}
%<package>\RequirePackage{pdftexcmds}
%<package>\RequirePackage{ifplatform}
-%<package>\RequirePackage{environ}
+%<package>\RequirePackage{xparse}
%<package>\RequirePackage{pgfplots}
%<package> \pgfplotsset{compat=1.18}
%<package> \usepgfplotslibrary{groupplots}
@@ -30,6 +30,7 @@
\usepackage{cprotect}
\usepackage[declutter]{bodeplot}
\usepackage[colorlinks]{hyperref}
+\usepackage{fancyvrb }
\usepackage{iftex}
\iftutex % LuaTeX, XeTeX
\usepackage{fontspec}
@@ -68,7 +69,7 @@
%</driver>
% \fi
%
-% \CheckSum{1645}
+% \CheckSum{1758}
%
% \changes{v1.0}{2021/10/25}{Initial release}
% \changes{v1.0.4}{2021/11/05}{Fixed unintended optional argument macro expansion}
@@ -78,11 +79,12 @@
% \changes{v1.0.8}{2022/07/06}{Added a new class option `declutter'}
% \changes{v1.1.0}{2022/07/06}{Fixed phase wrapping in gnuplot mode}
% \changes{v1.1.1}{2022/07/31}{Enable Hz and rad units}
+% \changes{v1.1.5}{2024/01/11}{Detect `babel-french' to handle active characters}
%
% \GetFileInfo{bodeplot.sty}
% \DoNotIndex{\newcommand,\xdef,\gdef,\def,\edef,\addplot,\approx,\arabic,\opt,\typ,\obj,\else,\if@pgfarg,\if@Hzarg,\if@radarg,\if@declutterarg,\fi,\begin,\end,\feature,\footnotesize,\draw,\detokenize,\DeclareOption,\foreach,\ifdim,\ifodd,\Im,\Re,\let,\newif,\nextgroupplot,\noexpand,\expandafter,\unexpanded,\PackageError,\PackageWarning,\relax,\RequirePackage,\tikzset,\pgfmathsetmacro,\pgfmathtruncatemacro,\ProcessOptions}
%
-% \title{The \textsf{bodeplot} package\\version 1.1.4}
+% \title{The \textsf{bodeplot} package\\version 1.1.5}
% \author{Rushikesh Kamalapurkar \\ \texttt{rlkamalapurkar@gmail.com}}
%
% \maketitle
@@ -103,6 +105,7 @@
% Since version 1.0.8, the |bodeplot| package places all |gnuplot| temporary files in the working directory. The package option |declutter| restores the original behavior where the temporary files are placed in a folder called |gnuplot|.
% \subsection{Limitations}
% \begin{itemize}
+% \item If French language support is needed through the |babel| package, \textbf{the |babel| package has to be loaded before the |bodeplot| package}. The options |french| or |main=french| need to be passed to |babel| locally, and not via class options.
% \item In |pgf| mode, Bode phase plots and Nichols charts in TF form wrap angles so that they are always between -180 and 180$^\circ$ or $-\pi$ and $-\pi$ radian. As such, these plots will show phase wrapping discontinuities. Since v1.1.1, in |gnuplot| mode, the package uses the |smooth unwrap| filter to correct wrapping discontinuities. As of now, I have not found a way to do this in |pgf| mode, any merge requests or ideas you may have are welcome! Since v1.1.4, you can redefine the |n@mod| macro using the commands |\makeatletter\renewcommand{\n@mod}{\n@mod@p}\makeatother| to wrap the phase between 0 and 360$^\circ$ or $0$ and $2\pi$ radian. The commands |\makeatletter\renewcommand{\n@mod}{\n@mod@n}\makeatother| will wrap the phase between -360 and 0$^\circ$ or $-2\pi$ and $0$ radian.
% \item Use of the |declutter| option with other directory management tools such as a |tikzexternalize| prefix is not recommended.
% \end{itemize}
@@ -456,28 +459,33 @@ Nyquist plots with additional commands, using two different macros
% \end{itemize}
% The options |{opt}| can be any |key=value| options that are supported by the |pgfplots| macros they are added to.
-% For example, given a transfer function \begin{equation}G(s) = 10\frac{s(s+0.1+0.5\mathrm{i})(s+0.1-0.5\mathrm{i})}{(s+0.5+10\mathrm{i})(s+0.5-10\mathrm{i})},\label{eq:ZPKExample}\end{equation} its Bode plot over the frequency range $[0.01,100]$ can be generated using\\
-% |\BodeZPK [blue,thick]|\\
-% | {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}|\\
-% | {0.01}{100}|\\
-% which generates the plot in Figure \ref{simpleBode}. If a delay is not specified, it is assumed to be zero. If a gain is not specified, it is assumed to be 1. By default, each of the axes, excluding ticks and labels, are 5cm wide and 2.5cm high. The width and the height, along with other properties of the plots, the axes, and the group can be customized using native |pgf| keys as shown in the example below.
+% For example, given a transfer function \begin{equation}G(s) = 10\frac{s(s+0.1+0.5\mathrm{i})(s+0.1-0.5\mathrm{i})}{(s+0.5+10\mathrm{i})(s+0.5-10\mathrm{i})},\label{eq:ZPKExample}\end{equation} its Bode plot over the frequency range $[0.01,100]$ can be generated using
+%\begin{verbatim}
+%\BodeZPK [blue,thick]
+% {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}
+% {0.01}{100}
+%\end{verbatim}
+% which generates the plot in Figure \ref{simpleBode}. In this example, a delay is not specified, so it is assumed to be zero. A gain is not specified, so it is assumed to be 1. A single comma-separated list of options |[blue,thick]| is passed, so it is passed on to the |\addplot| commands in both the magnitude and the phase plots. The default plots are thick black lines and each of the axes, excluding ticks and labels, are 5cm wide and 2.5cm high.
%
% \begin{figure}
% \begin{center}
% \BodeZPK[blue,thick]{z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}{0.01}{100}
-% \cprotect\caption{\label{simpleBode}Output of the default |\BodeZPK| macro.}
+% \cprotect\caption{\label{simpleBode}Output of the |\BodeZPK| macro.}
% \end{center}
% \end{figure}
-% As demonstrated in this example, if a single comma-separated list of options is passed, it applies to both the magnitude and the phase plots. Without any optional arguments, we gets a thick black Bode plot.
-%
-% A linear approximation of the Bode plot with customization of the plots, the axes, and the group can be generated using\\
-% |\BodeZPK[plot/mag/{red,thick},plot/ph/{blue,thick},|\\
-% | axes/mag/{ytick distance=40,xmajorticks=true,|\\
-% | xlabel={Frequency (rad/s)}},axes/ph/{ytick distance=90},|\\
-% | group/{group style={group size=2 by 1,horizontal sep=2cm,|\\
-% | width=4cm,height=2cm}},approx/linear]|\\
-% | {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}|\\
-% | {0.01}{100}|\\
+%
+% The width and the height, along with other properties of the plots, the axes, and the group can be customized using native |pgf| keys. For example, a linear approximation of the Bode plot with customization of the plots, the axes, and the group can be generated using
+%\begin{verbatim}
+%\BodeZPK[%
+% plot/mag/{red,thick},
+% plot/ph/{blue,thick},
+% axes/mag/{ytick distance=40,xmajorticks=true,xlabel={Frequency (rad/s)}},
+% axes/ph/{ytick distance=90},
+% group/{group style={group size=2 by 1,horizontal sep=2cm,width=4cm,height=2cm}},
+% approx/linear]
+% {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}
+% {0.01}{100}
+%\end{verbatim}
% which generates the plot in Figure \ref{customBode}.
%
% \begin{figure}
@@ -494,11 +502,14 @@ Nyquist plots with additional commands, using two different macros
%
% \noindent Plots the Bode plot of a transfer function given in TF format. The three mandatory arguments include: (1) a list of tuples comprised of the coefficients in the numerator and the denominator of the transfer function and the transport delay, (2) the lower end of the frequency range for the $x-$ axis, and (3) the higher end of the frequency range for the $x-$axis. The coefficients are entered as a comma-separated list, in order from the highest degree of $s$ to the lowest, with zeros for missing degrees. The optional arguments are the same as |\BodeZPK|, except that linear/asymptotic approximation is not supported, so |approx/...| is ignored.
%
-% For example, given the same transfer function as (\ref{eq:ZPKExample}) in TF form and with a small transport delay, \begin{equation}G(s) = e^{-0.01s}\frac{s(10s^2+2s+2.6)}{(s^2+s+100.25)},\label{eq:TFExample}\end{equation} its Bode plot over the frequency range $[0.01,100]$ can be generated using\\
-% |\BodeTF[commands/mag/{\node at (axis cs: 2.1,0) |\\
-% | [circle,fill,inner sep=0.05cm,label=below:{$\omega_{gc}$}]{};}]|\\
-% | {num/{10,2,2.6,0},den/{1,1,100.25},d/0.01}|\\
-% | {0.01}{100}|\\
+% For example, given the same transfer function as (\ref{eq:ZPKExample}) in TF form and with a small transport delay, \begin{equation}G(s) = e^{-0.01s}\frac{s(10s^2+2s+2.6)}{(s^2+s+100.25)},\label{eq:TFExample}\end{equation} its Bode plot over the frequency range $[0.01,100]$ can be generated using
+%\begin{verbatim}
+%\BodeTF[%
+% commands/mag/{\node at (axis cs: 2.1,0) [circle,fill,inner sep=0.05cm,
+% label=below:{$\omega_{gc}$}]{};}]
+% {num/{10,2,2.6,0},den/{1,1,100.25},d/0.01}
+% {0.01}{100}
+%\end{verbatim}
% which generates the plot in Figure \ref{simpleBodeTF}. Note the $0$ added to the numerator coefficients to account for the fact that the numerator does not have a constant term in it. Note the semicolon after the TikZ command passed to the |\commands| option.
%
% \begin{figure}
@@ -608,14 +619,14 @@ Nyquist plots with additional commands, using two different macros
% All 20 of the macros defined by combinations of |Type|, |Feature|, and |Approx|, and any |gnuplot| (or |pgfplot| if the |pgf| class option is loaded) compatible function of the 20 macros can be used as |plot-command| in the |addBodeComponentPlot| macro. This is sufficient to generate the Bode plot of any rational transfer function with delay. For example, the Bode phase plot in Figure \ref{multiBodeZPK} can also be generated using:
%\begin{verbatim}
%\begin{BodePhPlot}[ytick distance=90]{0.01}{100}
-% \addBodeComponentPlot[black,thick]{\PhZero{0}{0} + \PhZero{-0.1}{-0.5} +
-% \PhZero{-0.1}{0.5} + \PhPole{-0.5}{-10} + \PhPole{-0.5}{10} +
-% \PhK{10}{0}}
-% \addBodeComponentPlot[red,dashed,thick] {\PhZeroLin{0}{0} +
-% \PhZeroLin{-0.1}{-0.5} + \PhZeroLin{-0.1}{0.5} +
+% \addBodeComponentPlot[black,thick]{%
+% \PhZero{0}{0} + \PhZero{-0.1}{-0.5} + \PhZero{-0.1}{0.5} +
+% \PhPole{-0.5}{-10} + \PhPole{-0.5}{10} + \PhK{10}{0}}
+% \addBodeComponentPlot[red,dashed,thick] {%
+% \PhZeroLin{0}{0} + \PhZeroLin{-0.1}{-0.5} + \PhZeroLin{-0.1}{0.5} +
% \PhPoleLin{-0.5}{-10} + \PhPoleLin{-0.5}{10} + \PhKLin{10}{20}}
-% \addBodeComponentPlot[blue,dotted,thick] {\PhZeroAsymp{0}{0} +
-% \PhZeroAsymp{-0.1}{-0.5} + \PhZeroAsymp{-0.1}{0.5} +
+% \addBodeComponentPlot[blue,dotted,thick] {%
+% \PhZeroAsymp{0}{0} + \PhZeroAsymp{-0.1}{-0.5} + \PhZeroAsymp{-0.1}{0.5} +
% \PhPoleAsymp{-0.5}{-10} + \PhPoleAsymp{-0.5}{10} + \PhKAsymp{10}{40}}
%\end{BodePhPlot}
%\end{verbatim}
@@ -683,16 +694,20 @@ Nyquist plots with additional commands, using two different macros
% \hspace*{2em}\marg{z/\marg{zeros},p/\marg{poles},k/\marg{gain},d/\marg{delay}}\\
% \hspace*{2em}\marg{min-freq}\marg{max-freq}
%
-% \noindent Plots the Nyquist plot of a transfer function given in ZPK format with a thick red $+$ marking the critical point (-1,0). The mandatory arguments are the same as |\BodeZPK|. Since there is only one plot in a Nyquist diagram, the |\typ| specifier in the optional argument tuples is not needed. As such, the supported optional argument tuples are |plot/{opt}|, which passes |{opt}| to |\addplot|, |axes/{opt}|, which passes |{\opt}| to the |axis| environment, and |tikz/{opt}|, which passes |{\opt}| to the |tikzpicture| environment. Asymptotic/linear approximations are not supported in Nyquist plots. If just |{opt}| is provided as the optional argument, it is interpreted as |plot/{opt}|. Arrows to indicate the direction of increasing $\omega$ can be added by adding |\usetikzlibrary{decorations.markings}| and |\usetikzlibrary{arrows.meta}| to the preamble and then passing a tuple of the form\\
-%|plot/{postaction=decorate,decoration={markings,|\\
-%| mark=between positions 0.1 and 0.9 step 5em with|\\
-%| {\arrow{Stealth| |[length=2mm, blue]}}}}|\\
+% \noindent Plots the Nyquist plot of a transfer function given in ZPK format with a thick red $+$ marking the critical point (-1,0). The mandatory arguments are the same as |\BodeZPK|. Since there is only one plot in a Nyquist diagram, the |\typ| specifier in the optional argument tuples is not needed. As such, the supported optional argument tuples are |plot/{opt}|, which passes |{opt}| to |\addplot|, |axes/{opt}|, which passes |{\opt}| to the |axis| environment, and |tikz/{opt}|, which passes |{\opt}| to the |tikzpicture| environment. Asymptotic/linear approximations are not supported in Nyquist plots. If just |{opt}| is provided as the optional argument, it is interpreted as |plot/{opt}|. Arrows to indicate the direction of increasing $\omega$ can be added by adding |\usetikzlibrary{decorations.markings}| and |\usetikzlibrary{arrows.meta}| to the preamble and then passing a tuple of the form
+%\begin{verbatim}
+%plot/{postaction=decorate,decoration={markings,
+% mark=between positions 0.1 and 0.9 step 5em with {%
+% \arrow{Stealth| |[length=2mm, blue]}}}}
+%\end{verbatim}
%\textbf{Caution:} with a high number of samples, adding arrows in this way may cause the error message |! Dimension too big|.
%
-% For example, the command\\
-% |\NyquistZPK[plot/{red,thick,samples=2000},axes/{blue,thick}]|\\
-% | {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}|\\
-% | {-30}{30}|\\
+% For example, the command
+%\begin{verbatim}
+%\NyquistZPK[plot/{red,thick,samples=2000},axes/{blue,thick}]
+% {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}
+% {-30}{30}
+%\end{verbatim}
% generates the Nyquist plot in Figure \ref{simpleNyquistZPK}.
%
% \begin{figure}
@@ -707,13 +722,15 @@ Nyquist plots with additional commands, using two different macros
% \hspace*{2em}\marg{num/\marg{coeffs},den/\marg{coeffs},d/\marg{delay}}\\
% \hspace*{2em}\marg{min-freq}\marg{max-freq}
%
-% \noindent Nyquist plot of a transfer function given in TF format. Same mandatory arguments as |\BodeTF| and same optional arguments as |\NyquistZPK|. For example, the command\\
-% |\NyquistTF[plot/{green,thick,samples=500,postaction=decorate,|\\
-% | decoration={markings,|\\
-% | mark=between positions 0.1 and 0.9 step 5em|\\
-% | with{\arrow{Stealth[length=2mm, blue]}}}}]|\\
-% | {num/{10,2,2.6,0},den/{1,1,100.25}}|\\
-% | {-30}{30}|\\
+% \noindent Nyquist plot of a transfer function given in TF format. Same mandatory arguments as |\BodeTF| and same optional arguments as |\NyquistZPK|. For example, the command
+%\begin{verbatim}
+%\NyquistTF[plot/{green,thick,samples=500,postaction=decorate,
+% decoration={markings,
+% mark=between positions 0.1 and 0.9 step 5em
+% with{\arrow{Stealth[length=2mm, blue]}}}}]
+% {num/{10,2,2.6,0},den/{1,1,100.25}}
+% {-30}{30}
+%\end{verbatim}
% generates the Nyquist plot in Figure \ref{simpleNyquistTF}.
%
% \begin{figure}
@@ -765,10 +782,12 @@ Nyquist plots with additional commands, using two different macros
% \hspace*{2em}\marg{num/\marg{coeffs},den/\marg{coeffs},d/\marg{delay}}\\
% \hspace*{2em}\marg{min-freq}\marg{max-freq}
%
-% \noindent Nichols chart of a transfer function given in TF format. Same arguments as |\NyquistTF|. For example, the command\\
-% |\NicholsTF[plot/{green,thick,samples=2000}]|\\
-% | {num/{10,2,2.6,0},den/{1,1,100.25},d/0.01}|\\
-% | {0.001}{100}|\\
+% \noindent Nichols chart of a transfer function given in TF format. Same arguments as |\NyquistTF|. For example, the command
+%\begin{verbatim}
+%\NicholsTF[plot/{green,thick,samples=2000}]
+% {num/{10,2,2.6,0},den/{1,1,100.25},d/0.01}
+% {0.001}{100}
+%\end{verbatim}
% generates the Nichols chart in Figure \ref{simpleNicholsTF}.
%
% \begin{figure}
@@ -821,7 +840,8 @@ Nyquist plots with additional commands, using two different macros
% \changes{v1.0.3}{2021/11/03}{Added jobname to gnuplot prefix}
% \changes{v1.0.8}{2022/07/06}{Fixed issue \#6}
% \changes{v1.1.4}{2023/10/12}{Changed phase wrapping in pgf mode}
-% This code is needed to support both |pgfplots| and |gnuplot| simultaneously. New macros are defined for the |pow| and |mod| functions to address differences between the two math engines. We start by processing the class options.
+% \changes{v1.1.5}{2024/01/11}{Added babel option to handle active characters}
+% We start by processing the class options.
% \begin{macrocode}
\newif\if@pgfarg\@pgfargfalse
\DeclareOption{pgf}{
@@ -841,7 +861,7 @@ Nyquist plots with additional commands, using two different macros
}
\ProcessOptions\relax
% \end{macrocode}
-% Then, we define new macros to unify |pgfplots| and |gnuplot|.
+% Then, we define new macros to unify |pgfplots| and |gnuplot|. New macros are defined for the |pow| and |mod| functions to address differences between the two math engines.
% \begin{macrocode}
\newcommand{\n@mod}[2]{(#1)-((round((#1)/(#2)))*(#2))}
\newcommand{\n@mod@p}[2]{(#1)-((floor((#1)/(#2)))*(#2))}
@@ -885,6 +905,14 @@ Nyquist plots with additional commands, using two different macros
% \end{macro}
% \end{macro}
% \end{macro}
+% \begin{macro}{\if@babel@french}
+% Check if the |babel| package is loaded with French language option.
+% \begin{macrocode}
+\newif\if@babel@french\@babel@frenchfalse
+\@ifpackagewith{babel}{french}{\@babel@frenchtrue}{}
+\@ifpackagewith{babel}{main=french}{\@babel@frenchtrue}{}
+% \end{macrocode}
+% \end{macro}
% \begin{macro}{bode@style}
% Default axis properties for all plot macros are collected in this |pgf| style.
% \begin{macrocode}
@@ -1295,6 +1323,20 @@ Nyquist plots with additional commands, using two different macros
\end{tikzpicture}
}
% \end{macrocode}
+% The following code handles active characters to avoid conflicts with `babel.'\changes{v1.1.5}{2023/01/11}{Added code to handle active characters}
+% \begin{macrocode}
+\if@babel@french
+ \let\Orig@BodeZPK\BodeZPK
+ \renewcommand{\BodeZPK}{%
+ \shorthandoff{;:!?}%
+ \BodeZPK@Shorthandoff
+ }
+ \newcommand{\BodeZPK@Shorthandoff}[4][]{%
+ \Orig@BodeZPK[#1]{#2}{#3}{#4}%
+ \shorthandon{;:!?}%
+ }
+\fi
+% \end{macrocode}
% \end{macro}
% \begin{macro}{\BodeTF}
% Implementation of this macro is very similar to the |\BodeZPK| macro above. The only difference is the lack of linear and asymptotic plots and slightly different parsing of the mandatory arguments. \changes{v1.0.3}{2021/11/03}{Added Tikz option} \changes{v1.1.0}{2022/07/06}{Fixed phase wrapping in gnuplot mode}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively}\changes{v1.1.4}{2023/10/12}{Changed phase wrapping in pgf mode}
@@ -1355,7 +1397,21 @@ Nyquist plots with additional commands, using two different macros
\end{groupplot}
\end{tikzpicture}
}
-% \end{macrocode}
+% \end{macrocode}
+% The following code handles active characters to avoid conflicts with `babel.'\changes{v1.1.5}{2023/01/11}{Added code to handle active characters}
+% \begin{macrocode}
+\if@babel@french
+ \let\Orig@BodeTF\BodeTF
+ \renewcommand{\BodeTF}{%
+ \shorthandoff{;:!?}%
+ \BodeTF@Shorthandoff
+ }
+ \newcommand{\BodeTF@Shorthandoff}[4][]{%
+ \Orig@BodeTF[#1]{#2}{#3}{#4}%
+ \shorthandon{;:!?}%
+ }
+\fi
+% \end{macrocode}
% \end{macro}
% \begin{macro}{\addBodeZPKPlots}
% This macro is designed to issues multiple |\addplot| macros for the same set of poles, zeros, gain, and delay. All of the work is done by the |\build@ZPK@plot| macro. \changes{v1.0.1}{2021/10/29}{Improved optional argument handling.}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively}\changes{v1.1.3}{2022/11/02}{Changed implementation to respect user-supplied domain}
@@ -1462,12 +1518,16 @@ Nyquist plots with additional commands, using two different macros
% \end{macrocode}
%\end{macro}
% \begin{environment}{BodePhPlot}
-% An environment to host phase plot macros that pass parametric functions to |\addplot| macros. Uses the defaults specified in |bode@style| to create a shortcut that includes the |tikzpicture| and |semilogaxis| environments.\changes{v1.1.0}{2022/07/20}{Added separate environments for phase and magnitude plots}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively}\changes{v1.1.2}{2022/10/29}{Defined using the `NewEnviron' command from the `environ' package to fix conflicts with externalization}
+% An environment to host phase plot macros that pass parametric functions to |\addplot| macros. Uses the defaults specified in |bode@style| to create a shortcut that includes the |tikzpicture| and |semilogaxis| environments.\changes{v1.1.0}{2022/07/20}{Added separate environments for phase and magnitude plots}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively}\changes{v1.1.2}{2022/10/29}{Defined using the `NewEnviron' command from the `environ' package to fix conflicts with externalization}\changes{v1.1.5}{2023/01/11}{Defined using the `NewDocumentEnvironment' command from the `xparse' package and added a hook to handle active characters}
% \begin{macrocode}
-\NewEnviron{BodePhPlot}[3][]{
+\if@babel@french
+ \AddToHook{env/BodePhPlot/begin}{\shorthandoff{;:!?}}
+\fi
+\NewDocumentEnvironment{BodePhPlot}{O{}mm+b}{
\parse@env@opt{#1}
- \edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}]
- \noexpand\begin{semilogxaxis}[
+ \edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}]}
+ \temp@cmd
+ \edef\temp@cmd{\noexpand\begin{semilogxaxis}[
ph@y@label,
freq@label,
bode@style,
@@ -1476,22 +1536,25 @@ Nyquist plots with additional commands, using two different macros
domain=#2:#3,
height=2.5cm,
\unexpanded\expandafter{\opt@axes}
- ]
- }
- \temp@cmd
- \BODY
+ ]}
+ \temp@cmd
+ #4
\end{semilogxaxis}
\end{tikzpicture}
-}
+}{}
% \end{macrocode}
% \end{environment}
% \begin{environment}{BodeMagPlot}
-% An environment to host magnitude plot macros that pass parametric functions to |\addplot| macros. Uses the defaults specified in |bode@style| to create a shortcut that includes the |tikzpicture| and |semilogaxis| environments.\changes{v1.1.0}{2022/07/20}{Added separate environments for phase and magnitude plots}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively}\changes{v1.1.2}{2022/10/29}{Defined using the `NewEnviron' command from the `environ' package to fix conflicts with externalization}
+% An environment to host magnitude plot macros that pass parametric functions to |\addplot| macros. Uses the defaults specified in |bode@style| to create a shortcut that includes the |tikzpicture| and |semilogaxis| environments.\changes{v1.1.0}{2022/07/20}{Added separate environments for phase and magnitude plots}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively}\changes{v1.1.2}{2022/10/29}{Defined using the `NewEnviron' command from the `environ' package to fix conflicts with externalization}\changes{v1.1.5}{2023/01/11}{Defined using the `NewDocumentEnvironment' command from the `xparse' package and added a hook to handle active characters}
% \begin{macrocode}
-\NewEnviron{BodeMagPlot}[3][]{
+\if@babel@french
+ \AddToHook{env/BodeMagPlot/begin}{\shorthandoff{;:!?}}
+\fi
+\NewDocumentEnvironment{BodeMagPlot}{O{}mm+b}{
\parse@env@opt{#1}
- \edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}]
- \noexpand\begin{semilogxaxis}[
+ \edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}]}
+ \temp@cmd
+ \edef\temp@cmd{\noexpand\begin{semilogxaxis}[
bode@style,
freq@label,
xmin={#2},
@@ -1500,22 +1563,25 @@ Nyquist plots with additional commands, using two different macros
height=2.5cm,
ylabel={Gain (dB)},
\unexpanded\expandafter{\opt@axes}
- ]
- }
- \temp@cmd
- \BODY
+ ]}
+ \temp@cmd
+ #4
\end{semilogxaxis}
\end{tikzpicture}
-}
+}{}
% \end{macrocode}
% \end{environment}
% \begin{environment}{BodePlot}
-% Same as |BodeMagPlot|. The |BodePlot| environment is deprecated as of v1.1.0, please use the |BodePhPlot| and |BodeMagPlot| environments instead.\changes{v1.0.3}{2021/11/03}{Added tikz option to environments}\changes{v1.1.0}{2022/02/20}{Deprecated BodePlot environment}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively}\changes{v1.1.2}{2022/10/29}{Defined using the `NewEnviron' command from the `environ' package to fix conflicts with externalization}
+% Same as |BodeMagPlot|. The |BodePlot| environment is deprecated as of v1.1.0, please use the |BodePhPlot| and |BodeMagPlot| environments instead.\changes{v1.0.3}{2021/11/03}{Added tikz option to environments}\changes{v1.1.0}{2022/02/20}{Deprecated BodePlot environment}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively}\changes{v1.1.2}{2022/10/29}{Defined using the `NewEnviron' command from the `environ' package to fix conflicts with externalization}\changes{v1.1.5}{2023/01/11}{Defined using the `NewDocumentEnvironment' command from the `xparse' package and added a hook to handle active characters}
% \begin{macrocode}
-\NewEnviron{BodePlot}[3][]{
+\if@babel@french
+ \AddToHook{env/BodePlot/begin}{\shorthandoff{;:!?}}
+\fi
+\NewDocumentEnvironment{BodePlot}{O{}mm+b}{
\parse@env@opt{#1}
- \edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}]
- \noexpand\begin{semilogxaxis}[
+ \edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}]}
+ \temp@cmd
+ \edef\temp@cmd{\noexpand\begin{semilogxaxis}[
bode@style,
freq@label,
xmin={#2},
@@ -1523,13 +1589,12 @@ Nyquist plots with additional commands, using two different macros
domain=#2:#3,
height=2.5cm,
\unexpanded\expandafter{\opt@axes}
- ]
- }
- \temp@cmd
- \BODY
+ ]}
+ \temp@cmd
+ #4
\end{semilogxaxis}
\end{tikzpicture}
-}
+}{}
% \end{macrocode}
% \end{environment}
% \subsubsection{Internal macros}
@@ -1812,6 +1877,20 @@ Nyquist plots with additional commands, using two different macros
\end{tikzpicture}
}
% \end{macrocode}
+% The following code handles active characters to avoid conflicts with `babel.'\changes{v1.1.5}{2023/01/11}{Added code to handle active characters}
+% \begin{macrocode}
+\if@babel@french
+ \let\Orig@NyquistZPK\NyquistZPK
+ \renewcommand{\NyquistZPK}{%
+ \shorthandoff{;:!?}%
+ \NyquistZPK@Shorthandoff
+ }
+ \newcommand{\NyquistZPK@Shorthandoff}[4][]{%
+ \Orig@NyquistZPK[#1]{#2}{#3}{#4}%
+ \shorthandon{;:!?}%
+ }
+\fi
+% \end{macrocode}
% \end{macro}
% \begin{macro}{\NyquistTF}
% Implementation of this macro is very similar to the |\NyquistZPK| macro above. The only difference is a slightly different parsing of the mandatory arguments via |\build@TF@plot|. \changes{v1.0.3}{2021/11/03}{Added commands and tikz options}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively}
@@ -1851,6 +1930,20 @@ Nyquist plots with additional commands, using two different macros
\end{tikzpicture}
}
% \end{macrocode}
+% The following code handles active characters to avoid conflicts with `babel.'\changes{v1.1.5}{2023/01/11}{Added code to handle active characters}
+% \begin{macrocode}
+\if@babel@french
+ \let\Orig@NyquistTF\NyquistTF
+ \renewcommand{\NyquistTF}{%
+ \shorthandoff{;:!?}%
+ \NyquistTF@Shorthandoff
+ }
+ \newcommand{\NyquistTF@Shorthandoff}[4][]{%
+ \Orig@NyquistTF[#1]{#2}{#3}{#4}%
+ \shorthandon{;:!?}%
+ }
+\fi
+% \end{macrocode}
% \end{macro}
% \begin{macro}{\addNyquistZPKPlot}
% Adds Nyquist plot of a transfer function in ZPK form. This macro is designed to pass two parametric function to an |\addplot| macro. The parametric functions for phase (|\func@ph|) and magnitude (|\func@mag|) are built using the |\build@ZPK@plot| macro, converted to real and imaginary parts and passed to |\addplot| commands.\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively}\changes{v1.1.3}{2022/11/02}{Changed implementation to respect user-supplied domain}
@@ -1897,26 +1990,29 @@ Nyquist plots with additional commands, using two different macros
% \end{macrocode}
%\end{macro}
%\begin{macro}{NyquistPlot}
-% An environment to host |\addNyquist...| macros that pass parametric functions to |\addplot|. Uses the defaults specified in |bode@style| to create a shortcut that includes the |tikzpicture| and |axis| environments. \changes{v1.0.3}{2021/11/03}{Added tikz option to environments}\changes{v1.1.2}{2022/10/29}{Defined using the `NewEniron' command from the `environ' package to fix conflicts with externalization}
+% An environment to host |\addNyquist...| macros that pass parametric functions to |\addplot|. Uses the defaults specified in |bode@style| to create a shortcut that includes the |tikzpicture| and |axis| environments. \changes{v1.0.3}{2021/11/03}{Added tikz option to environments}\changes{v1.1.2}{2022/10/29}{Defined using the `NewEniron' command from the `environ' package to fix conflicts with externalization}\changes{v1.1.5}{2023/01/11}{Defined using the `NewDocumentEnvironment' command from the `xparse' package and added a hook to handle active characters}
% \begin{macrocode}
-\NewEnviron{NyquistPlot}[3][]{
+\if@babel@french
+ \AddToHook{env/NyquistPlot/begin}{\shorthandoff{;:!?}}
+\fi
+\NewDocumentEnvironment{NyquistPlot}{O{}mm+b}{
\parse@env@opt{#1}
- \edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}]
- \noexpand\begin{axis}[
+ \edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}]}
+ \temp@cmd
+ \edef\temp@cmd{\noexpand\begin{axis}[
bode@style,
height=5cm,
domain=#2:#3,
xlabel={$\Re$},
ylabel={$\Im$},
\unexpanded\expandafter{\opt@axes}
- ]
- }
- \temp@cmd
+ ]}
+ \temp@cmd
\addplot [only marks,mark=+,thick,red] (-1 , 0);
- \BODY
+ #4
\end{axis}
\end{tikzpicture}
-}
+}{}
% \end{macrocode}
%\end{macro}
% \subsubsection{Internal commands\label{sec:NInternal}}
@@ -1953,11 +2049,11 @@ Nyquist plots with additional commands, using two different macros
% \end{macro}
% \subsection{Nichols charts}
% \begin{macro}{\NicholsZPK}
-% \changes{v1.0.3}{2021/11/03}{Added commands and tikz options}
+% \changes{v1.0.3}{2021/11/03}{Added commands and tikz options}\changes{v1.1.5}{2023/01/11}{Added code to handle active characters}
% \begin{macro}{\NicholsTF}
-% \changes{v1.0.3}{2021/11/03}{Added commands and tikz options}
+% \changes{v1.0.3}{2021/11/03}{Added commands and tikz options}\changes{v1.1.5}{2023/01/11}{Added code to handle active characters}
% \begin{macro}{NicholsChart}
-% \changes{v1.0.3}{2021/11/03}{Added tikz option to environments}\changes{v1.1.2}{2022/10/29}{Defined using the `NewEniron' command from the `environ' package to fix conflicts with externalization}
+% \changes{v1.0.3}{2021/11/03}{Added tikz option to environments}\changes{v1.1.2}{2022/10/29}{Defined using the `NewEniron' command from the `environ' package to fix conflicts with externalization}\changes{v1.1.5}{2023/01/11}{Defined using the `NewDocumentEnvironment' command from the `xparse' package and added a hook to handle active characters}
% \begin{macro}{\addNicholsZPKChart}
% \changes{v1.1.3}{2022/11/02}{Changed implementation to respect user-supplied domain}
% \begin{macro}{\addNicholsTFChart}
@@ -2002,6 +2098,17 @@ Nyquist plots with additional commands, using two different macros
\end{axis}
\end{tikzpicture}
}
+\if@babel@french
+ \let\Orig@NicholsZPK\NicholsZPK
+ \renewcommand{\NicholsZPK}{%
+ \shorthandoff{;:!?}%
+ \NicholsZPK@Shorthandoff
+ }
+ \newcommand{\NicholsZPK@Shorthandoff}[4][]{%
+ \Orig@NicholsZPK[#1]{#2}{#3}{#4}%
+ \shorthandon{;:!?}%
+ }
+\fi
\newcommand{\NicholsTF}[4][]{
\parse@N@opt{#1}
\gdef\func@mag{}
@@ -2043,23 +2150,35 @@ Nyquist plots with additional commands, using two different macros
\end{axis}
\end{tikzpicture}
}
-\NewEnviron{NicholsChart}[3][]{
+\if@babel@french
+ \let\Orig@NicholsTF\NicholsTF
+ \renewcommand{\NicholsTF}{%
+ \shorthandoff{;:!?}%
+ \NicholsTF@Shorthandoff
+ }
+ \newcommand{\NicholsTF@Shorthandoff}[4][]{%
+ \Orig@NicholsTF[#1]{#2}{#3}{#4}%
+ \shorthandon{;:!?}%
+ }
+ \AddToHook{env/NicholsChart/begin}{\shorthandoff{;:!?}}
+\fi
+\NewDocumentEnvironment{NicholsChart}{O{}mm+b}{
\parse@env@opt{#1}
- \edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}]
- \noexpand\begin{axis}[
+ \edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}]}
+ \temp@cmd
+ \edef\temp@cmd{\noexpand\begin{axis}[
ph@x@label,
bode@style,
domain=#2:#3,
height=5cm,
ylabel={Gain (dB)},
\unexpanded\expandafter{\opt@axes}
- ]
- }
- \temp@cmd
- \BODY
+ ]}
+ \temp@cmd
+ #4
\end{axis}
\end{tikzpicture}
-}
+}{}
\newcommand{\addNicholsZPKChart}[2][]{
\gdef\func@mag{}
\gdef\func@ph{}
diff --git a/graphics/pgf/contrib/braids/README.txt b/graphics/pgf/contrib/braids/README.txt
index 84a8e7c010..f1231c95ba 100644
--- a/graphics/pgf/contrib/braids/README.txt
+++ b/graphics/pgf/contrib/braids/README.txt
@@ -1,10 +1,13 @@
----------------------------------------------------------------
-braids --- a style file for drawing braid diagrams with TikZ/PGF
-E-mail: loopspace@mathforge.org
+braids --- a TikZ library for drawing braid diagrams
+bundle version: v2.3 2024/01/09
+E-mail: Andrew Stacey <loopspace@mathforge.org>
Released under the LaTeX Project Public License v1.3c or later
See http://www.latex-project.org/lppl.txt
----------------------------------------------------------------
-This package defines some commands for drawing braid diagrams with TikZ/PGF.
-The initial idea of this package came from a question and answer on the site http://tex.stackexchange.com.
+This library defines some commands for drawing braid diagrams with TikZ/PGF.
+The initial idea of this package came from a question and answer on the site https://tex.stackexchange.com.
+
+The package comes in two versions: a package (braids.sty) and a TikZ library (tikzlibrarybraids.code.tex). The original package (braids.sty) is depreciated and has been frozen at version 1.1. The TikZ library is maintained and should be used in preference, except for legacy code.
diff --git a/graphics/pgf/contrib/braids/braids.pdf b/graphics/pgf/contrib/braids/braids.pdf
index 32712530b6..bc23135447 100644
--- a/graphics/pgf/contrib/braids/braids.pdf
+++ b/graphics/pgf/contrib/braids/braids.pdf
Binary files differ
diff --git a/graphics/pgf/contrib/braids/braids.tex b/graphics/pgf/contrib/braids/braids.tex
index fa99fd937b..4486b2ab30 100644
--- a/graphics/pgf/contrib/braids/braids.tex
+++ b/graphics/pgf/contrib/braids/braids.tex
@@ -3,8 +3,12 @@
\usepackage{lmodern}
\usepackage{morefloats}
\usepackage{tikz}
-\usepackage{braids}
-\usetikzlibrary{braids}
+\usepackage[nowarning]{braids}
+\usetikzlibrary{
+ braids,
+ calc,
+ decorations.markings
+}
\usepackage[numbered]{hypdoc}
\definecolor{lstbgcolor}{rgb}{0.9,0.9,0.9}
@@ -23,21 +27,48 @@
\usepackage{fancyvrb}
\newenvironment{example}
- {\VerbatimEnvironment
- \begin{VerbatimOut}{example.out}}
- {\end{VerbatimOut}
- \begin{center}
- \setlength{\parindent}{0pt}
- \fbox{\begin{minipage}{.9\linewidth}
- \lstinputlisting[]{example.out}
- \end{minipage}}
-
- \fbox{\begin{minipage}{.9\linewidth}
- \input{example.out}
- \end{minipage}}
-\end{center}
+{\VerbatimEnvironment
+ \begin{VerbatimOut}{example.out}}
+{\end{VerbatimOut}
+ \begin{center}
+ \setlength{\parindent}{0pt}
+ \fbox{\begin{minipage}{.9\linewidth}
+ \lstinputlisting[]{example.out}
+ \end{minipage}}
+
+ \fbox{\begin{minipage}{.9\linewidth}
+ \centering
+ \input{example.out}
+ \end{minipage}}
+ \end{center}
+}
+
+\newenvironment{justexample}
+{\VerbatimEnvironment
+ \begin{VerbatimOut}{example.out}}
+{\end{VerbatimOut}
+ \begin{center}
+ \setlength{\parindent}{0pt}
+ \fbox{\begin{minipage}{.9\linewidth}
+ \lstinputlisting[]{example.out}
+ \end{minipage}}
+ \end{center}
+}
+
+\usepgfmodule{nonlineartransformations}
+\makeatletter
+\def\polartransformation{%
+ % \pgf@x will contain the radius
+ % \pgf@y will contain the distance
+ \pgfmathsincos@{\pgf@sys@tonumber\pgf@x}%
+ % pgfmathresultx is now the cosine of radius and
+ % pgfmathresulty is the sine of radius
+ \pgf@x=\pgfmathresultx\pgf@y%
+ \pgf@y=\pgfmathresulty\pgf@y%
}
+\makeatother
+
\providecommand*{\url}{\texttt}
\GetFileInfo{tikzlibrarybraids.code.tex}
@@ -57,7 +88,7 @@
line cap=round,
braid/.cd,
width=.75cm,
- height=.5cm,
+ crossing height=.5cm,
strand 3/.style={gray,line width=1pt},
strand 6/.style={gray,line width=1pt},
strand 7/.style={gray,line width=1pt},
@@ -90,6 +121,17 @@ An example follows.
\end{center}
\end{example}
+This is actually the documentation for two packages: a \emph{package} and a TikZ \emph{library}.
+If your preamble contains \Verb+\usepackage{braids}+ then you are using the package, if \Verb+\usetikzlibrary{braids}+ then the library.
+
+The package was the original version, and then with the advent of \Verb+pic+s I rewrote it as a TikZ library.
+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.
+So although the original package should be considered \emph{depreciated}, it is not (yet) obsolete.
+I will continue to fix bugs for the original package, but new features only go in the TikZ library.
+
+The best place to report bugs or make suggestions for improvements is on \href{https://github.com/loopspace/braids}{github}.
+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.
+
\section{TikZ Library Usage}
Version 2.0 changed the implementation to use the TikZ \Verb+pic+ syntax.
@@ -113,7 +155,10 @@ The usual syntax for this is as follows:
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.
-The subscript determines how the strands cross, as follows:
+The subscript and superscript determine how the strands cross.
+The following describes the default behaviour and is written from the viewpoint that the braid flows down the page.
+This default behaviour can be altered by using the \Verb+crossing convention+ or \Verb+flip crossing convention+ keys (described in a moment).
+%
\begin{enumerate}
\item If the subscript is a single number, as in \Verb+s_2+, the crossing goes from that number over the next.
\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.
@@ -144,11 +189,11 @@ 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 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).
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:
+This takes one argument which is a comma separated list of parameters that specifies the position and size of the floor:
%
\begin{verbatim}
braid/add floor={x,y,width,height,name}
@@ -159,6 +204,14 @@ The \Verb+name+ is optional and if given can be used to style the floor in that
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.
+The default definition is:
+
+\begin{lstlisting}
+ floor/.pic={
+ \path[pic actions, draw=none] (0,0) rectangle (1,1);
+ \path[pic actions, fill=none] (0,0) -- (1,0) (0,1) -- (1,1);
+ }
+\end{lstlisting}
\item The identity element can occur in the braid-word.
It is represented by \Verb+1+.
@@ -167,23 +220,108 @@ However, it takes the same amount of space as if there were a crossing.
\end{enumerate}
+The crossing behaviour can be modified by use of one of the following keys.
+All are in the \Verb+/tikz/braid/+ namespace.
+
+\DescribeMacro{crossing convention, flip crossing convention, set symbols, flip symbols} These keys determine the behaviour of the braid symbols.
+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+.
+The default for both is \Verb+over+.
+Then \Verb+flip crossing convention+ and \Verb+flip symbols+ reverses the current behaviour of the corresponding setting key.
+
+These have similar but not identical behaviours.
+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).
+The \Verb+set symbols+ keys can be used to invert the braid element represented by each symbol.
+
+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.
+But for the other symbols, such as \(s_{1-3}\), then these achieve different things.
+With the \Verb+crossing convention+ set to \Verb+under+ then \(s_{1-3}\) still moves strands \(1\) and \(2\) to the right.
+But with \Verb+set symbols+ set to \Verb+under+ then these strands now move to the left.
+
+To see the effect of these options, consider \(s_{1-3}\).
+The equivalences of this, as a braid element, under the various options is in Table~\ref{tab:overunder}.
+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.
+
+\begin{table}
+\begin{center}
+\begin{tabular}{lcc}
+Defaults & \(s_2 s_1\) & \tikz[baseline=(defaults.east)]{ \pic[scale=.5,draw,thin] (defaults) {braid={s_{1-3}}}; \path (defaults.south) +(0,-.1); } \\
+\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); } \\
+\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); }\\
+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); }\\
+\end{tabular}
+\caption{Equivalences of \(s_{1-3}\)}
+\label{tab:overunder}
+\end{center}
+
+\end{table}
+
+
+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.
+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.
+
+\begin{example}
+\begin{tikzpicture}[
+ braid/.cd,
+ strand 1/.style={red},
+ strand 2/.style={green},
+ strand 3/.style={blue},
+ strand 4/.style={magenta},
+]
+\pic at (0,0) {braid={s_1 s_{1-4} s_{1,3,4}}};
+\pic[braid/crossing convention=under] at (4,0) {braid={s_1 s_{1-4} s_{1,3,4}}};
+\pic[braid/set symbols=under] at (8,0) {braid={s_1 s_{1-4} s_{1,3,4}}};
+\end{tikzpicture}
+\end{example}
+
\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.
+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.
+Any unknown keys are dropped back to the \Verb+tikz+ namespace.
+See the TikZ/pgf documentation for more details on key handling.
\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.
+The key \Verb+height+ is used to set the height of the piece of the braid corresponding to a single element in the group.
+This can be negative, and indeed the default value is negative because the default is for a braid to flow down the page.
+
+This key is depreciated and is only kept for backwards compatibility, the fact that the default is negative proved confusing.
+Therefore the following key should be used in its place.
+
+\DescribeMacro{crossing height}
+The key \Verb+crossing height+ also sets the height of the piece of the braid corresponding to an element in the group.
+The sign of this is ignored.
+
+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.
+
+\begin{example}
+\begin{tikzpicture}[
+ every braid/.style={
+ ultra thick,
+ braid/strand 1/.style=red,
+ braid/strand 2/.style=green,
+ braid/strand 3/.style=blue,
+ braid/anchor=center,
+ }
+ ]
+\pic {braid={s_1 s_2^{-1}}};
+\pic[rotate=90] at (3,0) {braid={s_1 s_2^{-1}}};
+\pic[rotate=180] at (6,0) {braid={s_1 s_2^{-1}}};
+\pic[yscale=-1] at (9,0) {braid={s_1 s_2^{-1}}};
+\end{tikzpicture}
+\end{example}
+
+The \Verb+crossing height+ and \Verb+height+ keys shouldn't be used together.
+If they are then a message will be printed on the console and the value for \Verb+crossing height+ will be used.
\DescribeMacro{width}
The key \Verb+width+ sets the separation of the strands in the braid.
-This can be negative.
+This can be negative (though the effect of a negative width would be better achieved with a transformation of `xscale=-1`).
\DescribeMacro{border height}
The key \Verb+border height+ adds a little extra length to the strands at the start and end of the braid.
@@ -191,10 +329,10 @@ The key \Verb+border height+ adds a little extra length to the strands at the st
\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.
+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.
\DescribeMacro{control factor}
-As just said, the parts of the strands involved in a crossing are drawn using a cubic bezier curve.
+As just said, the parts of the strands involved in a crossing are drawn using a cubic b\'ezier 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.
@@ -210,6 +348,43 @@ 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.
+\bigskip
+
+The following example illustrates the above keys.
+
+\begin{example}
+\begin{tikzpicture}
+\pic[
+ draw,
+ ultra thick,
+ magenta,
+ braid/.cd,
+ border height=3mm,
+ nudge factor=.2,
+ gap=.3
+] (lengths) {braid={s_1 s_2}};
+\draw (lengths-1-s) -- +(-1,0) coordinate (a);
+\draw (lengths-1-0) -- +(-1,0) coordinate (b);
+\draw (lengths-3-1) -- +(1,0) coordinate (c);
+\draw (lengths-1-2) -- +(1,0) coordinate (d);
+\draw (lengths-1-s) -- +(0,1) coordinate (e);
+\draw (lengths-2-s) -- +(0,1) coordinate (f);
+\draw (lengths-2-1) -- +(-1,0) coordinate (g);
+\draw ($(lengths-2-1)!.2!(lengths-1-0)$) -- +(-1,0) coordinate (h);
+\draw (lengths-1-1) -- +(.5,0) coordinate (i);
+\draw ($(lengths-1-1)!.5!(lengths-2-0)$) -- +(.5,0) coordinate (j);
+\draw[|<->|] (a) -- node[left] {border height} (b);
+\draw[|<->|] (c) -- node[right] {crossing height} (d);
+\draw[|<->|] (e) -- node[above] {width} (f);
+\draw[|<->|] (g) -- node[left] {nudge factor} (h);
+\draw[|<->|] (i) -- node[right] {control factor} (j);
+\end{tikzpicture}
+\end{example}
+
+\DescribeMacro{every braid}
+This style is invoked on a scope that surrounds the actual braid.
+It can be used to set defaults for a group of braids.
+
\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.
@@ -219,43 +394,90 @@ 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.
+They can even be used to change the \Verb+pic+ used to draw individual floors.
+The \Verb+n+ is the level number, starting at \(1\).
+
+\begin{example}
+\begin{tikzpicture}
+\pic[
+ braid/floor 3/.style={
+ floor/.pic={
+ \path[pic actions, draw=none] (.5,.5) circle[x radius=.5, y radius=.5];
+ \path[pic actions, fill=none, dashed] (0,0) -- (1,0);
+ \path[pic actions, fill=none, dotted] (0,1) -- (1,1);
+ },
+ },
+ braid/every floor/.style={
+ fill=yellow,
+ draw=black
+ }
+] {braid={| s_1 s_2 | s_1^{-1}}};
+\end{tikzpicture}
+\end{example}
\subsection{Coordinates and Anchors}
+\label{sec:coords}
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:
+If the braid has been named, the coordinate names look like the following:
%
-\begin{verbatim}
-<name prefix>-<strand number>-<crossing number>
-<name prefix>-rev-<strand number>-<crossing number>
-\end{verbatim}
+\begin{lstlisting}
+ <braid name>-<strand number>-<crossing number>
+ <braid name>-rev-<strand number>-<crossing number>
+\end{lstlisting}
%
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.
+\begin{example}
+\begin{tikzpicture}
+\pic[draw,braid/strand 1/.style={red}] (coords) {braid={s_1}};
+\node[at=(coords-1-s),pin=west:strand 1 start] {};
+\node[at=(coords-1-e),pin=east:strand 1 end] {};
+\end{tikzpicture}
+\end{example}
+
+See Section~\ref{sec:picexamples} for more examples using these anchors.
+
In addition, if the braid is named then a rectangular node is defined that fits around the whole braid.
-This node is not actually rendered but its anchors can be used afterwards as if it had been.
+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.
+In particular its anchors can be used to define locations around the edge of the braid.
+
+\begin{example}
+\begin{tikzpicture}[ultra thick]
+\pic (anchors) at (1,2) {braid={s_1 s_2}};
+\draw[<-,cyan] (anchors.east) -- +(1,0) node[right] {east};
+\draw[<-,cyan] (anchors.west) -- +(-1,0) node[left] {west};
+\draw[<-,cyan] (anchors.north) -- +(0,1) node[above] {north};
+\draw[<-,cyan] (anchors.south) -- +(0,-1) node[below] {south};
+\end{tikzpicture}
+\end{example}
\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.
-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 (except without the \Verb+<name prefix>-+, of course).
+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.
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).
-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)+
+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}};
+\pic[
+ rotate=90,
+ braid/anchor=3-2,
+ braid/strand 3/.style={red},
+] at (1,1) {braid={s_2 s_1 s_2 s_1}};
\end{tikzpicture}
\end{center}
\end{example}
-\section{Examples}
+\subsection{Examples}
+\label{sec:picexamples}
Here are more detailed examples.
@@ -271,13 +493,13 @@ Here are more detailed examples.
braid/strand 3/.style={green},
braid/add floor={2,4,3,2,a},
braid/floor a/.style={fill=pink},
- name prefix=braid,
+ name=coordinates,
] 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] {};
+\node[at=(coordinates-3-s),pin=north west:strand 3 start] {};
+\node[at=(coordinates-3-e),pin=south west:strand 3 end] {};
+\node[at=(coordinates-rev-3-s),pin=north east:strand 3 (from bottom) start] {};
+\node[at=(coordinates-rev-3-e),pin=south east:strand 3 (from bottom) end] {};
\end{tikzpicture}
\end{center}
\end{example}
@@ -295,11 +517,11 @@ Here are more detailed examples.
gap=0.1,
control factor=0,
nudge factor=0,
- name prefix=braid,
+ name=symbols,
] {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) {\(+\)};
+\node[circle,draw,fill=white,inner sep=0pt] at (symbols-2-1) {\(+\)};
+\node[circle,draw,fill=white,inner sep=0pt] at (symbols-3-1) {\(-\)};
+\node[circle,draw,fill=white,inner sep=0pt] at (symbols-2-3) {\(+\)};
\end{tikzpicture}
\end{center}
@@ -316,15 +538,153 @@ Here are more detailed examples.
strand 2/.style={green},
strand 3/.style={blue},
gap=0.1,
-% control factor=0,
-% nudge factor=0,
- name prefix=braid,
] {braid={a_{1-3} a_{1,3}}};
\end{tikzpicture}
\end{center}
\end{example}
+The next example uses the nonlinear transformations pgf module with the following definition.
+
+\begin{lstlisting}
+ \usepgfmodule{nonlineartransformations}
+ \makeatletter
+ \def\polartransformation{%
+ % \pgf@x will contain the radius
+ % \pgf@y will contain the distance
+ \pgfmathsincos@{\pgf@sys@tonumber\pgf@x}%
+ % pgfmathresultx is now the cosine of radius and
+ % pgfmathresulty is the sine of radius
+ \pgf@x=\pgfmathresultx\pgf@y%
+ \pgf@y=\pgfmathresulty\pgf@y%
+ }
+ \makeatother
+\end{lstlisting}
+
+\begin{example}
+\begin{tikzpicture}[scale=.5]
+\begin{scope}
+\pgftransformnonlinear{\polartransformation}% see above
+\pic[
+ rotate=90,
+ braid/.cd,
+ every strand/.style={line width=6pt,magenta!67},
+ border height=0cm,
+ crossing height=15.7pt,
+ gap=.2,
+ nudge factor=0.01,
+] at (0,5) {braid=%
+ s_2^{-1} s_3 s_1 s_3 s_2^{-1} s_3 s_1 s_3
+ s_2^{-1} s_3 s_1 s_2^{-1} s_3 s_1 s_2^{-1}
+ s_1 s_3 s_1 s_2^{-1} s_1 s_3 s_1 s_2^{-1}
+};
+\end{scope}
+
+\end{tikzpicture}
+\end{example}
+
+\newpage
+
+Here's an example using a decoration library to style the strands.
+
+\begin{justexample}
+\begin{tikzpicture}[remember picture, overlay]
+\pic[
+ decoration={
+ markings,
+ mark=between positions 2mm and 1 step 5mm with {
+ \draw[black,thick] (-2mm,-1.5mm) .. controls +(4mm,0) and +(-4mm,0) .. (2mm,1.5mm);
+ }
+ },
+ braid/number of strands=10,
+ braid/gap=.15,
+ braid/every strand/.style={
+ line width=3mm,
+ draw,
+ brown!50,
+ postaction={
+ decorate,
+ },
+ preaction={
+ draw,
+ black,
+ line width=3.3mm,
+ }
+ },
+ braid/every floor/.style={
+ draw
+ },
+ braid/height=-3cm,
+ braid/width=2cm,
+ braid/anchor=1-0,
+]
+at ([shift={(2,-2)}]current page.north west)
+{braid={
+ s_1-s_3-s_5^{-1}-s_7^{-1}
+ s_1-s_3-s_5^{-1}-s_7^{-1}
+ s_1-s_3-s_5^{-1}-s_7^{-1}
+ s_1-s_3-s_5^{-1}-s_7^{-1}
+ s_1-s_3-s_5^{-1}-s_7^{-1}
+ s_1-s_3-s_5^{-1}-s_7^{-1}
+ s_1-s_3-s_5^{-1}-s_7^{-1}
+ s_1-s_3-s_5^{-1}-s_7^{-1}
+}};
+\begin{scope}[shift={([shift={(1,-2)}]current page.north west)}]
+\draw (0,0) grid[xstep=4cm,ystep=3cm] ++(20,-24.1);
+\draw (18,0) -- +(0,-24.1);
+\end{scope}
+\end{tikzpicture}
+\end{justexample}
+
+\newpage
+
+\begin{tikzpicture}[remember picture, overlay]
+\pic[
+ decoration={
+ markings,
+ mark=between positions 2mm and 1 step 5mm with {
+ \draw[black,thick] (-2mm,-1.5mm) .. controls +(4mm,0) and +(-4mm,0) .. (2mm,1.5mm);
+ }
+ },
+ braid/number of strands=10,
+ braid/gap=.15,
+ braid/every strand/.style={
+ line width=3mm,
+ draw,
+ brown!50,
+ postaction={
+ decorate,
+ },
+ preaction={
+ draw,
+ black,
+ line width=3.3mm,
+ }
+ },
+ braid/every floor/.style={
+ draw
+ },
+ braid/height=-3cm,
+ braid/width=2cm,
+ braid/anchor=1-0,
+]
+at ([shift={(2,-2)}]current page.north west)
+{braid={
+ s_1-s_3-s_5^{-1}-s_7^{-1}
+ s_1-s_3-s_5^{-1}-s_7^{-1}
+ s_1-s_3-s_5^{-1}-s_7^{-1}
+ s_1-s_3-s_5^{-1}-s_7^{-1}
+ s_1-s_3-s_5^{-1}-s_7^{-1}
+ s_1-s_3-s_5^{-1}-s_7^{-1}
+ s_1-s_3-s_5^{-1}-s_7^{-1}
+ s_1-s_3-s_5^{-1}-s_7^{-1}
+}};
+\begin{scope}[shift={([shift={(1,-2)}]current page.north west)}]
+\draw (0,0) grid[xstep=4cm,ystep=3cm] ++(20,-24.1);
+\draw (18,0) -- +(0,-24.1);
+\end{scope}
+\end{tikzpicture}
+
\newpage
\section{Original Package Usage (Depreciated)}
@@ -337,6 +697,14 @@ To use this package, you need to put the following in the preamble.
\usepackage{braids}
\end{verbatim}
+This will generate a warning saying that it is preferable to use the TikZ library version.
+To suppress this warning use the \Verb+nowarning+ option:
+
+\begin{verbatim}
+\usepackage[nowarning]{braids}
+\end{verbatim}
+
+
\DescribeMacro{\braid}
A braid is specified by the command \Verb+\braid+.
The syntax for this command is as follows:
@@ -422,10 +790,10 @@ The key \Verb+border height+ adds a little extra length to the strands at the st
\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.
+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.
\DescribeMacro{control factor}
-As just said, the parts of the strands involved in a crossing are drawn using a cubic bezier curve.
+As just said, the parts of the strands involved in a crossing are drawn using a cubic b\'ezier 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.
@@ -469,7 +837,8 @@ Anything specified in the \Verb+floor command+ will take precedence over both of
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}
+\subsection{Examples}
+\label{sec:pkgexamples}
Here are more detailed examples.
@@ -487,13 +856,13 @@ Here are more detailed examples.
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};
+] (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};
\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)] {};
+\fill[purple] (strands) circle (4pt);
+\node[at=(strands-3-s),pin=north west:strand 3] {};
+\node[at=(strands-3-e),pin=south west:strand 3] {};
+\node[at=(strands-rev-3-s),pin=north east:strand 3 (from bottom)] {};
+\node[at=(strands-rev-3-e),pin=south east:strand 3 (from bottom)] {};
\end{tikzpicture}
\end{center}
\end{example}
diff --git a/graphics/pgf/contrib/braids/braids_code.dtx b/graphics/pgf/contrib/braids/braids_code.dtx
index f1f59c29b0..7ea298c6cd 100644
--- a/graphics/pgf/contrib/braids/braids_code.dtx
+++ b/graphics/pgf/contrib/braids/braids_code.dtx
@@ -4,14 +4,17 @@
%</internal>
%<*readme>
----------------------------------------------------------------
-braids --- a style file for drawing braid diagrams with TikZ/PGF
-E-mail: loopspace@mathforge.org
+braids --- a TikZ library for drawing braid diagrams
+bundle version: v2.3 2024/01/09
+E-mail: Andrew Stacey <loopspace@mathforge.org>
Released under the LaTeX Project Public License v1.3c or later
See http://www.latex-project.org/lppl.txt
----------------------------------------------------------------
-This package defines some commands for drawing braid diagrams with TikZ/PGF.
-The initial idea of this package came from a question and answer on the site http://tex.stackexchange.com.
+This library defines some commands for drawing braid diagrams with TikZ/PGF.
+The initial idea of this package came from a question and answer on the site https://tex.stackexchange.com.
+
+The package comes in two versions: a package (braids.sty) and a TikZ library (tikzlibrarybraids.code.tex). The original package (braids.sty) is depreciated and has been frozen at version 1.1. The TikZ library is maintained and should be used in preference, except for legacy code.
%</readme>
%<*internal>
\fi
@@ -26,8 +29,9 @@ The initial idea of this package came from a question and answer on the site htt
\askforoverwritefalse
\preamble
----------------------------------------------------------------
-braids --- a style file for drawing braid diagrams with TikZ/PGF
-E-mail: loopspace@mathforge.org
+braids --- a TikZ library for drawing braid diagrams
+bundle version: v2.3 2024/01/09
+E-mail: Andrew Stacey <loopspace@mathforge.org>
Released under the LaTeX Project Public License v1.3c or later
See http://www.latex-project.org/lppl.txt
----------------------------------------------------------------
@@ -35,7 +39,7 @@ See http://www.latex-project.org/lppl.txt
\endpreamble
\postamble
-Copyright (C) 2011-2022 by Andrew Stacey <loopspace@mathforge.org>
+Copyright (C) 2011-2024 by Andrew Stacey <loopspace@mathforge.org>
This work may be distributed and/or modified under the
conditions of the LaTeX Project Public License (LPPL), either
@@ -82,16 +86,12 @@ and the derived files README.txt,
\expandafter\endgroup
\fi
%</internal>
-%<*package>
-\NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{braids}[2011/10/18 v1.1 Tikz/PGF commands for drawing braid diagrams]
-%</package>
%<*driver>
\documentclass{l3doc}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
\usepackage{tikz}
-\usepackage{braids}
+\usepackage[nowarning]{braids}
\usetikzlibrary{braids}
\EnableCrossrefs
@@ -103,7 +103,7 @@ and the derived files README.txt,
%</driver>
% \fi
%
-% \CheckSum{2352}
+% \CheckSum{2401}
%
% \CharacterTable
% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
@@ -127,6 +127,7 @@ and the derived files README.txt,
% \changes{2.0}{2019/03/20}{Converted TikZ library}
% \changes{2.1}{2019/08/14}{Extended crossing capability}
% \changes{2.2}{2022/10/26}{Advanced positioning}
+% \changes{2.3}{2024/01/09}{Disambiguated height}
%
% \DoNotIndex{\newcommand,\newenvironment}
%
@@ -162,9 +163,21 @@ and the derived files README.txt,
%
% Issue a notice that this is a depreciated version of the braids package.
% \begin{macrocode}
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{braids}[2011/10/18 v1.1 Tikz/PGF commands for drawing braid diagrams (depreciated package)]
+\newif\if@braids@warning@
+\@braids@warning@true
+\DeclareOption{nowarning}{%
+\@braids@warning@false
+}
+
+\ProcessOptions
+
+\if@braids@warning@
\PackageWarning{braids}{%
- This package has been reimplemented as a TikZ library; if starting with a fresh document, please consider using that instead.%
+ This package is frozen at v1.1 from 2011/10/18 and has been reimplemented as a TikZ library; if starting with a fresh document, please consider using that instead.%
}%
+\fi
% \end{macrocode}
%
% \begin{macro}[internal]{\ge@addto@macro}
@@ -1183,7 +1196,7 @@ and the derived files README.txt,
% Life is so much easier with \LaTeX3.
% \begin{macrocode}
\ProvidesFile{tikzlibrarybraids.code.tex}[%
- 2022/10/26 v2.2 Tikz/PGF library for drawing braid diagrams%
+ 2024/01/09 v2.3 Tikz/PGF library for drawing braid diagrams%
]
\RequirePackage{expl3}
\ExplSyntaxOn
@@ -1227,33 +1240,33 @@ and the derived files README.txt,
\seq_new:N \l_@@_anchor_seq
\seq_new:N \l_@@_floors_seq
\str_new:N \l_@@_tmpa_str
-\str_new:N \l_@@_sup_str
-\str_set:Nn \l_@@_sup_str {^}
-\str_new:N \l_@@_sub_str
-\str_set:Nn \l_@@_sub_str {_}
-\str_new:N \l_@@_hyphen_str
-\str_set:Nn \l_@@_hyphen_str {-}
-\str_new:N \l_@@_bar_str
-\str_set:Nn \l_@@_bar_str {|}
-\str_new:N \l_@@_one_str
-\str_set:Nn \l_@@_one_str {1}
\bool_new:N \l_@@_step_level_bool
\bool_new:N \l_@@_swap_crossing_bool
+\bool_new:N \l_@@_default_crossing_bool
+\bool_new:N \l_@@_default_symbol_bool
+\bool_set_true:N \l_@@_default_crossing_bool
+\bool_set_true:N \l_@@_default_symbol_bool
\bool_new:N \l_@@_floor_bool
+\bool_new:N \l_@@_height_bool
+\bool_new:N \l_@@_crossing_height_bool
\prop_new:N \l_@@_strands_prop
\prop_new:N \l_@@_permutation_prop
\prop_new:N \l_@@_crossing_permutation_prop
\prop_new:N \l_@@_inverse_prop
\prop_new:N \l_@@_anchor_prop
+\msg_new:nnn {braids} {height} {The~ keys~ "height"~ and~ "crossing~ height"~ shouldn't~ be~ used~ together~ (the~ setting~ for~ "crossing~ height"~ will~ be~ used)}
\cs_generate_variant:Nn \seq_set_split:Nnn {NVn}
+\cs_generate_variant:Nn \str_compare:nNnTF {VNnTF}
% \end{macrocode}
% Our interface is through a TikZ pic.
% \begin{macrocode}
\tikzset{
braid/.pic={
+ \begin{scope}[every~ braid/.try]
\@@_parse_word:n {#1}
\@@_count:
\@@_render:
+ \end{scope}
},
floor/.pic={
\path[pic~ actions, draw=none] (0,0) rectangle (1,1);
@@ -1276,9 +1289,86 @@ and the derived files README.txt,
% \begin{macrocode}
number~ of~ strands/.initial=0,
% \end{macrocode}
-% \Verb+height+ is the distance between crossings (can be negative).
+%
+% These keys determine whether crossings are over or under by default.
+% \begin{macrocode}
+ crossing~ convention/.is~choice,
+ crossing~ convention/over/.code={
+ \bool_set_true:N \l_@@_default_crossing_bool
+ },
+ crossing~ convention/down/.code={
+ \bool_set_true:N \l_@@_default_crossing_bool
+ },
+ crossing~ convention/under/.code={
+ \bool_set_false:N \l_@@_default_crossing_bool
+ },
+ crossing~ convention/up/.code={
+ \bool_set_false:N \l_@@_default_crossing_bool
+ },
+ crossing~ convention/.default=over,
+% \end{macrocode}
+%
+% \begin{macrocode}
+ flip~ crossing~ convention/.code={
+ \bool_set_inverse:N \l_@@_default_crossing_bool
+ },
+% \end{macrocode}
+%
+% These keys determine whether elements should be inverted by default.
+% \begin{macrocode}
+ set~ symbols/.is~choice,
+ set~ symbols/over/.code={
+ \bool_set_true:N \l_@@_default_symbol_bool
+ },
+ set~ symbols/down/.code={
+ \bool_set_true:N \l_@@_default_symbol_bool
+ },
+ set~ symbols/under/.code={
+ \bool_set_false:N \l_@@_default_symbol_bool
+ },
+ set~ symbols/up/.code={
+ \bool_set_false:N \l_@@_default_symbol_bool
+ },
+ set~ symbols/.default=over,
+% \end{macrocode}
+%
+% \begin{macrocode}
+ flip~ symbols/.code={
+ \bool_set_inverse:N \l_@@_default_symbol_bool
+ },
+% \end{macrocode}
+%
+% The next two keys are used to control the separation between the crossings.
+% The original braid package used the \Verb+height+ as part of how it determined the direction of the braid on the page.
+% In particular, the \Verb+height+ could be negative, and indeed the default is for it to be so since a vertical braid usually flows from top to bottom.
+% Now that the drawing is reimplemented as a \Verb+pic+ then the direction is better controlled using transformations.
+% So then \Verb+height+ should be simply to set the gap between crossings in whatever orientation.
+% In particular, \Verb+height+ should be a positive length.
+%
+% To avoid backwards incompatibility, the original (counter-intuitive) version of \Verb+height+ is retained but a new key, \Verb+crossing height+, is introduced which can only be positive (rather, the code will take its absolute value so you can \emph{declare} it to be negative but the code will laugh at you and ignore the sign).
+%
+% To ensure that \Verb+crossing height+ wins, we use a boolean to see if it has been invoked by the user.
% \begin{macrocode}
height/.initial=-1cm,
+ height/.code={
+ \bool_if:NTF \l_@@_crossing_height_bool
+ {
+ \msg_term:nn {braids} {height}
+ }
+ {
+ \pgfkeyssetvalue{/tikz/braid/height}{#1}
+ \bool_set_true:N \l_@@_height_bool
+ }
+ },
+ crossing~ height/.code={
+ \bool_if:NT \l_@@_height_bool
+ {
+ \msg_term:nn {braids} {height}
+ }
+ \exp_args:Nnx \pgfkeyssetvalue {/tikz/braid/height}
+ {\dim_eval:n {-\dim_abs:n{#1}}}
+ \bool_set_true:N \l_@@_crossing_height_bool
+ },
% \end{macrocode}
% \Verb+width+ is the distance between strands (can be negative).
% \begin{macrocode}
@@ -1464,7 +1554,7 @@ and the derived files README.txt,
{
\seq_put_right:Nx \l_@@_crossing_seq {\int_eval:n {#1 + 1} }
}
- \bool_if:NF \l_@@_swap_crossing_bool
+ \bool_xor:nnT {\l_@@_swap_crossing_bool} {\l_@@_default_symbol_bool}
{
\seq_reverse:N \l_@@_crossing_seq
}
@@ -1473,7 +1563,7 @@ and the derived files README.txt,
% \end{macro}
%
% \begin{macro}{\@@_parse_exponent:n}
-% Parse an exponent, basically testing to see if it is \(-1\) in which case our crossing numbers should be reversed..
+% Parse an exponent, basically testing to see if it is \(-1\) in which case our crossing numbers should be reversed.
% \begin{macrocode}
\cs_new_nopar:Npn \@@_parse_exponent:n #1
{
@@ -1838,7 +1928,7 @@ and the derived files README.txt,
\fp_zero:N \l_@@_height_fp
\fp_zero:N \l_@@_nudge_fp
\fp_zero:N \l_@@_control_fp
-% \end{macrocode}
+% \end{macrocode}
% This holds our current \Verb+height+ of our strands.
% \begin{macrocode}
\fp_set:Nn \l_@@_height_fp
@@ -2008,8 +2098,15 @@ and the derived files README.txt,
% \begin{macrocode}
\int_step_inline:nnn {2} {\seq_count:N \l_@@_crossing_seq}
{
- \int_set:Nn \l_@@_tmpa_int {####1}
- \int_set:Nn \l_@@_tmpb_int {####1 - 1}
+ \bool_if:NTF \l_@@_default_crossing_bool
+ {
+ \int_set:Nn \l_@@_tmpa_int {####1}
+ \int_set:Nn \l_@@_tmpb_int {####1 - 1}
+ }
+ {
+ \int_set:Nn \l_@@_tmpa_int {####1 - 1}
+ \int_set:Nn \l_@@_tmpb_int {####1}
+ }
% \end{macrocode}
% Keep track of the current permutation.
% \begin{macrocode}
diff --git a/graphics/pgf/contrib/braids/braids_code.pdf b/graphics/pgf/contrib/braids/braids_code.pdf
index e001392bde..bf6aa9fa5b 100644
--- a/graphics/pgf/contrib/braids/braids_code.pdf
+++ b/graphics/pgf/contrib/braids/braids_code.pdf
Binary files differ