Debian Codegraph @

texmf-dist/source/latex/bodeplot/bodeplot.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2021-2026 by Rushikesh Kamalapurkar <[email protected]>
4 % -----------------------------------------------------------
5 %
6 % This file may be distributed and/or modified under the conditions of
7 % the LaTeX Project Public License, either version 1.3c of this license
8 % or (at your option) any later version. The latest version of this
9 % license is in:
10 %
11 % http://www.latex-project.org/lppl.txt
12 %
13 % and version 1.3c or later is part of all distributions of LaTeX
14 % version 2006/05/20 or later.
15 %
16 % \fi
17 %
18 % \iffalse
19 %<package>\NeedsTeXFormat{LaTeX2e}[2018/04/01]
20 %<package>\DeclareRelease{}{2024-02-06}{bodeplot-2024-02-06.sty}
21 %<package>\DeclareCurrentRelease{}{2026/05/14}
22 %<package>\ProvidesPackage{bodeplot}[2026/05/18 v3.1 Generate Bode, Nichols, Nyquist, and pole-zero plots]
23 %<package>\RequirePackage{pdftexcmds}
24 %<package>\RequirePackage{ifplatform}
25 %<package>\RequirePackage{xparse}
26 %<package>\RequirePackage{pgfplots}
27 %<package> \pgfplotsset{compat=1.18}
28 %<package> \usepgfplotslibrary{groupplots}
29 %
30 %<*driver>
31 \documentclass{ltxdoc}
32 \usepackage{cprotect}
33 \usepackage[declutter]{bodeplot}
34 \usepackage[colorlinks]{hyperref}
35 \usepackage{fancyvrb}
36 \usepackage{iftex}
37 \iftutex % LuaTeX, XeTeX
38 \usepackage{fontspec}
39 \setmonofont{DejaVuSansMono}[Scale=MatchUppercase]
40 \else % old engines
41 \usepackage[T1]{fontenc}
42 \usepackage{lmodern}
43 \usepackage[scaled]{DejaVuSansMono}
44 \fi
45 \usepackage{showexpl}
46 \lstset{
47 explpreset={numbers=none},
48 language=[LaTeX]Tex,
49 basicstyle=\ttfamily\tiny,
50 commentstyle=\itshape\ttfamily\tiny,
51 showspaces=false,
52 showstringspaces=false,
53 breaklines=true,
54 backgroundcolor=\color{white!90!black},
55 breakautoindent=true,
56 captionpos=t
57 }
58 \usepackage{geometry}
59 \geometry{lmargin=2in,rmargin=1in,tmargin=1in,bmargin=1in}
60 \usetikzlibrary{decorations.markings,arrows.meta,spy,backgrounds}
61 \usepackage[nottoc]{tocbibind}
62 \sloppy
63 \def\MakePrivateLetters{
64 \catcode`\@=11\relax
65 \catcode`\_=11\relax
66 \catcode`\:=11\relax
67 }
68 \EnableCrossrefs
69 \CodelineIndex
70 \RecordChanges
71 \begin{document}
72 \DocInput{bodeplot.dtx}
73 \clearpage
74 \addcontentsline{toc}{section}{Index}
75 \PrintIndex
76 \clearpage
77 \addcontentsline{toc}{section}{Change History}
78 \PrintChanges
79 \end{document}
80 %</driver>
81 % \fi
82 %
83 % \CheckSum{4912}
84 %
85 % \changes{v1.0}{2021/10/25}{Initial release}
86 % \changes{v1.0.4}{2021/11/05}{Fixed unintended optional argument macro expansion}
87 % \changes{v1.0.6}{2021/11/18}{Fixed issue \#3}
88 % \changes{v1.0.7}{2021/12/02}{Removed unnecessary semicolons}
89 % \changes{v1.0.7}{2022/01/18}{Updated documentation}
90 % \changes{v1.0.8}{2022/07/06}{Added a new class option `declutter'}
91 % \changes{v1.1.0}{2022/07/06}{Fixed phase wrapping in gnuplot mode}
92 % \changes{v1.1.1}{2022/07/31}{Enable Hz and rad units}
93 % \changes{v1.1.7}{2024/02/06}{Detect and turn off shorthands to improve `babel' compatibility}
94 % \changes{v1.2}{2024/04/18}{Removed global option to process pgf commands in radians}
95 % \changes{v2.0}{2025/09/25}{Added pole zero maps}
96 % \changes{v2.1}{2025/09/30}{Added an environment and macros to add multiple transfer functions to a single Bode plot}
97 % \changes{v2.1.1}{2025/10/04}{Added a new option |prefix| to enable per-plot custom file names for gnuplot tables}
98 % \changes{v3.0}{2025/10/21}{Improved the interface to enable PGF-style options and more natural syntax for complex numbers in zeros and poles}
99 % \changes{v3.1}{2026/05/19}{Fixed |foreach| iteration when |zeros| or |poles| are passed as macros to |BodeZPK|; |pgffor| was treating the unexpanded macro token as a single list item causing incorrect or empty Bode plots}
100 % \changes{v3.1}{2026/05/19}{Added |bp@tf@to@zpk| and companion |AtBeginDocument| Python helper-script writer; converts polynomial TF coefficients to ZPK form via |python3| and |scipy.signal.tf2zpk| under |--shell-escape|}
101 %
102 % \GetFileInfo{bodeplot.sty}
103 % \DoNotIndex{\newcommand,\xdef,\gdef,\def,\edef,\addplot,\approx,\arabic,\opt,\typ,\obj,\feature,\values,\value,\z,\p,\y,\n,\d,\numcoeff,\numpow,\dencoeff,\denpow,\zcnt,\pcnt,\else,\fi,\iffalse,\begin,\end,\footnotesize,\draw,\detokenize,\DeclareOption,\foreach,\ifdim,\ifodd,\Im,\Re,\let,\newif,\nextgroupplot,\noexpand,\expandafter,\unexpanded,\PackageError,\PackageWarning,\relax,\RequirePackage,\tikzset,\pgfkeys,\pgfkeysalso,\pgfkeyscurrentkey,\pgfkeyscurrentvalue,\pgfkeysgetvalue,\pgfkeysnovalue,\pgfkeyssetvalue,\pgfkeysvalueof,\pgfmathfloattofixed,\pgfmathfloattoint,\pgfmathparse,\pgfmathresult,\pgfmathsetmacro,\pgfmathtruncatemacro,\pgfplotsset,\pgfutil@ifempty,\ProcessOptions,\ExplSyntaxOn,\ExplSyntaxOff,\@empty,\empty,\ifnum,\ifwindows,\ifx,\immediate,\jobname,\newcounter,\NewDocumentCommand,\NewDocumentEnvironment,\pdf@strcmp,\global,\g@add@to@macro,\endgroup,\begingroup,\~,\-,\@ifpackageloaded,\setcounter,\shorthandoff,\shorthandon,\stepcounter,\write,\MakePrivateLetters,\do,\tick,\lccode,\ifcat,\ifbabelshorthand,\AddToHook,\AtBeginDocument}
104 %
105 % \title{The \textsf{bodeplot} package\\version 3.1}
106 % \author{Rushikesh Kamalapurkar \\ \texttt{[email protected]}}
107 %
108 % \maketitle
109 % \tableofcontents
110 % \clearpage
111 % \section{Introduction}
112 %
113 % Generate Bode, Nyquist, and Nichols plots for transfer functions in the canonical (TF) form \begin{equation}G(s) = e^{-Ts}\frac{b_ms^m+\cdots+b_1s+b_0}{a_ns^n+\cdots+a_1s+a_0}\label{eq:TF}\end{equation} and the zero-pole-gain (ZPK) form \begin{equation}G(s) = Ke^{-Ts}\frac{(s-z_1)(s-z_2)\cdots(s-z_m)}{(s-p_1)(s-p_2)\cdots(s-p_n)}.\label{eq:ZPK}\end{equation} In the equations above, $b_m,\cdots,b_0$ and $a_n,\cdots,a_0$ are real coefficients, $T\geq 0$ is the loop delay, $z_1,\cdots,z_m$ and $p_1,\cdots,p_n$ are complex zeros and poles of the transfer function, respectively, and $K\in \Re$ is the loop gain.
114 %
115 % For transfer functions in the ZPK format in (\ref{eq:ZPK}) \emph{with zero delay}, this package also supports linear and asymptotic approximation of Bode plots.
116 %
117 % All phase plots use degrees as units. Use the |rad| package option or the optional argument |phase unit=rad| to generate plots in radians. The |phase unit| key accepts either |rad| or |deg| as inputs.
118 %
119 % Frequency inputs and outputs are in radians per second. Use the |Hz| package option or the optional argument |frequency unit=Hz| to generate plots in Hertz. The |frequency unit| key accepts either |rad| or |Hz| as inputs.
120 % \subsection{External Dependencies}
121 % By default, the package uses |gnuplot| to do all the computations. If |gnuplot| is not available, the |pgf| package option can be used to do the calculations using the native |pgf| math engine. Compilation using the |pgf| math engine is typically slower, but the end result should be the identical (other than phase wrapping in the TF form, see limitations below).
122 %\subsection{Directory Structure}
123 % 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|.
124 % \subsection{Limitations}
125 % \begin{itemize}
126 % \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.
127 % \item Use of the |declutter| option with other directory management tools such as a |tikzexternalize| prefix is not recommended.
128 % \end{itemize}
129 % \clearpage
130 % \section{TL;DR}
131 % All Bode plots in this section are for the transfer function
132 % \begin{equation}
133 % 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})} = \frac{s(10s^2+2s+2.6)}{(s^2+s+100.25)}.
134 % \end{equation}
135 % Some of the examples include a transport delay. The examples use PGF-style key-value options and natural syntax for complex numbers in zeros and poles introduced in v3.0. For examples that show the legacy syntax (version 2.1.1 and earlier), please refer to Section~\ref{sec:oldtldr}.
136 % \iffalse
137 %<*ignore>
138 % \fi
139
140 {\centering
141
142 \hrulefill
143
144 Bode plot in ZPK format
145
146 \begin{LTXexample}[pos=l,hsep=20pt,width=0.5\textwidth]
147 \BodeZPK[domain=0.01:100]{%
148 zeros={0,-0.1-0.5i,-0.1+0.5i},
149 poles={-0.5-10i,-0.5+10i},
150 gain=10%
151 }
152 \end{LTXexample}
153
154 \hrulefill
155
156 Same Bode plot over the same frequency range but supplied in Hz, in TF format with arrow decoration, transport delay, unit, and color customization (the phase plot may show wrapping if the |pgf| package option is used)
157 \begin{LTXexample}[pos=r,width=0.5\textwidth]
158 \BodeTF[%
159 domain=0.01/(2*pi):100/(2*pi),
160 samples=1000,
161 mag plot={blue,thick},
162 ph plot={green,thick},
163 tikz={%
164 >=latex,
165 phase unit=rad,
166 frequency unit=Hz%
167 },
168 mag commands={
169 \draw[->](axis cs:0.1,40) -- (axis cs:{10/(2*pi)},60);
170 \node at (axis cs: 0.08,30) {\tiny Resonant Peak};
171 }%
172 ]
173 {%
174 numerator={10,2,2.6,0},
175 denominator={1,1,100.25}%
176 }
177 \end{LTXexample}
178
179 \hrulefill
180 \clearpage
181 \hrulefill
182
183 Linear approximation with customization
184 \begin{LTXexample}[pos=l,hsep=20pt,width=0.5\textwidth]
185 \BodeZPK[%
186 domain=0.01:100,
187 mag plot={red,thick},
188 ph plot={blue,thick},
189 mag axes={ytick distance=40},
190 ph axes={ytick distance=90},
191 approx=linear%
192 ]{%
193 zeros={0,-0.1-0.5i,-0.1+0.5i},
194 poles={-0.5-10i,-0.5+10i},
195 gain=10%
196 }
197 \end{LTXexample}
198
199 \hrulefill
200
201 Plot with delay and customization
202 \begin{LTXexample}[pos=r,hsep=20pt,width=0.5\textwidth]
203 \BodeZPK[%
204 domain=0.01:100,
205 mag plot={blue,thick},
206 ph plot={green,thick},
207 mag axes={ytick distance=40},
208 ph axes={ytick distance=90}%
209 ]{%
210 zeros={0,-0.1-0.5i,-0.1+0.5i},
211 poles={-0.5-10i,-0.5+10i},
212 gain=10,
213 delay=0.01%
214 }
215 \end{LTXexample}
216
217 \hrulefill
218 \clearpage
219 \hrulefill
220
221 Individual gain and phase plots with more customization
222
223 \begin{minipage}[t]{0.45\textwidth}
224 \begin{LTXexample}[pos=t,width=\columnwidth]
225 \begin{BodeMagPlot}[%
226 axes={height=2cm,
227 width=4cm},
228 domain=0.01:100%
229 ]
230 \addBodeZPKPlots[%
231 true={black,thick},
232 linear={red,dashed,thick},
233 asymptotic={blue,dotted,thick}%
234 ]
235 {magnitude}
236 {%
237 zeros={0,-0.1-0.5i,-0.1+0.5i},
238 poles={-0.5-10i,-0.5+10i},
239 gain=10%
240 }
241 \end{BodeMagPlot}
242 \end{LTXexample}
243 \end{minipage}\hfill
244 \begin{minipage}[t]{0.45\textwidth}
245 \begin{LTXexample}[pos=t,width=\columnwidth]
246 \begin{BodePhPlot}[%
247 height=2cm,
248 width=4cm,
249 ytick distance=90,
250 domain=0.01:100%
251 ]
252 \addBodeZPKPlots[%
253 true={black,thick},
254 linear={red,dashed,thick},
255 asymptotic={blue,dotted,thick}%
256 ]
257 {phase}
258 {%
259 zeros={0,-0.1-0.5i,-0.1+0.5i},
260 poles={-0.5-10i,-0.5+10i},
261 gain=10%
262 }
263 \end{BodePhPlot}
264 \end{LTXexample}
265 \end{minipage}
266
267 \hrulefill
268
269 Multiple transfer functions in a single Bode plot using the |BodePlot| environment and the |\addBodePlot| macro introduced in v2.1.
270
271 \begin{LTXexample}[pos=r,hsep=20pt,width=0.5\textwidth]
272 \begin{BodePlot}[domain=0.01:100]
273 \addBodePlot[red,postaction=decorate,
274 decoration={%
275 markings,
276 mark=between positions 0.1 and 0.9 step 2em with {%
277 \arrow{Stealth [length=2mm, blue]}
278 }
279 },linear]{%
280 zeros={0,-0.1-0.5i,-0.1+0.5i},
281 poles={-5-10i,-5+10i},
282 gain=10%
283 }
284 \addBodePlot[black,thick]{%
285 zeros={0,-0.1-0.5i,-0.1+0.5i},
286 poles={-5-10i,-5+10i},
287 gain=10%
288 }%
289 \addBodePlot[blue,dashed]{%
290 numerator={10,2,2.6,0},
291 denominator={1,1,100.25}%
292 }
293 \end{BodePlot}
294 \end{LTXexample}
295
296 \hrulefill
297 \clearpage
298 \hrulefill
299
300 Nichols chart
301 \begin{LTXexample}[pos=l,hsep=20pt,width=0.5\textwidth]
302 \NicholsZPK[domain=0.001:500,samples=1000]
303 {%
304 zeros={0,-0.1-0.5i,-0.1+0.5i},
305 poles={-0.5-10i,-0.5+10i},
306 gain=10,
307 delay=0.01%
308 }
309 \end{LTXexample}
310
311 \hrulefill
312
313 Same Nichols chart in TF format (may show wrapping in |pgf| mode)
314 \begin{LTXexample}[pos=r,hsep=20pt,width=0.5\textwidth]
315 \NicholsTF[domain=0.001:500,samples=1000]
316 {%
317 numerator={10,2,2.6,0},
318 denominator={1,1,100.25},
319 delay=0.01%
320 }
321 \end{LTXexample}
322
323 \hrulefill
324 \clearpage
325 \hrulefill
326
327 Multiple Nichols charts with customization
328 \begin{LTXexample}[pos=l,hsep=20pt,width=0.5\textwidth]
329 \begin{NicholsChart}[%
330 ytick distance=20,
331 xtick distance=30,
332 domain=0.001:100%
333 ]
334 \addNicholsZPKChart [red,samples=1000] {%
335 zeros={0,-0.1-0.5i,-0.1+0.5i},
336 poles={-0.5-10i,-0.5+10i},
337 gain=10%
338 }
339 \addNicholsZPKChart [blue,samples=1000] {%
340 zeros={0,-0.1-0.5i,-0.1+0.5i},
341 poles={-0.5-10i,-0.5+10i},
342 gain=5%
343 }
344 \end{NicholsChart}
345 \end{LTXexample}
346
347 \hrulefill
348
349 Nyquist plot
350 \begin{LTXexample}[pos=r,hsep=20pt,width=0.5\textwidth]
351 \NyquistZPK[domain=-30:30,plot={red,thick,samples=1000}]
352 {%
353 zeros={0,-0.1-0.5i,-0.1+0.5i},
354 poles={-0.5-10i,-0.5+10i},
355 gain=10%
356 }
357 \end{LTXexample}
358
359 \hrulefill
360
361 Nyquist plot in TF format with arrows
362 \begin{LTXexample}[pos=l,width=0.5\textwidth]
363 \NyquistTF[%
364 domain=-30:30,
365 plot={%
366 samples=1000,
367 postaction=decorate,
368 decoration={%
369 markings,
370 mark=between positions 0.1 and 0.9 step 5em with {%
371 \arrow{Stealth [length=2mm, blue]}
372 }
373 }
374 }%
375 ]
376 {%
377 numerator={10,2,2.6,0},
378 denominator={1,1,100.25}%
379 }
380 \end{LTXexample}
381
382 \hrulefill
383 \clearpage
384 \hrulefill
385
386 Multiple Nyquist plots with customization
387
388 \begin{LTXexample}[pos=r,hsep=20pt,width=0.5\textwidth]
389 \begin{NyquistPlot}[domain=-30:30]
390 \addNyquistZPKPlot [red,samples=1000] {%
391 zeros={0,-0.1-0.5i,-0.1+0.5i},
392 poles={-0.5-10i,-0.5+10i},
393 gain=10%
394 }
395 \addNyquistZPKPlot [blue,samples=1000] {%
396 zeros={0,-0.1-0.5i,-0.1+0.5i},
397 poles={-0.5-10i,-0.5+10i},
398 gain=5%
399 }
400 \end{NyquistPlot}
401 \end{LTXexample}
402
403 \hrulefill
404
405 Nyquist plots with additional commands, using two different macros
406
407 \begin{minipage}[t]{0.48\textwidth}
408 \begin{LTXexample}[pos=t,width=\columnwidth]
409 \begin{NyquistPlot}[%
410 tikz={
411 spy using outlines={%
412 circle,
413 magnification=3,
414 connect spies,
415 size=2cm
416 }
417 },
418 domain=-30:30%
419 ]
420 \addNyquistZPKPlot [blue,samples=1000] {%
421 zeros={0,-0.1-0.5i,-0.1+0.5i},
422 poles={-0.5-10i,-0.5+10i},
423 gain=0.5%
424 }
425 \coordinate (spyon) at (axis cs:0,0);
426 \coordinate (spyat) at (axis cs:-22,5);
427 \spy [green] on (spyon) in
428 node [fill=white] at (spyat);
429 \end{NyquistPlot}
430 \end{LTXexample}
431 \end{minipage}\hfill
432 \begin{minipage}[t]{0.48\textwidth}
433 \begin{LTXexample}[pos=t,width=\columnwidth]
434 \NyquistZPK[%
435 plot={blue,samples=1000},
436 tikz={
437 spy using outlines={%
438 circle,
439 magnification=3,
440 connect spies,
441 size=2cm
442 }
443 },
444 commands={
445 \coordinate (spyon) at (axis cs:0,0);
446 \coordinate (spyat) at (axis cs:-22,5);
447 \spy [green] on (spyon) in
448 node [fill=white] at (spyat);
449 },
450 domain=-30:30%
451 ]
452 {%
453 zeros={0,-0.1-0.5i,-0.1+0.5i},
454 poles={-0.5-10i,-0.5+10i},
455 gain=0.5%
456 }
457 \end{LTXexample}
458 \end{minipage}
459
460 \hrulefill
461
462 \clearpage
463
464 \hrulefill
465
466 Pole-zero map
467
468 \begin{LTXexample}[pos=l,hsep=20pt,width=0.5\textwidth]
469 \PoleZeroMapZPK
470 {%
471 zeros={0,-0.1-0.5i,-0.1+0.5i},
472 poles={-0.5-10i,-0.5+10i},
473 gain=10%
474 }
475 \end{LTXexample}
476
477 \hrulefill
478
479 Pole-zero map (symmetric log scale)
480
481 \begin{LTXexample}[pos=r,width=0.5\textwidth]
482 \PoleZeroMapZPK[scale={log}]
483 {%
484 zeros={0,-0.1-0.5i,-0.1+0.5i},
485 poles={-0.5-10i,-0.5+10i},
486 gain=10%
487 }
488 \end{LTXexample}}
489
490 \hrulefill
491
492 \clearpage
493
494 % \iffalse
495 %</ignore>
496 % \fi
497 %
498 % \section{Usage}
499 % \noindent In all the macros described here, the frequency limits supplied by the user are assumed to be in |rad/s| unless either the |Hz| package option is used or the optional argument |frequency unit=Hz| is supplied by the user. All phase plots are generated in degrees unless either the |rad| package option is used or the optional argument |phase unit=rad| is supplied by the user.
500 %
501 % \subsection{Bode plots}
502 % \DescribeMacro{\BodeZPK}|\BodeZPK|\oarg{options}\marg{zpk-spec}
503 %
504 % \noindent Plots the Bode plot of a transfer function given in ZPK format using the |groupplot| environment.
505 %
506 % \noindent\textbf{zpk-spec:} A pgfkeys-style specification using keys |zeros={...}|, |poles={...}|, |gain=...|, and |delay=...| within the |/bodeplot/zpk/| family. Zeros and poles are comma-separated lists with complex poles and zeros entered using the format |a+bi|, where |a| and |b| can be arbitrary pgfmath/gnuplot expressions. The parser starts by detecting the trailing |i| and then finds the first top-level |+| or |-|. Everything between the |i| and the |+| or |-| is treated as the imaginary part, and everything before that is treated as the real part. If no |+| or |-| is found, the entire string except the trailing |i| is treated as the imaginary part and the real part is assumed to be zero. If the |gain| key is not specified, it is assumed to be 1. If the |delay| key is not specified, it is assumed to be zero.
507 %
508 % \noindent\textbf{options:} The optional argument supports a comma-separated list of options in the form |key=value|. The following keys are supported:
509 % \begin{itemize}
510 % \item |domain=min:max|: Sets the frequency range, assumed to be |0.01:100| if not specified.
511 % \item |plot={opt}|: Options passed to |\addplot| for both magnitude and phase plots.
512 % \item |mag plot={opt}|: Options passed only to the magnitude plot.
513 % \item |ph plot={opt}|: Options passed only to the phase plot.
514 % \item |axes={opt}|: Options passed to |\nextgroupplot| for both plots.
515 % \item |mag axes={opt}|: Options passed only to magnitude axis.
516 % \item |ph axes={opt}|: Options passed only to phase axis.
517 % \item |group={opt}|: Options passed to the |groupplot| environment.
518 % \item |tikz={opt}|: Options passed to the |tikzpicture| environment.
519 % \item |commands={opt}|: TikZ commands added after both plots.
520 % \item |mag commands={opt}|: TikZ commands added after magnitude plot.
521 % \item |ph commands={opt}|: TikZ commands added after phase plot.
522 % \item |approx=|\meta{true\textbar linear\textbar asymptotic}: Approximation type for the plot.
523 % \item |prefix={name}|: Prefix for gnuplot temporary files.
524 % \item |phase unit=|\meta{deg\textbar rad}: Phase axis units.
525 % \item |frequency unit=|\meta{rad\textbar Hz}: Frequency axis units.
526 % \item Any other key-value pair is passed as plot options to both plots.
527 % \end{itemize}
528 %
529 % \noindent 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
530 % \begin{verbatim}
531 %\BodeZPK [domain=0.01:100, blue, thick]
532 % {zeros={0, -0.1-0.5i, -0.1+0.5i},
533 % poles={-0.5-10i, -0.5+10i},
534 % gain=10}
535 %\end{verbatim}
536 % 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.
537 %
538 % \begin{figure}
539 % \begin{center}
540 % \BodeZPK[domain=0.01:100,blue,thick]{zeros={0,-0.1-0.5i,-0.1+0.5i},poles={-0.5-10i,-0.5+10i},gain=10}
541 % \cprotect\caption{\label{simpleBode}Output of the |\BodeZPK| macro.}
542 % \end{center}
543 % \end{figure}
544 %
545 % 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
546 %\begin{verbatim}
547 %\BodeZPK[%
548 % mag plot={red,thick},
549 % ph plot={blue,thick},
550 % mag axes={ytick distance=40,xmajorticks=true,xlabel={Frequency (rad/s)}},
551 % ph axes={ytick distance=90},
552 % group={group style={group size=2 by 1,horizontal sep=2cm,width=4cm,height=2cm}},
553 % approx=linear]
554 % {zeros={0,-0.1-0.5i,-0.1+0.5i},poles={-0.5-10i,-0.5+10i},gain=10}
555 %\end{verbatim}
556 % which generates the plot in Figure \ref{customBode}.
557 %
558 % \begin{figure}
559 % \begin{center}
560 % \BodeZPK[domain=0.01:100,mag plot={red,thick},ph plot={blue,thick},mag axes={ytick distance=40,xmajorticks=true,xlabel={Frequency (rad/s)}},ph axes={ytick distance=90},approx=linear,group={group style={group size = 2 by 1,horizontal sep=2cm},width=4cm,height=2cm}] {zeros={0,-0.1-0.5i,-0.1+0.5i},poles={-0.5-10i,-0.5+10i},gain=10}
561 % \cprotect\caption{\label{customBode}Customization of the default |\BodeZPK| macro.}
562 % \end{center}
563 % \end{figure}
564 %
565 % \noindent\textbf{Legacy interface (v2.1.1 and earlier):}
566 %
567 % \noindent |\BodeZPK| \oarg{options}\marg{zpk-spec}\marg{min-freq}\marg{max-freq}
568 %
569 % If both frequency arguments are provided, the macro falls back to the legacy format. This format is supported for backward compatibility with versions 2.1.1 and earlier:
570 %
571 % \noindent\textbf{zpk-spec (v2.1.1 and earlier):} |z/{zeros},p/{poles},k/{gain},d/{delay}| where zeros and poles are comma-separated lists of complex numbers of the form |{{real part 1,imaginary part 1},{real part 2,imaginary part 2},...}|. If the imaginary part is not provided, it is assumed to be zero. This format requires the frequency arguments |min-freq| and |max-freq| to be provided.
572 %
573 % \noindent\textbf{options (v2.1.1 and earlier):} A comma-separated list of options that modify the plots. The following options are supported:
574 % \begin{itemize}
575 % \item |plot/typ/{opt}|: modify plot properties by adding options |{opt}| to the |\addplot| macro for the magnitude plot if |typ| is |mag| and the phase plot if |typ| is |ph|.
576 % \item |axes/typ/{opt}|: modify axis properties by adding options |{opt}| to the |\nextgroupplot| macro for the magnitude plot if |typ| is |mag| and the phase plot if |typ| is |ph|.
577 % \item |commands/typ/{opt}|: add any valid TikZ commands to the magnitude plot if |typ| is |mag| and the phase plot if |typ| is |ph|.
578 % \item |plot/{opt}|: adds options |{opt}| to |\addplot| macros for both the magnitude and the phase plots.
579 % \item |axes/{opt}|: adds options |{opt}| to |\nextgroupplot| macros for both the magnitude and the phase plots.
580 % \item |group/{opt}|: adds options |{opt}| to the |groupplot| environment.
581 % \item |tikz/{opt}|: adds options |{opt}| to the |tikzpicture| environment.
582 % \item |approx/linear|: plots linear approximation.
583 % \item |approx/asymptotic|: plots asymptotic approximation.
584 % \item |prefix/{opt}|: adds the string |opt| as a prefix to all temporary files generated by |gnuplot| for this plot.
585 % \item |{opt}| (bare options): add all of the supplied options to |\addplot| macros for both the magnitude and the phase plots.
586 % \end{itemize}
587 % \noindent Example of the legacy interface:
588 %\begin{verbatim}
589 %\BodeZPK [blue,thick]
590 % {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}
591 % {0.01}{100}
592 %\end{verbatim}
593 % \DescribeMacro{\BodeTF}|\BodeTF|\oarg{options}\marg{tf-spec}
594 %
595 % \noindent Plots the Bode plot of a transfer function given in TF format.
596 %
597 % \noindent \textbf{tf-spec:} The mandatory argument contains the pgf keys |numerator={coeffs}|, |denominator={coeffs}|, and optionally |delay=value|. 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.
598 %
599 % \noindent \textbf{options:} The frequency range is specified in the first optional argument using |domain=min:max|. The optional argument can also contain any of the keys supported by the |\BodeZPK| macro except for the |approx| key since linear/asymptotic approximation is not supported for TF format.
600 %
601 % \noindent 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
602 %\begin{verbatim}
603 %\BodeTF[%
604 % domain=0.01:100,
605 % mag commands={\node at (axis cs: 2.1,0) [circle,fill,inner sep=0.05cm,
606 % label=below:{$\omega_{gc}$}]{};}]
607 % {numerator={10,2,2.6,0}, denominator={1,1,100.25}, delay=0.01}
608 %\end{verbatim}
609 % 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.
610 % \begin{figure}
611 % \begin{center}
612 % \BodeTF[domain=0.01:100,mag commands={\node at (axis cs: 2.1,0) [circle,fill,inner sep=0.05cm,label=below:{$\omega_{gc}$}] {};}]{numerator={10,2,2.6,0},denominator={1,1,100.25},delay=0.01}
613 % \cprotect\caption{\label{simpleBodeTF}Output of the |\BodeTF| macro with an optional TikZ command used to mark the gain crossover frequency.}
614 % \end{center}
615 % \end{figure}
616 %
617 % \noindent \textbf{Legacy interface (v2.1.1 and earlier):}
618 %
619 % \noindent |\BodeTF| \oarg{options}\marg{tf-spec}\marg{min-freq}\marg{max-freq}
620 %
621 % If both frequency arguments are provided, the macro falls back to the legacy 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 (format: |num/{coeffs},den/{coeffs},d/{delay}|), (2) the lower end of the frequency range, and (3) the upper end of the frequency range. 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. Example of the legacy interface:
622 %\begin{verbatim}
623 %\BodeTF[%
624 % commands/mag/{\node at (axis cs: 2.1,0) [circle,fill,inner sep=0.05cm,
625 % label=below:{$\omega_{gc}$}]{};}]
626 % {num/{10,2,2.6,0},den/{1,1,100.25},d/0.01}
627 % {0.01}{100}
628 %\end{verbatim}
629 % \DescribeEnv{BodeMagPlot}
630 % |\begin{BodeMagPlot}|\oarg{options}\\
631 % \hspace*{2em}|\addBode...|\\
632 % \noindent |\end{BodeMagPlot}|
633 %
634 % \noindent The |BodeMagPlot| environment works in conjunction with the parametric function generator macros |\addBodeZPKPlots|, |\addBodeTFPlot|, and |\addBodeComponentPlot|, intended to be used for magnitude plots. The first optional argument can contain keys from the |/bodeplot/env/| family, including |domain=min:max| to set the frequency range, |axes={...}| for axis options, |tikz={...}| for tikzpicture options, and |prefix={...}| for gnuplot file prefixes. The |prefix| option adds the provided string as a prefix to all temporary files generated by |gnuplot| for all plots in this environment. This option is useful if data generated by gnuplot for a specific plot needs to be uniquely identified. All other key-value pairs are passed as options to the |semilogaxis| environment. For examples, see the description of |\addBodeZPKPlots|, |\addBodeTFPlot|, and |\addBodeComponentPlot|.
635 %
636 % \noindent \textbf{Legacy interface (v2.1.1 and earlier):}
637 %
638 % \noindent |\begin{BodeMagPlot}|\oarg{options}\marg{min-freq}\marg{max-freq}\\
639 % \hspace*{2em}|\addBode...|\\
640 % \noindent |\end{BodeMagPlot}|
641 %
642 % \noindent If both frequency arguments are provided, the environment uses the legacy format. The first optional argument is comprised of a comma separated list of tuples, either |obj/{opt}| or just |{opt}|. Each tuple passes options to different |pgfplots| macros that generate the axes and the plots according to:
643 % \begin{itemize}
644 % \item Tuples of the form |obj/{opt}|:
645 % \begin{itemize}
646 % \item |tikz/{opt}|: modify picture properties by adding options |{opt}| to the |tikzpicture| environment.
647 % \item |axes/{opt}|: modify axis properties by adding options |{opt}| to the |semilogaxis| environment.
648 % \item |prefix/{opt}|: adds the string |opt| as a prefix to all temporary files generated by |gnuplot| for all plots in this environment. This option is useful if data generated by gnuplot for a specific plot needs to be uniquely identified.
649 % \end{itemize}
650 % \item Tuples of the form |{opt}| are passed directly to the |semilogaxis| environment.
651 % \end{itemize}
652 % The frequency limits are translated to the x-axis limits and the domain of the |semilogaxis| environment.
653 %
654 %\DescribeEnv{BodePhPlot}
655 % \hspace*{-1.75em} |\begin{BodePhPlot}|\oarg{options}\\
656 % \hspace*{2em}|\addBode...|\\
657 % \noindent |\end{BodePhPlot}|
658 %
659 % Same as |BodeMagPlot|, but intended to be used for phase plots.
660 %
661 % \DescribeMacro{\addBodeZPKPlots}
662 % \hspace*{-1.75em} |\addBodeZPKPlots|\oarg{options}\marg{plot-type}\marg{zpk-spec}
663 %
664 % \noindent Generates the appropriate parametric functions and supplies them to multiple |\addplot| macros, one for each approximation type specified in the optional argument. If no optional argument is supplied, then a single |\addplot| command corresponding to a thick true Bode plot is generated. The |options| argument accepts keys |true=|\marg{plot-opts}, |linear=|\marg{plot-opts}, and |asymptotic=|\marg{plot-opts}, where \meta{plot-opts} are TikZ/pgfplots styling options. Multiple approximations can be specified as |true={black,thick},linear={red,dashed}|, etc. This macro can be used inside any |semilogaxis| environment as long as a domain for the x-axis is supplied in the environment or parent axis options. Use with the |BodeMagPlot| or |BodePhPlot| environments supplied with this package is recommended. The second mandatory argument, |plot-type| is either |magnitude| or |phase|. If it is not equal to |phase|, it is assumed to be |magnitude|. The third mandatory argument, |zpk-spec| is the same as that of the |\BodeZPK| macro described earlier.
665 %
666 % For example, given the transfer function in (\ref{eq:ZPKExample}), its linear, asymptotic, and true Bode plots can be superimposed using:
667 %\begin{verbatim}
668 %\begin{BodeMagPlot}[height=2cm,width=4cm,domain=0.01:100,xlabel={}]
669 % \addBodeZPKPlots[true={black,thick},
670 % linear={red,dashed,thick},
671 % asymptotic={blue,dotted,thick}]
672 % {magnitude}
673 % {zeros={0,-0.1-0.5i,-0.1+0.5i},poles={-0.5-10i,-0.5+10i},gain=10}
674 %\end{BodeMagPlot}
675 %\begin{BodePhPlot}[height=2cm,width=4cm,ytick distance=90,domain=0.01:100]
676 % \addBodeZPKPlots[true={black,thick},
677 % linear={red,dashed,thick},
678 % asymptotic={blue,dotted,thick}]
679 % {phase}
680 % {zeros={0,-0.1-0.5i,-0.1+0.5i},poles={-0.5-10i,-0.5+10i},gain=10}
681 %\end{BodePhPlot}
682 %\end{verbatim}
683 % \begin{figure}
684 % \begin{center}
685 % \begin{BodeMagPlot}[height=2cm,width=4cm,domain=0.01:100,xlabel={}]
686 % \addBodeZPKPlots[true={black,thick},
687 % linear={red,dashed,thick},
688 % asymptotic={blue,dotted,thick}]
689 % {magnitude}
690 % {zeros={0,-0.1-0.5i,-0.1+0.5i},poles={-0.5-10i,-0.5+10i},gain=10}
691 % \end{BodeMagPlot}
692 % \begin{BodePhPlot}[height=2cm,width=4cm,ytick distance=90,domain=0.01:100]
693 % \addBodeZPKPlots[true={black,thick},
694 % linear={red,dashed,thick},
695 % asymptotic={blue,dotted,thick}]
696 % {phase}
697 % {zeros={0,-0.1-0.5i,-0.1+0.5i},poles={-0.5-10i,-0.5+10i},gain=10}
698 % \end{BodePhPlot}
699 % \end{center}
700 % \caption{\label{multiBodeZPK}Superimposed approximate and true Bode plots using the \texttt{BodeMagPlot} and \texttt{BodePhPlot} environments and the \texttt{\textbackslash addBodeZPKPlots} macro.}
701 % \end{figure}
702 % which generates the plot in Figure \ref{multiBodeZPK}.
703 %
704 % \noindent For backward compatibility, the legacy format with explicit frequency arguments is also supported.
705 %
706 % \noindent |\addBodeZPKPlots|\oarg{options}\marg{plot-type}\marg{zpk-spec}
707 %
708 % If an equals sign is not detected in the zpk-spec, then the macro falls back to the legacy format. In the legacy format, the macro generates the appropriate parametric functions and supplies them to multiple |\addplot| macros, one for each |approx/{opt}| pair in the optional argument. If no optional argument is supplied, then a single |\addplot| command corresponding to a thick true Bode plot is generated. If an optional argument is supplied, it needs to be one of |true/{opt}|, |linear/{opt}|, or |asymptotic/{opt}|. For example, the plots in Figure \ref{multiBodeZPK} can also be generated using:
709 %
710 %\begin{verbatim}
711 %\begin{BodeMagPlot}[height=2cm,width=4cm] {0.01} {100}
712 % \addBodeZPKPlots[%
713 % true/{black,thick},
714 % linear/{red,dashed,thick},
715 % asymptotic/{blue,dotted,thick}]
716 % {magnitude}
717 % {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}
718 %\end{BodeMagPlot}
719 %
720 %\begin{BodePhPlot}[height=2cm, width=4cm, ytick distance=90] {0.01} {100}
721 % \addBodeZPKPlots[%
722 % true/{black,thick},
723 % linear/{red,dashed,thick},
724 % asymptotic/{blue,dotted,thick}]
725 % {phase}
726 % {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}
727 %\end{BodePhPlot}
728 %\end{verbatim}
729 %
730 % \DescribeMacro{\addBodeTFPlot}
731 % \hspace{-1.75em} |\addBodeTFPlot|\oarg{options}\marg{plot-type}\marg{tf-spec}
732 %
733 % \noindent Generates a single parametric function for either Bode magnitude or phase plot of a transfer function in TF form. The generated parametric function is passed to the |\addplot| macro. This macro can be used inside any |semilogaxis| environment as long as a domain for the x-axis is supplied through the |options| argument or in the optional argument of the container |semilogaxis| environment. Use with the |BodeMagPlot| and |BodePhPlot| environments supplied with this package is recommended. The |options| can include any options that are accepted by the |\addplot| macro. The mandatory argument |plot-type| is either |magnitude| or |phase|. If it is not equal to |phase|, it is assumed to be |magnitude|. The last mandatory argument supports both legacy format |num/{coeffs},den/{coeffs},d/{delay}| and new format (v3.0) using pgfkeys like |numerator={...},denominator={...},delay=...|. The frequency range is specified using |domain=min:max| in the |options| argument.
734 %
735 % \DescribeMacro{\addBodeComponentPlot}
736 % \hspace{-1.75em} |\addBodeComponentPlot|\oarg{plot-options}\marg{plot-command}
737 %
738 % \noindent Generates a single parametric function corresponding to the mandatory argument |plot-command| and passes it to the |\addplot| macro. The plot command can be any parametric function that uses |t| as the independent variable. The parametric function must be |gnuplot| compatible (or |pgfplots| compatible if the package is loaded using the |pgf| option, \textbf{with angles passed to trigonometric functions in radian}). The intended use of this macro is to plot the parametric functions generated using the basic component macros described in Section \ref{sec:BasicComponents} below.
739 %
740 % \DescribeMacro{\addBodePlot}
741 % \hspace{-1.75em} |\addBodePlot|\oarg{plot-options}\marg{system-data}
742 %
743 % \noindent Unified macro to add Bode plots for both ZPK and TF system representations. Unlike the |\addBodeZPKPlots| and |\addBodeTFPlots| macros, this macro can only be used inside a |BodePlot| environment. \textbf{It will not function if used in a generic |semilogxaxis| environment or in the |BodeMagPlot| and |BodePhPlot| environments.} For ZPK systems, the |system-data| has the same format |zeros={...},poles={...},gain=..., delay=...| as |\addBodeZPKPlots|. For TF systems, it has the same format |numerator={...},denominator={...},gain=...,delay=...| as |\addBodeTFPlot|. The optional arguments are the same as the |\addBodeTfPlot| macro, with two additions. Passing |linear| or |asymptotic| options will generate linear or asymptotic approximations if the system representation is ZPK. These two options are ignored for TF systems. The macro automatically detects the system representation based on the presence of |zeros| or |poles| keys (ZPK) versus |numerator| or |denominator| keys (TF) in the |system-data| argument.
744 %
745 % \noindent \textbf{Legacy format (v2.1.1 and earlier):}
746 %
747 % \hspace{-1.75em} |\addBodePlot|\oarg{plot-options}\marg{system-type}\marg{system-data}
748 %
749 % If invoked using two mandatory arguments, the command falls back to the legacy format. In the legacy format, the command does not automatically detect the system representation. The second mandatory argument |system-type| should be either |zpk| or |tf| to specify the system representation. \changes{v2.1}{2025/09/26}{Added unified Bode plot macro supporting both ZPK and TF systems}
750 %
751 % \DescribeEnv{BodePlot}
752 % \hspace{-1.75em} |\begin{BodePlot}|\oarg{options}\\
753 % \hspace*{2em}|\addBodePlot...|\\
754 % \noindent |\end{BodePlot}|
755 %
756 % \noindent Starting from version 2.1, the deprecated |BodePlot| environment is revived exclusively to host multiple instances of the unified |\addBodePlot| macro. The |\addBodeZPKPlots| and |\addBodeTFPlot| macros \textbf{will not function inside this environment.} The purpose of this environment is to plot a Bode plot that contains both phase and magnitude plots for several different transfer functions.
757 %
758 % The environment uses the pgfkeys interface from the |/bodeplot/combinedenv/| family, supporting keys like |domain=min:max|, |group={...}|, |approx=...|, |mag axes={...}|, |ph axes={...}|, |mag commands={...}|, |ph commands={...}|, |tikz={...}|, and |prefix={...}| similar to the |\BodeZPK| macro.
759 %
760 % \noindent For example, the Bode plot of two different transfer functions, one in ZPK form and the other in TF form, can be generated using:
761 %\begin{verbatim}
762 %\begin{BodePlot}[domain=0.01:100,group={group style={horizontal sep=2cm}}]
763 % \addBodePlot[true={black,thick},linear={red,dashed,thick},asymptotic={blue,dotted,thick}]
764 % {zeros={0,-0.1-0.5i,-0.1+0.5i},poles={-0.5-10i,-0.5+10i},gain=10}
765 % \addBodePlot[blue,thick]
766 % {numerator={10,2,2.6,0}, denominator={1,1,100.25}, delay=0.01}
767 %\end{BodePlot}
768 %\end{verbatim}
769 %\begin{figure}
770 % \begin{center}
771 % \begin{BodePlot}[domain=0.01:100]
772 % \addBodePlot[linear,blue,thick]
773 % {zeros={0,-0.1-0.5i,-0.1+0.5i},poles={-0.5-10i,-0.5+10i},gain=10}
774 % \addBodePlot[red,thick]
775 % {numerator={10,2,2.6,0}, denominator={1,1,100.25}, delay=0.01}
776 % \end{BodePlot}
777 % \end{center}
778 % \cprotect\caption{\label{combinedBode}Bode plot combining ZPK and TF systems using the |BodePlot| environment and the unified |\addBodePlot| macro.}
779 % \end{figure}
780 % which generates the plot in Figure \ref{combinedBode}.
781 %
782 % \textbf{Legacy interface (v2.1.1 and earlier):}
783 %
784 % \noindent|\begin{BodePlot}|\oarg{options}\marg{min-freq}\marg{max-freq}\\
785 % \hspace*{2em}|\addBodePlot...|\\
786 % \noindent |\end{BodePlot}|
787 %
788 % If both frequency arguments are provided, the environment falls back to the legacy interface, where the optional arguments are the same as the legacy interface for the |\BodeZPK| macro, supporting |plot/|, |axes/|, |group/|, |tikz/| options with |mag| and |ph| sub-types. \changes{v2.1}{2025/09/26}{Enhanced BodePlot environment with unified plot command collection}
789 %
790 % \subsubsection{Basic components up to first order\label{sec:BasicComponents}}
791 %
792 % \DescribeMacro{\TypeFeatureApprox}
793 % |\TypeFeatureApprox|\marg{real-part}\marg{imaginary-part}
794 %
795 % \noindent This entry describes 20 different macros of the form |\TypeFeatureApprox| that take the real part and the imaginary part of a complex number as arguments. The |Type| in the macro name should be replaced by either |Mag| or |Ph| to generate a parametric function corresponding to the magnitude or the phase plot, respectively. The |Feature| in the macro name should be replaced by one of |K|, |Pole|, |Zero|, or |Del|, to generate the Bode plot of a gain, a complex pole, a complex zero, or a transport delay, respectively. If the |Feature| is set to either |K| or |Del|, the |imaginary-part| mandatory argument is ignored. The |Approx| in the macro name should either be removed, or it should be replaced by |Lin| or |Asymp| to generate the true Bode plot, the linear approximation, or the asymptotic approximation, respectively. If the |Feature| is set to |Del|, then |Approx| has to be removed. For example,
796 % \begin{itemize}
797 % \item |\MagK{k}{0}| or |\MagK{k}{400}| generates a parametric function for the true Bode magnitude of $ G(s) = k $
798 % \item |\PhPoleLin{a}{b}| generates a parametric function for the linear approximation of the Bode phase of $ G(s) = \frac{1}{s-a-\mathrm{i}b} $.
799 % \item |\PhDel{T}{200}| or |\PhDel{T}{0}| generates a parametric function for the Bode phase of $ G(s) = e^{-Ts} $.
800 % \end{itemize}
801 % 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:
802 %\begin{verbatim}
803 %\begin{BodePhPlot}[ytick distance=90,domain=0.01:100]
804 % \addBodeComponentPlot[black,thick]{%
805 % \PhZero{0}{0} + \PhZero{-0.1}{-0.5} + \PhZero{-0.1}{0.5} +
806 % \PhPole{-0.5}{-10} + \PhPole{-0.5}{10} + \PhK{10}{0}}
807 % \addBodeComponentPlot[red,dashed,thick] {%
808 % \PhZeroLin{0}{0} + \PhZeroLin{-0.1}{-0.5} + \PhZeroLin{-0.1}{0.5} +
809 % \PhPoleLin{-0.5}{-10} + \PhPoleLin{-0.5}{10} + \PhKLin{10}{20}}
810 % \addBodeComponentPlot[blue,dotted,thick] {%
811 % \PhZeroAsymp{0}{0} + \PhZeroAsymp{-0.1}{-0.5} + \PhZeroAsymp{-0.1}{0.5} +
812 % \PhPoleAsymp{-0.5}{-10} + \PhPoleAsymp{-0.5}{10} + \PhKAsymp{10}{40}}
813 %\end{BodePhPlot}
814 %\end{verbatim}
815 %\begin{figure}
816 % \begin{center}
817 % \begin{BodePhPlot}[ytick distance=90,domain=0.01:100]
818 % \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}}
819 % \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}}
820 % \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}}
821 % \end{BodePhPlot}
822 % \end{center}
823 % \caption{\label{multiBodeComponents}Superimposed approximate and true Bode Phase plot using the \texttt{BodePhPlot} environment, the \texttt{\textbackslash addBodeComponentPlot} macro, and several macros of the \texttt{\textbackslash TypeFeatureApprox} form.}
824 %\end{figure}
825 % which gives us the plot in Figure \ref{multiBodeComponents}.
826 %
827 % \subsubsection{Basic components of the second order}
828 %
829 % \DescribeMacro{\TypeSOFeatureApprox}
830 % |\TypeSOFeatureApprox|\marg{a1}\marg{a0}
831 %
832 % \noindent This entry describes 12 different macros of the form |\TypeSOFeatureApprox| that take the coefficients $ a_1 $ and $ a_0 $ of a general second order system as inputs. The |Feature| in the macro name should be replaced by either |Poles| or |Zeros| to generate the Bode plot of $G(s)=\frac{1}{s^2+a_1 s+a_0}$ or $G(s)=s^2+a_1 s+a_0$, respectively. The |Type| in the macro name should be replaced by either |Mag| or |Ph| to generate a parametric function corresponding to the magnitude or the phase plot, respectively. The |Approx| in the macro name should either be removed, or it should be replaced by |Lin| or |Asymp| to generate the true Bode plot, the linear approximation, or the asymptotic approximation, respectively.
833 %
834 % \DescribeMacro{\MagSOFeaturePeak}
835 % \hspace{-1.75em} |\MagSOFeaturePeak|\oarg{draw-options}\marg{a1}\marg{a0}
836 %
837 % \noindent This entry describes 2 different macros of the form |\MagSOFeaturePeak| that take the the coefficients $ a_1 $ and $ a_0 $ of a general second order system as inputs, and draw a resonant peak using the |\draw| TikZ macro. The |Feature| in the macro name should be replaced by either |Poles| or |Zeros| to generate a peak for poles and a valley for zeros, respectively. For example, the command
838 %\begin{verbatim}
839 %\begin{BodeMagPlot}[xlabel={},domain=0.1:10]
840 % \addBodeComponentPlot[red,dashed,thick]{\MagSOPoles{0.2}{1}}
841 % \addBodeComponentPlot[black,thick]{\MagSOPolesLin{0.2}{1}}
842 % \MagSOPolesPeak[thick]{0.2}{1}
843 %\end{BodeMagPlot}
844 %\end{verbatim}
845 % generates the plot in Figure \ref{BodePeak}.
846 %
847 % \begin{figure}
848 % \begin{center}
849 % \begin{BodeMagPlot}[xlabel={},domain=0.1:10]
850 % \addBodeComponentPlot[red,dashed,thick]{\MagSOPoles{0.2}{1}}
851 % \addBodeComponentPlot[black,thick]{\MagSOPolesLin{0.2}{1}}
852 % \MagSOPolesPeak[very thick]{0.2}{1}
853 % \end{BodeMagPlot}
854 % \end{center}
855 % \cprotect\caption{\label{BodePeak} Resonant peak in asymptotic Bode plot using |\MagSOPolesPeak|.}
856 % \end{figure}
857 %
858 % \DescribeMacro{\TypeCSFeatureApprox}
859 % \hspace{-1.75em} |\TypeCSFeatureApprox|\marg{zeta}\marg{omega-n}
860 %
861 % \noindent This entry describes 12 different macros of the form |\TypeCSFeatureApprox| that take the damping ratio, $ \zeta $, and the natural frequency, $ \omega_n $ of a canonical second order system as inputs. The |Type| in the macro name should be replaced by either |Mag| or |Ph| to generate a parametric function corresponding to the magnitude or the phase plot, respectively. The |Feature| in the macro name should be replaced by either |Poles| or |Zeros| to generate the Bode plot of $G(s)=\frac{1}{s^2+2\zeta\omega_n s+\omega_n^2}$ or $G(s)=s^2+2\zeta\omega_n s+\omega_n^2$, respectively. The |Approx| in the macro name should either be removed, or it should be replaced by |Lin| or |Asymp| to generate the true Bode plot, the linear approximation, or the asymptotic approximation, respectively.
862 %
863 % \DescribeMacro{\MagCSFeaturePeak}
864 % \hspace{-1.75em} |\MagCSFeaturePeak|\oarg{draw-options}\marg{zeta}\marg{omega-n}
865 %
866 % \noindent This entry describes 2 different macros of the form |\MagCSFeaturePeak| that take the damping ratio, $ \zeta $, and the natural frequency, $ \omega_n $ of a canonical second order system as inputs, and draw a resonant peak using the |\draw| TikZ macro. The |Feature| in the macro name should be replaced by either |Poles| or |Zeros| to generate a peak for poles and a valley for zeros, respectively.
867 %
868 % \DescribeMacro{\MagCCFeaturePeak}
869 % \hspace{-1.75em} |\MagCCFeaturePeak|\oarg{draw-options}\marg{real-part}\marg{imaginary-part}
870 %
871 % \noindent This entry describes 2 different macros of the form |\MagCCFeaturePeak| that take the real and imaginary parts of a pair of complex conjugate poles or zeros as inputs, and draw a resonant peak using the |\draw| TikZ macro. The |Feature| in the macro name should be replaced by either |Poles| or |Zeros| to generate a peak for poles and a valley for zeros, respectively.
872 %
873 % \subsection{Nyquist plots}
874 % \DescribeMacro{\NyquistZPK}
875 % |\NyquistZPK| \oarg{options}\marg{zpk-spec}
876 %
877 % \noindent Generates the Nyquist diagram of a transfer function given in ZPK form and marks the critical point $(-1,0)$ with a thick red $+$.
878 %
879 % \noindent \textbf{zpk-spec:} Same as the |\BodeZPK| macro. Provide zeros, poles, gain, and optional delay with the pgfkeys-style format |zeros={...},poles={...},gain=...,delay=...|. Complex numbers are written as |a+bi|, where |a| and |b| can be arbitrary pgfmath/gnuplot expressions. The macro assumes unit gain and zero delay when those keys are omitted.
880 %
881 % \noindent \textbf{options:}
882 % \begin{itemize}
883 % \item |domain=min:max|: Sets the frequency sweep for the contour. The default sweep is |-30:30| when the key is not provided.
884 % \item |plot={opt}|: Appends |opt| to the |\addplot| options that draw the Nyquist curve, e.g., |samples=2000|.
885 % \item |axes={opt}|: Adds |opt| to the surrounding |axis| environment.
886 % \item |commands={opt}|: Inserts |opt| immediately after the contour inside the |axis|, which is useful for annotations or additional plotting commands.
887 % \item |tikz={opt}|: Adds |opt| to the enclosing |tikzpicture|.
888 % \item |prefix={name}|: Overrides the prefix used for auxiliary gnuplot tables.
889 % \end{itemize}
890 % Any additional |key=value| entries are forwarded to |\addplot|, so native |pgfplots| options may be supplied without wrapping them in |plot={...}|. Linear or asymptotic approximations are not available for Nyquist plots. To indicate the direction of increasing frequency, load |decorations.markings| and |arrows.meta| and add |plot={postaction=decorate,decoration={...}}|. Very large sample counts in combination with decorations can trigger the warning |! Dimension too big|.
891 %
892 % \noindent For example, the command
893 %\begin{verbatim}
894 %\NyquistZPK[
895 % domain=-30:30,
896 % plot={red,thick,samples=2000},
897 % axes={blue,thick}]
898 % {zeros={0,-0.1-0.5i,-0.1+0.5i},
899 % poles={-0.5-10i,-0.5+10i},
900 % gain=10}
901 %\end{verbatim}
902 % \noindent generates the Nyquist plot in Figure \ref{simpleNyquistZPK}.
903 %
904 % \noindent \textbf{Legacy interface (v2.1.1 and earlier):}
905 %
906 % \noindent |\NyquistZPK|\oarg{options}\marg{zpk-spec}\marg{min-freq}\marg{max-freq}
907 %
908 % The optional argument accepts comma-separated tuples |plot/{opt}|, |axes/{opt}|, |commands/{opt}|, |tikz/{opt}|, and |prefix/{opt}|, while a bare |{opt}| is treated as |plot/{opt}|. The |zpk-spec| uses the legacy format |z/{...},p/{...},k/...,d/...|, where complex numbers are expressed as |{a,b}|. Supplying the frequency arguments auto-selects the legacy behaviour and is intended only for maintaining older documents.
909 %
910 % \noindent Example of legacy usage:
911 %\begin{verbatim}
912 %\NyquistZPK[plot/{red,thick,samples=2000},axes/{blue,thick}]
913 % {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}
914 % {-30}{30}
915 %\end{verbatim}
916 %
917 % \begin{figure}
918 % \begin{center}
919 % \NyquistZPK[domain=-30:30,plot={red,thick,samples=2000},axes={blue,thick}] {zeros={0,-0.1-0.5i,-0.1+0.5i},poles={-0.5-10i,-0.5+10i},gain=10}
920 % \cprotect\caption{\label{simpleNyquistZPK}Output of the |\NyquistZPK| macro.}
921 % \end{center}
922 % \end{figure}
923 %
924 % \DescribeMacro{\NyquistTF}
925 % \hspace{-1.75em} |\NyquistTF|\oarg{options}\marg{tf-spec}
926 %
927 % \noindent Generates the Nyquist diagram of a transfer function expressed in polynomial form. The |tf-spec| is the same as that of the |\BodeTF| macro described earlier and the |options| argument uses the same pgfkeys interface as |\NyquistZPK|. A legacy interface similar to the one in |\NyquistZPK| is also supported when both frequency arguments are provided. For example,
928 %\begin{verbatim}
929 %\NyquistTF[
930 % domain=-30:30,
931 % plot={green,thick,samples=500,postaction=decorate,
932 % decoration={markings,
933 % mark=between positions 0.1 and 0.9 step 5em
934 % with{\arrow{Stealth[length=2mm, blue]}}}}]
935 % {numerator={10,2,2.6,0}, denominator={1,1,100.25}}
936 %\end{verbatim}
937 % \noindent yields the Nyquist plot in Figure \ref{simpleNyquistTF}. As with the ZPK variant, combining dense sampling with |decorations.markings| may trigger the warning |! Dimension too big|.
938 %
939 % \noindent Legacy syntax remains available:
940 %\begin{verbatim}
941 %\NyquistTF[plot/{green,thick,samples=500,postaction=decorate,
942 % decoration={markings,
943 % mark=between positions 0.1 and 0.9 step 5em
944 % with{\arrow{Stealth[length=2mm, blue]}}}}]
945 % {num/{10,2,2.6,0},den/{1,1,100.25}}
946 % {-30}{30}
947 %\end{verbatim}
948 %
949 % \begin{figure}
950 % \begin{center}
951 % \NyquistTF[domain=-30:30,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]}}}}] {numerator={10,2,2.6,0},denominator={1,1,100.25},delay=0.01}
952 % \cprotect\caption{\label{simpleNyquistTF}Output of the |\NyquistTF| macro with direction arrows. Increasing the number of samples can cause |decorations.markings| to throw errors.}
953 % \end{center}
954 % \end{figure}
955 %
956 % \DescribeEnv{NyquistPlot}
957 % \hspace{-1.75em} |\begin{NyquistPlot}|\oarg{options}\\
958 % \hspace*{2em}|\addNyquist...|\\
959 % \noindent |\end{NyquistPlot}|
960 %
961 % \noindent Wraps a |tikzpicture|/|axis| pair tailored for Nyquist diagrams and hosts one or more |\addNyquist...| commands.
962 %
963 % \textbf{options:}
964 % \begin{itemize}
965 % \item |domain=min:max|: Sets the frequency sweep that is forwarded to the enclosed |\addplot| commands. The default sweep is |0.01:100|; choose a symmetric interval such as |-30:30| for traditional Nyquist diagrams.
966 % \item |axes={opt}|: Appends |opt| to the |axis| options (for example, |axis equal| or |grid=both|).
967 % \item |tikz={opt}|: Adds |opt| to the surrounding |tikzpicture|.
968 % \item |prefix={name}|: Overrides the prefix used for auxiliary gnuplot tables created inside the environment.
969 % \item |phase unit=deg|/|rad| and |frequency unit=rad|/|Hz|: Synchronises the environment with the package-wide unit switches.
970 % \item Additional |key=value| pairs are passed straight to the |axis| environment, so native |pgfplots| options can be provided without extra wrapping.
971 % \end{itemize}
972 % The environment marks the critical point $(-1,0)$ with a red |+| by default. Pair it with |\addNyquistZPKPlot| or |\addNyquistTFPlot| to draw the actual contour.
973 %
974 % \noindent \textbf{Legacy interface (v2.1.1 and earlier):}
975 %
976 % \noindent |\begin{NyquistPlot}|\oarg{options}\marg{min-freq}\marg{max-freq}\\
977 % \hspace*{2em}|\addNyquist...|\\
978 % \noindent |\end{NyquistPlot}|
979 %
980 % \noindent The legacy optional argument accepts comma-separated tuples |obj/{opt}| or bare |{opt}|. Valid |obj| tokens are |tikz|, |axes|, and |prefix|; unqualified entries are appended to the |axis| options. The mandatory frequency limits fix the axis and plot domain.
981 %
982 % \DescribeMacro{\addNyquistZPKPlot}
983 % \hspace*{-1.5em}|\addNyquistZPKPlot|\oarg{plot-options}\marg{zpk-spec}
984 %
985 % \noindent Adds a Nyquist contour for a transfer function supplied in ZPK form.
986 %
987 % \noindent \textbf{zpk-spec:} Same as the |\NyquistZPK| macro.
988 %
989 % \noindent \textbf{plot-options:} Appended verbatim to |\addplot|, enabling control over sampling density, decorations, colors, and so on. Ensure that the surrounding |axis| (typically provided by |\begin{NyquistPlot}|) defines a suitable |domain| so that the generated parametric function matches the frequency sweep.
990 %
991 % \noindent \textbf{Legacy interface (v2.1.1 and earlier):}
992 %
993 % \noindent |\addNyquistZPKPlot|\oarg{plot-options}\marg{z/\{\ldots\},p/\{\ldots\},k/\ldots,d/\ldots}
994 %
995 % \noindent The legacy format is preserved for backward compatibility; the optional argument continues to be forwarded directly to |\addplot|.
996 %
997 % \DescribeMacro{\addNyquistTFPlot}
998 % \hspace*{-1.75em} |\addNyquistTFPlot|\oarg{plot-options}\marg{tf-spec}
999 %
1000 % \noindent Identical to |\addNyquistZPKPlot| but expects |tf-spec| in the same polynomial format accepted by |\BodeTF|.
1001 %
1002 % \subsection{Nichols charts}
1003 % \DescribeMacro{\NicholsZPK}
1004 % |\NicholsZPK| \oarg{options}\marg{zpk-spec}
1005 %
1006 % \noindent Generates a Nichols chart (phase versus gain) for a transfer function in ZPK form.
1007 %
1008 % The |zpk-spec| and |options| arguments are the same as those of the |\BodeZPK| macro described earlier except that the |domain=min:max| key now sets the frequency sweep for the Nichols contour (default |0.01:100|).
1009 %
1010 % Supplying both frequency arguments activates the legacy behaviour for backward compatibility.
1011 %
1012 % \noindent |\NicholsZPK| \oarg{options}\marg{zpk-spec}\marg{min-freq}\marg{max-freq}
1013 %
1014 % \noindent Example:
1015 %\begin{verbatim}
1016 %\NicholsZPK[
1017 % domain=0.001:100,
1018 % plot={red,thick,samples=2000},
1019 % axes={ytick distance=20}]
1020 % {zeros={0,-0.1-0.5i,-0.1+0.5i},
1021 % poles={-0.5-10i,-0.5+10i},
1022 % gain=10}
1023 %\end{verbatim}
1024 % Legacy usage remains available:
1025 %\begin{verbatim}
1026 %\NicholsZPK[plot/{red,thick,samples=2000}]
1027 % {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}
1028 % {0.001}{100}
1029 %\end{verbatim}
1030 %
1031 % \DescribeMacro{\NicholsTF}
1032 % \hspace{-1.75em} |\NicholsTF| \oarg{options}\marg{tf-spec}
1033 %
1034 % \noindent Produces a Nichols chart for transfer functions expressed in polynomial form. Same as |\NicholsZPK| except that |tf-spec| is akin to |\BodeTF|. Supplying both frequency arguments reverts the macro to the legacy interface.
1035 %
1036 % \noindent Example:
1037 %\begin{verbatim}
1038 %\NicholsTF[
1039 % domain=0.001:100,
1040 % plot={green,thick,samples=2000}]
1041 % {numerator={10,2,2.6,0},
1042 % denominator={1,1,100.25},
1043 % delay=0.01}
1044 %\end{verbatim}
1045 % Legacy usage remains available:
1046 %\begin{verbatim}
1047 %\NicholsTF[plot/{green,thick,samples=2000}]
1048 % {num/{10,2,2.6,0},den/{1,1,100.25},d/0.01}
1049 % {0.001}{100}
1050 %\end{verbatim}
1051 % Both examples produce the chart in Figure \ref{simpleNicholsTF}.
1052 %
1053 % \begin{figure}
1054 % \begin{center}
1055 % \NicholsTF[domain=0.001:100,plot={green,thick,samples=2000}] {numerator={10,2,2.6,0},denominator={1,1,100.25},delay=0.01}
1056 % \cprotect\caption{\label{simpleNicholsTF}Output of the |\NicholsTF| macro.}
1057 % \end{center}
1058 % \end{figure}
1059 %
1060 % \DescribeEnv{NicholsChart}
1061 % \hspace{-1.75em} |\begin{NicholsChart}|\oarg{options}\\
1062 % \hspace*{2em}|\addNichols...|\\
1063 % \noindent|\end{NicholsChart}|
1064 %
1065 % \noindent Provides a ready-made |tikzpicture|/|axis| scaffold for Nichols charts and collects |\addNichols...| commands. Current and legacy interfaces are similar to the |NyquistPlot| environment, except that the domain defaults to |0.01:100| if not supplied.
1066 %
1067 % \DescribeMacro{\addNicholsZPKChart}
1068 % \hspace{-1.75em} |\addNicholsZPKChart|\oarg{plot-options}\marg{zpk-spec}
1069 %
1070 % \noindent Adds a Nichols contour for a transfer function expressed in ZPK form. Current and legacy interfaces are similar to those of |\addNyquistZPKPlot|, with the |domain| key now setting the frequency sweep for the Nichols contour, with a default of |0.01:100|.
1071 %
1072 % \DescribeMacro{\addNicholsTFChart}
1073 % \hspace{-1.75em} |\addNicholsTFChart|\oarg{plot-options}\marg{tf-spec}
1074 %
1075 % \noindent Equivalent to |\addNicholsZPKChart| for transfer functions supplied in polynomial form similar to |\BodeTF|. Phase unwrapping in |gnuplot| mode mirrors the behaviour of |\BodeTF|.
1076 %
1077 % \subsection{Pole-zero maps}
1078 % \DescribeMacro{\PoleZeroMapZPK}
1079 % |\PoleZeroMapZPK| \oarg{options}\marg{zpk-spec}
1080 %
1081 % \noindent Plots the pole-zero map of a transfer function given in ZPK format, similar to MATLAB's |pzmap| function. The poles are marked with red 'x' symbols and the zeros are marked with blue 'o' symbols. The mandatory argument supports both the current |zeros={...},poles={...},gain=...| format with complex numbers expressed as |a+bi| (where |a| and |b| can be arbitrary pgfmath/gnuplot expressions) and the legacy format |z/{zeros},p/{poles},k/{gain}| with complex numbers expressed as |{a,b}|. Note that the delay parameter |d| is ignored since delays do not affect pole-zero locations. The optional argument supports the same tuples as |\NyquistZPK|.\changes{v2.0}{2025/09/26}{Added pole-zero map functionality}
1082 %
1083 % The |scale={log}| option enables symmetric logarithmic (symlog) scaling for both axes. This is particularly useful for systems with poles and zeros spanning multiple decades. The symlog scaling preserves the sign of coordinates while applying logarithmic scaling to their magnitude, allowing visualization of both positive and negative values on the same plot.
1084 %
1085 % The following example generates a standard linear pole-zero map with the zeros at the origin and at $-0.1 \pm 0.5i$, and poles at $-0.5 \pm 10i$.
1086 %\begin{verbatim}
1087 %\PoleZeroMapZPK[axes/{grid=major}]
1088 % {zeros={0, -0.1-0.5i, -0.1+0.5i}, poles={-0.5-10i, -0.5+10i}, gain=10}
1089 %\end{verbatim}
1090 % For logarithmic scaling:
1091 %\begin{verbatim}
1092 %\PoleZeroMapZPK[scale=log]
1093 % {zeros={0, -0.1-0.5i, -0.1+0.5i}, poles={-0.5-10i, -0.5+10i}, gain=10}
1094 %\end{verbatim}
1095 % The legacy format remains available:
1096 %\begin{verbatim}
1097 %\PoleZeroMapZPK[axes/{grid=major}]
1098 % {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}
1099 %\PoleZeroMapZPK[scale/log]
1100 % {zeros={0, -0.1-0.5i, -0.1+0.5i}, poles={-0.5-10i, -0.5+10i}, gain=10}
1101 %\end{verbatim}
1102 % Both examples produce the pole-zero maps in Figure \ref{poleZeroMaps}.
1103 % \begin{figure}
1104 % \begin{center}
1105 % \PoleZeroMapZPK[axes={grid=major}]
1106 % {zeros={0, -0.1-0.5i, -0.1+0.5i}, poles={-0.5-10i, -0.5+10i}, gain=10}
1107 %
1108 % \vspace{1em}
1109 %
1110 % \PoleZeroMapZPK[scale=log]
1111 % {zeros={0, -0.1-0.5i, -0.1+0.5i}, poles={-0.5-10i, -0.5+10i}, gain=10}
1112 % \cprotect\caption{\label{poleZeroMaps}Pole-zero maps generated using the |\PoleZeroMapZPK| macro with linear and logarithmic scaling.}
1113 % \end{center}
1114 % \end{figure}
1115 % \StopEventually{\PrintIndex}
1116 % \clearpage
1117 % \section{Implementation}
1118 % \subsection{Initialization}
1119 % \begin{macro}{\n@mod}
1120 % \begin{macro}{\n@mod@p}
1121 % \begin{macro}{\n@mod@n}
1122 % \begin{macro}{\n@pow}
1123 % \begin{macro}{bp@gnuplot@id}
1124 % \begin{macro}{bp@gnu@prefix}
1125 % \changes{v1.0.3}{2021/11/03}{Added jobname to gnuplot prefix}
1126 % \changes{v1.0.8}{2022/07/06}{Fixed issue \#6}
1127 % \changes{v1.1.4}{2023/10/12}{Changed phase wrapping in pgf mode}
1128 % \changes{v1.2}{2024/04/18}{Removed global option to process pgf commands in radians}
1129 % We start by processing the class options.
1130 % \begin{macrocode}
1131 \newif\if@pgfarg\@pgfargfalse
1132 \DeclareOption{pgf}{
1133 \@pgfargtrue
1134 }
1135 \newif\if@declutterarg\@declutterargfalse
1136 \DeclareOption{declutter}{
1137 \@declutterargtrue
1138 }
1139 \newif\if@radarg\@radargfalse
1140 \DeclareOption{rad}{
1141 \@radargtrue
1142 }
1143 \newif\if@hzarg\@hzargfalse
1144 \DeclareOption{Hz}{
1145 \@hzargtrue
1146 }
1147 \ProcessOptions\relax
1148 % \end{macrocode}
1149 % 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.
1150 % \begin{macrocode}
1151 \newcommand{\n@mod}[2]{(#1)-((round((#1)/(#2)))*(#2))}
1152 \newcommand{\n@mod@p}[2]{(#1)-((floor((#1)/(#2)))*(#2))}
1153 \newcommand{\n@mod@n}[2]{(#1)-((floor((#1)/(#2))+1)*(#2))}
1154 \if@pgfarg
1155 \newcommand{\n@pow}[2]{(#1)^(#2)}
1156 \else
1157 \newcommand{\n@pow}[2]{(#1)**(#2)}
1158 % \end{macrocode}
1159 % A counter so that a new data table is generated and for each new plot. If the plot macros have not changed, the tables, once generated, can be reused by |gnuplot|, which reduces compilation time. The |declutter| option is used to enable the |gnuplot| directory to declutter the working directory. The |gnuplot| prefix is set to be the name of the tex file unless the user supplies a prefix through the |prefix| option. \changes{v2.1.1}{2025/10/04}{Added a new helper command to allow the user to set per-plot gnuplot file names to address feature request \#14}
1160 % \begin{macrocode}
1161 \newcounter{bp@gnuplot@id}
1162 \setcounter{bp@gnuplot@id}{0}
1163 \newcommand{\bp@prefix}{%
1164 \ifx\bp@user@prefix\@empty
1165 \if@declutterarg
1166 gnuplot/\jobname
1167 \else
1168 \jobname
1169 \fi
1170 \else
1171 \if@declutterarg
1172 gnuplot/\bp@user@prefix
1173 \else
1174 \bp@user@prefix
1175 \fi
1176 \fi
1177 }
1178 \tikzset{
1179 bp@gnu@prefix/.style={
1180 id=\arabic{bp@gnuplot@id},
1181 prefix=\bp@prefix
1182 }
1183 }
1184 % \end{macrocode}
1185 % If the operating system is not Windows, and if the |declutter| option is passed, we create the |gnuplot| folder if it does not already exist. \changes{v1.0.2}{2021/11/01}{Fixed issue \#1}
1186 % \begin{macrocode}
1187 \ifwindows\else
1188 \if@declutterarg
1189 \immediate\write18{mkdir -p gnuplot}
1190 \fi
1191 \fi
1192 \fi
1193 % \end{macrocode}
1194 % \end{macro}
1195 % \end{macro}
1196 % \end{macro}
1197 % \end{macro}
1198 % \end{macro}
1199 % \end{macro}
1200 % \begin{macro}{\if@babel}
1201 % \begin{macro}{\bp@short@list}
1202 % Check if the |babel| package is loaded and generate a list of shorthands if it is. The code is based on \href{https://tex.stackexchange.com/a/708797/110602}{this stackexchange answer}.\changes{v1.1.6}{2024/01/14}{Detect `babel-french' using `frenchbsetup'}\changes{v1.1.7}{2024/02/06}{Directly detect shorthands instead of detecting the language.}
1203 % \begin{macrocode}
1204 \newif\if@babel\@babelfalse
1205 \AtBeginDocument{%
1206 \@ifpackageloaded{babel}{%
1207 \@babeltrue
1208 \let\bp@short@list\@empty
1209 \def\do#1{%
1210 \begingroup
1211 \lccode`\~=`#1\relax
1212 \lowercase{\ifbabelshorthand~{\g@addto@macro\bp@short@list{~}}{}}
1213 \endgroup
1214 }
1215 \dospecials
1216 }{}
1217 }
1218 % \end{macrocode}
1219 % \end{macro}
1220 % \end{macro}
1221 % \begin{macro}{bp@style}
1222 % Default axis properties for all plot macros are collected in this |pgf| style.
1223 % \begin{macrocode}
1224 \pgfplotsset{
1225 bp@style/.style = {
1226 label style={font=\footnotesize},
1227 tick label style={font=\footnotesize},
1228 grid=both,
1229 major grid style={color=gray!80},
1230 minor grid style={color=gray!20},
1231 x label style={at={(ticklabel cs:0.5)},anchor=near ticklabel},
1232 y label style={at={(ticklabel cs:0.5)},anchor=near ticklabel},
1233 scale only axis,
1234 samples=200,
1235 width=5cm,
1236 log basis x=10
1237 }
1238 }
1239 % \end{macrocode}
1240 % \end{macro}
1241 % \begin{macro}{bp@freq@filter}
1242 % \begin{macro}{bp@freq@label}
1243 % \begin{macro}{\bp@freq@scale}
1244 % \begin{macro}{\bp@ph@scale}
1245 % \begin{macro}{bp@ph@x@label}
1246 % \begin{macro}{bp@ph@y@label}
1247 % These macros handle the |Hz| and |rad| class options and two new |pgf| keys named |frequency unit| and |phase unit| for conversion of frequency and phase units, respectively. \changes{v1.1.1}{2022/07/31}{New macros to enable `Hz' and `rad' units for frequency and phase, respectively}
1248 % \begin{macrocode}
1249 \pgfplotsset{bp@freq@filter/.style = {}}
1250 \def\bp@freq@scale{1}
1251 \pgfplotsset{bp@freq@label/.style = {xlabel = {Frequency (rad/s)}}}
1252 \pgfplotsset{bp@ph@x@label/.style = {xlabel={Phase (deg)}}}
1253 \pgfplotsset{bp@ph@y@label/.style = {ylabel={Phase (deg)}}}
1254 \def\bp@ph@scale{180/pi}
1255 \if@radarg
1256 \pgfplotsset{bp@ph@y@label/.style = {ylabel={Phase (rad)}}}
1257 \pgfplotsset{bp@ph@x@label/.style = {xlabel={Phase (rad)}}}
1258 \def\bp@ph@scale{1}
1259 \tikzset{
1260 phase unit/.initial={rad},
1261 phase unit/.default={rad},
1262 }
1263 \else
1264 \tikzset{
1265 phase unit/.initial={deg},
1266 phase unit/.default={deg},
1267 }
1268 \fi
1269 \if@hzarg
1270 \def\bp@freq@scale{2*pi}
1271 \pgfplotsset{bp@freq@label/.style = {xlabel = {Frequency (Hz)}}}
1272 \if@pgfarg
1273 \pgfplotsset{bp@freq@filter/.style = {x filter/.expression={x-log10(2*pi)}}}
1274 \fi
1275 \tikzset{
1276 frequency unit/.initial={Hz},
1277 frequency unit/.default={Hz},
1278 }
1279 \else
1280 \tikzset{
1281 frequency unit/.initial={rad},
1282 frequency unit/.default={rad},
1283 }
1284 \fi
1285 \tikzset{
1286 phase unit/.is choice,
1287 phase unit/deg/.code={
1288 \pgfkeys{/bodeplot/phase unit=deg}
1289 },
1290 phase unit/rad/.code={
1291 \pgfkeys{/bodeplot/phase unit=rad}
1292 },
1293 frequency unit/.is choice,
1294 frequency unit/Hz/.code={
1295 \pgfkeys{/bodeplot/frequency unit=Hz}
1296 },
1297 frequency unit/rad/.code={
1298 \pgfkeys{/bodeplot/frequency unit=rad}
1299 }
1300 }
1301 % \end{macrocode}
1302 % \end{macro}
1303 % \end{macro}
1304 % \end{macro}
1305 % \end{macro}
1306 % \end{macro}
1307 % \end{macro}
1308 % \subsection{PGF keys interface}
1309 % \begin{macro}{/bodeplot/env}
1310 % |PGF| keys for environment options.\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}
1311 % \begin{macrocode}
1312 \pgfkeys{
1313 /bodeplot/env/.is family,
1314 /bodeplot/env/.cd,
1315 reset/.code={%
1316 \pgfkeyssetvalue{/bodeplot/env/@tikz}{}
1317 \pgfkeyssetvalue{/bodeplot/env/@prefix}{}
1318 \pgfkeyssetvalue{/bodeplot/env/@domain}{}
1319 \if@hzarg
1320 \pgfkeys{/bodeplot/env/frequency unit=Hz}
1321 \else
1322 \pgfkeys{/bodeplot/env/frequency unit=rad}
1323 \fi
1324 \if@radarg
1325 \pgfkeys{/bodeplot/env/phase unit=rad}
1326 \else
1327 \pgfkeys{/bodeplot/env/phase unit=deg}
1328 \fi
1329 \gdef\bp@domain@start{0.01}
1330 \gdef\bp@domain@end{100}
1331 \gdef\bp@axes{}
1332 },
1333 axes/.code={
1334 \ifx\bp@axes\@empty
1335 \xdef\bp@axes{\unexpanded\expandafter{#1}}
1336 \else
1337 \xdef\bp@axes{\unexpanded\expandafter{\bp@axes},
1338 \unexpanded\expandafter{#1}}
1339 \fi
1340 },
1341 axes/.value required,
1342 tikz/.code={\pgfkeyssetvalue{/bodeplot/env/@tikz}{#1}},
1343 tikz/.value required,
1344 prefix/.code={\pgfkeyssetvalue{/bodeplot/env/@prefix}{#1}},
1345 prefix/.value required,
1346 domain/.code args={#1:#2}{%
1347 \gdef\bp@domain@start{#1}%
1348 \gdef\bp@domain@end{#2}%
1349 },
1350 domain/.value required,
1351 phase unit/.initial={deg},
1352 phase unit/.default={deg},
1353 phase unit/.is choice,
1354 phase unit/deg/.code={
1355 \renewcommand{\bp@ph@scale}{180/pi}
1356 \pgfplotsset{bp@ph@x@label/.style = {xlabel={Phase (deg)}}}
1357 \pgfplotsset{bp@ph@y@label/.style = {ylabel={Phase (deg)}}}
1358 },
1359 phase unit/rad/.code={
1360 \renewcommand{\bp@ph@scale}{1}
1361 \pgfplotsset{bp@ph@y@label/.style = {ylabel={Phase (rad)}}}
1362 \pgfplotsset{bp@ph@x@label/.style = {xlabel={Phase (rad)}}}
1363 },
1364 frequency unit/.initial={rad},
1365 frequency unit/.default={rad},
1366 frequency unit/.is choice,
1367 frequency unit/Hz/.code={
1368 \renewcommand{\bp@freq@scale}{2*pi}
1369 \pgfplotsset{bp@freq@label/.style = {xlabel = {Frequency (Hz)}}}
1370 \if@pgfarg
1371 \pgfplotsset{bp@freq@filter/.style = {x filter/.expression={x-log10(2*pi)}}}
1372 \fi
1373 },
1374 frequency unit/rad/.code={
1375 \renewcommand{\bp@freq@scale}{1}
1376 \pgfplotsset{bp@freq@label/.style = {xlabel = {Frequency (rad/s)}}}
1377 \if@pgfarg
1378 \pgfplotsset{bp@freq@filter/.style = {x filter/.expression={x}}}
1379 \fi
1380 },
1381 .unknown/.code={%
1382 \edef\bp@full{\pgfkeyscurrentkey}%
1383 \def\stripbodeprefix##1/bodeplot/env/##2\relax{##2}%
1384 \edef\bp@short{\expandafter\stripbodeprefix\bp@full\relax}%
1385 \edef\bp@checkfull{\bp@full}%
1386 \edef\bp@checkshort{\bp@short}%
1387 \ifx\bp@checkfull\bp@checkshort
1388 \def\removeslash##1/##2\relax{##2}%
1389 \edef\bp@short{\expandafter\removeslash\bp@full\relax}%
1390 \fi
1391 \ifx\pgfkeyscurrentvalue\pgfkeysnovalue
1392 \edef\bp@new{\bp@short}%
1393 \else
1394 \edef\bp@new{\bp@short=
1395 {\unexpanded\expandafter{\pgfkeyscurrentvalue}}}%
1396 \fi
1397 \ifx\bp@new\@empty\else
1398 \ifx\bp@axes\@empty
1399 \xdef\bp@axes{\unexpanded\expandafter{\bp@new}}
1400 \else
1401 \xdef\bp@axes{\unexpanded\expandafter{\bp@axes},%
1402 \unexpanded\expandafter{\bp@new}}
1403 \fi
1404 \fi
1405 }
1406 }
1407 % \end{macrocode}
1408 % \end{macro}
1409 % \begin{macro}{/bodeplot}
1410 % |PGF| keys for bode command options.\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}
1411 % \begin{macrocode}
1412 \pgfkeys{
1413 /bodeplot/.is family,
1414 /bodeplot/.cd,
1415 reset/.code={%
1416 \pgfkeyssetvalue{/bodeplot/@axes/mag}{}
1417 \pgfkeyssetvalue{/bodeplot/@axes/ph}{}
1418 \pgfkeyssetvalue{/bodeplot/@group}{}
1419 \pgfkeyssetvalue{/bodeplot/@approx}{true}
1420 \pgfkeyssetvalue{/bodeplot/@commands/mag}{}
1421 \pgfkeyssetvalue{/bodeplot/@commands/ph}{}
1422 \pgfkeyssetvalue{/bodeplot/@tikz}{}
1423 \pgfkeyssetvalue{/bodeplot/@prefix}{}
1424 \gdef\bp@domain@start{0.01}
1425 \gdef\bp@domain@end{100}
1426 \if@hzarg
1427 \pgfkeys{/bodeplot/frequency unit=Hz}
1428 \else
1429 \pgfkeys{/bodeplot/frequency unit=rad}
1430 \fi
1431 \if@radarg
1432 \pgfkeys{/bodeplot/phase unit=rad}
1433 \else
1434 \pgfkeys{/bodeplot/phase unit=deg}
1435 \fi
1436 \gdef\bp@mag@plot{}
1437 \gdef\bp@ph@plot{}
1438 },
1439 plot/.code={%
1440 \ifx\bp@mag@plot\@empty
1441 \xdef\bp@mag@plot{\unexpanded\expandafter{#1}}
1442 \else
1443 \xdef\bp@mag@plot{\unexpanded\expandafter{\bp@mag@plot,#1}}
1444 \fi
1445 \ifx\bp@ph@plot\@empty
1446 \xdef\bp@ph@plot{\unexpanded\expandafter{#1}}
1447 \else
1448 \xdef\bp@ph@plot{\unexpanded\expandafter{\bp@ph@plot,#1}}
1449 \fi
1450 },
1451 plot/.value required,
1452 mag plot/.code={%
1453 \ifx\bp@mag@plot\@empty
1454 \xdef\bp@mag@plot{\unexpanded\expandafter{#1}}
1455 \else
1456 \xdef\bp@mag@plot{\unexpanded\expandafter{\bp@mag@plot},
1457 \unexpanded\expandafter{#1}}
1458 \fi
1459 },
1460 mag plot/.value required,
1461 ph plot/.code={%
1462 \ifx\bp@ph@plot\@empty
1463 \xdef\bp@ph@plot{\unexpanded\expandafter{#1}}
1464 \else
1465 \xdef\bp@ph@plot{\unexpanded\expandafter{\bp@ph@plot},
1466 \unexpanded\expandafter{#1}}
1467 \fi
1468 },
1469 ph plot/.value required,
1470 axes/.code={%
1471 \pgfkeysalso{/bodeplot/mag axes={#1}}
1472 \pgfkeysalso{/bodeplot/ph axes={#1}}%
1473 },
1474 axes/.value required,
1475 mag axes/.code={\pgfkeyssetvalue{/bodeplot/@axes/mag}{#1}},
1476 mag axes/.value required,
1477 ph axes/.code={\pgfkeyssetvalue{/bodeplot/@axes/ph}{#1}},
1478 ph axes/.value required,
1479 group/.code={\pgfkeyssetvalue{/bodeplot/@group}{#1}},
1480 group/.value required,
1481 approx/.code={\pgfkeyssetvalue{/bodeplot/@approx}{#1}},
1482 approx/.value required,
1483 commands/.code={%
1484 \pgfkeysalso{/bodeplot/mag commands={#1}}
1485 \pgfkeysalso{/bodeplot/ph commands={#1}}%
1486 },
1487 commands/.value required,
1488 mag commands/.code={\pgfkeyssetvalue{/bodeplot/@commands/mag}{#1}},
1489 mag commands/.value required,
1490 ph commands/.code={\pgfkeyssetvalue{/bodeplot/@commands/ph}{#1}},
1491 ph commands/.value required,
1492 tikz/.code={\pgfkeyssetvalue{/bodeplot/@tikz}{#1}},
1493 tikz/.value required,
1494 prefix/.code={\pgfkeyssetvalue{/bodeplot/@prefix}{#1}},
1495 prefix/.value required,
1496 domain/.code args={#1:#2}{%
1497 \gdef\bp@domain@start{#1}%
1498 \gdef\bp@domain@end{#2}%
1499 },
1500 domain/.value required,
1501 phase unit/.initial={deg},
1502 phase unit/.default={deg},
1503 phase unit/.is choice,
1504 phase unit/deg/.code={
1505 \renewcommand{\bp@ph@scale}{180/pi}
1506 \pgfplotsset{bp@ph@x@label/.style = {xlabel={Phase (deg)}}}
1507 \pgfplotsset{bp@ph@y@label/.style = {ylabel={Phase (deg)}}}
1508 },
1509 phase unit/rad/.code={
1510 \renewcommand{\bp@ph@scale}{1}
1511 \pgfplotsset{bp@ph@y@label/.style = {ylabel={Phase (rad)}}}
1512 \pgfplotsset{bp@ph@x@label/.style = {xlabel={Phase (rad)}}}
1513 },
1514 frequency unit/.initial={rad},
1515 frequency unit/.default={rad},
1516 frequency unit/.is choice,
1517 frequency unit/Hz/.code={
1518 \renewcommand{\bp@freq@scale}{2*pi}
1519 \pgfplotsset{bp@freq@label/.style = {xlabel = {Frequency (Hz)}}}
1520 \if@pgfarg
1521 \pgfplotsset{bp@freq@filter/.style = {x filter/.expression={x-log10(2*pi)}}}
1522 \fi
1523 },
1524 frequency unit/rad/.code={
1525 \renewcommand{\bp@freq@scale}{1}
1526 \pgfplotsset{bp@freq@label/.style = {xlabel = {Frequency (rad/s)}}}
1527 \if@pgfarg
1528 \pgfplotsset{bp@freq@filter/.style = {x filter/.expression={x}}}
1529 \fi
1530 },
1531 .unknown/.code={%
1532 \edef\bp@full{\pgfkeyscurrentkey}%
1533 \def\stripbodeprefix##1/bodeplot/##2\relax{##2}%
1534 \edef\bp@short{\expandafter\stripbodeprefix\bp@full\relax}%
1535 \edef\bp@checkfull{\bp@full}%
1536 \edef\bp@checkshort{\bp@short}%
1537 \ifx\bp@checkfull\bp@checkshort
1538 \def\removeslash##1/##2\relax{##2}%
1539 \edef\bp@short{\expandafter\removeslash\bp@full\relax}%
1540 \fi
1541 \ifx\pgfkeyscurrentvalue\pgfkeysnovalue
1542 \edef\bp@new{\bp@short}%
1543 \else
1544 \edef\bp@new{\bp@short=
1545 {\unexpanded\expandafter{\pgfkeyscurrentvalue}}}%
1546 \fi
1547 \ifx\bp@new\@empty\else
1548 \ifx\bp@mag@plot\@empty
1549 \xdef\bp@mag@plot{\unexpanded\expandafter{\bp@new}}
1550 \else
1551 \xdef\bp@mag@plot{\unexpanded\expandafter{\bp@mag@plot},%
1552 \unexpanded\expandafter{\bp@new}}
1553 \fi
1554 \fi
1555 \ifx\bp@new\@empty\else
1556 \ifx\bp@ph@plot\@empty
1557 \xdef\bp@ph@plot{\unexpanded\expandafter{\bp@new}}
1558 \else
1559 \xdef\bp@ph@plot{\unexpanded\expandafter{\bp@ph@plot},%
1560 \unexpanded\expandafter{\bp@new}}
1561 \fi
1562 \fi
1563 }
1564 }
1565 % \end{macrocode}
1566 % \end{macro}
1567 % \begin{macro}{/bodeplot/combinedenv}
1568 % |PGF| keys for combined Bode environment options.\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}
1569 % \begin{macrocode}
1570 \pgfkeys{
1571 /bodeplot/combinedenv/.is family,
1572 /bodeplot/combinedenv/.cd,
1573 reset/.code={%
1574 \pgfkeyssetvalue{/bodeplot/combinedenv/@group}{}
1575 \pgfkeyssetvalue{/bodeplot/combinedenv/@approx}{true}
1576 \pgfkeyssetvalue{/bodeplot/combinedenv/@commands/mag}{}
1577 \pgfkeyssetvalue{/bodeplot/combinedenv/@commands/ph}{}
1578 \pgfkeyssetvalue{/bodeplot/combinedenv/@tikz}{}
1579 \pgfkeyssetvalue{/bodeplot/combinedenv/@prefix}{}
1580 \gdef\bp@domain@start{0.01}
1581 \gdef\bp@domain@end{100}
1582 \if@hzarg
1583 \pgfkeys{/bodeplot/frequency unit=Hz}
1584 \else
1585 \pgfkeys{/bodeplot/frequency unit=rad}
1586 \fi
1587 \if@radarg
1588 \pgfkeys{/bodeplot/phase unit=rad}
1589 \else
1590 \pgfkeys{/bodeplot/phase unit=deg}
1591 \fi
1592 \gdef\bp@mag@axes{}
1593 \gdef\bp@ph@axes{}
1594 },
1595 axes/.code={%
1596 \ifx\bp@mag@axes\@empty
1597 \xdef\bp@mag@axes{\unexpanded\expandafter{#1}}
1598 \else
1599 \xdef\bp@mag@axes{\unexpanded\expandafter{\bp@mag@axes,#1}}
1600 \fi
1601 \ifx\bp@ph@axes\@empty
1602 \xdef\bp@ph@axes{\unexpanded\expandafter{#1}}
1603 \else
1604 \xdef\bp@ph@axes{\unexpanded\expandafter{\bp@ph@axes,#1}}
1605 \fi
1606 },
1607 axes/.value required,
1608 mag axes/.code={%
1609 \ifx\bp@mag@axes\@empty
1610 \xdef\bp@mag@axes{\unexpanded\expandafter{#1}}
1611 \else
1612 \xdef\bp@mag@axes{\unexpanded\expandafter{\bp@mag@axes,#1}}
1613 \fi
1614 },
1615 mag axes/.value required,
1616 ph axes/.code={%
1617 \ifx\bp@ph@axes\@empty
1618 \xdef\bp@ph@axes{\unexpanded\expandafter{#1}}
1619 \else
1620 \xdef\bp@ph@axes{\unexpanded\expandafter{\bp@ph@axes,#1}}
1621 \fi
1622 },
1623 ph axes/.value required,
1624 group/.code={\pgfkeyssetvalue{/bodeplot/combinedenv/@group}{#1}},
1625 group/.value required,
1626 approx/.code={\pgfkeyssetvalue{/bodeplot/combinedenv/@approx}{#1}},
1627 approx/.value required,
1628 commands/.code={%
1629 \pgfkeysalso{/bodeplot/combinedenv/mag commands={#1}}
1630 \pgfkeysalso{/bodeplot/combinedenv/ph commands={#1}}%
1631 },
1632 commands/.value required,
1633 mag commands/.code={\pgfkeyssetvalue{/bodeplot/combinedenv/@commands/mag}{#1}},
1634 mag commands/.value required,
1635 ph commands/.code={\pgfkeyssetvalue{/bodeplot/combinedenv/@commands/ph}{#1}},
1636 ph commands/.value required,
1637 tikz/.code={\pgfkeyssetvalue{/bodeplot/combinedenv/@tikz}{#1}},
1638 tikz/.value required,
1639 prefix/.code={\pgfkeyssetvalue{/bodeplot/combinedenv/@prefix}{#1}},
1640 prefix/.value required,
1641 domain/.code args={#1:#2}{%
1642 \gdef\bp@domain@start{#1}%
1643 \gdef\bp@domain@end{#2}%
1644 },
1645 domain/.value required,
1646 phase unit/.initial={deg},
1647 phase unit/.default={deg},
1648 phase unit/.is choice,
1649 phase unit/deg/.code={
1650 \renewcommand{\bp@ph@scale}{180/pi}
1651 \pgfplotsset{bp@ph@x@label/.style = {xlabel={Phase (deg)}}}
1652 \pgfplotsset{bp@ph@y@label/.style = {ylabel={Phase (deg)}}}
1653 },
1654 phase unit/rad/.code={
1655 \renewcommand{\bp@ph@scale}{1}
1656 \pgfplotsset{bp@ph@y@label/.style = {ylabel={Phase (rad)}}}
1657 \pgfplotsset{bp@ph@x@label/.style = {xlabel={Phase (rad)}}}
1658 },
1659 frequency unit/.initial={rad},
1660 frequency unit/.default={rad},
1661 frequency unit/.is choice,
1662 frequency unit/Hz/.code={
1663 \renewcommand{\bp@freq@scale}{2*pi}
1664 \pgfplotsset{bp@freq@label/.style = {xlabel = {Frequency (Hz)}}}
1665 \if@pgfarg
1666 \pgfplotsset{bp@freq@filter/.style = {x filter/.expression={x-log10(2*pi)}}}
1667 \fi
1668 },
1669 frequency unit/rad/.code={
1670 \renewcommand{\bp@freq@scale}{1}
1671 \pgfplotsset{bp@freq@label/.style = {xlabel = {Frequency (rad/s)}}}
1672 \if@pgfarg
1673 \pgfplotsset{bp@freq@filter/.style = {x filter/.expression={x}}}
1674 \fi
1675 },
1676 .unknown/.code={%
1677 \edef\bp@full{\pgfkeyscurrentkey}%
1678 \def\stripbodeprefix##1/bodeplot/combinedenv/##2\relax{##2}%
1679 \edef\bp@short{\expandafter\stripbodeprefix\bp@full\relax}%
1680 \edef\bp@checkfull{\bp@full}%
1681 \edef\bp@checkshort{\bp@short}%
1682 \ifx\bp@checkfull\bp@checkshort
1683 \def\removeslash##1/##2\relax{##2}%
1684 \edef\bp@short{\expandafter\removeslash\bp@full\relax}%
1685 \fi
1686 \ifx\pgfkeyscurrentvalue\pgfkeysnovalue
1687 \edef\bp@new{\bp@short}%
1688 \else
1689 \edef\bp@new{\bp@short=
1690 {\unexpanded\expandafter{\pgfkeyscurrentvalue}}}%
1691 \fi
1692 \ifx\bp@new\@empty\else
1693 \ifx\bp@mag@axes\@empty
1694 \xdef\bp@mag@axes{\unexpanded\expandafter{\bp@new}}
1695 \else
1696 \xdef\bp@mag@axes{\unexpanded\expandafter{\bp@mag@axes},%
1697 \unexpanded\expandafter{\bp@new}}
1698 \fi
1699 \fi
1700 \ifx\bp@new\@empty\else
1701 \ifx\bp@ph@axes\@empty
1702 \xdef\bp@ph@axes{\unexpanded\expandafter{\bp@new}}
1703 \else
1704 \xdef\bp@ph@axes{\unexpanded\expandafter{\bp@ph@axes},%
1705 \unexpanded\expandafter{\bp@new}}
1706 \fi
1707 \fi
1708 }
1709 }
1710 % \end{macrocode}
1711 % \end{macro}
1712 % \begin{macro}{/bodeplot/zpk}
1713 % |PGF| keys for supplying zero-pole-gain-delay (ZPK) representations.\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}
1714 % \begin{macrocode}
1715 \pgfkeys{
1716 /bodeplot/zpk/.is family,
1717 /bodeplot/zpk/.cd,
1718 reset/.code={%
1719 \pgfkeyssetvalue{/bodeplot/zpk/@zeros}{}
1720 \pgfkeyssetvalue{/bodeplot/zpk/@poles}{}
1721 \pgfkeyssetvalue{/bodeplot/zpk/@gain}{}
1722 \pgfkeyssetvalue{/bodeplot/zpk/@delay}{}
1723 },
1724 zeros/.code={\pgfkeyssetvalue{/bodeplot/zpk/@zeros}{#1}},
1725 zeros/.value required,
1726 poles/.code={\pgfkeyssetvalue{/bodeplot/zpk/@poles}{#1}},
1727 poles/.value required,
1728 gain/.code={\pgfkeyssetvalue{/bodeplot/zpk/@gain}{#1}},
1729 gain/.value required,
1730 delay/.code={\pgfkeyssetvalue{/bodeplot/zpk/@delay}{#1}},
1731 delay/.value required,
1732 }
1733 % \end{macrocode}
1734 % \end{macro}
1735 % \begin{macro}{/bodeplot/tf}
1736 % |PGF| keys for supplying transfer function (TF) representations.\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}
1737 % \begin{macrocode}
1738 \pgfkeys{
1739 /bodeplot/tf/.is family,
1740 /bodeplot/tf/.cd,
1741 reset/.code={%
1742 \pgfkeyssetvalue{/bodeplot/tf/@numerator}{}
1743 \pgfkeyssetvalue{/bodeplot/tf/@denominator}{}
1744 \pgfkeyssetvalue{/bodeplot/tf/@delay}{}
1745 },
1746 numerator/.code={\pgfkeyssetvalue{/bodeplot/tf/@numerator}{#1}},
1747 numerator/.value required,
1748 denominator/.code={\pgfkeyssetvalue{/bodeplot/tf/@denominator}{#1}},
1749 denominator/.value required,
1750 delay/.code={\pgfkeyssetvalue{/bodeplot/tf/@delay}{#1}},
1751 delay/.value required
1752 }
1753 % \end{macrocode}
1754 % \end{macro}
1755 % \begin{macro}{/bodeplot/add}
1756 % |PGF| keys for adding asymptotic and linear plots.\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}
1757 % \begin{macrocode}
1758 \pgfkeys{
1759 /bodeplot/add/.is family,
1760 /bodeplot/add/.cd,
1761 reset/.code={%
1762 \gdef\bp@add@O{}%
1763 },
1764 true/.default={},
1765 true/.code={%
1766 \pgfutil@ifempty{#1}{
1767 \ifx\bp@add@O\@empty
1768 \g@addto@macro\bp@add@O{true}%
1769 \else
1770 \g@addto@macro\bp@add@O{,true}%
1771 \fi
1772 }{%
1773 \ifx\bp@add@O\@empty
1774 \g@addto@macro\bp@add@O{true/{#1}}%
1775 \else
1776 \g@addto@macro\bp@add@O{,true/{#1}}%
1777 \fi
1778 }
1779 },
1780 linear/.default={},
1781 linear/.code={%
1782 \pgfutil@ifempty{#1}{
1783 \ifx\bp@add@O\@empty
1784 \g@addto@macro\bp@add@O{linear}%
1785 \else
1786 \g@addto@macro\bp@add@O{,linear}%
1787 \fi
1788 }{%
1789 \ifx\bp@add@O\@empty
1790 \g@addto@macro\bp@add@O{linear/{#1}}%
1791 \else
1792 \g@addto@macro\bp@add@O{,linear/{#1}}%
1793 \fi
1794 }
1795 },
1796 asymptotic/.default={},
1797 asymptotic/.code={%
1798 \pgfutil@ifempty{#1}{
1799 \ifx\bp@add@O\@empty
1800 \g@addto@macro\bp@add@O{asymptotic}%
1801 \else
1802 \g@addto@macro\bp@add@O{,asymptotic}%
1803 \fi
1804 }{%
1805 \ifx\bp@add@O\@empty
1806 \g@addto@macro\bp@add@O{asymptotic/{#1}}%
1807 \else
1808 \g@addto@macro\bp@add@O{,asymptotic/{#1}}%
1809 \fi
1810 }%
1811 },
1812 .unknown/.code={%
1813 \edef\bp@full{\pgfkeyscurrentkey}%
1814 \def\stripbodeprefix##1/bodeplot/add/##2\relax{##2}%
1815 \edef\bp@short{\expandafter\stripbodeprefix\bp@full\relax}%
1816 \edef\bp@checkfull{\bp@full}%
1817 \edef\bp@checkshort{\bp@short}%
1818 \ifx\bp@checkfull\bp@checkshort
1819 \def\removeslash##1/##2\relax{##2}%
1820 \edef\bp@short{\expandafter\removeslash\bp@full\relax}%
1821 \fi
1822 \ifx\pgfkeyscurrentvalue\pgfkeysnovalue
1823 \edef\bp@new{\bp@short}%
1824 \else
1825 \edef\bp@new{\bp@short=
1826 {\unexpanded\expandafter{\pgfkeyscurrentvalue}}}%
1827 \fi
1828 \ifx\bp@new\@empty\else
1829 \ifx\bp@add@O\@empty
1830 \xdef\bp@add@O{\unexpanded\expandafter{\bp@new}}
1831 \else
1832 \xdef\bp@add@O{\unexpanded\expandafter{\bp@add@O},%
1833 \unexpanded\expandafter{\bp@new}}
1834 \fi
1835 \fi
1836 }
1837 }
1838 % \end{macrocode}
1839 % \end{macro}
1840 % \begin{macro}{/bodeplot/nyquist}
1841 % |PGF| keys for Nyquist plot options.\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}
1842 % \begin{macrocode}
1843 \pgfkeys{
1844 /bodeplot/nyquist/.is family,
1845 /bodeplot/nyquist/.cd,
1846 reset/.code={
1847 \pgfkeyssetvalue{/bodeplot/nyquist/@axes}{}
1848 \pgfkeyssetvalue{/bodeplot/nyquist/@plot}{}
1849 \pgfkeyssetvalue{/bodeplot/nyquist/@commands}{}
1850 \pgfkeyssetvalue{/bodeplot/nyquist/@tikz}{}
1851 \pgfkeyssetvalue{/bodeplot/nyquist/@prefix}{}
1852 \gdef\bp@domain@start{-30}
1853 \gdef\bp@domain@end{30}
1854 \gdef\bp@plot{}
1855 },
1856 axes/.code={\pgfkeyssetvalue{/bodeplot/nyquist/@axes}{#1}},
1857 axes/.value required,
1858 plot/.code={%
1859 \xdef\bp@plot{\unexpanded\expandafter{#1}}
1860 },
1861 plot/.value required,
1862 commands/.code={\pgfkeyssetvalue{/bodeplot/nyquist/@commands}{#1}},
1863 commands/.value required,
1864 tikz/.code={\pgfkeyssetvalue{/bodeplot/nyquist/@tikz}{#1}},
1865 tikz/.value required,
1866 prefix/.code={\pgfkeyssetvalue{/bodeplot/nyquist/@prefix}{#1}},
1867 prefix/.value required,
1868 domain/.code args={#1:#2}{\gdef\bp@domain@start{#1}\gdef\bp@domain@end{#2}},
1869 domain/.value required,
1870 .unknown/.code={%
1871 \edef\bp@full{\pgfkeyscurrentkey}%
1872 \def\stripbodeprefix##1/bodeplot/nyquist/##2\relax{##2}%
1873 \edef\bp@short{\expandafter\stripbodeprefix\bp@full\relax}%
1874 \edef\bp@checkfull{\bp@full}%
1875 \edef\bp@checkshort{\bp@short}%
1876 \ifx\bp@checkfull\bp@checkshort
1877 \def\removeslash##1/##2\relax{##2}%
1878 \edef\bp@short{\expandafter\removeslash\bp@full\relax}%
1879 \fi
1880 \ifx\pgfkeyscurrentvalue\pgfkeysnovalue
1881 \edef\bp@new{\bp@short}%
1882 \else
1883 \edef\bp@new{\bp@short=
1884 {\unexpanded\expandafter{\pgfkeyscurrentvalue}}}%
1885 \fi
1886 \ifx\bp@new\@empty\else
1887 \ifx\bp@plot\@empty
1888 \xdef\bp@plot{\unexpanded\expandafter{\bp@new}}
1889 \else
1890 \xdef\bp@plot{\unexpanded\expandafter{\bp@plot},%
1891 \unexpanded\expandafter{\bp@new}}
1892 \fi
1893 \fi
1894 }
1895 }
1896 % \end{macrocode}
1897 % \end{macro}
1898 % \begin{macro}{/bodeplot/nichols}
1899 % |PGF| keys for Nichols plot options.\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}
1900 % \begin{macrocode}
1901 \pgfkeys{
1902 /bodeplot/nichols/.is family,
1903 /bodeplot/nichols/.cd,
1904 reset/.code={
1905 \pgfkeyssetvalue{/bodeplot/nichols/@axes}{}
1906 \pgfkeyssetvalue{/bodeplot/nichols/@plot}{}
1907 \pgfkeyssetvalue{/bodeplot/nichols/@commands}{}
1908 \pgfkeyssetvalue{/bodeplot/nichols/@tikz}{}
1909 \pgfkeyssetvalue{/bodeplot/nichols/@prefix}{}
1910 \gdef\bp@domain@start{0.01}
1911 \gdef\bp@domain@end{100}
1912 \gdef\bp@plot{}
1913 },
1914 axes/.code={\pgfkeyssetvalue{/bodeplot/nichols/@axes}{#1}},
1915 axes/.value required,
1916 plot/.code={%
1917 \xdef\bp@plot{\unexpanded\expandafter{#1}}
1918 },
1919 plot/.value required,
1920 commands/.code={\pgfkeyssetvalue{/bodeplot/nichols/@commands}{#1}},
1921 commands/.value required,
1922 tikz/.code={\pgfkeyssetvalue{/bodeplot/nichols/@tikz}{#1}},
1923 tikz/.value required,
1924 prefix/.code={\pgfkeyssetvalue{/bodeplot/nichols/@prefix}{#1}},
1925 prefix/.value required,
1926 domain/.code args={#1:#2}{\gdef\bp@domain@start{#1}\gdef\bp@domain@end{#2}},
1927 domain/.value required,
1928 .unknown/.code={%
1929 \edef\bp@full{\pgfkeyscurrentkey}%
1930 \def\stripbodeprefix##1/bodeplot/nichols/##2\relax{##2}%
1931 \edef\bp@short{\expandafter\stripbodeprefix\bp@full\relax}%
1932 \edef\bp@checkfull{\bp@full}%
1933 \edef\bp@checkshort{\bp@short}%
1934 \ifx\bp@checkfull\bp@checkshort
1935 \def\removeslash##1/##2\relax{##2}%
1936 \edef\bp@short{\expandafter\removeslash\bp@full\relax}%
1937 \fi
1938 \ifx\pgfkeyscurrentvalue\pgfkeysnovalue
1939 \edef\bp@new{\bp@short}%
1940 \else
1941 \edef\bp@new{\bp@short=
1942 {\unexpanded\expandafter{\pgfkeyscurrentvalue}}}%
1943 \fi
1944 \ifx\bp@new\@empty\else
1945 \ifx\bp@plot\@empty
1946 \xdef\bp@plot{\unexpanded\expandafter{\bp@new}}
1947 \else
1948 \xdef\bp@plot{\unexpanded\expandafter{\bp@plot},%
1949 \unexpanded\expandafter{\bp@new}}
1950 \fi
1951 \fi
1952 }
1953 }
1954 % \end{macrocode}
1955 % \end{macro}
1956 % \begin{macro}{/bodeplot/pzmap}
1957 % |PGF| keys for pole-zero map options.\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}
1958 % \begin{macrocode}
1959 \pgfkeys{
1960 /bodeplot/pzmap/.is family,
1961 /bodeplot/pzmap/.cd,
1962 reset/.code={
1963 \pgfkeyssetvalue{/bodeplot/pzmap/@axes}{}
1964 \pgfkeyssetvalue{/bodeplot/pzmap/@plot}{}
1965 \pgfkeyssetvalue{/bodeplot/pzmap/@commands}{}
1966 \pgfkeyssetvalue{/bodeplot/pzmap/@tikz}{}
1967 \pgfkeyssetvalue{/bodeplot/pzmap/@prefix}{}
1968 \pgfkeyssetvalue{/bodeplot/pzmap/@scale}{linear}
1969 },
1970 axes/.code={\pgfkeyssetvalue{/bodeplot/pzmap/@axes}{#1}},
1971 axes/.value required,
1972 plot/.code={\pgfkeyssetvalue{/bodeplot/pzmap/@plot}{#1}},
1973 plot/.value required,
1974 commands/.code={\pgfkeyssetvalue{/bodeplot/pzmap/@commands}{#1}},
1975 commands/.value required,
1976 tikz/.code={\pgfkeyssetvalue{/bodeplot/pzmap/@tikz}{#1}},
1977 tikz/.value required,
1978 prefix/.code={\pgfkeyssetvalue{/bodeplot/pzmap/@prefix}{#1}},
1979 prefix/.value required,
1980 scale/.initial=linear,
1981 scale/.default=linear,
1982 scale/.is choice,
1983 scale/linear/.code={\pgfkeyssetvalue{/bodeplot/pzmap/@scale}{linear}},
1984 scale/log/.code={\pgfkeyssetvalue{/bodeplot/pzmap/@scale}{log}},
1985 }
1986 % \end{macrocode}
1987 % \end{macro}
1988 % \subsection{Parametric function generators for poles, zeros, gains, and delays.}
1989 % All calculations are carried out assuming that frequeny inputs are in |rad/s|. Magnitude outputs are in |dB| and phase outputs are in degrees or radians, depending on the value of |\bp@ph@scale|.
1990 % \begin{macro}{\MagK}
1991 % \begin{macro}{\MagKAsymp}
1992 % \begin{macro}{\MagKLin}
1993 % \begin{macro}{\PhK}
1994 % \begin{macro}{\PhKAsymp}
1995 % \begin{macro}{\PhKLin}
1996 % True, linear, and asymptotic magnitude and phase parametric functions for a pure gain $G(s)=k+0\mathrm{i}$. The macros take two arguments corresponding to real and imaginary part of the gain to facilitate code reuse between delays, gains, poles, and zeros, but only real gains are supported. The second argument, if supplied, is ignored.
1997 % \begin{macrocode}
1998 \newcommand*{\MagK}[2]{(20*log10(abs(#1)))}
1999 \newcommand*{\MagKAsymp}{\MagK}
2000 \newcommand*{\MagKLin}{\MagK}
2001 \newcommand*{\PhK}[2]{((#1<0?-pi:0)*\bp@ph@scale)}
2002 \newcommand*{\PhKAsymp}{\PhK}
2003 \newcommand*{\PhKLin}{\PhK}
2004 % \end{macrocode}
2005 % \end{macro}
2006 % \end{macro}
2007 % \end{macro}
2008 % \end{macro}
2009 % \end{macro}
2010 % \end{macro}
2011 % \begin{macro}{\PhKAsymp}
2012 % \begin{macro}{\PhKLin}
2013 % True magnitude and phase parametric functions for a pure delay $G(s)=e^{-Ts}$. The macros take two arguments corresponding to real and imaginary part of the gain to facilitate code reuse between delays, gains, poles, and zeros, but only real gains are supported. The second argument, if supplied, is ignored.
2014 % \begin{macrocode}
2015 \newcommand*{\MagDel}[2]{0}
2016 \newcommand*{\PhDel}[2]{(-#1*t*\bp@ph@scale)}
2017 % \end{macrocode}
2018 % \end{macro}
2019 % \end{macro}
2020 % \begin{macro}{\MagPole}
2021 % \begin{macro}{\MagPoleAsymp}
2022 % \begin{macro}{\MagPoleLin}
2023 % \begin{macro}{\PhPole}
2024 % \begin{macro}{\PhPoleAsymp}
2025 % \begin{macro}{\PhPoleLin}
2026 % These macros are the building blocks for most of the plotting functions provided by this package. We start with Parametric function for the true magnitude of a complex pole.
2027 % \begin{macrocode}
2028 \newcommand*{\MagPole}[2]
2029 {(-20*log10(sqrt(\n@pow{#1}{2} + \n@pow{t - (#2)}{2})))}
2030 % \end{macrocode}
2031 % Parametric function for linear approximation of the magnitude of a complex pole.
2032 % \begin{macrocode}
2033 \newcommand*{\MagPoleLin}[2]{(t < sqrt(\n@pow{#1}{2} + \n@pow{#2}{2}) ?
2034 -20*log10(sqrt(\n@pow{#1}{2} + \n@pow{#2}{2})) :
2035 -20*log10(t)
2036 )}
2037 % \end{macrocode}
2038 % Parametric function for asymptotic approximation of the magnitude of a complex pole, same as linear approximation.
2039 % \begin{macrocode}
2040 \newcommand*{\MagPoleAsymp}{\MagPoleLin}
2041 % \end{macrocode}
2042 % Parametric function for the true phase of a complex pole.
2043 % \begin{macrocode}
2044 \newcommand*{\PhPole}[2]{((#1 > 0 ? (#2 > 0 ?
2045 (\n@mod@p{-atan2((t - (#2)),-(#1))}{2*pi}) :
2046 (-atan2((t - (#2)),-(#1)))) :
2047 (-atan2((t - (#2)),-(#1))))*\bp@ph@scale)}
2048 % \end{macrocode}
2049 % Parametric function for linear approximation of the phase of a complex pole.
2050 % \begin{macrocode}
2051 \newcommand*{\PhPoleLin}[2]{
2052 ((abs(#1)+abs(#2) == 0 ? -pi/2 :
2053 (t < (sqrt(\n@pow{#1}{2} + \n@pow{#2}{2}) /
2054 (\n@pow{10}{sqrt(\n@pow{#1}{2}/(\n@pow{#1}{2} + \n@pow{#2}{2}))})) ?
2055 (-atan2(-(#2),-(#1))) :
2056 (t >= (sqrt(\n@pow{#1}{2} + \n@pow{#2}{2}) *
2057 (\n@pow{10}{sqrt(\n@pow{#1}{2}/(\n@pow{#1}{2} + \n@pow{#2}{2}))})) ?
2058 (#2>0?(#1>0?3*pi/2:-pi/2):-pi/2) :
2059 (-atan2(-(#2),-(#1)) + (log10(t/(sqrt(\n@pow{#1}{2} + \n@pow{#2}{2}) /
2060 (\n@pow{10}{sqrt(\n@pow{#1}{2}/(\n@pow{#1}{2} +
2061 \n@pow{#2}{2}))}))))*((#2>0?(#1>0?3*pi/2:-pi/2):-pi/2) + atan2(-(#2),-(#1)))/
2062 (log10(\n@pow{10}{sqrt((4*\n@pow{#1}{2})/
2063 (\n@pow{#1}{2} + \n@pow{#2}{2}))}))))))*\bp@ph@scale)}
2064 % \end{macrocode}
2065 % Parametric function for asymptotic approximation of the phase of a complex pole.
2066 % \begin{macrocode}
2067 \newcommand*{\PhPoleAsymp}[2]{((t < (sqrt(\n@pow{#1}{2} + \n@pow{#2}{2})) ?
2068 (-atan2(-(#2),-(#1))) :
2069 (#2>0?(#1>0?3*pi/2:-pi/2):-pi/2))*\bp@ph@scale)}
2070 % \end{macrocode}
2071 % \end{macro}
2072 % \end{macro}
2073 % \end{macro}
2074 % \end{macro}
2075 % \end{macro}
2076 % \end{macro}
2077 % \begin{macro}{\MagZero}
2078 % \begin{macro}{\MagZeroAsymp}
2079 % \begin{macro}{\MagZeroLin}
2080 % \begin{macro}{\PhZero}
2081 % \begin{macro}{\PhZeroAsymp}
2082 % \begin{macro}{\PhZeroLin}
2083 % Plots of zeros are defined to be negative of plots of poles. The |0-| is necessary due to a bug in |gnuplot| (fixed in version 5.4, patchlevel 3).
2084 % \begin{macrocode}
2085 \newcommand*{\MagZero}{0-\MagPole}
2086 \newcommand*{\MagZeroLin}{0-\MagPoleLin}
2087 \newcommand*{\MagZeroAsymp}{0-\MagPoleAsymp}
2088 \newcommand*{\PhZero}{0-\PhPole}
2089 \newcommand*{\PhZeroLin}{0-\PhPoleLin}
2090 \newcommand*{\PhZeroAsymp}{0-\PhPoleAsymp}
2091 % \end{macrocode}
2092 % \end{macro}
2093 % \end{macro}
2094 % \end{macro}
2095 % \end{macro}
2096 % \end{macro}
2097 % \end{macro}
2098 % \subsection{Second order systems.}
2099 % Although second order systems can be dealt with using the macros defined so far, the following dedicated macros for second order systems involve less computation.
2100 % \begin{macro}{\MagCSPoles}
2101 % \begin{macro}{\MagCSPolesAsymp}
2102 % \begin{macro}{\MagCSPolesLin}
2103 % \begin{macro}{\PhCSPoles}
2104 % \begin{macro}{\PhCSPolesAsymp}
2105 % \begin{macro}{\PhCSPolesLin}
2106 % \begin{macro}{\MagCSZeros}
2107 % \begin{macro}{\MagCSZerosAsymp}
2108 % \begin{macro}{\MagCSZerosLin}
2109 % \begin{macro}{\PhCSZeros}
2110 % \begin{macro}{\PhCSZerosAsymp}
2111 % \begin{macro}{\PhCSZerosLin}
2112 % Consider the canonical second order transfer function $G(s) = \frac{1}{s^2 + 2 \zeta w_n s + w_n^2}$. We start with true, linear, and asymptotic magnitude plots for this transfer function.
2113 % \begin{macrocode}
2114 \newcommand*{\MagCSPoles}[2]{(-20*log10(sqrt(\n@pow{\n@pow{#2}{2}
2115 - \n@pow{t}{2}}{2} + \n@pow{2*#1*#2*t}{2})))}
2116 \newcommand*{\MagCSPolesLin}[2]{(t < #2 ? -40*log10(#2) : - 40*log10(t))}
2117 \newcommand*{\MagCSPolesAsymp}{\MagCSPolesLin}
2118 % \end{macrocode}
2119 % True, linear, and asymptotic phase plots for the canonical second order transfer function.
2120 % \begin{macrocode}
2121 \newcommand*{\PhCSPoles}[2]{((-atan2((2*(#1)*(#2)*t),(\n@pow{#2}{2}
2122 - \n@pow{t}{2})))*\bp@ph@scale)}
2123 \newcommand*{\PhCSPolesLin}[2]{((t < (#2 / (\n@pow{10}{abs(#1)})) ?
2124 0 :
2125 (t >= (#2 * (\n@pow{10}{abs(#1)})) ?
2126 (#1>0 ? -pi : pi) :
2127 (#1>0 ? (-pi*(log10(t*(\n@pow{10}{#1})/#2))/(2*#1)) :
2128 (pi*(log10(t*(\n@pow{10}{abs(#1)})/#2))/(2*abs(#1))))))*\bp@ph@scale)}
2129 \newcommand*{\PhCSPolesAsymp}[2]{((#1>0?(t<#2?0:-pi):(t<#2?0:pi))*\bp@ph@scale)}
2130 % \end{macrocode}
2131 % Plots of the inverse function $G(s)=s^2+2\zeta\omega_n s+\omega_n^2$ are defined to be negative of plots of poles. The |0-| is necessary due to a bug in |gnuplot| (fixed in version 5.4, patchlevel 3).
2132 % \begin{macrocode}
2133 \newcommand*{\MagCSZeros}{0-\MagCSPoles}
2134 \newcommand*{\MagCSZerosLin}{0-\MagCSPolesLin}
2135 \newcommand*{\MagCSZerosAsymp}{0-\MagCSPolesAsymp}
2136 \newcommand*{\PhCSZeros}{0-\PhCSPoles}
2137 \newcommand*{\PhCSZerosLin}{0-\PhCSPolesLin}
2138 \newcommand*{\PhCSZerosAsymp}{0-\PhCSPolesAsymp}
2139 % \end{macrocode}
2140 % \end{macro}
2141 % \end{macro}
2142 % \end{macro}
2143 % \end{macro}
2144 % \end{macro}
2145 % \end{macro}
2146 % \end{macro}
2147 % \end{macro}
2148 % \end{macro}
2149 % \end{macro}
2150 % \end{macro}
2151 % \end{macro}
2152 % \begin{macro}{\MagCSPolesPeak}
2153 % \begin{macro}{\MagCSZerosPeak}
2154 % These macros are used to add a resonant peak to linear and asymptotic plots of canonical second order poles and zeros. Since the plots are parametric, a separate |\draw| command is needed to add a vertical arrow.
2155 % \begin{macrocode}
2156 \newcommand*{\MagCSPolesPeak}[3][]{
2157 \draw[#1,->] (axis cs:{#3},{-40*log10(#3)}) --
2158 (axis cs:{#3},{-40*log10(#3)-20*log10(2*abs(#2))})
2159 }
2160 \newcommand*{\MagCSZerosPeak}[3][]{
2161 \draw[#1,->] (axis cs:{#3},{40*log10(#3)}) --
2162 (axis cs:{#3},{40*log10(#3)+20*log10(2*abs(#2))})
2163 }
2164 % \end{macrocode}
2165 % \end{macro}
2166 % \end{macro}
2167 % \begin{macro}{\MagSOPoles}
2168 % \begin{macro}{\MagSOPolesAsymp}
2169 % \begin{macro}{\MagSOPolesLin}
2170 % \begin{macro}{\PhSOPoles}
2171 % \begin{macro}{\PhSOPolesAsymp}
2172 % \begin{macro}{\PhSOPolesLin}
2173 % \begin{macro}{\MagSOZeros}
2174 % \begin{macro}{\MagSOZerosAsymp}
2175 % \begin{macro}{\MagSOZerosLin}
2176 % \begin{macro}{\PhSOZeros}
2177 % \begin{macro}{\PhSOZerosAsymp}
2178 % \begin{macro}{\PhSOZerosLin}
2179 % Consider a general second order transfer function $G(s) = \frac{1}{s^2 + a s + b}$. We start with true, linear, and asymptotic magnitude plots for this transfer function.
2180 % \changes{v1.1.2}{2022/10/29}{Fix scaling bug introduced in v1.1.1}
2181 % \begin{macrocode}
2182 \newcommand*{\MagSOPoles}[2]{
2183 (-20*log10(sqrt(\n@pow{#2 - \n@pow{t}{2}}{2} + \n@pow{#1*t}{2})))}
2184 \newcommand*{\MagSOPolesLin}[2]{
2185 (t < sqrt(abs(#2)) ? -20*log10(abs(#2)) : - 40*log10(t))}
2186 \newcommand*{\MagSOPolesAsymp}{\MagSOPolesLin}
2187 % \end{macrocode}
2188 % True, linear, and asymptotic phase plots for the general second order transfer function.
2189 % \begin{macrocode}
2190 \newcommand*{\PhSOPoles}[2]{((-atan2((#1)*t,((#2) - \n@pow{t}{2})))*\bp@ph@scale)}
2191 \newcommand*{\PhSOPolesLin}[2]{((#2>0 ?
2192 \PhCSPolesLin{(#1/(2*sqrt(#2)))}{(sqrt(#2))} :
2193 (#1>0 ? -pi : pi)))}
2194 \newcommand*{\PhSOPolesAsymp}[2]{((#2>0 ?
2195 \PhCSPolesAsymp{(#1/(2*sqrt(#2)))}{(sqrt(#2))} :
2196 (#1>0 ? -pi : pi)))}
2197 % \end{macrocode}
2198 % Plots of the inverse function $G(s)=s^2+as+b$ are defined to be negative of plots of poles. The |0-| is necessary due to a bug in |gnuplot| (fixed in version 5.4, patchlevel 3).
2199 % \begin{macrocode}
2200 \newcommand*{\MagSOZeros}{0-\MagSOPoles}
2201 \newcommand*{\MagSOZerosLin}{0-\MagSOPolesLin}
2202 \newcommand*{\MagSOZerosAsymp}{0-\MagSOPolesAsymp}
2203 \newcommand*{\PhSOZeros}{0-\PhSOPoles}
2204 \newcommand*{\PhSOZerosLin}{0-\PhSOPolesLin}
2205 \newcommand*{\PhSOZerosAsymp}{0-\PhSOPolesAsymp}
2206 % \end{macrocode}
2207 % \end{macro}
2208 % \end{macro}
2209 % \end{macro}
2210 % \end{macro}
2211 % \end{macro}
2212 % \end{macro}
2213 % \end{macro}
2214 % \end{macro}
2215 % \end{macro}
2216 % \end{macro}
2217 % \end{macro}
2218 % \end{macro}
2219 % \begin{macro}{\MagSOPolesPeak}
2220 % \begin{macro}{\MagSOZerosPeak}
2221 % These macros are used to add a resonant peak to linear and asymptotic plots of general second order poles and zeros. Since the plots are parametric, a separate |\draw| command is needed to add a vertical arrow.
2222 % \begin{macrocode}
2223 \newcommand*{\MagSOPolesPeak}[3][]{
2224 \draw[#1,->] (axis cs:{sqrt(abs(#3))},{-20*log10(abs(#3))}) --
2225 (axis cs:{sqrt(abs(#3))},{-20*log10(abs(#3)) -
2226 20*log10(abs(#2/sqrt(abs(#3))))});
2227 }
2228 \newcommand*{\MagSOZerosPeak}[3][]{
2229 \draw[#1,->] (axis cs:{sqrt(abs(#3))},{20*log10(abs(#3))}) --
2230 (axis cs:{sqrt(abs(#3))},{20*log10(abs(#3)) +
2231 20*log10(abs(#2/sqrt(abs(#3))))});
2232 }
2233 % \end{macrocode}
2234 % \end{macro}
2235 % \end{macro}
2236 % \subsection{Commands for Bode plots}
2237 % \subsubsection{User macros}
2238 % \begin{macro}{\BodeZPK}
2239 % This macro takes lists of complex poles and zeros of the form |{re,im}|, and values of gain and delay as inputs and constructs parametric functions for the Bode magnitude and phase plots. This is done by adding together the parametric functions generated by the macros for individual zeros, poles, gain, and delay, described above. The parametric functions are then plotted in a |tikzpicture| environment using the |\addplot| macro. Unless the package is loaded with the option |pgf|, the parametric functions are evaluated using |gnuplot|. \changes{v1.0.1}{2021/10/29}{Pass arbitrary TikZ commands as options.}\changes{v3.0}{2025/10/21}{Updated to use a pgfkeys-based interface}\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}
2240 % \begin{macrocode}
2241 \NewDocumentCommand{\BodeZPK}{ O{} m G{} G{} }{%
2242 % \end{macrocode}
2243 % The macro now accepts an optional argument followed by a mandatory ZPK specification and two optional frequency arguments. If the frequency arguments are not provided, the pgfkeys interface introduced in v3.0 is used. Otherwise, the legacy interface is used for backward compatibility.
2244 % \begin{macrocode}
2245 \pgfutil@ifempty{#3}{%
2246 \pgfkeys{/bodeplot/.cd, reset}
2247 \pgfkeys{/bodeplot/.cd, #1}
2248 \pgfkeysgetvalue{/bodeplot/@axes/mag}{\bp@mag@axes}
2249 \pgfkeysgetvalue{/bodeplot/@axes/ph}{\bp@ph@axes}
2250 \pgfkeysgetvalue{/bodeplot/@group}{\bp@group}
2251 \pgfkeysgetvalue{/bodeplot/@approx}{\bp@approx}
2252 \pgfkeysgetvalue{/bodeplot/@commands/mag}{\bp@mag@commands}
2253 \pgfkeysgetvalue{/bodeplot/@commands/ph}{\bp@ph@commands}
2254 \pgfkeysgetvalue{/bodeplot/@tikz}{\bp@tikz}
2255 \pgfkeysgetvalue{/bodeplot/@prefix}{\bp@user@prefix}
2256 \bp@zpk@new@to@legacy{#2}
2257 }{%
2258 \if@radarg
2259 \pgfkeys{/bodeplot/phase unit=rad}
2260 \else
2261 \pgfkeys{/bodeplot/phase unit=deg}
2262 \fi
2263 \if@hzarg
2264 \pgfkeys{/bodeplot/frequency unit=Hz}
2265 \else
2266 \pgfkeys{/bodeplot/frequency unit=rad}
2267 \fi
2268 \bp@parse@opt{#1}
2269 \edef\bp@legacy{#2}
2270 \edef\bp@domain@start{#3}
2271 \edef\bp@domain@end{#4}
2272 }%
2273
2274 \edef\bp@tmp{\noexpand\begin{tikzpicture}
2275 [\unexpanded\expandafter{\bp@tikz}]}
2276 \bp@tmp
2277 \gdef\bp@mag{}
2278 \gdef\bp@ph{}
2279 \bp@ZPK@plot{\bp@mag}{\bp@ph}{\bp@approx}{\bp@legacy}
2280 \edef\bp@tmp{\noexpand\begin{groupplot}[
2281 bp@style,
2282 xmin=\bp@domain@start,
2283 xmax=\bp@domain@end,
2284 domain=\bp@domain@start*\bp@freq@scale:\bp@domain@end*\bp@freq@scale,
2285 height=2.5cm,
2286 xmode=log,
2287 group style = {group size = 1 by 2,vertical sep=0.25cm},
2288 \unexpanded\expandafter{\bp@group}
2289 ]}
2290 \bp@tmp
2291 \edef\bp@tmp@mag{\noexpand\nextgroupplot
2292 [ylabel={Gain (dB)}, xmajorticks=false, \bp@mag@axes]
2293 \noexpand\addplot [bp@freq@filter, variable=t, thick,
2294 \unexpanded\expandafter{\bp@mag@plot}]}
2295 \edef\bp@tmp@ph{\noexpand\nextgroupplot
2296 [bp@ph@y@label, bp@freq@label, \bp@ph@axes]
2297 \noexpand\addplot [bp@freq@filter, variable=t, thick, trig format plots=rad,
2298 \unexpanded\expandafter{\bp@ph@plot}]}
2299 \if@pgfarg
2300 \bp@tmp@mag {\bp@mag};
2301 \bp@mag@commands
2302 \bp@tmp@ph {\bp@ph};
2303 \bp@ph@commands
2304 \else
2305 \stepcounter{bp@gnuplot@id}
2306 \edef\gnu@id{\arabic{bp@gnuplot@id}}
2307 \bp@gnu@plot{\bp@mag}{\gnu@id}
2308 \expandafter\bp@tmp@mag\bp@gnu@cmd
2309 \bp@mag@commands
2310 \stepcounter{bp@gnuplot@id}
2311 \edef\gnu@id{\arabic{bp@gnuplot@id}}
2312 \bp@gnu@plot{\bp@ph}{\gnu@id}
2313 \expandafter\bp@tmp@ph\bp@gnu@cmd
2314 \bp@ph@commands
2315 \fi
2316 \end{groupplot}
2317 \end{tikzpicture}
2318 }
2319 % \end{macrocode}
2320 % The following code handles active characters to avoid conflicts with `babel.'\changes{v1.1.5}{2024/01/11}{Added code to handle active characters}\changes{v1.1.7}{2024/02/06}{Use auto-generated list of shorthands instead of manually specifying them}\changes{v3.0.4}{2026/05/14}{Fixed babel wrapper command argument specification for grabbing arguments}
2321 % \begin{macrocode}
2322 \AtBeginDocument{%
2323 \if@babel
2324 \let\Orig@BodeZPK\BodeZPK
2325 \renewcommand{\BodeZPK}{%
2326 \expandafter\shorthandoff\expandafter{\bp@short@list}
2327 \BodeZPK@Shorthandoff
2328 }
2329 \NewDocumentCommand{\BodeZPK@Shorthandoff}{ O{} m G{} G{} }{%
2330 \Orig@BodeZPK[#1]{#2}{#3}{#4}
2331 \expandafter\shorthandon\expandafter{\bp@short@list}
2332 }
2333 \fi
2334 }
2335 % \end{macrocode}
2336 % \end{macro}
2337 % \begin{macro}{\BodeTF}
2338 % 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}\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}\changes{v3.1}{2026/05/19}{To avoid wrapping in pgf mode, use python to convert tf to zpk if available. If python is not available, fall back to the legacy implementation.}\changes{v3.1}{2026/05/19}{In pgf mode, legacy 4-argument calls now forward frequency limits via domain options when dispatching to \cs{BodeZPK}.}
2339 % \begin{macrocode}
2340 \NewDocumentCommand{\BodeTF}{ O{} m G{} G{} }{%
2341 \if@pgfarg
2342 \bp@tf@to@zpk{#2}{\bp@tmp@zpk}{\bp@tmp@status}
2343 \ifnum\pdf@strcmp{\bp@tmp@status}{true}=0
2344 \pgfutil@ifempty{#3}{%
2345 \BodeZPK[#1]{\bp@tmp@zpk}%
2346 }{%
2347 \BodeZPK[domain=#3:#4,#1]{\bp@tmp@zpk}%
2348 }%
2349 \def\bp@fallback{false}
2350 \else
2351 \def\bp@fallback{true}
2352 \fi
2353 \else
2354 \def\bp@fallback{true}
2355 \fi
2356 \ifnum\pdf@strcmp{\bp@fallback}{true}=0
2357 \pgfutil@ifempty{#3}{%
2358 \pgfkeys{/bodeplot/.cd, reset}
2359 \pgfkeys{/bodeplot/.cd, #1}
2360 \pgfkeysgetvalue{/bodeplot/@axes/mag}{\bp@mag@axes}
2361 \pgfkeysgetvalue{/bodeplot/@axes/ph}{\bp@ph@axes}
2362 \pgfkeysgetvalue{/bodeplot/@group}{\bp@group}
2363 \pgfkeysgetvalue{/bodeplot/@approx}{\bp@approx}
2364 \pgfkeysgetvalue{/bodeplot/@commands/mag}{\bp@mag@commands}
2365 \pgfkeysgetvalue{/bodeplot/@commands/ph}{\bp@ph@commands}
2366 \pgfkeysgetvalue{/bodeplot/@tikz}{\bp@tikz}
2367 \pgfkeysgetvalue{/bodeplot/@prefix}{\bp@user@prefix}
2368 \bp@tf@new@to@legacy{#2}
2369 }{%
2370 \if@radarg
2371 \pgfkeys{/bodeplot/phase unit=rad}
2372 \else
2373 \pgfkeys{/bodeplot/phase unit=deg}
2374 \fi
2375 \if@hzarg
2376 \pgfkeys{/bodeplot/frequency unit=Hz}
2377 \else
2378 \pgfkeys{/bodeplot/frequency unit=rad}
2379 \fi
2380 \bp@parse@opt{#1}
2381 \edef\bp@legacy{#2}
2382 \edef\bp@domain@start{#3}
2383 \edef\bp@domain@end{#4}
2384 }%
2385 \edef\bp@cmd{\noexpand\begin{tikzpicture}
2386 [\unexpanded\expandafter{\bp@tikz}]}
2387 \bp@cmd
2388 \gdef\bp@mag{}
2389 \gdef\bp@ph{}
2390 \bp@TF@plot{\bp@mag}{\bp@ph}{\bp@legacy}
2391 \edef\bp@cmd{\noexpand\begin{groupplot}[
2392 bp@style,
2393 xmin=\bp@domain@start,
2394 xmax=\bp@domain@end,
2395 domain=\bp@domain@start*\bp@freq@scale:\bp@domain@end*\bp@freq@scale,
2396 height=2.5cm,
2397 xmode=log,
2398 group style = {group size = 1 by 2,vertical sep=0.25cm},
2399 \unexpanded\expandafter{\bp@group}
2400 ]}
2401 \bp@cmd
2402 \edef\bp@mag@cmd{\noexpand\nextgroupplot
2403 [ylabel={Gain (dB)}, xmajorticks=false, \bp@mag@axes]
2404 \noexpand\addplot [bp@freq@filter, variable=t, thick,
2405 \unexpanded\expandafter{\bp@mag@plot}]}
2406 \edef\bp@ph@cmd{\noexpand\nextgroupplot
2407 [bp@ph@y@label, bp@freq@label, \bp@ph@axes]
2408 \noexpand\addplot [bp@freq@filter, variable=t, thick, trig format plots=rad,
2409 \unexpanded\expandafter{\bp@ph@plot}]}
2410 \if@pgfarg
2411 \bp@mag@cmd {\bp@mag};
2412 \bp@mag@commands
2413 \bp@ph@cmd {\n@mod{\bp@ph}{2*pi*\bp@ph@scale}};
2414 \bp@ph@commands
2415 \else
2416 \stepcounter{bp@gnuplot@id}
2417 \edef\gnu@id{\arabic{bp@gnuplot@id}}
2418 \bp@gnu@plot{\bp@mag}{\gnu@id}
2419 \expandafter\bp@mag@cmd\bp@gnu@cmd
2420 \bp@mag@commands
2421 \stepcounter{bp@gnuplot@id}
2422 \edef\gnu@id{\arabic{bp@gnuplot@id}}
2423 \bp@gnu@unwrap@plot{\bp@ph}{\gnu@id}
2424 \expandafter\bp@ph@cmd\bp@gnu@cmd
2425 \bp@ph@commands
2426 \fi
2427 \end{groupplot}
2428 \end{tikzpicture}
2429 \fi
2430 }
2431 % \end{macrocode}
2432 % The following code handles active characters to avoid conflicts with `babel.'\changes{v1.1.5}{2024/01/11}{Added code to handle active characters}\changes{v1.1.7}{2024/02/06}{Use auto-generated list of shorthands instead of manually specifying them}\changes{v3.0.4}{2026/05/14}{Fixed babel wrapper command argument specification for grabbing arguments}
2433 % \begin{macrocode}
2434 \AtBeginDocument{
2435 \if@babel
2436 \let\Orig@BodeTF\BodeTF
2437 \renewcommand{\BodeTF}{%
2438 \expandafter\shorthandoff\expandafter{\bp@short@list}
2439 \BodeTF@Shorthandoff
2440 }
2441 \NewDocumentCommand{\BodeTF@Shorthandoff}{ O{} m G{} G{} }{%
2442 \Orig@BodeTF[#1]{#2}{#3}{#4}
2443 \expandafter\shorthandon\expandafter{\bp@short@list}
2444 }
2445 \fi
2446 }
2447 % \end{macrocode}
2448 % \end{macro}
2449 % \begin{macro}{\addBodeZPKPlots}
2450 % This macro is designed to issue multiple |\addplot| macros for the same set of poles, zeros, gain, and delay. All of the work is done by the |\bp@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}\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}\changes{v3.1}{2026/05/19}{Pre-expand \marg{zpk-spec} and expand it before \cs{bp@contains@equal} so macro-valued specs route correctly.}
2451 % \begin{macrocode}
2452 \NewDocumentCommand{\addBodeZPKPlots}{ O{} m m }{%
2453 \edef\bp@spec@arg{#3}%
2454 \expandafter\bp@contains@equal\expandafter{\bp@spec@arg}{
2455 \pgfkeys{/bodeplot/add/.cd, reset}
2456 \pgfkeys{/bodeplot/add/.cd, #1}
2457 \bp@zpk@new@to@legacy{\bp@spec@arg}
2458 \expandafter\bp@fix@add@opt\expandafter{\bp@add@O}
2459 }{
2460 \bp@fix@add@opt{#1}
2461 \edef\bp@legacy{\bp@spec@arg}
2462 }
2463 \foreach \approx/\opt in \bp@add@O {
2464 \ifx\approx\@empty\else
2465 \gdef\bp@plot{}
2466 \gdef\bp@tmp{}
2467 \ifnum\pdf@strcmp{#2}{phase}=0
2468 \bp@ZPK@plot{\bp@tmp}{\bp@plot}{\approx}{\bp@legacy}
2469 \else
2470 \bp@ZPK@plot{\bp@plot}{\bp@tmp}{\approx}{\bp@legacy}
2471 \fi
2472 \if@pgfarg
2473 \edef\bp@cmd{\noexpand\addplot [bp@freq@filter,
2474 domain=\bp@freq@scale*\pgfkeysvalueof{/pgfplots/domain}*\bp@freq@scale,
2475 variable=t, thick, trig format plots=rad, \unexpanded\expandafter{\opt}]}
2476 \bp@cmd {\bp@plot};
2477 \else
2478 \stepcounter{bp@gnuplot@id}
2479 \edef\gnu@id{\arabic{bp@gnuplot@id}}
2480 \bp@gnu@plot[\bp@freq@scale]{\bp@plot}{\gnu@id}
2481 \edef\bp@cmd{\noexpand\addplot [variable=t, thick,
2482 \unexpanded\expandafter{\opt}]}
2483 \expandafter\bp@cmd\bp@gnu@cmd
2484 \fi
2485 \fi
2486 }
2487 }
2488 % \end{macrocode}
2489 % \end{macro}
2490 % \begin{macro}{\addBodeTFPlot}
2491 % This macro is designed to issues a single |\addplot| macros for the set of coefficients and delay. All of the work is done by the |\bp@TF@plot| macro. \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.3}{2022/11/02}{Changed implementation to respect user-supplied domain}\changes{v1.1.4}{2023/10/12}{Changed phase wrapping in pgf mode}\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}\changes{v3.1}{2026/05/19}{Pre-expand \marg{tf-spec} and expand it before \cs{bp@contains@equal} so macro-valued specs route correctly.}
2492 % \begin{macrocode}
2493 \NewDocumentCommand{\addBodeTFPlot}{ O{} m m }{%
2494 \edef\bp@spec@arg{#3}%
2495 \expandafter\bp@contains@equal\expandafter{\bp@spec@arg}{
2496 \bp@tf@new@to@legacy{\bp@spec@arg}
2497 }{
2498 \edef\bp@legacy{\bp@spec@arg}
2499 }
2500 \gdef\bp@plot{}
2501 \gdef\bp@tmp{}
2502 \ifnum\pdf@strcmp{#2}{phase}=0
2503 \bp@TF@plot{\bp@tmp}{\bp@plot}{\bp@legacy}
2504 \else
2505 \bp@TF@plot{\bp@plot}{\bp@tmp}{\bp@legacy}
2506 \fi
2507 \if@pgfarg
2508 \ifnum\pdf@strcmp{#2}{phase}=0
2509 \edef\bp@cmd{\noexpand\addplot [bp@freq@filter,
2510 domain=\bp@freq@scale*\pgfkeysvalueof{/pgfplots/domain}*\bp@freq@scale,
2511 variable=t, thick, trig format plots=rad,
2512 \unexpanded\expandafter{#1}]}
2513 \bp@cmd {\n@mod{\bp@plot}{2*pi}};
2514 \else
2515 \edef\bp@cmd{\noexpand\addplot [bp@freq@filter,
2516 domain=\bp@freq@scale*\pgfkeysvalueof{/pgfplots/domain}*\bp@freq@scale,
2517 variable=t, thick, \unexpanded\expandafter{#1}]}
2518 \bp@cmd {\bp@plot};
2519 \fi
2520 \else
2521 \stepcounter{bp@gnuplot@id}
2522 \edef\gnu@id{\arabic{bp@gnuplot@id}}
2523 \edef\bp@cmd{\noexpand\addplot [variable=t, thick,
2524 \unexpanded\expandafter{#1}]}
2525 \ifnum\pdf@strcmp{#2}{phase}=0
2526 \bp@gnu@unwrap@plot[\bp@freq@scale]{\bp@plot}{\gnu@id}
2527 \expandafter\bp@cmd\bp@gnu@cmd
2528 \else
2529 \bp@gnu@plot[\bp@freq@scale]{\bp@plot}{\gnu@id}
2530 \expandafter\bp@cmd\bp@gnu@cmd
2531 \fi
2532 \fi
2533 }
2534 % \end{macrocode}
2535 % \end{macro}
2536 % \begin{macro}{\addBodeTFPlots}
2537 % Similar to |\addBodeZPKPlots| but for systems specified in the TF format. This macro converts the TF specification to ZPK format internally using Python via |--shell-escape| and then calls |\addBodeZPKPlots| to generate the plots. If Python with the |scipy| and |numpy| libraries is not available on the shell, the package returns an error message. \changes{v3.1}{2026/05/19}{Added support for linear and asymptotic approximations when using the TF format.}
2538 % \begin{macrocode}
2539 \NewDocumentCommand{\addBodeTFPlots}{ O{} m m }{%
2540 \bp@tf@to@zpk{#3}{\bp@tmp@zpk}{\bp@tmp@status}
2541 \ifnum\pdf@strcmp{\bp@tmp@status}{true}=0
2542 \addBodeZPKPlots[#1]{#2}{\bp@tmp@zpk}
2543 \else
2544 \PackageError{bodeplot}{The |\addBodeTFPlots| macro enables linear and asymptotic approximation plots, but requires Python with the scipy and numpy libraries. Please ensure that Python is installed and accessible via --shell-escape. If Python is not available, use |\addBodeTFPlot| to generate plots without approximation.}{}
2545 \fi
2546 }
2547 % \end{macrocode}
2548 % \end{macro}
2549 % \begin{macro}{\addBodeComponentPlot}
2550 % This macro is designed to create a single |\addplot| macro capable of plotting linear combinations of the basic components described in Section \ref{sec:BasicComponents}. The only work to do here is to handle the |pgf| package option.\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}\changes{v3.0}{2025/10/21}{Updated to use \textbackslash bp@prefix for consistency}
2551 % \begin{macrocode}
2552 \newcommand{\addBodeComponentPlot}[2][]{
2553 \if@pgfarg
2554 \edef\bp@cmd{\noexpand\addplot [bp@freq@filter,
2555 domain=\bp@freq@scale*\pgfkeysvalueof{/pgfplots/domain}*\bp@freq@scale,
2556 variable=t, thick, trig format plots=rad, #1]}
2557 \bp@cmd {#2};
2558 \else
2559 \stepcounter{bp@gnuplot@id}
2560 \edef\gnu@id{\arabic{bp@gnuplot@id}}
2561 \edef\bp@cmd{\noexpand\addplot [variable=t, thick, #1]}
2562 \bp@gnu@plot[\bp@freq@scale]{#2}{\gnu@id}
2563 \expandafter\bp@cmd\bp@gnu@cmd
2564 \fi
2565 }
2566 % \end{macrocode}
2567 % \end{macro}
2568 % \begin{environment}{BodePhPlot}
2569 % An environment to host phase plot macros that pass parametric functions to |\addplot| macros. Uses the defaults specified in |bp@style| to create a shortcut that includes the |tikzpicture| and |semilogaxis| environments. The body of the environment is grabbed as a macro to maintain compatibility with externalization in |tikz|.\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}{2024/01/11}{Defined using the `NewDocumentEnvironment' command from the `xparse' package and added a hook to handle active characters}\changes{v1.1.7}{2024/02/06}{Use auto-generated list of active characters instead of manually entering them.}\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}\changes{v3.0.1}{2025/10/21}{Fixed a typo to resolve issue \#17}
2570 % \begin{macrocode}
2571 \AtBeginDocument{%
2572 \if@babel
2573 \AddToHook{env/BodePhPlot/begin}{%
2574 \expandafter\shorthandoff\expandafter{\bp@short@list}
2575 }
2576 \AddToHook{env/BodePhPlot/end}{%
2577 \expandafter\shorthandon\expandafter{\bp@short@list}
2578 }
2579 \fi
2580 }
2581 \NewDocumentEnvironment{BodePhPlot}{ O{} G{} G{} +b }{
2582 \pgfutil@ifempty{#2}{%
2583 \pgfkeys{/bodeplot/env/.cd, reset}
2584 \pgfkeys{/bodeplot/env/.cd, #1}
2585 \pgfkeysgetvalue{/bodeplot/env/@tikz}{\bp@tikz}
2586 \pgfkeysgetvalue{/bodeplot/env/@prefix}{\bp@user@prefix}
2587 }{%
2588 \bp@parse@env@opt{#1}
2589 \edef\bp@domain@start{#2}
2590 \edef\bp@domain@end{#3}
2591 }
2592 \edef\bp@cmd{\noexpand\begin{tikzpicture}
2593 [\unexpanded\expandafter{\bp@tikz}]}
2594 \bp@cmd
2595 \edef\bp@cmd{\noexpand\begin{semilogxaxis}[
2596 bp@ph@y@label,
2597 bp@freq@label,
2598 bp@style,
2599 xmin={\bp@domain@start},
2600 xmax={\bp@domain@end},
2601 domain=\bp@domain@start:\bp@domain@end,
2602 height=2.5cm,
2603 \unexpanded\expandafter{\bp@axes}
2604 ]}
2605 \bp@cmd
2606 #4
2607 \end{semilogxaxis}
2608 \end{tikzpicture}
2609 }{}
2610 % \end{macrocode}
2611 % \end{environment}
2612 % \begin{environment}{BodeMagPlot}
2613 % An environment to host magnitude plot macros that pass parametric functions to |\addplot| macros. Uses the defaults specified in |bp@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}{2024/01/11}{Defined using the `NewDocumentEnvironment' command from the `xparse' package and added a hook to handle active characters}\changes{v1.1.7}{2024/02/06}{Use auto-generated list of active characters instead of manually entering them.}\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}
2614 % \begin{macrocode}
2615 \AtBeginDocument{%
2616 \if@babel
2617 \AddToHook{env/BodeMagPlot/begin}{%
2618 \expandafter\shorthandoff\expandafter{\bp@short@list}
2619 }
2620 \AddToHook{env/BodeMagPlot/end}{%
2621 \expandafter\shorthandon\expandafter{\bp@short@list}
2622 }
2623 \fi
2624 }
2625 \NewDocumentEnvironment{BodeMagPlot}{ O{} G{} G{} +b }{
2626 \pgfutil@ifempty{#2}{%
2627 \pgfkeys{/bodeplot/env/.cd, reset}
2628 \pgfkeys{/bodeplot/env/.cd, #1}
2629 \pgfkeysgetvalue{/bodeplot/env/@tikz}{\bp@tikz}
2630 \pgfkeysgetvalue{/bodeplot/env/@prefix}{\bp@user@prefix}
2631 }{%
2632 \bp@parse@env@opt{#1}
2633 \edef\bp@domain@start{#2}
2634 \edef\bp@domain@end{#3}
2635 }
2636 \edef\bp@cmd{\noexpand\begin{tikzpicture}
2637 [\unexpanded\expandafter{\bp@tikz}]}
2638 \bp@cmd
2639 \edef\bp@cmd{\noexpand\begin{semilogxaxis}[
2640 bp@style,
2641 bp@freq@label,
2642 xmin={\bp@domain@start},
2643 xmax={\bp@domain@end},
2644 domain=\bp@domain@start:\bp@domain@end,
2645 height=2.5cm,
2646 ylabel={Gain (dB)},
2647 \unexpanded\expandafter{\bp@axes}
2648 ]}
2649 \bp@cmd
2650 #4
2651 \end{semilogxaxis}
2652 \end{tikzpicture}
2653 }{}
2654 % \end{macrocode}
2655 % \end{environment}
2656 % \begin{macro}{\addBodePlot}
2657 % Unified macro to add Bode plots for both ZPK and TF system representations inside a BodePlot environment. Supports both pgfkeys interface introduced in v3.0 and the legacy interface.\changes{v2.1}{2025/09/26}{Added unified Bode plot macro supporting both ZPK and TF systems}\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}
2658 % \begin{macrocode}
2659 \NewDocumentCommand{\addBodePlot}{ O{} m G{} }{%
2660 \gdef\bp@mag{}
2661 \gdef\bp@ph{}
2662 \pgfutil@ifempty{#3}{%
2663 \pgfkeys{/bodeplot/add/.cd, reset}
2664 \pgfkeys{/bodeplot/add/.cd, #1}
2665 \expandafter\bp@parse@add@Bode@opt\expandafter{\bp@add@O}
2666 \bp@contains@num{#2}{%
2667 \bp@tf@new@to@legacy{#2}
2668 \bp@TF@plot{\bp@mag}{\bp@ph}{\bp@legacy}
2669 \edef\bp@mode{tf}
2670 }{
2671 \bp@zpk@new@to@legacy{#2}
2672 \bp@ZPK@plot{\bp@mag}{\bp@ph}{\bp@approx}{\bp@legacy}
2673 \edef\bp@mode{zpk}
2674 }
2675 }{
2676 \bp@parse@add@Bode@opt{#1}
2677 \ifnum\pdf@strcmp{#2}{zpk}=0
2678 \edef\bp@mode{zpk}
2679 \bp@ZPK@plot{\bp@mag}{\bp@ph}{\bp@approx}{#3}
2680 \else
2681 \ifnum\pdf@strcmp{#2}{tf}=0
2682 \edef\bp@mode{tf}
2683 \bp@TF@plot{\bp@mag}{\bp@ph}{#3}
2684 \else
2685 \PackageError {bodeplot} {Unknown system representation `#2'.}
2686 {Supported representations are `zpk' and `tf'.}
2687 \fi
2688 \fi
2689 }
2690 \if@pgfarg
2691 \xdef\bp@mag@cmd{\unexpanded\expandafter{\bp@mag@cmd}\noexpand\addplot
2692 [bp@freq@filter, domain=\bp@freq@scale*\pgfkeysvalueof{/pgfplots/domain},
2693 variable=t, thick, trig format plots=rad,
2694 \unexpanded\expandafter{\bp@plot}] {\bp@mag};}
2695 \xdef\bp@ph@cmd{\unexpanded\expandafter{\bp@ph@cmd}\noexpand\addplot
2696 [bp@freq@filter, domain=\bp@freq@scale*\pgfkeysvalueof{/pgfplots/domain},
2697 variable=t, thick, trig format plots=rad,
2698 \unexpanded\expandafter{\bp@plot}] {\bp@ph};}
2699 \else
2700 \stepcounter{bp@gnuplot@id}
2701 \edef\gnu@id{\arabic{bp@gnuplot@id}}
2702 \bp@gnu@plot{\bp@mag}{\gnu@id}
2703 \xdef\bp@mag@cmd{\unexpanded\expandafter{\bp@mag@cmd}\noexpand\addplot
2704 [variable=t, thick, \unexpanded\expandafter{\bp@plot}]\bp@gnu@cmd}
2705 \stepcounter{bp@gnuplot@id}
2706 \edef\gnu@id{\arabic{bp@gnuplot@id}}
2707 \ifnum\pdf@strcmp{\bp@mode}{zpk}=0
2708 \bp@gnu@plot{\bp@ph}{\gnu@id}
2709 \else
2710 \ifnum\pdf@strcmp{\bp@mode}{tf}=0
2711 \bp@gnu@unwrap@plot{\bp@ph}{\gnu@id}
2712 \fi
2713 \fi
2714 \xdef\bp@ph@cmd{\unexpanded\expandafter{\bp@ph@cmd}\noexpand\addplot
2715 [variable=t, thick, \unexpanded\expandafter{\bp@plot}]\bp@gnu@cmd}
2716 \fi
2717 }
2718 % \end{macrocode}
2719 % \end{macro}
2720 % \begin{environment}{BodePlot}
2721 % An environment that works with the unified |\addBodePlot| macro. Creates a grouped plot with magnitude on top and phase on bottom, automatically collecting and inserting plot commands generated by |\addBodePlot| calls within the environment body.\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}{2024/01/11}{Defined using the `NewDocumentEnvironment' command from the `xparse' package and added a hook to handle active characters}\changes{v1.1.7}{2024/02/06}{Use auto-generated list of active characters instead of manually entering them}\changes{v2.1}{2025/09/26}{Enhanced BodePlot environment with unified plot command collection}\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}
2722 % \begin{macrocode}
2723 \NewDocumentEnvironment{BodePlot}{ O{} G{} G{} +b }{
2724 \pgfutil@ifempty{#2}{%
2725 \pgfkeys{/bodeplot/combinedenv/.cd, reset}
2726 \pgfkeys{/bodeplot/combinedenv/.cd, #1}
2727 \pgfkeysgetvalue{/bodeplot/combinedenv/@group}{\bp@group}
2728 \pgfkeysgetvalue{/bodeplot/combinedenv/@approx}{\bp@approx}
2729 \pgfkeysgetvalue{/bodeplot/combinedenv/@commands/mag}{\bp@mag@commands}
2730 \pgfkeysgetvalue{/bodeplot/combinedenv/@commands/ph}{\bp@ph@commands}
2731 \pgfkeysgetvalue{/bodeplot/combinedenv/@tikz}{\bp@tikz}
2732 \pgfkeysgetvalue{/bodeplot/combinedenv/@prefix}{\bp@user@prefix}
2733 }{%
2734 \bp@parse@opt{#1}
2735 \edef\bp@domain@start{#2}
2736 \edef\bp@domain@end{#3}
2737 }
2738 \gdef\bp@mag@cmd{}
2739 \gdef\bp@ph@cmd{}
2740 \edef\bp@cmd{\noexpand\begin{tikzpicture}
2741 [\unexpanded\expandafter{\bp@tikz}]}
2742 \bp@cmd
2743 \edef\bp@cmd{\noexpand\begin{groupplot}[
2744 bp@style,
2745 xmin=\bp@domain@start,
2746 xmax=\bp@domain@end,
2747 domain=\bp@domain@start*\bp@freq@scale:\bp@domain@end*\bp@freq@scale,
2748 height=2.5cm,
2749 xmode=log,
2750 group style = {group size = 1 by 2,vertical sep=0.25cm},
2751 \unexpanded\expandafter{\bp@group}
2752 ]}
2753 \bp@cmd
2754 #4
2755 \edef\temp@mag@cmd{\noexpand\nextgroupplot
2756 [ylabel={Gain (dB)}, xmajorticks=false,
2757 \unexpanded\expandafter{\bp@mag@axes}]}
2758 \edef\temp@ph@cmd{\noexpand\nextgroupplot
2759 [bp@ph@y@label, bp@freq@label,
2760 \unexpanded\expandafter{\bp@ph@axes}]}
2761 \temp@mag@cmd
2762 \bp@mag@cmd
2763 \temp@ph@cmd
2764 \bp@ph@cmd
2765 \end{groupplot}
2766 \end{tikzpicture}
2767 }{}
2768 % \end{macrocode}
2769 % \end{environment}
2770 % \subsubsection{Internal macros}
2771 % \begin{macro}{\bp@parse@complex}
2772 % Parses complex numbers in the format |a+bi| where |a| and |b| can be arbitrary pgfmath/gnuplot expressions. The scans to the left starting from the trailing |i| and finds the first top-level |+| or |-|, i.e., the first such operator not inside braces or parentheses. Everything between the |i| and the |+| or |-| is treated as the imaginary part, and everything else is treated as the real part. Sets |\bp@realpart|, |\bp@imagpart|, and |\bp@complex|. \changes{v3.0}{2025/10/21}{Added complex number parser for new interface}\changes{v3.0.3}{2026/01/15}{Rewritten to support arbitrary expressions with nested braces and parentheses}
2773 % \begin{macrocode}
2774 \ExplSyntaxOn
2775 \tl_new:N \l_real_tl
2776 \tl_new:N \l_imag_tl
2777 \tl_new:N \bp@complex
2778 \tl_new:N \bp@realpart
2779 \tl_new:N \bp@imagpart
2780
2781 % Variables for the complex number parser
2782 \tl_new:N \l__bp_input_tl
2783 \tl_new:N \l__bp_before_tl
2784 \tl_new:N \l__bp_after_tl
2785 \tl_new:N \l__bp_sep_tl
2786 \int_new:N \l__bp_pos_int
2787 \int_new:N \l__bp_seppos_int
2788 \int_new:N \l__bp_paren_int
2789 \bool_new:N \l__bp_found_bool
2790
2791 % Generate V variant for tl_if_single_token
2792 \prg_generate_conditional_variant:Nnn \tl_if_single_token:n { V } { TF, T, F }
2793
2794 \NewDocumentCommand{\bp@parse@complex}{m}{
2795 \tl_set:Nx \l__bp_input_tl {#1}
2796 \tl_remove_all:Nn \l__bp_input_tl { ~ }
2797
2798 % Check if it ends with 'i'
2799 \regex_match:nVTF { i$ } \l__bp_input_tl
2800 { \__bp_parse_complex_with_i: }
2801 { \__bp_parse_real_only: }
2802
2803 \tl_gset_eq:NN \bp@realpart \l_real_tl
2804 \tl_gset_eq:NN \bp@imagpart \l_imag_tl
2805 \tl_gset:Nx \bp@complex { { { \l_real_tl } , { \l_imag_tl } } }
2806 }
2807
2808 % Parse a pure real number (no trailing i)
2809 \cs_new_protected:Npn \__bp_parse_real_only:
2810 {
2811 \__bp_unwrap_braces:N \l__bp_input_tl
2812 \tl_set_eq:NN \l_real_tl \l__bp_input_tl
2813 \tl_set:Nn \l_imag_tl {0}
2814 }
2815
2816 % Parse a complex number (has trailing i)
2817 \cs_new_protected:Npn \__bp_parse_complex_with_i:
2818 {
2819 % Remove trailing 'i'
2820 \regex_replace_once:nnN { i$ } {} \l__bp_input_tl
2821
2822 % Find the last + or - at depth 0 (but not at position 0)
2823 \__bp_find_separator:
2824
2825 \bool_if:NTF \l__bp_found_bool
2826 { \__bp_split_at_separator: }
2827 { \__bp_parse_pure_imaginary: }
2828 }
2829
2830 % Parse pure imaginary (no separator found)
2831 \cs_new_protected:Npn \__bp_parse_pure_imaginary:
2832 {
2833 \tl_set:Nn \l_real_tl {0}
2834 \__bp_set_signed_value:NN \l_imag_tl \l__bp_input_tl
2835 }
2836
2837 % Set target to value with sign handling
2838 \cs_new_protected:Npn \__bp_set_signed_value:NN #1#2
2839 {
2840 \tl_if_empty:NTF #2
2841 { \tl_set:Nn #1 {1} }
2842 {
2843 \tl_set:Nx \l_tmpa_tl { \tl_head:N #2 }
2844 \str_if_eq:VnTF \l_tmpa_tl {-}
2845 {
2846 \tl_set:Nx \l_tmpb_tl { \tl_tail:N #2 }
2847 \tl_if_empty:NTF \l_tmpb_tl
2848 { \tl_set:Nn #1 {-1} }
2849 {
2850 \__bp_unwrap_braces:N \l_tmpb_tl
2851 \tl_set:Nx #1 { -( \l_tmpb_tl ) }
2852 }
2853 }
2854 {
2855 \str_if_eq:VnTF \l_tmpa_tl {+}
2856 {
2857 \tl_set:Nx \l_tmpb_tl { \tl_tail:N #2 }
2858 \tl_if_empty:NTF \l_tmpb_tl
2859 { \tl_set:Nn #1 {1} }
2860 {
2861 \__bp_unwrap_braces:N \l_tmpb_tl
2862 \tl_set_eq:NN #1 \l_tmpb_tl
2863 }
2864 }
2865 {
2866 \__bp_unwrap_braces:N #2
2867 \tl_set_eq:NN #1 #2
2868 }
2869 }
2870 }
2871 }
2872
2873 % Helper to unwrap a single braced group
2874 \cs_new_protected:Npn \__bp_unwrap_braces:N #1
2875 {
2876 \tl_if_single_token:VF #1
2877 {
2878 \tl_set:Nx \l_tmpc_tl { \tl_count:N #1 }
2879 \int_compare:nNnT { \l_tmpc_tl } = {1}
2880 { \tl_set:Nx #1 { \exp_after:wN \use:n #1 } }
2881 }
2882 }
2883
2884 % Process one token/group to find separator
2885 \cs_new_protected:Npn \__bp_process_item:n #1
2886 {
2887 \tl_if_single_token:nTF {#1}
2888 {
2889 % Track parenthesis depth
2890 \token_if_eq_charcode:NNT #1 ( { \int_incr:N \l__bp_paren_int }
2891 \token_if_eq_charcode:NNT #1 ) { \int_decr:N \l__bp_paren_int }
2892 % Only consider separators at position > 0 and paren depth 0
2893 \int_compare:nNnT { \l__bp_pos_int } > {0}
2894 {
2895 \int_compare:nNnT { \l__bp_paren_int } = {0}
2896 {
2897 \bool_lazy_or:nnT
2898 { \token_if_eq_charcode_p:NN #1 + }
2899 { \token_if_eq_charcode_p:NN #1 - }
2900 {
2901 \bool_set_true:N \l__bp_found_bool
2902 \int_set_eq:NN \l__bp_seppos_int \l__bp_pos_int
2903 \tl_set:Nn \l__bp_sep_tl {#1}
2904 }
2905 }
2906 }
2907 }
2908 { }
2909 \int_incr:N \l__bp_pos_int
2910 }
2911
2912 % Find the last + or - at depth 0
2913 \cs_new_protected:Npn \__bp_find_separator:
2914 {
2915 \bool_set_false:N \l__bp_found_bool
2916 \int_zero:N \l__bp_pos_int
2917 \int_zero:N \l__bp_paren_int
2918 \tl_map_function:NN \l__bp_input_tl \__bp_process_item:n
2919 }
2920
2921 % Collect items for splitting
2922 \cs_new_protected:Npn \__bp_collect_item:n #1
2923 {
2924 \int_compare:nNnTF { \l__bp_pos_int } < { \l__bp_seppos_int }
2925 { \tl_put_right:Nn \l__bp_before_tl {#1} }
2926 {
2927 \int_compare:nNnF { \l__bp_pos_int } = { \l__bp_seppos_int }
2928 { \tl_put_right:Nn \l__bp_after_tl {#1} }
2929 }
2930 \int_incr:N \l__bp_pos_int
2931 }
2932
2933 % Split the input at the separator position
2934 \cs_new_protected:Npn \__bp_split_at_separator:
2935 {
2936 \tl_clear:N \l__bp_before_tl
2937 \tl_clear:N \l__bp_after_tl
2938 \int_zero:N \l__bp_pos_int
2939
2940 \tl_map_function:NN \l__bp_input_tl \__bp_collect_item:n
2941
2942 \__bp_unwrap_braces:N \l__bp_before_tl
2943 \__bp_unwrap_braces:N \l__bp_after_tl
2944
2945 \tl_if_empty:NTF \l__bp_before_tl
2946 { \tl_set:Nn \l_real_tl {0} }
2947 { \tl_set_eq:NN \l_real_tl \l__bp_before_tl }
2948
2949 \tl_if_empty:NTF \l__bp_after_tl
2950 {
2951 \str_if_eq:VnTF \l__bp_sep_tl {-}
2952 { \tl_set:Nn \l_imag_tl {-1} }
2953 { \tl_set:Nn \l_imag_tl {1} }
2954 }
2955 {
2956 \str_if_eq:VnTF \l__bp_sep_tl {-}
2957 { \tl_set:Nx \l_imag_tl { -( \l__bp_after_tl ) } }
2958 { \tl_set_eq:NN \l_imag_tl \l__bp_after_tl }
2959 }
2960 }
2961 % \end{macrocode}
2962 %\end{macro}
2963 % \begin{macro}{\bp_if_contains:nnTF}
2964 % Helper function to check if a token list contains a substring. \changes{v3.0}{2025/10/21}{Added substring checker}
2965 % \begin{macrocode}
2966 \tl_new:N \l__bode_check_tl
2967 \cs_new_protected:Npn \bp_if_contains:nnTF #1#2#3#4 {
2968 \tl_set:Nx \l__bode_check_tl {#1}
2969 \tl_if_in:VnTF \l__bode_check_tl {#2} {#3} {#4}
2970 }
2971 % \end{macrocode}
2972 %\end{macro}
2973 % \begin{macro}{\bp@contains@equal}
2974 % Checks if argument contains '=' to distinguish new from legacy interface. \changes{v3.0}{2025/10/21}{Added interface detector}
2975 % \begin{macrocode}
2976 \NewDocumentCommand{\bp@contains@equal}{m m m}{%
2977 \bp_if_contains:nnTF {#1} {=} {#2} {#3}%
2978 }
2979 % \end{macrocode}
2980 %\end{macro}
2981 % \begin{macro}{\bp@contains@num}
2982 % Checks if argument contains 'numerator' keyword. \changes{v3.0}{2025/10/21}{Added keyword detector}
2983 % \begin{macrocode}
2984 \NewDocumentCommand{\bp@contains@num}{m m m}{%
2985 \bp_if_contains:nnTF {#1} {numerator} {#2} {#3}%
2986 }
2987 \ExplSyntaxOff
2988 % \end{macrocode}
2989 %\end{macro}
2990 % \begin{macro}{\bp@fix@add@opt}
2991 % Processes options for addplot commands, organizing by approximation type. \changes{v3.0}{2025/10/21}{Added option processor for add commands}\changes{v3.0.2}{2025/10/24}{Added a conditional to avoid always plotting the true plot, fixes issue \#18}
2992 % \begin{macrocode}
2993 \NewDocumentCommand{\bp@fix@add@opt}{ m }{%
2994 \gdef\bp@add@O{}
2995 \gdef\bp@add@tmp{}
2996 \foreach \approx/\opt in {#1} {
2997 \ifx\approx\@empty\else
2998 \ifnum\pdf@strcmp{\approx}{linear}=0
2999 \xdef\bp@add@O{\unexpanded\expandafter{\bp@add@O}%
3000 linear/{\unexpanded\expandafter{\opt}},}
3001 \else
3002 \ifnum\pdf@strcmp{\approx}{asymptotic}=0
3003 \xdef\bp@add@O{\unexpanded\expandafter{\bp@add@O}%
3004 asymptotic/{\unexpanded\expandafter{\opt}},}
3005 \else
3006 \ifnum\pdf@strcmp{\approx}{true}=0
3007 \xdef\bp@add@tmp{\unexpanded\expandafter{\bp@add@tmp}%
3008 \unexpanded\expandafter{\opt},}
3009 \else
3010 \xdef\bp@add@tmp{\unexpanded\expandafter{\bp@add@tmp}%
3011 \unexpanded\expandafter{\approx},}
3012 \fi
3013 \fi
3014 \fi
3015 \fi
3016 }
3017 \ifx\bp@add@tmp\@empty\else
3018 \xdef\bp@add@O{\unexpanded\expandafter{\bp@add@O}%
3019 true/{\unexpanded\expandafter{\bp@add@tmp}}}
3020 \fi
3021 }
3022 % \end{macrocode}
3023 %\end{macro}
3024 % \begin{macro}{\bp@add}
3025 % Helper macro to build up magnitude and phase expressions by adding contributions from zeros, poles, gain, and delay. \changes{v3.0}{2025/10/21}{Changed macro name from |add@feature| to |bp@add| for consistency}
3026 % \begin{macrocode}
3027 \newcommand*{\bp@add}[3]{
3028 \ifcat$\detokenize\expandafter{#1}$
3029 \xdef#1{\unexpanded\expandafter{#1 0+#2}}
3030 \else
3031 \xdef#1{\unexpanded\expandafter{#1+#2}}
3032 \fi
3033 \foreach \y [count=\n] in #3 {
3034 \xdef#1{\unexpanded\expandafter{#1}{\y}}
3035 \xdef\Last@LoopValue{\n}
3036 }
3037 \ifnum\Last@LoopValue=1
3038 \xdef#1{\unexpanded\expandafter{#1}{0}}
3039 \fi
3040 }
3041 % \end{macrocode}
3042 %\end{macro}
3043 % \begin{macro}{\bp@ZPK@plot}
3044 % Builds magnitude and phase plot expressions from zero-pole-gain representation. Handles linear, asymptotic, and true Bode plot approximations. \changes{v3.0}{2025/10/21}{Changed macro name from |build@ZPK@plot| to |bp@ZPK@plot| for consistency}
3045 % \begin{macrocode}
3046 \newcommand{\bp@ZPK@plot}[4]{
3047 \edef\bp@list{#4}
3048 \foreach \feature/\values in \bp@list {
3049 \ifx\values\empty\else
3050 \ifnum\pdf@strcmp{\feature}{z}=0
3051 \foreach \z in \values {
3052 \ifx\z\empty\else
3053 \ifnum\pdf@strcmp{#3}{linear}=0
3054 \bp@add{#2}{\PhZeroLin}{\z}
3055 \bp@add{#1}{\MagZeroLin}{\z}
3056 \else
3057 \ifnum\pdf@strcmp{#3}{asymptotic}=0
3058 \bp@add{#2}{\PhZeroAsymp}{\z}
3059 \bp@add{#1}{\MagZeroAsymp}{\z}
3060 \else
3061 \bp@add{#2}{\PhZero}{\z}
3062 \bp@add{#1}{\MagZero}{\z}
3063 \fi
3064 \fi
3065 \fi
3066 }
3067 \fi
3068 \ifnum\pdf@strcmp{\feature}{p}=0
3069 \foreach \p in \values {
3070 \ifx\p\empty\else
3071 \ifnum\pdf@strcmp{#3}{linear}=0
3072 \bp@add{#2}{\PhPoleLin}{\p}
3073 \bp@add{#1}{\MagPoleLin}{\p}
3074 \else
3075 \ifnum\pdf@strcmp{#3}{asymptotic}=0
3076 \bp@add{#2}{\PhPoleAsymp}{\p}
3077 \bp@add{#1}{\MagPoleAsymp}{\p}
3078 \else
3079 \bp@add{#2}{\PhPole}{\p}
3080 \bp@add{#1}{\MagPole}{\p}
3081 \fi
3082 \fi
3083 \fi
3084 }
3085 \fi
3086 \ifnum\pdf@strcmp{\feature}{k}=0
3087 \ifnum\pdf@strcmp{#3}{linear}=0
3088 \bp@add{#2}{\PhKLin}{\values}
3089 \bp@add{#1}{\MagKLin}{\values}
3090 \else
3091 \ifnum\pdf@strcmp{#3}{asymptotic}=0
3092 \bp@add{#2}{\PhKAsymp}{\values}
3093 \bp@add{#1}{\MagKAsymp}{\values}
3094 \else
3095 \bp@add{#2}{\PhK}{\values}
3096 \bp@add{#1}{\MagK}{\values}
3097 \fi
3098 \fi
3099 \fi
3100 \ifnum\pdf@strcmp{\feature}{d}=0
3101 \ifnum\pdf@strcmp{#3}{linear}=0
3102 \PackageError {bodeplot}
3103 {Linear approximation for pure delays is not supported.}
3104 {Plot the true Bode plot using `true' instead of `linear'.}
3105 \else
3106 \ifnum\pdf@strcmp{#3}{asymptotic}=0
3107 \PackageError {bodeplot}
3108 {Asymptotic approximation for pure delays is not supported.}
3109 {Plot the true Bode plot using `true' instead of `asymptotic'.}
3110 \else
3111 \ifdim\values pt < 0pt
3112 \PackageError {bodeplot} {Delay needs to be a positive number.}
3113 \fi
3114 \bp@add{#2}{\PhDel}{\values}
3115 \bp@add{#1}{\MagDel}{\values}
3116 \fi
3117 \fi
3118 \fi
3119 \fi
3120 }
3121 }
3122 % \end{macrocode}
3123 %\end{macro}
3124 % \begin{macro}{\bp@gnu@plot}
3125 % Generates gnuplot commands for computing Bode plot data. \changes{v3.0}{2025/10/21}{Changed macro name from |build@gnu@plot| to |bp@gnu@plot| for consistency}
3126 % \begin{macrocode}
3127 \newcommand{\bp@gnu@plot}[3][1]{
3128 \xdef\bp@gnu@cmd{ gnuplot [raw gnuplot, id=#3, prefix=\bp@prefix]
3129 { set table $meta;
3130 set dummy t;
3131 set logscale x 10;
3132 set xrange [#1*\pgfkeysvalueof{/pgfplots/domain}*#1];
3133 set samples \pgfkeysvalueof{/pgfplots/samples};
3134 plot #2;
3135 set table "\bp@prefix#3.table";
3136 plot "$meta" using ($1/(\bp@freq@scale)):($2);
3137 };}
3138 }
3139 % \end{macrocode}
3140 %\end{macro}
3141 % \begin{macro}{\bp@zpk@new@to@legacy}
3142 % Converts the pgfkeys interface format to the legacy ZPK format. Parses complex zeros and poles using |\bp@parse@complex|. \changes{v3.0}{2025/10/21}{Added converter from new to legacy ZPK interface}\changes{v3.1}{2026/05/19}{Added |edef| before |foreach| loops so that macro-valued |zeros| and |poles| arguments are fully expanded to character tokens before |pgffor| iterates over them}\changes{v3.1}{2026/05/19}{Pre-expand the entire \marg{spec} argument via |edef| before the |pgfkeys| call so that a macro-valued spec (e.g., the output of |bp@tf@to@zpk|) is expanded to character tokens and pgfkeys can split it on commas correctly}
3143 % \begin{macrocode}
3144 \NewDocumentCommand{\bp@zpk@new@to@legacy}{ m }{%
3145 % Pre-expand #1 so pgfkeys sees character tokens (not a macro token).
3146 % This allows passing a macro whose expansion is a key=value list.
3147 \edef\bp@zpknl@spec{/bodeplot/zpk/.cd, reset, #1}%
3148 \expandafter\pgfkeys\expandafter{\bp@zpknl@spec}
3149 \pgfkeysgetvalue{/bodeplot/zpk/@zeros}{\bp@z}
3150 \edef\bp@z{\bp@z}%
3151 \gdef\bp@z@list{}
3152 \ifx\bp@z\@empty\else
3153 \foreach \z in \bp@z {
3154 \bp@parse@complex{\z}
3155 \xdef\bp@z@list{\unexpanded\expandafter{\bp@z@list} \bp@complex,}
3156 }
3157 \fi
3158 \pgfkeysgetvalue{/bodeplot/zpk/@poles}{\bp@p}
3159 \edef\bp@p{\bp@p}%
3160 \gdef\bp@p@list{}
3161 \ifx\bp@p\@empty\else
3162 \foreach \p in \bp@p {
3163 \bp@parse@complex{\p}
3164 \xdef\bp@p@list{\unexpanded\expandafter{\bp@p@list} \bp@complex,}
3165 }
3166 \fi
3167 \pgfkeysgetvalue{/bodeplot/zpk/@gain}{\bp@k}
3168 \pgfkeysgetvalue{/bodeplot/zpk/@delay}{\bp@d}
3169 \xdef\bp@legacy{z/{\bp@z@list},p/{\bp@p@list},k/\bp@k,d/\bp@d}
3170 }
3171 % \end{macrocode}
3172 %\end{macro}
3173 % \begin{macro}{\bp@tf@new@to@legacy}
3174 % Converts the pgfkeys interface format to the legacy TF format. \changes{v3.0}{2025/10/21}{Added converter from new to legacy TF interface}\changes{v3.1}{2026/05/19}{Pre-expand the entire \marg{spec} argument via |edef| before the |pgfkeys| call so that a macro-valued spec is expanded to character tokens and pgfkeys can split it on commas correctly}
3175 % \begin{macrocode}
3176 \NewDocumentCommand{\bp@tf@new@to@legacy}{ m }{%
3177 % Pre-expand #1 so pgfkeys sees character tokens (not a macro token).
3178 \edef\bp@tfnl@spec{/bodeplot/tf/.cd, reset, #1}%
3179 \expandafter\pgfkeys\expandafter{\bp@tfnl@spec}
3180 \pgfkeysgetvalue{/bodeplot/tf/@numerator}{\bp@num}
3181 \pgfkeysgetvalue{/bodeplot/tf/@denominator}{\bp@den}
3182 \pgfkeysgetvalue{/bodeplot/tf/@delay}{\bp@d}
3183 \gdef\bp@num@list{}
3184 \ifx\bp@num\@empty\else
3185 \foreach \n in \bp@num {
3186 \xdef\bp@num@list{\unexpanded\expandafter{\bp@num@list} \n,}
3187 }
3188 \fi
3189 \gdef\bp@den@list{}
3190 \ifx\bp@den\@empty\else
3191 \foreach \d in \bp@den {
3192 \xdef\bp@den@list{\unexpanded\expandafter{\bp@den@list} \d,}
3193 }
3194 \fi
3195 \xdef\bp@legacy{num/{\bp@num@list},den/{\bp@den@list},d/\bp@d}
3196 }
3197 % \end{macrocode}
3198 %\end{macro}
3199 % \begin{macro}{\bp@tztpk@outfile}
3200 % \begin{macro}{\bp@tf@to@zpk}
3201 % Converts a transfer-function specification to zero-pole-gain (ZPK) form
3202 % by invoking a |python3| helper script via |--shell-escape|.
3203 %
3204 % At the start of the document the package registers an |\AtBeginDocument|
3205 % hook that writes a six-line Python driver to |\jobname-tf2zpk.py|.
3206 % The script is intentionally written as a set of zero-indented one-liners
3207 % so that TeX's space-collapsing rules inside |\write| arguments do not
3208 % corrupt Python indentation. Characters that would require a backslash
3209 % in TeX (|\|, |{|, |}|) and the newline character are obtained at runtime
3210 % using |chr(92)|, |chr(123)|, |chr(125)|, and |chr(10)|, so that no
3211 % |\detokenize| wrapper is needed for any line.
3212 %
3213 % |\bp@tf@to@zpk| accepts a TF specification in either the new pgfkeys
3214 % format (e.g.\ |numerator={2,10},denominator={1,3,2},delay=0|) or the
3215 % legacy slash format (e.g.\ |num/{2,10},den/{1,3,2},d/0|), mirroring
3216 % the two interfaces accepted by |\BodeTF|. The numerator and denominator
3217 % coefficient lists are extracted and passed to the Python helper as
3218 % comma-separated strings.
3219 %
3220 % On success the macro |\edef|s into the caller-supplied output control
3221 % sequence a ZPK specification string in the new pgfkeys format, e.g.\
3222 % |zeros={-5.0},poles={-2.0,-1.0},gain=2.000000,delay=|. The delay
3223 % value is taken from the TF spec and passed through unchanged; if no
3224 % delay was specified it is the empty string, which the ZPK pgfkeys
3225 % family treats as zero. The result can be passed to |\BodeZPK| via
3226 % |\expandafter|:
3227 % \begin{quote}
3228 % |\expandafter\BodeZPK\expandafter|\oarg{opts}|\expandafter{|\meta{output-cs}|}|
3229 % \end{quote}
3230 % \noindent and directly to |\bp@zpk@new@to@legacy| or |\bp@ZPK@plot|
3231 % via the same |\expandafter| idiom for internal use.
3232 %
3233 % \medskip\noindent\textbf{Usage:}
3234 % \begin{quote}
3235 % |\bp@tf@to@zpk|\marg{tf-spec}\marg{\textbackslash zpk-cs}%
3236 % \marg{\textbackslash status}
3237 % \end{quote}
3238 % \begin{description}
3239 % \item[\textit{tf-spec}] Transfer-function specification in either the
3240 % pgfkeys format accepted by |\BodeTF| (new interface) or the legacy
3241 % slash format (legacy interface).
3242 % \item[\textit{\textbackslash zpk-cs}] Control sequence |\edef|-bound
3243 % on success to a ZPK spec string in the format accepted by |\BodeZPK|:
3244 % |zeros={|\ldots|},poles={|\ldots|},gain=|\ldots|,delay=|\ldots.
3245 % \item[\textit{\textbackslash status}] Control sequence |\def|-bound to
3246 % |true| on success, or |false| if the Python script did not produce
3247 % an output file (|python3| unavailable, missing dependencies, or no
3248 % |--shell-escape|).
3249 % \end{description}
3250 % \changes{v3.1}{2026/05/19}{Added |bp@tf@to@zpk| and companion Python
3251 % helper-script writer; converts polynomial TF coefficients to ZPK form
3252 % via |python3| and |scipy.signal.tf2zpk| invoked under |--shell-escape|}
3253 % \changes{v3.1}{2026/05/19}{Redesigned |bp@tf@to@zpk| to accept the
3254 % full TF spec in either new or legacy format and output a single ZPK
3255 % spec macro instead of separate gain/poles/zeros control sequences}
3256 % \begin{macrocode}
3257 \newcommand*{\bp@tztpk@outfile}{\jobname-tf2zpk-out.tex}
3258 \AtBeginDocument{%
3259 \newwrite\bp@tztpk@file
3260 \immediate\openout\bp@tztpk@file=\jobname-tf2zpk.py
3261 \immediate\write\bp@tztpk@file{import sys,numpy as np}
3262 \immediate\write\bp@tztpk@file{from scipy.signal import tf2zpk}
3263 \immediate\write\bp@tztpk@file{bs,lb,rb=chr(92),chr(123),chr(125)}
3264 \immediate\write\bp@tztpk@file{fmt=lambda arr:",".join([str(round(c.real,6)) if abs(round(c.imag,6))<1e-5 else str(round(c.real,6))+("+"+str(round(c.imag,6)) if round(c.imag,6)>=0 else str(round(c.imag,6)))+"i" for c in arr])}
3265 \immediate\write\bp@tztpk@file{try: num=[float(x) for x in sys.argv[1].split(",")]; den=[float(x) for x in sys.argv[2].split(",")]; z,p,k=tf2zpk(num,den); nl=chr(10); f=open(sys.argv[3],"w"); f.write(bs+"def"+bs+"zpkGain"+lb+format(k,".6f")+rb+nl); f.write(bs+"def"+bs+"zpkZeros"+lb+fmt(z)+rb+nl); f.write(bs+"def"+bs+"zpkPoles"+lb+fmt(p)+rb+nl); f.close()}
3266 \immediate\write\bp@tztpk@file{except Exception as e: sys.stderr.write(str(e))}
3267 \immediate\closeout\bp@tztpk@file
3268 }
3269 \NewDocumentCommand{\bp@tf@to@zpk}{ m m m }{%
3270 % Step 1: Extract numerator, denominator, and delay from the TF spec.
3271 % Supports both the new pgfkeys format (numerator={...},denominator={...},
3272 % delay=...) and the legacy slash format (num/{...},den/{...},d/...).
3273 \bp@contains@equal{#1}{%
3274 % New pgfkeys format
3275 \pgfkeys{/bodeplot/tf/.cd, reset}%
3276 \pgfkeys{/bodeplot/tf/.cd, #1}%
3277 \pgfkeysgetvalue{/bodeplot/tf/@numerator}{\bp@tztpk@num}%
3278 \pgfkeysgetvalue{/bodeplot/tf/@denominator}{\bp@tztpk@den}%
3279 \pgfkeysgetvalue{/bodeplot/tf/@delay}{\bp@tztpk@d}%
3280 }{%
3281 % Legacy slash format
3282 \gdef\bp@tztpk@num{}\gdef\bp@tztpk@den{}\gdef\bp@tztpk@d{}%
3283 \edef\bp@tztpk@list{#1}%
3284 \foreach \bp@tztpk@feat/\bp@tztpk@val in \bp@tztpk@list {%
3285 \ifnum\pdf@strcmp{\bp@tztpk@feat}{num}=0
3286 \xdef\bp@tztpk@num{\bp@tztpk@val}%
3287 \fi
3288 \ifnum\pdf@strcmp{\bp@tztpk@feat}{den}=0
3289 \xdef\bp@tztpk@den{\bp@tztpk@val}%
3290 \fi
3291 \ifnum\pdf@strcmp{\bp@tztpk@feat}{d}=0
3292 \xdef\bp@tztpk@d{\bp@tztpk@val}%
3293 \fi
3294 }%
3295 }%
3296 % Step 2: Invoke the Python helper.
3297 \ifwindows
3298 \immediate\write18{if exist "\bp@tztpk@outfile" del /f "\bp@tztpk@outfile"}%
3299 \else
3300 \immediate\write18{rm -f "\bp@tztpk@outfile"}%
3301 \fi
3302 \immediate\write18{python3 "\jobname-tf2zpk.py" "\bp@tztpk@num" "\bp@tztpk@den" "\bp@tztpk@outfile"}%
3303 % Step 3: Build the ZPK spec and set status.
3304 \IfFileExists{\bp@tztpk@outfile}{%
3305 \input{\bp@tztpk@outfile}%
3306 \edef#2{zeros={\zpkZeros},poles={\zpkPoles},gain=\zpkGain,delay=\bp@tztpk@d}%
3307 \def#3{true}%
3308 }{%
3309 \def#3{false}%
3310 }%
3311 }
3312 % \end{macrocode}
3313 %\end{macro}
3314 %\end{macro}
3315 % \begin{macro}{\bp@TF@plot}
3316 % Builds magnitude and phase plot expressions from transfer function representation. \changes{v3.0}{2025/10/21}{Changed macro name from |build@TF@plot| to |bp@TF@plot| for consistency}
3317 % \begin{macrocode}
3318 \newcommand{\bp@TF@plot}[3]{
3319 \gdef\bp@num@re{0}
3320 \gdef\bp@num@im{0}
3321 \gdef\bp@den@re{0}
3322 \gdef\bp@den@im{0}
3323 \gdef\bp@loop@delay{0}
3324 \edef\bp@list{#3}
3325 \foreach \feature/\values in \bp@list {
3326 \ifx\values\empty\else
3327 \ifnum\pdf@strcmp{\feature}{num}=0
3328 \foreach \numcoeff [count=\numpow] in \values {
3329 \ifx\numcoeff\empty\else
3330 \xdef\bp@num@deg{\numpow}
3331 \fi
3332 }
3333 \foreach \numcoeff [count=\numpow] in \values {
3334 \ifx\numcoeff\empty\else
3335 \pgfmathtruncatemacro{\currentdegree}{\bp@num@deg-\numpow}
3336 \ifnum\currentdegree = 0
3337 \xdef\bp@num@re{\bp@num@re+\numcoeff}
3338 \else
3339 \ifodd\currentdegree
3340 \xdef\bp@num@im{\bp@num@im+(\numcoeff*(\n@pow{-1}{(\currentdegree-1)/2})*%
3341 (\n@pow{t}{\currentdegree}))}
3342 \else
3343 \xdef\bp@num@re{\bp@num@re+(\numcoeff*(\n@pow{-1}{(\currentdegree)/2})*%
3344 (\n@pow{t}{\currentdegree}))}
3345 \fi
3346 \fi
3347 \fi
3348 }
3349 \fi
3350 \ifnum\pdf@strcmp{\feature}{den}=0
3351 \foreach \dencoeff [count=\denpow] in \values {
3352 \ifx\dencoeff\empty\else
3353 \xdef\bp@den@deg{\denpow}
3354 \fi
3355 }
3356 \foreach \dencoeff [count=\denpow] in \values {
3357 \ifx\dencoeff\empty\else
3358 \pgfmathtruncatemacro{\currentdegree}{\bp@den@deg-\denpow}
3359 \ifnum\currentdegree = 0
3360 \xdef\bp@den@re{\bp@den@re+\dencoeff}
3361 \else
3362 \ifodd\currentdegree
3363 \xdef\bp@den@im{\bp@den@im+(\dencoeff*(\n@pow{-1}{(\currentdegree-1)/2})*%
3364 (\n@pow{t}{\currentdegree}))}
3365 \else
3366 \xdef\bp@den@re{\bp@den@re+(\dencoeff*(\n@pow{-1}{(\currentdegree)/2})*%
3367 (\n@pow{t}{\currentdegree}))}
3368 \fi
3369 \fi
3370 \fi
3371 }
3372 \fi
3373 \ifnum\pdf@strcmp{\feature}{d}=0
3374 \xdef\bp@loop@delay{\values}
3375 \fi
3376 \fi
3377 }
3378 \xdef#2{((atan2((\bp@num@im),(\bp@num@re))-atan2((\bp@den@im),%
3379 (\bp@den@re))-\bp@loop@delay*t)*(\bp@ph@scale))}
3380 \xdef#1{(20*log10(sqrt((\n@pow{\bp@num@re}{2})+(\n@pow{\bp@num@im}{2})))-%
3381 20*log10(sqrt((\n@pow{\bp@den@re}{2})+(\n@pow{\bp@den@im}{2}))))}
3382 }
3383 % \end{macrocode}
3384 %\end{macro}
3385 % \begin{macro}{\bp@gnu@unwrap@plot}
3386 % Generates gnuplot commands with phase unwrapping for TF plots. \changes{v3.0}{2025/10/21}{Changed macro name from |build@gnu@unwrap@plot| to |bp@gnu@unwrap@plot| for consistency}
3387 % \begin{macrocode}
3388 \newcommand{\bp@gnu@unwrap@plot}[3][1]{
3389 \xdef\bp@gnu@cmd{ gnuplot [raw gnuplot, id=#3, prefix=\bp@prefix]
3390 { set table $meta;
3391 set dummy t;
3392 set logscale x 10;
3393 set trange [#1*\pgfkeysvalueof{/pgfplots/domain}*#1];
3394 set samples \pgfkeysvalueof{/pgfplots/samples};
3395 plot '+' using (t) : ((#2)/(\bp@ph@scale)) smooth unwrap;
3396 set table "\bp@prefix#3.table";
3397 plot "$meta" using ($1/(\bp@freq@scale)):($2*\bp@ph@scale);
3398 };}
3399 }
3400 % \end{macrocode}
3401 %\end{macro}
3402 % \begin{macro}{\bp@parse@opt}
3403 % Parses options supplied to the main Bode macros. A |for| loop over tuples of the form |\obj/\typ/\opt| with a long list of nested if-else statements does the job. If the input |\obj| is |plot|, |axes|, |group|, |approx|, or |tikz| the corresponding |\opt| are passed, unexpanded, to the |\addplot| macro, the |\nextgroupplot| macro, the |groupplot| environment, the |\build@ZPK@plot| macro, and the |tikzpicture| environment, respectively. If |\obj| is |commands|, the corresponding |\opt| are stored, unexpanded, in the macros |\bp@ph@commands| and |\bp@mag@commands|, to be executed in appropriate |axis| environments. \changes{v1.0.3}{2021/11/03}{Added Tikz option} \changes{v1.0.5}{2021/11/15}{Fixed a bug}\changes{v2.1.1}{2025/10/04}{Added a new option |prefix| to enable per-plot custom file names for gnuplot tables}
3404 % \begin{macrocode}
3405 \newcommand{\bp@parse@opt}[1]{
3406 \gdef\bp@mag@axes{}
3407 \gdef\bp@ph@axes{}
3408 \gdef\bp@ph@plot{}
3409 \gdef\bp@mag@plot{}
3410 \gdef\bp@group{}
3411 \gdef\bp@approx{}
3412 \gdef\bp@ph@commands{}
3413 \gdef\bp@mag@commands{}
3414 \gdef\bp@tikz{}
3415 \gdef\bp@user@prefix{}
3416 \foreach \obj/\typ/\opt in {#1} {
3417 \ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{plot}=0
3418 \ifnum\pdf@strcmp{\unexpanded\expandafter{\typ}}{mag}=0
3419 \xdef\bp@mag@plot{\unexpanded\expandafter{\opt}}
3420 \else
3421 \ifnum\pdf@strcmp{\unexpanded\expandafter{\typ}}{ph}=0
3422 \xdef\bp@ph@plot{\unexpanded\expandafter{\opt}}
3423 \else
3424 \xdef\bp@mag@plot{\unexpanded\expandafter{\opt}}
3425 \xdef\bp@ph@plot{\unexpanded\expandafter{\opt}}
3426 \fi
3427 \fi
3428 \else
3429 \ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{axes}=0
3430 \ifnum\pdf@strcmp{\unexpanded\expandafter{\typ}}{mag}=0
3431 \xdef\bp@mag@axes{\unexpanded\expandafter{\opt}}
3432 \else
3433 \ifnum\pdf@strcmp{\unexpanded\expandafter{\typ}}{ph}=0
3434 \xdef\bp@ph@axes{\unexpanded\expandafter{\opt}}
3435 \else
3436 \xdef\bp@mag@axes{\unexpanded\expandafter{\opt}}
3437 \xdef\bp@ph@axes{\unexpanded\expandafter{\opt}}
3438 \fi
3439 \fi
3440 \else
3441 \ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{group}=0
3442 \xdef\bp@group{\unexpanded\expandafter{\opt}}
3443 \else
3444 \ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{approx}=0
3445 \xdef\bp@approx{\unexpanded\expandafter{\opt}}
3446 \else
3447 \ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{commands}=0
3448 \ifnum\pdf@strcmp{\unexpanded\expandafter{\typ}}{ph}=0
3449 \xdef\bp@ph@commands{\unexpanded\expandafter{\opt}}
3450 \else
3451 \xdef\bp@mag@commands{\unexpanded\expandafter{\opt}}
3452 \fi
3453 \else
3454 \ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{tikz}=0
3455 \xdef\bp@tikz{\unexpanded\expandafter{\opt}}
3456 \else
3457 \ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{prefix}=0
3458 \xdef\bp@user@prefix{\unexpanded\expandafter{\opt}}
3459 \else
3460 \xdef\bp@user@prefix{}
3461 \xdef\bp@mag@plot{\unexpanded\expandafter{\bp@mag@plot},
3462 \unexpanded\expandafter{\obj}}
3463 \xdef\bp@ph@plot{\unexpanded\expandafter{\bp@ph@plot},
3464 \unexpanded\expandafter{\obj}}
3465 \fi
3466 \fi
3467 \fi
3468 \fi
3469 \fi
3470 \fi
3471 \fi
3472 }
3473 }
3474 % \end{macrocode}
3475 %\end{macro}
3476 % \begin{macro}{\bp@parse@env@opt}
3477 % Parses options supplied to the Bode, Nyquist, and Nichols environments. A |for| loop over tuples of the form |\obj/\opt|, processed using nested if-else statements does the job. The input |\obj| should either be |axes| or |tikz|, and the corresponding |\opt| are passed, unexpanded, to the |axis| environment and the |tikzpicture| environment, respectively. \changes{v1.0.3}{2021/11/03}{Added tikz option to environments}\changes{v2.1.1}{2025/10/04}{Added a new option |prefix| to enable per-plot custom file names for gnuplot tables}
3478 % \begin{macrocode}
3479 \newcommand{\bp@parse@env@opt}[1]{
3480 \gdef\bp@axes{}
3481 \gdef\bp@tikz{}
3482 \gdef\bp@user@prefix{}
3483 \foreach \obj/\opt in {#1} {
3484 \ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{axes}=0
3485 \xdef\bp@axes{\unexpanded\expandafter{\opt}}
3486 \else
3487 \ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{tikz}=0
3488 \xdef\bp@tikz{\unexpanded\expandafter{\opt}}
3489 \else
3490 \ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{prefix}=0
3491 \xdef\bp@user@prefix{\unexpanded\expandafter{\opt}}
3492 \else
3493 \xdef\bp@user@prefix{}
3494 \xdef\bp@axes{\unexpanded\expandafter{\bp@axes},
3495 \unexpanded\expandafter{\obj}}
3496 \fi
3497 \fi
3498 \fi
3499 }
3500 }
3501 % \end{macrocode}
3502 % \end{macro}
3503 % \begin{macro}{\bp@parse@add@Bode@opt}
3504 % Parses options for the unified |\addBodePlot| macro. Handles |linear| and |asymptotic| approximation options plus general plot styling options.\changes{v2.1}{2025/09/26}{Added option parser for unified Bode plot macro}
3505 % \begin{macrocode}
3506 \newcommand{\bp@parse@add@Bode@opt}[1]{
3507 \gdef\bp@plot{}
3508 \gdef\bp@approx{}
3509 \foreach \opt in {#1} {
3510 \ifx\opt\@empty\else
3511 \ifnum\pdf@strcmp{\unexpanded\expandafter{\opt}}{linear}=0
3512 \xdef\bp@approx{\unexpanded\expandafter{\opt}}
3513 \else
3514 \ifnum\pdf@strcmp{\unexpanded\expandafter{\opt}}{asymptotic}=0
3515 \xdef\bp@approx{\unexpanded\expandafter{\opt}}
3516 \else
3517 \xdef\bp@plot{\unexpanded\expandafter{\bp@plot}%
3518 \unexpanded\expandafter{\opt},}
3519 \fi
3520 \fi
3521 \fi
3522 }
3523 }
3524 % \end{macrocode}
3525 %\end{macro}
3526 % \subsection{Nyquist plots}
3527 % \subsubsection{User macros}
3528 % \begin{macro}{\NyquistZPK}
3529 % Converts magnitude and phase parametric functions built using |\bp@ZPK@plot| into real part and imaginary part parametric functions. A plot of these is the Nyquist plot. The parametric functions are then plotted in a |tikzpicture| environment using the |\addplot| macro. Unless the package is loaded with the option |pgf|, the parametric functions are evaluated using |gnuplot|. A large number of samples is typically needed to get a smooth plot because frequencies near 0 result in plot points that are very close to each other. Linear frequency sampling is unnecessarily fine near zero and very coarse for large $\omega$. Logarithmic sampling makes it worse, perhaps inverse logarithmic sampling will help, pull requests to fix that are welcome! \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}\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}
3530 % \begin{macrocode}
3531 \NewDocumentCommand{\NyquistZPK}{ O{} m G{} G{} }{%
3532 \pgfutil@ifempty{#3}{%
3533 \pgfkeys{/bodeplot/nyquist/.cd, reset}
3534 \pgfkeys{/bodeplot/nyquist/.cd, #1}
3535 \pgfkeysgetvalue{/bodeplot/nyquist/@axes}{\bp@axes}
3536 \pgfkeysgetvalue{/bodeplot/nyquist/@commands}{\bp@commands}
3537 \pgfkeysgetvalue{/bodeplot/nyquist/@tikz}{\bp@tikz}
3538 \pgfkeysgetvalue{/bodeplot/nyquist/@prefix}{\bp@user@prefix}
3539 \bp@zpk@new@to@legacy{#2}
3540 }{%
3541 \bp@parse@N@opt{#1}
3542 \edef\bp@legacy{#2}
3543 \edef\bp@domain@start{#3}
3544 \edef\bp@domain@end{#4}
3545 }%
3546 \gdef\bp@mag{}\gdef\bp@ph{}%
3547 \edef\bp@cmd{\noexpand\begin{tikzpicture}
3548 [\unexpanded\expandafter{\bp@tikz}]}\bp@cmd
3549 \bp@ZPK@plot{\bp@mag}{\bp@ph}{}{\bp@legacy}%
3550 \edef\bp@cmd{\noexpand\begin{axis}[
3551 bp@style,
3552 domain=\bp@domain@start*\bp@freq@scale:\bp@domain@end*\bp@freq@scale,
3553 height=5cm,
3554 xlabel={$\Re$},
3555 ylabel={$\Im$},
3556 samples=500,
3557 \unexpanded\expandafter{\bp@axes}
3558 ]}
3559 \bp@cmd
3560 \addplot [only marks,mark=+,thick,red] (-1 , 0);
3561 \edef\bp@cmd{\noexpand\addplot
3562 [variable=t, thick, trig format plots=rad,
3563 \unexpanded\expandafter{\bp@plot}]}
3564 \if@pgfarg
3565 \bp@cmd
3566 ( {\n@pow{10}{((\bp@mag)/20)}*cos((\bp@ph)/(\bp@ph@scale))},
3567 {\n@pow{10}{((\bp@mag)/20)}*sin((\bp@ph)/(\bp@ph@scale))} );
3568 \bp@commands
3569 \else
3570 \stepcounter{bp@gnuplot@id}
3571 \bp@cmd gnuplot [parametric, bp@gnu@prefix] {
3572 \n@pow{10}{((\bp@mag)/20)}*cos((\bp@ph)/(\bp@ph@scale)),
3573 \n@pow{10}{((\bp@mag)/20)}*sin((\bp@ph)/(\bp@ph@scale))
3574 };
3575 \bp@commands
3576 \fi
3577 \end{axis}
3578 \end{tikzpicture}
3579 }
3580 % \end{macrocode}
3581 % The following code handles active characters to avoid conflicts with `babel.'\changes{v1.1.5}{2024/01/11}{Added code to handle active characters}\changes{v1.1.7}{2024/02/06}{Use auto-generated list of shorthands instead of manually specifying them}\changes{v3.0.4}{2026/05/14}{Fixed babel wrapper command argument specification for grabbing arguments}
3582 % \begin{macrocode}
3583 \AtBeginDocument{%
3584 \if@babel
3585 \let\Orig@NyquistZPK\NyquistZPK
3586 \renewcommand{\NyquistZPK}{%
3587 \expandafter\shorthandoff\expandafter{\bp@short@list}
3588 \NyquistZPK@Shorthandoff
3589 }
3590 \NewDocumentCommand{\NyquistZPK@Shorthandoff}{ O{} m G{} G{} }{%
3591 \Orig@NyquistZPK[#1]{#2}{#3}{#4}
3592 \expandafter\shorthandon\expandafter{\bp@short@list}
3593 }
3594 \fi
3595 }
3596 % \end{macrocode}
3597 % \end{macro}
3598 % \begin{macro}{\NyquistTF}
3599 % 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 |\bp@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}\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}
3600 % \begin{macrocode}
3601 \NewDocumentCommand{\NyquistTF}{ O{} m G{} G{} }{%
3602 \pgfutil@ifempty{#3}{%
3603 \pgfkeys{/bodeplot/nyquist/.cd, reset}
3604 \pgfkeys{/bodeplot/nyquist/.cd, #1}
3605 \pgfkeysgetvalue{/bodeplot/nyquist/@axes}{\bp@axes}
3606 \pgfkeysgetvalue{/bodeplot/nyquist/@commands}{\bp@commands}
3607 \pgfkeysgetvalue{/bodeplot/nyquist/@tikz}{\bp@tikz}
3608 \pgfkeysgetvalue{/bodeplot/nyquist/@prefix}{\bp@user@prefix}
3609 \bp@tf@new@to@legacy{#2}
3610 }{%
3611 \bp@parse@N@opt{#1}
3612 \edef\bp@legacy{#2}
3613 \edef\bp@domain@start{#3}
3614 \edef\bp@domain@end{#4}
3615 }%
3616 \gdef\bp@mag{}\gdef\bp@ph{}%
3617 \edef\bp@cmd{\noexpand\begin{tikzpicture}
3618 [\unexpanded\expandafter{\bp@tikz}]}\bp@cmd
3619 \bp@TF@plot{\bp@mag}{\bp@ph}{\bp@legacy}%
3620 \edef\bp@cmd{\noexpand\begin{axis}[
3621 bp@style,
3622 domain=\bp@domain@start*\bp@freq@scale:\bp@domain@end*\bp@freq@scale,
3623 height=5cm,
3624 xlabel={$\Re$},
3625 ylabel={$\Im$},
3626 samples=500,
3627 \unexpanded\expandafter{\bp@axes}
3628 ]}
3629 \bp@cmd
3630 \addplot [only marks, mark=+, thick, red] (-1 , 0);
3631 \edef\bp@cmd{\noexpand\addplot
3632 [variable=t, thick, trig format plots=rad,
3633 \unexpanded\expandafter{\bp@plot}]}
3634 \if@pgfarg
3635 \bp@cmd
3636 ( {\n@pow{10}{((\bp@mag)/20)}*cos((\bp@ph)/(\bp@ph@scale))},
3637 {\n@pow{10}{((\bp@mag)/20)}*sin((\bp@ph)/(\bp@ph@scale))} );
3638 \bp@commands
3639 \else
3640 \stepcounter{bp@gnuplot@id}
3641 \bp@cmd gnuplot [parametric, bp@gnu@prefix] {
3642 \n@pow{10}{((\bp@mag)/20)}*cos((\bp@ph)/(\bp@ph@scale)),
3643 \n@pow{10}{((\bp@mag)/20)}*sin((\bp@ph)/(\bp@ph@scale))
3644 };
3645 \bp@commands
3646 \fi
3647 \end{axis}
3648 \end{tikzpicture}
3649 }
3650 % \end{macrocode}
3651 % The following code handles active characters to avoid conflicts with `babel.'\changes{v1.1.5}{2024/01/11}{Added code to handle active characters}\changes{v1.1.7}{2024/02/06}{Use auto-generated list of shorthands instead of manually specifying them}\changes{v3.0.4}{2026/05/14}{Fixed babel wrapper command argument specification for grabbing arguments}
3652 % \begin{macrocode}
3653 \AtBeginDocument{%
3654 \if@babel
3655 \let\Orig@NyquistTF\NyquistTF
3656 \renewcommand{\NyquistTF}{%
3657 \expandafter\shorthandoff\expandafter{\bp@short@list}
3658 \NyquistTF@Shorthandoff
3659 }
3660 \NewDocumentCommand{\NyquistTF@Shorthandoff}{ O{} m G{} G{} }{%
3661 \Orig@NyquistTF[#1]{#2}{#3}{#4}
3662 \expandafter\shorthandon\expandafter{\bp@short@list}
3663 }
3664 \fi
3665 }
3666 % \end{macrocode}
3667 % \end{macro}
3668 % \begin{macro}{\addNyquistZPKPlot}
3669 % Adds Nyquist plot of a transfer function in ZPK form with dual interface support. Converts magnitude and phase to real and imaginary parts for parametric plotting.\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}\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}\changes{v3.1}{2026/05/19}{Pre-expand \marg{zpk-spec} via |edef| before |bp@contains@equal| routing so that a macro-valued spec is accepted}\changes{v3.1}{2026/05/19}{Use \cs{expandafter} when calling \cs{bp@contains@equal} so the pre-expanded spec is tested as character tokens.}
3670 % \begin{macrocode}
3671 \NewDocumentCommand{\addNyquistZPKPlot}{ O{} m }{%
3672 \edef\bp@spec@arg{#2}%
3673 \expandafter\bp@contains@equal\expandafter{\bp@spec@arg}{%
3674 \bp@zpk@new@to@legacy{\bp@spec@arg}}{\edef\bp@legacy{\bp@spec@arg}}%
3675 \gdef\bp@mag{}\gdef\bp@ph{}%
3676 \bp@ZPK@plot{\bp@mag}{\bp@ph}{}{\bp@legacy}%
3677 \if@pgfarg
3678 \edef\bp@cmd{\noexpand\addplot
3679 [domain=\bp@freq@scale*\pgfkeysvalueof{/pgfplots/domain}*\bp@freq@scale,
3680 variable=t, thick, trig format plots=rad, #1]}%
3681 \bp@cmd ( {\n@pow{10}{((\bp@mag)/20)}*cos((\bp@ph)/(\bp@ph@scale))},
3682 {\n@pow{10}{((\bp@mag)/20)}*sin((\bp@ph)/(\bp@ph@scale))} );
3683 \else
3684 \stepcounter{bp@gnuplot@id}%
3685 \edef\bp@cmd{\noexpand\addplot
3686 [domain=\bp@freq@scale*\pgfkeysvalueof{/pgfplots/domain}*\bp@freq@scale, thick, #1]}%
3687 \bp@cmd gnuplot [parametric, bp@gnu@prefix] {%
3688 \n@pow{10}{((\bp@mag)/20)}*cos((\bp@ph)/(\bp@ph@scale)),
3689 \n@pow{10}{((\bp@mag)/20)}*sin((\bp@ph)/(\bp@ph@scale))
3690 };
3691 \fi
3692 }
3693 % \end{macrocode}
3694 %\end{macro}
3695 % \begin{macro}{\addNyquistTFPlot}
3696 % Adds Nyquist plot of a transfer function in TF form with dual interface support. Converts magnitude and phase to real and imaginary parts for parametric plotting.\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}\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}\changes{v3.1}{2026/05/19}{Pre-expand \marg{tf-spec} via |edef| before |bp@contains@equal| routing so that a macro-valued spec is accepted}\changes{v3.1}{2026/05/19}{Use \cs{expandafter} when calling \cs{bp@contains@equal} so the pre-expanded spec is tested as character tokens.}
3697 % \begin{macrocode}
3698 \NewDocumentCommand{\addNyquistTFPlot}{ O{} m }{%
3699 \edef\bp@spec@arg{#2}%
3700 \expandafter\bp@contains@equal\expandafter{\bp@spec@arg}{%
3701 \bp@tf@new@to@legacy{\bp@spec@arg}}{\edef\bp@legacy{\bp@spec@arg}}%
3702 \gdef\bp@mag{}\gdef\bp@ph{}%
3703 \bp@TF@plot{\bp@mag}{\bp@ph}{\bp@legacy}%
3704 \if@pgfarg
3705 \edef\bp@cmd{\noexpand\addplot
3706 [domain=\bp@freq@scale*\pgfkeysvalueof{/pgfplots/domain}*\bp@freq@scale,
3707 variable=t, thick, trig format plots=rad, #1]}%
3708 \bp@cmd ( {\n@pow{10}{((\bp@mag)/20)}*cos((\bp@ph)/(\bp@ph@scale))},
3709 {\n@pow{10}{((\bp@mag)/20)}*sin((\bp@ph)/(\bp@ph@scale))} );
3710 \else
3711 \stepcounter{bp@gnuplot@id}%
3712 \edef\bp@cmd{\noexpand\addplot
3713 [domain=\bp@freq@scale*\pgfkeysvalueof{/pgfplots/domain}*\bp@freq@scale, thick, #1]}%
3714 \bp@cmd gnuplot [parametric, bp@gnu@prefix] {%
3715 \n@pow{10}{((\bp@mag)/20)}*cos((\bp@ph)/(\bp@ph@scale)),
3716 \n@pow{10}{((\bp@mag)/20)}*sin((\bp@ph)/(\bp@ph@scale))
3717 };
3718 \fi
3719 }
3720 % \end{macrocode}
3721 %\end{macro}
3722 %\begin{macro}{NyquistPlot}
3723 % An environment to host |\addNyquist...| macros that pass parametric functions to |\addplot|. Uses the defaults specified in |bp@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}{2024/01/11}{Defined using the `NewDocumentEnvironment' command from the `xparse' package and added a hook to handle active characters}\changes{v1.1.7}{2024/02/06}{Use auto-generated list of active characters instead of manually entering them.}
3724 % \begin{macrocode}
3725 \AtBeginDocument{%
3726 \if@babel
3727 \AddToHook{env/NyquistPlot/begin}{%
3728 \expandafter\shorthandoff\expandafter{\bp@short@list}
3729 }
3730 \AddToHook{env/NyquistPlot/end}{%
3731 \expandafter\shorthandon\expandafter{\bp@short@list}
3732 }
3733 \fi
3734 }
3735 \NewDocumentEnvironment{NyquistPlot}{ O{} G{} G{} +b }{
3736 \pgfutil@ifempty{#2}{%
3737 \pgfkeys{/bodeplot/env/.cd, reset}
3738 \pgfkeys{/bodeplot/env/.cd, #1}
3739 \pgfkeysgetvalue{/bodeplot/env/@tikz}{\bp@tikz}
3740 \pgfkeysgetvalue{/bodeplot/env/@prefix}{\bp@user@prefix}
3741 }{%
3742 \bp@parse@env@opt{#1}
3743 \edef\bp@domain@start{#2}%
3744 \edef\bp@domain@end{#3}%
3745 }
3746 \edef\bp@cmd{\noexpand\begin{tikzpicture}
3747 [\unexpanded\expandafter{\bp@tikz}]}\bp@cmd
3748 \edef\bp@cmd{\noexpand\begin{axis}[
3749 bp@style,
3750 height=5cm,
3751 domain=\bp@domain@start:\bp@domain@end,
3752 xlabel={$\Re$},
3753 ylabel={$\Im$},
3754 \unexpanded\expandafter{\bp@axes}%
3755 ]}\bp@cmd
3756 \addplot [only marks,mark=+,thick,red] (-1 , 0);
3757 #4
3758 \end{axis}
3759 \end{tikzpicture}
3760 }{}
3761 % \end{macrocode}
3762 %\end{macro}
3763 % \subsubsection{Internal macros\label{sec:NInternal}}
3764 % \begin{macro}{\bp@parse@N@opt}
3765 % Parses options supplied to the main Nyquist and Nichols macros. A |for| loop over tuples of the form |\obj/\opt|, processed using nested if-else statements does the job. If the input |\obj| is |plot|, |axes|, |scale|, or |tikz| then the corresponding |\opt| are passed, unexpanded, to the |\addplot| macro, the |axis| environment, the scaling option, and the |tikzpicture| environment, respectively. \changes{v1.0.3}{2021/11/03}{Added commands and tikz options}\changes{v2.1.1}{2025/10/04}{Added a new option |prefix| to enable per-plot custom file names for gnuplot tables}
3766 % \begin{macrocode}
3767 \newcommand{\bp@parse@N@opt}[1]{
3768 \gdef\bp@axes{}
3769 \gdef\bp@plot{}
3770 \gdef\bp@commands{}
3771 \gdef\bp@tikz{}
3772 \gdef\bp@user@prefix{}
3773 \gdef\bp@scale{linear}
3774 \foreach \obj/\opt in {#1} {
3775 \ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{axes}=0
3776 \xdef\bp@axes{\unexpanded\expandafter{\opt}}
3777 \else
3778 \ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{plot}=0
3779 \xdef\bp@plot{\unexpanded\expandafter{\opt}}
3780 \else
3781 \ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{commands}=0
3782 \xdef\bp@commands{\unexpanded\expandafter{\opt}}
3783 \else
3784 \ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{tikz}=0
3785 \xdef\bp@tikz{\unexpanded\expandafter{\opt}}
3786 \else
3787 \ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{scale}=0
3788 \xdef\bp@scale{\unexpanded\expandafter{\opt}}
3789 \else
3790 \ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{prefix}=0
3791 \xdef\bp@user@prefix{\unexpanded\expandafter{\opt}}
3792 \else
3793 \xdef\bp@user@prefix{}
3794 \xdef\bp@plot{\unexpanded\expandafter{\bp@plot},
3795 \unexpanded\expandafter{\obj}}
3796 \fi
3797 \fi
3798 \fi
3799 \fi
3800 \fi
3801 \fi
3802 }
3803 }
3804 % \end{macrocode}
3805 % \end{macro}
3806 % \subsection{Nichols charts}
3807 % \begin{macro}{\NicholsZPK}
3808 % \changes{v1.0.3}{2021/11/03}{Added commands and tikz options}\changes{v1.1.5}{2024/01/11}{Added code to handle active characters}\changes{v1.1.7}{2024/02/06}{Use auto-generated list of shorthands instead of manually specifying them}\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}
3809 % \begin{macrocode}
3810 \NewDocumentCommand{\NicholsZPK}{ O{} m G{} G{} }{%
3811 \pgfutil@ifempty{#3}{%
3812 \pgfkeys{/bodeplot/nichols/.cd, reset}
3813 \pgfkeys{/bodeplot/nichols/.cd, #1}
3814 \pgfkeysgetvalue{/bodeplot/nichols/@axes}{\bp@axes}
3815 \pgfkeysgetvalue{/bodeplot/nichols/@commands}{\bp@commands}
3816 \pgfkeysgetvalue{/bodeplot/nichols/@tikz}{\bp@tikz}
3817 \pgfkeysgetvalue{/bodeplot/nichols/@prefix}{\bp@user@prefix}
3818 \bp@zpk@new@to@legacy{#2}
3819 }{%
3820 \bp@parse@N@opt{#1}
3821 \edef\bp@legacy{#2}
3822 \edef\bp@domain@start{#3}
3823 \edef\bp@domain@end{#4}
3824 }%
3825 \gdef\bp@mag{}\gdef\bp@ph{}%
3826 \edef\bp@cmd{\noexpand\begin{tikzpicture}
3827 [\unexpanded\expandafter{\bp@tikz}]}\bp@cmd
3828 \bp@ZPK@plot{\bp@mag}{\bp@ph}{}{\bp@legacy}%
3829 \edef\bp@cmd{\noexpand\begin{axis}[
3830 bp@ph@x@label,
3831 bp@style,
3832 domain=\bp@domain@start*\bp@freq@scale:\bp@domain@end*\bp@freq@scale,
3833 height=5cm,
3834 ylabel={Gain (dB)},
3835 samples=500,
3836 \unexpanded\expandafter{\bp@axes}
3837 ]}
3838 \bp@cmd
3839 \edef\bp@cmd{\noexpand\addplot
3840 [variable=t, thick, trig format plots=rad,
3841 \unexpanded\expandafter{\bp@plot}]}
3842 \if@pgfarg
3843 \bp@cmd ( {\bp@ph} , {\bp@mag} );
3844 \bp@commands
3845 \else
3846 \stepcounter{bp@gnuplot@id}
3847 \bp@cmd gnuplot [raw gnuplot, bp@gnu@prefix]
3848 { set table $meta;
3849 set logscale x 10;
3850 set dummy t;
3851 set samples \pgfkeysvalueof{/pgfplots/samples};
3852 set trange [\bp@domain@start*\bp@freq@scale:\bp@domain@end*\bp@freq@scale];
3853 plot '+' using (\bp@mag) : ((\bp@ph)/(\bp@ph@scale));
3854 unset logscale x;
3855 set table "\bp@prefix\arabic{bp@gnuplot@id}.table";
3856 plot "$meta" using ($2*\bp@ph@scale):($1);
3857 };
3858 \bp@commands
3859 \fi
3860 \end{axis}
3861 \end{tikzpicture}
3862 }
3863 \AtBeginDocument{%
3864 \if@babel
3865 \let\Orig@NicholsZPK\NicholsZPK
3866 \renewcommand{\NicholsZPK}{%
3867 \expandafter\shorthandoff\expandafter{\bp@short@list}
3868 \NicholsZPK@Shorthandoff
3869 }
3870 \NewDocumentCommand{\NicholsZPK@Shorthandoff}{ O{} m G{} G{} }{%
3871 \Orig@NicholsZPK[#1]{#2}{#3}{#4}
3872 \expandafter\shorthandon\expandafter{\bp@short@list}
3873 }
3874 \fi
3875 }
3876 % \end{macrocode}
3877 % \end{macro}
3878 % \begin{macro}{\NicholsTF}
3879 % \changes{v1.0.3}{2021/11/03}{Added commands and tikz options}\changes{v1.1.5}{2024/01/11}{Added code to handle active characters}\changes{v1.1.7}{2024/02/06}{Use auto-generated list of shorthands instead of manually specifying them}\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}\changes{v3.1}{2026/05/19}{To avoid wrapping in pgf mode, use python to convert tf to zpk if available. If python is not available, fall back to the legacy implementation.}\changes{v3.1}{2026/05/19}{In pgf mode, legacy 4-argument calls now forward frequency limits via domain options when dispatching to \cs{NicholsZPK}.}
3880 % \begin{macrocode}
3881 \NewDocumentCommand{\NicholsTF}{ O{} m G{} G{} }{%
3882 \if@pgfarg
3883 \bp@tf@to@zpk{#2}{\bp@tmp@zpk}{\bp@tmp@status}
3884 \ifnum\pdf@strcmp{\bp@tmp@status}{true}=0
3885 \pgfutil@ifempty{#3}{%
3886 \NicholsZPK[#1]{\bp@tmp@zpk}%
3887 }{%
3888 \NicholsZPK[domain=#3:#4,#1]{\bp@tmp@zpk}%
3889 }%
3890 \def\bp@fallback{false}
3891 \else
3892 \def\bp@fallback{true}
3893 \fi
3894 \else
3895 \def\bp@fallback{true}
3896 \fi
3897 \ifnum\pdf@strcmp{\bp@fallback}{true}=0
3898 \pgfutil@ifempty{#3}{%
3899 \pgfkeys{/bodeplot/nichols/.cd, reset}
3900 \pgfkeys{/bodeplot/nichols/.cd, #1}
3901 \pgfkeysgetvalue{/bodeplot/nichols/@axes}{\bp@axes}
3902 \pgfkeysgetvalue{/bodeplot/nichols/@commands}{\bp@commands}
3903 \pgfkeysgetvalue{/bodeplot/nichols/@tikz}{\bp@tikz}
3904 \pgfkeysgetvalue{/bodeplot/nichols/@prefix}{\bp@user@prefix}
3905 \bp@tf@new@to@legacy{#2}
3906 }{%
3907 \bp@parse@N@opt{#1}
3908 \edef\bp@legacy{#2}
3909 \edef\bp@domain@start{#3}
3910 \edef\bp@domain@end{#4}
3911 }%
3912 \gdef\bp@mag{}\gdef\bp@ph{}%
3913 \edef\bp@cmd{\noexpand\begin{tikzpicture}
3914 [\unexpanded\expandafter{\bp@tikz}]}\bp@cmd
3915 \bp@TF@plot{\bp@mag}{\bp@ph}{\bp@legacy}%
3916 \edef\bp@cmd{\noexpand\begin{axis}[
3917 bp@ph@x@label,
3918 bp@style,
3919 domain=\bp@domain@start*\bp@freq@scale:\bp@domain@end*\bp@freq@scale,
3920 height=5cm,
3921 ylabel={Gain (dB)},
3922 samples=500,
3923 \unexpanded\expandafter{\bp@axes}
3924 ]}
3925 \bp@cmd
3926 \edef\bp@cmd{\noexpand\addplot
3927 [variable=t, thick, trig format plots=rad,
3928 \unexpanded\expandafter{\bp@plot}]}%
3929 \if@pgfarg
3930 \bp@cmd ( {\n@mod{\bp@ph}{2*pi*\bp@ph@scale}} , {\bp@mag} );
3931 \bp@commands
3932 \else
3933 \stepcounter{bp@gnuplot@id}
3934 \bp@cmd gnuplot [raw gnuplot, bp@gnu@prefix]
3935 { set table $meta1;
3936 set logscale x 10;
3937 set dummy t;
3938 set samples \pgfkeysvalueof{/pgfplots/samples};
3939 set trange [\bp@domain@start*\bp@freq@scale:\bp@domain@end*\bp@freq@scale];
3940 plot '+' using (\bp@mag) : ((\bp@ph)/(\bp@ph@scale));
3941 unset logscale x;
3942 set table $meta2;
3943 plot "$meta1" using ($1):($2) smooth unwrap;
3944 set table "\bp@prefix\arabic{bp@gnuplot@id}.table";
3945 plot "$meta2" using ($2*\bp@ph@scale):($1);
3946 };
3947 \bp@commands
3948 \fi
3949 \end{axis}
3950 \end{tikzpicture}
3951 \fi
3952 }
3953 % \end{macrocode}
3954 % The following code handles active characters to avoid conflicts with `babel.' \changes{v1.1.5}{2024/01/11}{Added code to handle active characters}\changes{v1.1.7}{2024/02/06}{Use auto-generated list of shorthands instead of manually specifying them}\changes{v3.0.4}{2026/05/14}{Fixed babel wrapper command argument specification for grabbing arguments}
3955 % \begin{macrocode}
3956 \AtBeginDocument{
3957 \if@babel
3958 \let\Orig@NicholsTF\NicholsTF
3959 \renewcommand{\NicholsTF}{%
3960 \expandafter\shorthandoff\expandafter{\bp@short@list}
3961 \NicholsTF@Shorthandoff
3962 }
3963 \NewDocumentCommand{\NicholsTF@Shorthandoff}{ O{} m G{} G{} }{%
3964 \Orig@NicholsTF[#1]{#2}{#3}{#4}
3965 \expandafter\shorthandon\expandafter{\bp@short@list}
3966 }
3967 \AddToHook{env/NicholsChart/begin}{%
3968 \expandafter\shorthandoff\expandafter{\bp@short@list}
3969 }
3970 \AddToHook{env/NicholsChart/end}{%
3971 \expandafter\shorthandon\expandafter{\bp@short@list}
3972 }
3973 \fi
3974 }
3975 % \end{macrocode}
3976 % \end{macro}
3977 % \begin{macro}{NicholsChart}
3978 % \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}{2024/01/11}{Defined using the `NewDocumentEnvironment' command from the `xparse' package and added a hook to handle active characters}\changes{v1.1.7}{2024/02/06}{Use auto-generated list of active characters instead of manually entering them.}
3979 % \begin{macrocode}
3980 \NewDocumentEnvironment{NicholsChart}{ O{} G{} G{} +b }{
3981 \pgfutil@ifempty{#2}{%
3982 \pgfkeys{/bodeplot/env/.cd, reset}
3983 \pgfkeys{/bodeplot/env/.cd, #1}
3984 \pgfkeysgetvalue{/bodeplot/env/@tikz}{\bp@tikz}
3985 \pgfkeysgetvalue{/bodeplot/env/@prefix}{\bp@user@prefix}
3986 }{%
3987 \bp@parse@env@opt{#1}
3988 \edef\bp@domain@start{#2}
3989 \edef\bp@domain@end{#3}
3990 }
3991 \edef\bp@cmd{\noexpand\begin{tikzpicture}
3992 [\unexpanded\expandafter{\bp@tikz}]}\bp@cmd
3993 \edef\bp@cmd{\noexpand\begin{axis}[
3994 bp@ph@x@label,
3995 bp@style,
3996 domain=\bp@domain@start:\bp@domain@end,
3997 height=5cm,
3998 ylabel={Gain (dB)},
3999 \unexpanded\expandafter{\bp@axes}%
4000 ]}\bp@cmd
4001 #4
4002 \end{axis}
4003 \end{tikzpicture}
4004 }{}
4005 % \end{macrocode}
4006 % \end{macro}
4007 % \begin{macro}{\addNicholsZPKChart}
4008 % Generates Nichols chart for ZPK system with dual interface support. Plots phase vs magnitude.\changes{v1.1.3}{2022/11/02}{Changed implementation to respect user-supplied domain}\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}\changes{v3.1}{2026/05/19}{Pre-expand \marg{zpk-spec} via |edef| before |bp@contains@equal| routing so that a macro-valued spec is accepted}\changes{v3.1}{2026/05/19}{Use \cs{expandafter} when calling \cs{bp@contains@equal} so the pre-expanded spec is tested as character tokens.}
4009 % \begin{macrocode}
4010 \NewDocumentCommand{\addNicholsZPKChart}{ O{} m }{%
4011 \edef\bp@spec@arg{#2}%
4012 \expandafter\bp@contains@equal\expandafter{\bp@spec@arg}{%
4013 \bp@zpk@new@to@legacy{\bp@spec@arg}}{\edef\bp@legacy{\bp@spec@arg}}%
4014 \gdef\bp@mag{}\gdef\bp@ph{}%
4015 \bp@ZPK@plot{\bp@mag}{\bp@ph}{}{\bp@legacy}%
4016 \if@pgfarg
4017 \edef\bp@cmd{\noexpand\addplot
4018 [domain=\bp@freq@scale*\pgfkeysvalueof{/pgfplots/domain}*\bp@freq@scale,
4019 variable=t, thick, trig format plots=rad, #1]}%
4020 \bp@cmd ( {\bp@ph} , {\bp@mag} );
4021 \else
4022 \stepcounter{bp@gnuplot@id}%
4023 \addplot [thick, #1] gnuplot [raw gnuplot, bp@gnu@prefix] {%
4024 set table $meta;
4025 set logscale x 10;
4026 set dummy t;
4027 set samples \pgfkeysvalueof{/pgfplots/samples};
4028 set trange [\bp@freq@scale*\pgfkeysvalueof{/pgfplots/domain}*\bp@freq@scale];
4029 plot '+' using (\bp@mag) : ((\bp@ph)/(\bp@ph@scale));
4030 unset logscale x;
4031 set table "\bp@prefix\arabic{bp@gnuplot@id}.table";
4032 plot "$meta" using ($2*\bp@ph@scale):($1);
4033 };
4034 \fi
4035 }
4036 % \end{macrocode}
4037 % \end{macro}
4038 % \begin{macro}{\addNicholsTFChart}
4039 % Generates Nichols chart for TF system with dual interface support. Plots phase vs magnitude with phase unwrapping.\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}\changes{v1.1.4}{2023/10/12}{Changed phase wrapping in pgf mode}\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}\changes{v3.1}{2026/05/19}{Pre-expand \marg{tf-spec} via |edef| before |bp@contains@equal| routing so that a macro-valued spec is accepted}\changes{v3.1}{2026/05/19}{Use \cs{expandafter} when calling \cs{bp@contains@equal} so the pre-expanded spec is tested as character tokens.}
4040 % \begin{macrocode}
4041 \NewDocumentCommand{\addNicholsTFChart}{ O{} m }{%
4042 \edef\bp@spec@arg{#2}%
4043 \expandafter\bp@contains@equal\expandafter{\bp@spec@arg}{%
4044 \bp@tf@new@to@legacy{\bp@spec@arg}}{\edef\bp@legacy{\bp@spec@arg}}%
4045 \gdef\bp@mag{}\gdef\bp@ph{}%
4046 \bp@TF@plot{\bp@mag}{\bp@ph}{\bp@legacy}%
4047 \if@pgfarg
4048 \edef\bp@cmd{\noexpand\addplot
4049 [domain=\bp@freq@scale*\pgfkeysvalueof{/pgfplots/domain}*\bp@freq@scale,
4050 variable=t, thick, trig format plots=rad, #1]}%
4051 \bp@cmd ( {\n@mod{\bp@ph}{2*pi*\bp@ph@scale}} , {\bp@mag} );
4052 \else
4053 \stepcounter{bp@gnuplot@id}%
4054 \addplot [thick, #1] gnuplot [raw gnuplot, bp@gnu@prefix] {%
4055 set table $meta1;
4056 set logscale x 10;
4057 set dummy t;
4058 set samples \pgfkeysvalueof{/pgfplots/samples};
4059 set trange [\bp@freq@scale*\pgfkeysvalueof{/pgfplots/domain}*\bp@freq@scale];
4060 plot '+' using (\bp@mag) : ((\bp@ph)/(\bp@ph@scale));
4061 unset logscale x;
4062 set table $meta2;
4063 plot "$meta1" using ($1):($2) smooth unwrap;
4064 set table "\bp@prefix\arabic{bp@gnuplot@id}.table";
4065 plot "$meta2" using ($2*\bp@ph@scale):($1);
4066 };
4067 \fi
4068 }
4069 % \end{macrocode}
4070 % \end{macro}
4071 % \subsection{Pole-zero maps}
4072 % \subsubsection{User macros}
4073 % \begin{macro}{\PoleZeroMapZPK}
4074 % Creates a pole-zero map similar to MATLAB's |pzmap| function. Poles are plotted as 'x' markers and zeros as 'o' markers on the complex s-plane. The gain parameter is ignored since it does not affect pole-zero locations, and delay is also ignored since it does not add poles or zeros. \changes{v2.0}{2025/09/26}{Added pole-zero map functionality}\changes{v3.0}{2025/10/21}{Added a pgfkeys-based simplified user interface}\changes{v3.1}{2026/05/19}{Pre-expand \marg{zpk-spec} via |edef| before |bp@contains@equal| routing so that a macro-valued spec is accepted}\changes{v3.1}{2026/05/19}{Use \cs{expandafter} when calling \cs{bp@contains@equal} so the pre-expanded spec is tested as character tokens.}
4075 % \begin{macrocode}
4076 \NewDocumentCommand{\PoleZeroMapZPK}{ O{} m }{%
4077 \edef\bp@spec@arg{#2}%
4078 \expandafter\bp@contains@equal\expandafter{\bp@spec@arg}{%
4079 \pgfkeys{/bodeplot/pzmap/.cd, reset}
4080 \pgfkeys{/bodeplot/pzmap/.cd, #1}
4081 \pgfkeysgetvalue{/bodeplot/pzmap/@axes}{\bp@axes}
4082 \pgfkeysgetvalue{/bodeplot/pzmap/@plot}{\bp@plot}
4083 \pgfkeysgetvalue{/bodeplot/pzmap/@commands}{\bp@commands}
4084 \pgfkeysgetvalue{/bodeplot/pzmap/@tikz}{\bp@tikz}
4085 \pgfkeysgetvalue{/bodeplot/pzmap/@prefix}{\bp@user@prefix}
4086 \pgfkeysgetvalue{/bodeplot/pzmap/@scale}{\bp@scale}
4087 \bp@zpk@new@to@legacy{\bp@spec@arg}
4088 }{%
4089 \bp@parse@N@opt{#1}
4090 \edef\bp@legacy{\bp@spec@arg}
4091 }%
4092 \ifnum\pdf@strcmp{\bp@scale}{log}=0
4093 \bp@min@real@ZPK{\bp@legacy}
4094 \bp@min@im@ZPK{\bp@legacy}
4095 \pgfkeys{/pgf/fpu=true}
4096 \ifx\bp@has@positive@values\@bp@min@false
4097 \xdef\bp@PZZPK@ticksXPos{0}
4098 \else
4099 \pgfmathparse{max(\bp@max@re@pos@pow@10 - \bp@min@re@pow@10 + 1, 1)}
4100 \pgfmathfloattoint{\pgfmathresult}
4101 \xdef\bp@PZZPK@ticksXPos{\pgfmathresult}
4102 \fi
4103 \ifx\bp@has@negative@values\@bp@min@false
4104 \xdef\bp@PZZPK@ticksXNeg{0}
4105 \else
4106 \pgfmathparse{max(\bp@max@re@neg@pow@10 - \bp@min@re@pow@10 + 1, 1)}
4107 \pgfmathfloattoint{\pgfmathresult}
4108 \xdef\bp@PZZPK@ticksXNeg{\pgfmathresult}
4109 \fi
4110 \pgfkeys{/pgf/fpu=false}
4111 \def\PoleZeroMapZPK@formatXTick##1{%
4112 \pgfmathtruncatemacro{\PoleZeroMapZPK@tick}{##1}%
4113 \ifnum\PoleZeroMapZPK@tick=0
4114 $0$
4115 \else
4116 \pgfmathtruncatemacro{\PoleZeroMapZPK@exp}
4117 {\bp@min@re@pow@10 + abs(\PoleZeroMapZPK@tick) - 1}%
4118 \ifnum\PoleZeroMapZPK@tick>0
4119 $10^{\PoleZeroMapZPK@exp}$%
4120 \else
4121 $-10^{\PoleZeroMapZPK@exp}$%
4122 \fi
4123 \fi
4124 }
4125 \def\PoleZeroMapZPK@formatYTick##1{%
4126 \pgfmathtruncatemacro{\PoleZeroMapZPK@tick}{##1}%
4127 \ifnum\PoleZeroMapZPK@tick=0
4128 $0$
4129 \else
4130 \pgfmathtruncatemacro{\PoleZeroMapZPK@exp}
4131 {\bp@min@im@pow@10 + abs(\PoleZeroMapZPK@tick) - 1}%
4132 \ifnum\PoleZeroMapZPK@tick>0
4133 $10^{\PoleZeroMapZPK@exp}$%
4134 \else
4135 $-10^{\PoleZeroMapZPK@exp}$%
4136 \fi
4137 \fi
4138 }
4139 \def\PoleZeroMapZPK@xticklabel{\PoleZeroMapZPK@formatXTick{\tick}}
4140 \def\PoleZeroMapZPK@yticklabel{\PoleZeroMapZPK@formatYTick{\tick}}
4141 \fi
4142 \edef\bp@cmd{\noexpand\begin{tikzpicture}
4143 [\unexpanded\expandafter{\bp@tikz}]}
4144 \bp@cmd
4145 \ifnum\pdf@strcmp{\bp@scale}{log}=0
4146 \edef\bp@cmd{\noexpand\begin{axis}[
4147 xlabel={$\Re$},
4148 ylabel={$\Im$},
4149 axis lines=center,
4150 grid=major,
4151 height=6cm,
4152 enlarge x limits=0.2,
4153 enlarge y limits=0.2,
4154 xtick distance=1,
4155 ytick distance=1,
4156 xticklabel=\noexpand\PoleZeroMapZPK@xticklabel,
4157 yticklabel=\noexpand\PoleZeroMapZPK@yticklabel,
4158 x filter/.expression={abs(x) < \bp@min@re@threshold@result ?
4159 0 : (x >= 0 ? (log10(max(min(x, 1e100), 1e-100)) - \bp@min@re@pow@10 + 1) :
4160 (-log10(max(min(-x, 1e100), 1e-100)) + \bp@min@re@pow@10 - 1))},
4161 y filter/.expression={abs(y) < \bp@min@im@threshold@result ?
4162 0 : (y >= 0 ? (log10(max(min(y, 1e100), 1e-100)) - \bp@min@im@pow@10 + 1) :
4163 (-log10(max(min(-y, 1e100), 1e-100)) + \bp@min@im@pow@10 - 1))},
4164 \unexpanded\expandafter{\bp@axes}
4165 ]}
4166 \else
4167 \edef\bp@cmd{\noexpand\begin{axis}[
4168 xlabel={$\Re$},
4169 ylabel={$\Im$},
4170 axis lines=center,
4171 grid=major,
4172 height=6cm,
4173 enlarge x limits=0.2,
4174 enlarge y limits=0.2,
4175 \unexpanded\expandafter{\bp@axes}
4176 ]}
4177 \fi
4178 \bp@cmd
4179 \foreach \feature/\values in \bp@legacy {
4180 \ifnum\pdf@strcmp{\feature}{z}=0
4181 \foreach \z in \values {
4182 \foreach \y [count=\zcnt] in \z {
4183 \ifnum\zcnt=1
4184 \xdef\bp@zre{\y}
4185 \fi
4186 \ifnum\zcnt=2
4187 \xdef\bp@zim{\y}
4188 \fi
4189 \xdef\bp@Last@Loop@z{\zcnt}
4190 }
4191 \ifnum\bp@Last@Loop@z=1
4192 \xdef\bp@zim{0}
4193 \fi
4194 \edef\bp@cmd{\noexpand\addplot
4195 [only marks, mark=o, mark size=3pt, thick, blue,
4196 \unexpanded\expandafter{\bp@plot}]}
4197 \bp@cmd coordinates {(\bp@zre,\bp@zim)};
4198 }
4199 \fi
4200 \ifnum\pdf@strcmp{\feature}{p}=0
4201 \foreach \p in \values {
4202 \foreach \y [count=\pcnt] in \p {
4203 \ifnum\pcnt=1
4204 \xdef\bp@pre{\y}
4205 \fi
4206 \ifnum\pcnt=2
4207 \xdef\bp@pim{\y}
4208 \fi
4209 \xdef\bp@Last@Loop@p{\pcnt}
4210 }
4211 \ifnum\bp@Last@Loop@p=1
4212 \xdef\bp@pim{0}
4213 \fi
4214 \edef\bp@cmd{\noexpand\addplot
4215 [only marks, mark=x, mark size=3pt, thick, red,
4216 \unexpanded\expandafter{\bp@plot}]}
4217 \bp@cmd coordinates {(\bp@pre,\bp@pim)};
4218 }
4219 \fi
4220 }
4221 \bp@commands
4222 \end{axis}
4223 \end{tikzpicture}
4224 }
4225 % \end{macrocode}
4226 % The following code handles active characters to avoid conflicts with `babel.'
4227 % \begin{macrocode}
4228 \AtBeginDocument{%
4229 \if@babel
4230 \let\Orig@PoleZeroMapZPK\PoleZeroMapZPK
4231 \renewcommand{\PoleZeroMapZPK}{%
4232 \expandafter\shorthandoff\expandafter{\bp@short@list}
4233 \PoleZeroMapZPK@Shorthandoff
4234 }
4235 \newcommand{\PoleZeroMapZPK@Shorthandoff}[2][]{%
4236 \Orig@PoleZeroMapZPK[#1]{#2}
4237 \expandafter\shorthandon\expandafter{\bp@short@list}
4238 }
4239 \fi
4240 }
4241 % \end{macrocode}
4242 % \end{macro}
4243 % \begin{macro}{\PoleZeroMapTF}
4244 % Similar to |\PoleZeroMapZPK| but for the system specified in the TF format. This macro converts the TF specification to ZPK format internally using Python via |--shell-escape| and then calls |\PoleZeroMapZPK| to generate the plot. If Python with the |scipy| and |numpy| libraries is not available on the shell, the package returns an error message. \changes{v3.1}{2026/05/19}{Added support for pole-zero maps with TF specifications using Python.}
4245 % \begin{macrocode}
4246 \NewDocumentCommand{\PoleZeroMapTF}{ O{} m }{%
4247 \bp@tf@to@zpk{#2}{\bp@tmp@zpk}{\bp@tmp@status}
4248 \ifnum\pdf@strcmp{\bp@tmp@status}{true}=0
4249 \PoleZeroMapZPK[#1]{\bp@tmp@zpk}
4250 \else
4251 \PackageError{bodeplot}{Python with scipy and numpy is required to convert TF to ZPK for pole-zero map. Please ensure Python is installed and accessible via --shell-escape.}{}
4252 \fi
4253 }
4254 % \end{macrocode}
4255 % The following code handles active characters to avoid conflicts with `babel.'
4256 % \begin{macrocode}
4257 \AtBeginDocument{%
4258 \if@babel
4259 \let\Orig@PoleZeroMapTF\PoleZeroMapTF
4260 \renewcommand{\PoleZeroMapTF}{%
4261 \expandafter\shorthandoff\expandafter{\bp@short@list}
4262 \PoleZeroMapTF@Shorthandoff
4263 }
4264 \newcommand{\PoleZeroMapTF@Shorthandoff}[2][]{%
4265 \Orig@PoleZeroMapTF[#1]{#2}
4266 \expandafter\shorthandon\expandafter{\bp@short@list}
4267 }
4268 \fi
4269 }
4270 % \end{macrocode}
4271 % \end{macro}
4272 % \subsubsection{Internal macros}
4273 % \begin{macro}{\bp@min@real@ZPK}
4274 % Computes the minimum nonzero absolute value of real parts from all poles and zeros in ZPK format. This is used for automatically setting the threshold in logarithmic pole-zero maps. The result is stored in |\bp@min@re@threshold@result| and the corresponding power of 10 is stored in |\bp@min@re@pow@10|.
4275 % \begin{macrocode}
4276 \newcommand{\bp@min@real@ZPK}[1]{
4277 \gdef\bp@min@re@threshold@result{1000}
4278 \def\@bp@min@false{false}
4279 \gdef\bp@min@threshold@found{false}
4280 \global\let\bp@min@thresh@float\relax
4281 \pgfkeys{/pgf/fpu=true}
4282 \pgfmathparse{0}
4283 \global\let\bp@max@re@float=\pgfmathresult
4284 \pgfmathparse{0}
4285 \global\let\bp@max@re@pos@float=\pgfmathresult
4286 \pgfmathparse{0}
4287 \global\let\bp@max@re@neg@float=\pgfmathresult
4288 \pgfkeys{/pgf/fpu=false}
4289 \gdef\bp@max@re@value{0}
4290 \gdef\bp@has@positive@values{false}
4291 \gdef\bp@has@negative@values{false}
4292 \foreach \feature/\values in {#1} {
4293 \ifnum\pdf@strcmp{\feature}{z}=0
4294 \foreach \z in \values {
4295 \foreach \y [count=\zcnt] in \z {
4296 \ifnum\zcnt=1
4297 \pgfkeys{/pgf/fpu=true}
4298 \pgfmathparse{abs(\y)}
4299 \let\abs@valuefloat=\pgfmathresult
4300 \pgfmathfloattofixed{\abs@valuefloat}
4301 \edef\abs@value{\pgfmathresult}
4302 \pgfkeys{/pgf/fpu=false}
4303 \ifnum\pdf@strcmp{\abs@value}{0}=0\else
4304 \ifnum\pdf@strcmp{\abs@value}{0.0}=0\else
4305 \pgfkeys{/pgf/fpu=true}
4306 \pgfmathparse{\y >= 0 ? 1 : 0}
4307 \pgfmathfloattoint{\pgfmathresult}
4308 \pgfkeys{/pgf/fpu=false}
4309 \ifnum\pgfmathresult=1
4310 \gdef\bp@has@positive@values{true}
4311 \pgfkeys{/pgf/fpu=true}
4312 \pgfmathparse{\abs@valuefloat > \bp@max@re@pos@float ? 1 : 0}
4313 \pgfmathfloattoint{\pgfmathresult}
4314 \pgfkeys{/pgf/fpu=false}
4315 \ifnum\pgfmathresult=1
4316 \global\let\bp@max@re@pos@float=\abs@valuefloat
4317 \fi
4318 \else
4319 \gdef\bp@has@negative@values{true}
4320 \pgfkeys{/pgf/fpu=true}
4321 \pgfmathparse{\abs@valuefloat > \bp@max@re@neg@float ? 1 : 0}
4322 \pgfmathfloattoint{\pgfmathresult}
4323 \pgfkeys{/pgf/fpu=false}
4324 \ifnum\pgfmathresult=1
4325 \global\let\bp@max@re@neg@float=\abs@valuefloat
4326 \fi
4327 \fi
4328 \pgfkeys{/pgf/fpu=true}
4329 \pgfmathparse{\abs@valuefloat > \bp@max@re@float ? 1 : 0}
4330 \pgfmathfloattoint{\pgfmathresult}
4331 \pgfkeys{/pgf/fpu=false}
4332 \ifnum\pgfmathresult=1
4333 \global\let\bp@max@re@float=\abs@valuefloat
4334 \xdef\bp@max@re@value{\abs@value}
4335 \fi
4336 \ifx\bp@min@threshold@found\@bp@min@false
4337 \xdef\bp@min@re@threshold@result{\abs@value}
4338 \global\let\bp@min@thresh@float=\abs@valuefloat
4339 \gdef\bp@min@threshold@found{true}
4340 \else
4341 \pgfkeys{/pgf/fpu=true}
4342 \pgfmathparse{\abs@valuefloat < \bp@min@thresh@float ? 1 : 0}
4343 \pgfmathfloattoint{\pgfmathresult}
4344 \pgfkeys{/pgf/fpu=false}
4345 \ifnum\pgfmathresult=1
4346 \xdef\bp@min@re@threshold@result{\abs@value}
4347 \global\let\bp@min@thresh@float=\abs@valuefloat
4348 \fi
4349 \fi
4350 \fi
4351 \fi
4352 \fi
4353 }
4354 }
4355 \fi
4356 \ifnum\pdf@strcmp{\feature}{p}=0
4357 \foreach \p in \values {
4358 \foreach \y [count=\pcnt] in \p {
4359 \ifnum\pcnt=1
4360 \pgfkeys{/pgf/fpu=true}
4361 \pgfmathparse{abs(\y)}
4362 \let\abs@valuefloat=\pgfmathresult
4363 \pgfmathfloattofixed{\abs@valuefloat}
4364 \edef\abs@value{\pgfmathresult}
4365 \pgfkeys{/pgf/fpu=false}
4366 \ifnum\pdf@strcmp{\abs@value}{0}=0\else
4367 \ifnum\pdf@strcmp{\abs@value}{0.0}=0\else
4368 \pgfkeys{/pgf/fpu=true}
4369 \pgfmathparse{\y >= 0 ? 1 : 0}
4370 \pgfmathfloattoint{\pgfmathresult}
4371 \pgfkeys{/pgf/fpu=false}
4372 \ifnum\pgfmathresult=1
4373 \gdef\bp@has@positive@values{true}
4374 \pgfkeys{/pgf/fpu=true}
4375 \pgfmathparse{\abs@valuefloat > \bp@max@re@pos@float ? 1 : 0}
4376 \pgfmathfloattoint{\pgfmathresult}
4377 \pgfkeys{/pgf/fpu=false}
4378 \ifnum\pgfmathresult=1
4379 \global\let\bp@max@re@pos@float=\abs@valuefloat
4380 \fi
4381 \else
4382 \gdef\bp@has@negative@values{true}
4383 \pgfkeys{/pgf/fpu=true}
4384 \pgfmathparse{\abs@valuefloat > \bp@max@re@neg@float ? 1 : 0}
4385 \pgfmathfloattoint{\pgfmathresult}
4386 \pgfkeys{/pgf/fpu=false}
4387 \ifnum\pgfmathresult=1
4388 \global\let\bp@max@re@neg@float=\abs@valuefloat
4389 \fi
4390 \fi
4391 \ifx\bp@min@threshold@found\@bp@min@false
4392 \xdef\bp@min@re@threshold@result{\abs@value}
4393 \global\let\bp@min@thresh@float=\abs@valuefloat
4394 \gdef\bp@min@threshold@found{true}
4395 \else
4396 \pgfkeys{/pgf/fpu=true}
4397 \pgfmathparse{\abs@valuefloat < \bp@min@thresh@float ? 1 : 0}
4398 \pgfmathfloattoint{\pgfmathresult}
4399 \pgfkeys{/pgf/fpu=false}
4400 \ifnum\pgfmathresult=1
4401 \xdef\bp@min@re@threshold@result{\abs@value}
4402 \global\let\bp@min@thresh@float=\abs@valuefloat
4403 \fi
4404 \fi
4405 \fi
4406 \fi
4407 \fi
4408 }
4409 }
4410 \fi
4411 }
4412 \ifx\bp@min@threshold@found\@bp@min@false
4413 \gdef\bp@min@re@threshold@result{0.01}
4414 \fi
4415 \xdef\bp@min@threshold@result{\bp@min@re@threshold@result}
4416 \pgfkeys{/pgf/fpu=true}
4417 \pgfmathparse{log10(\bp@min@re@threshold@result)}
4418 \let\log@result=\pgfmathresult
4419 \pgfmathparse{\log@result + 1e-5}
4420 \let\log@adjusted=\pgfmathresult
4421 \pgfmathparse{floor(\log@adjusted)}
4422 \pgfmathfloattofixed{\pgfmathresult}
4423 \xdef\bp@min@re@pow@10{\pgfmathresult}
4424 \xdef\bp@min@pow@10{\bp@min@re@pow@10}
4425 \ifx\bp@has@positive@values\@bp@min@false
4426 \xdef\bp@max@re@pos@pow@10{\bp@min@re@pow@10}
4427 \else
4428 \pgfmathparse{log10(max(\bp@max@re@pos@float,1e-100))}
4429 \let\log@bp@max@re@pos=\pgfmathresult
4430 \pgfmathparse{\log@bp@max@re@pos + 1e-5}
4431 \let\log@bp@max@re@pos@adjusted=\pgfmathresult
4432 \pgfmathparse{ceil(\log@bp@max@re@pos@adjusted)}
4433 \pgfmathfloattoint{\pgfmathresult}
4434 \xdef\bp@max@re@pos@pow@10{\pgfmathresult}
4435 \fi
4436 \ifx\bp@has@negative@values\@bp@min@false
4437 \xdef\bp@max@re@neg@pow@10{\bp@min@re@pow@10}
4438 \else
4439 \pgfmathparse{log10(max(\bp@max@re@neg@float,1e-100))}
4440 \let\log@bp@max@re@neg=\pgfmathresult
4441 \pgfmathparse{\log@bp@max@re@neg + 1e-5}
4442 \let\log@bp@max@re@neg@adjusted=\pgfmathresult
4443 \pgfmathparse{ceil(\log@bp@max@re@neg@adjusted)}
4444 \pgfmathfloattoint{\pgfmathresult}
4445 \xdef\bp@max@re@neg@pow@10{\pgfmathresult}
4446 \fi
4447 \pgfmathparse{max(\bp@max@re@pos@float > 0 ?
4448 \bp@max@re@pos@float : 0, \bp@max@re@neg@float > 0 ? \bp@max@re@neg@float : 0)}
4449 \let\bp@max@re@valuefloat=\pgfmathresult
4450 \pgfmathparse{\bp@max@re@valuefloat > 0 ?
4451 \bp@max@re@valuefloat : \bp@min@re@threshold@result}
4452 \let\bp@max@re@valuefloat=\pgfmathresult
4453 \pgfmathparse{log10(max(\bp@max@re@valuefloat,1e-100))}
4454 \let\log@bp@max@re=\pgfmathresult
4455 \pgfmathparse{\log@bp@max@re + 1e-5}
4456 \let\log@bp@max@re@adjusted=\pgfmathresult
4457 \pgfmathparse{ceil(\log@bp@max@re@adjusted)}
4458 \pgfmathfloattoint{\pgfmathresult}
4459 \xdef\bp@max@re@pow@10{\pgfmathresult}
4460 \pgfkeys{/pgf/fpu=false}
4461 }
4462 % \end{macrocode}
4463 % \end{macro}
4464 % \begin{macro}{\bp@min@im@ZPK}
4465 % Computes the minimum nonzero absolute value of imaginary parts from all poles and zeros in ZPK format. This is used for automatically setting thresholds in logarithmic pole-zero maps for imaginary axis scaling. The result is stored in |\bp@min@im@threshold@result| and the corresponding power of 10 is stored in |\bp@min@im@pow@10|.
4466 % \begin{macrocode}
4467 \newcommand{\bp@min@im@ZPK}[1]{
4468 \gdef\bp@min@im@threshold@result{1000}
4469 \def\@bp@min@false{false}
4470 \gdef\bp@min@im@threshold@found{false}
4471 \global\let\bp@min@im@thresh@float\relax
4472 \pgfkeys{/pgf/fpu=true}
4473 \pgfmathparse{0}
4474 \global\let\bp@max@im@float=\pgfmathresult
4475 \pgfkeys{/pgf/fpu=false}
4476 \gdef\bp@max@im@value{0}
4477 \foreach \feature/\values in {#1} {
4478 \ifnum\pdf@strcmp{\feature}{z}=0
4479 \foreach \z in \values {
4480 \foreach \y [count=\zcnt] in \z {
4481 \ifnum\zcnt=2
4482 \pgfkeys{/pgf/fpu=true}
4483 \pgfmathparse{abs(\y)}
4484 \let\abs@valuefloat=\pgfmathresult
4485 \pgfmathfloattofixed{\abs@valuefloat}
4486 \edef\abs@value{\pgfmathresult}
4487 \pgfkeys{/pgf/fpu=false}
4488 \ifnum\pdf@strcmp{\abs@value}{0}=0\else
4489 \ifnum\pdf@strcmp{\abs@value}{0.0}=0\else
4490 \pgfkeys{/pgf/fpu=true}
4491 \pgfmathparse{\abs@valuefloat > \bp@max@im@float ? 1 : 0}
4492 \pgfmathfloattoint{\pgfmathresult}
4493 \pgfkeys{/pgf/fpu=false}
4494 \ifnum\pgfmathresult=1
4495 \global\let\bp@max@im@float=\abs@valuefloat
4496 \xdef\bp@max@im@value{\abs@value}
4497 \fi
4498 \ifx\bp@min@im@threshold@found\@bp@min@false
4499 \xdef\bp@min@im@threshold@result{\abs@value}
4500 \global\let\bp@min@im@thresh@float=\abs@valuefloat
4501 \gdef\bp@min@im@threshold@found{true}
4502 \else
4503 \pgfkeys{/pgf/fpu=true}
4504 \pgfmathparse{\abs@valuefloat < \bp@min@im@thresh@float ?
4505 1 : 0}
4506 \pgfmathfloattoint{\pgfmathresult}
4507 \pgfkeys{/pgf/fpu=false}
4508 \ifnum\pgfmathresult=1
4509 \xdef\bp@min@im@threshold@result{\abs@value}
4510 \global\let\bp@min@im@thresh@float=\abs@valuefloat
4511 \fi
4512 \fi
4513 \fi
4514 \fi
4515 \fi
4516 }
4517 }
4518 \fi
4519 \ifnum\pdf@strcmp{\feature}{p}=0
4520 \foreach \p in \values {
4521 \foreach \y [count=\pcnt] in \p {
4522 \ifnum\pcnt=2
4523 \pgfkeys{/pgf/fpu=true}
4524 \pgfmathparse{abs(\y)}
4525 \let\abs@valuefloat=\pgfmathresult
4526 \pgfmathfloattofixed{\abs@valuefloat}
4527 \edef\abs@value{\pgfmathresult}
4528 \pgfkeys{/pgf/fpu=false}
4529 \ifnum\pdf@strcmp{\abs@value}{0}=0\else
4530 \ifnum\pdf@strcmp{\abs@value}{0.0}=0\else
4531 \ifx\bp@min@im@threshold@found\@bp@min@false
4532 \xdef\bp@min@im@threshold@result{\abs@value}
4533 \global\let\bp@min@im@thresh@float=\abs@valuefloat
4534 \gdef\bp@min@im@threshold@found{true}
4535 \else
4536 \pgfkeys{/pgf/fpu=true}
4537 \pgfmathparse{\abs@valuefloat < \bp@min@im@thresh@float ?
4538 1 : 0}
4539 \pgfmathfloattoint{\pgfmathresult}
4540 \pgfkeys{/pgf/fpu=false}
4541 \ifnum\pgfmathresult=1
4542 \xdef\bp@min@im@threshold@result{\abs@value}
4543 \global\let\bp@min@im@thresh@float=\abs@valuefloat
4544 \fi
4545 \fi
4546 \fi
4547 \fi
4548 \fi
4549 }
4550 }
4551 \fi
4552 }
4553 \ifx\bp@min@im@threshold@found\@bp@min@false
4554 \gdef\bp@min@im@threshold@result{0.01}
4555 \fi
4556 \pgfkeys{/pgf/fpu=true}
4557 \pgfmathparse{log10(\bp@min@im@threshold@result)}
4558 \let\log@result=\pgfmathresult
4559 \pgfmathparse{\log@result + 1e-5}
4560 \let\log@adjusted=\pgfmathresult
4561 \pgfmathparse{floor(\log@adjusted)}
4562 \pgfmathfloattofixed{\pgfmathresult}
4563 \xdef\bp@min@im@pow@10{\pgfmathresult}
4564 \xdef\bp@min@Im@pow@10{\bp@min@im@pow@10}
4565 \pgfmathparse{\bp@max@im@float > 0 ?
4566 \bp@max@im@float : \bp@min@im@threshold@result}
4567 \let\bp@max@im@valuefloat=\pgfmathresult
4568 \pgfmathparse{log10(max(\bp@max@im@valuefloat,1e-100))}
4569 \let\log@bp@max@im=\pgfmathresult
4570 \pgfmathparse{\log@bp@max@im + 1e-5}
4571 \let\log@bp@max@im@adjusted=\pgfmathresult
4572 \pgfmathparse{ceil(\log@bp@max@im@adjusted)}
4573 \pgfmathfloattoint{\pgfmathresult}
4574 \xdef\bp@max@im@pow@10{\pgfmathresult}
4575 \pgfkeys{/pgf/fpu=false}
4576 }
4577 % \end{macrocode}
4578 % \end{macro}
4579 % \clearpage
4580 % \appendix
4581 % \section{TL;DR for package version 2.1.1 and earlier \label{sec:oldtldr}}
4582 % All Bode plots in this section are for the transfer function (with and without a transport delay)
4583 % \begin{equation}
4584 % 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})} = \frac{s(10s^2+2s+2.6)}{(s^2+s+100.25)}.
4585 % \end{equation}
4586 % \iffalse
4587 %<*ignore>
4588 % \fi
4589
4590 {\centering
4591
4592 \hrulefill
4593
4594 Bode plot in ZPK format
4595
4596 \begin{LTXexample}[pos=l,hsep=20pt,width=0.5\textwidth]
4597 \BodeZPK{%
4598 z/{0,{-0.1,-0.5},{-0.1,0.5}},
4599 p/{{-0.5,-10},{-0.5,10}},
4600 k/10%
4601 }
4602 {0.01}
4603 {100}
4604 \end{LTXexample}
4605
4606 \hrulefill
4607
4608 Same Bode plot over the same frequency range but supplied in Hz, in TF format with arrow decoration, transport delay, unit, and color customization (the phase plot may show wrapping if the |pgf| package option is used)
4609 \begin{LTXexample}[pos=r,width=0.5\textwidth]
4610 \BodeTF[%
4611 samples=1000,
4612 plot/mag/{blue,thick},
4613 plot/ph/{green,thick},
4614 tikz/{%
4615 >=latex,
4616 phase unit=rad,
4617 frequency unit=Hz%
4618 },
4619 commands/mag/{
4620 \draw[->](axis cs:0.1,40) -- (axis cs:{10/(2*pi)},60);
4621 \node at (axis cs: 0.08,30) {\tiny Resonant Peak};
4622 }%
4623 ]
4624 {%
4625 num/{10,2,2.6,0},
4626 den/{1,1,100.25}%
4627 }
4628 {0.01/(2*pi)}
4629 {100/(2*pi)}
4630 \end{LTXexample}
4631
4632 \hrulefill
4633 \clearpage
4634 \hrulefill
4635
4636 Linear approximation with customization
4637 \begin{LTXexample}[pos=l,hsep=20pt,width=0.5\textwidth]
4638 \BodeZPK[%
4639 plot/mag/{red,thick},
4640 plot/ph/{blue,thick},
4641 axes/mag/{ytick distance=40},
4642 axes/ph/{ytick distance=90},
4643 approx/linear%
4644 ]{%
4645 z/{0,{-0.1,-0.5},{-0.1,0.5}},
4646 p/{{-0.5,-10},{-0.5,10}},
4647 k/10%
4648 }
4649 {0.01}
4650 {100}
4651 \end{LTXexample}
4652
4653 \hrulefill
4654
4655 Plot with delay and customization
4656 \begin{LTXexample}[pos=r,hsep=20pt,width=0.5\textwidth]
4657 \BodeZPK[%
4658 plot/mag/{blue,thick},
4659 plot/ph/{green,thick},
4660 axes/mag/ytick distance=40,
4661 axes/ph/ytick distance=90%
4662 ]{%
4663 z/{0,{-0.1,-0.5},{-0.1,0.5}},
4664 p/{{-0.5,-10},{-0.5,10}},
4665 k/10,
4666 d/0.01%
4667 }
4668 {0.01}
4669 {100}
4670 \end{LTXexample}
4671
4672 \hrulefill
4673 \clearpage
4674 \hrulefill
4675
4676 Individual gain and phase plots with more customization
4677
4678 \begin{minipage}[t]{0.45\textwidth}
4679 \begin{LTXexample}[pos=t,width=\columnwidth]
4680 \begin{BodeMagPlot}[%
4681 axes/{height=2cm,
4682 width=4cm}%
4683 ]
4684 {0.01}
4685 {100}
4686 \addBodeZPKPlots[%
4687 true/{black,thick},
4688 linear/{red,dashed,thick},
4689 asymptotic/{blue,dotted,thick}%
4690 ]
4691 {magnitude}
4692 {%
4693 z/{0,{-0.1,-0.5},{-0.1,0.5}},
4694 p/{{-0.5,-10},{-0.5,10}},
4695 k/10%
4696 }
4697 \end{BodeMagPlot}
4698 \end{LTXexample}
4699 \end{minipage}\hfill
4700 \begin{minipage}[t]{0.45\textwidth}
4701 \begin{LTXexample}[pos=t,width=\columnwidth]
4702 \begin{BodePhPlot}[%
4703 height=2cm,
4704 width=4cm,
4705 ytick distance=90
4706 ]
4707 {0.01}
4708 {100}
4709 \addBodeZPKPlots[%
4710 true/{black,thick},
4711 linear/{red,dashed,thick},
4712 asymptotic/{blue,dotted,thick}%
4713 ]
4714 {phase}
4715 {%
4716 z/{0,{-0.1,-0.5},{-0.1,0.5}},
4717 p/{{-0.5,-10},{-0.5,10}},
4718 k/10%
4719 }
4720 \end{BodePhPlot}
4721 \end{LTXexample}
4722 \end{minipage}
4723
4724 \hrulefill
4725
4726 Multiple transfer functions in a single Bode plot using the |BodePlot| environment and the |\addBodePlot| macro introduced in v2.1.
4727
4728 \begin{LTXexample}[pos=r,hsep=20pt,width=0.5\textwidth]
4729 \begin{BodePlot}{0.01}{100}
4730 \addBodePlot[red,postaction=decorate,
4731 decoration={%
4732 markings,
4733 mark=between positions 0.1 and 0.9 step 2em with {%
4734 \arrow{Stealth [length=2mm, blue]}
4735 }
4736 },linear]{zpk}{%
4737 z/{0,{-0.1,-0.5},{-0.1,0.5}},
4738 p/{{-5,-10},{-5,10}},
4739 k/10%
4740 }
4741 \addBodePlot[black,thick]{zpk}{%
4742 z/{0,{-0.1,-0.5},{-0.1,0.5}},
4743 p/{{-5,-10},{-5,10}},
4744 k/10%
4745 }
4746 \addBodePlot[blue,dashed]{tf}{%
4747 num/{10,2,2.6,0},
4748 den/{1,1,100.25}%
4749 }
4750 \end{BodePlot}
4751 \end{LTXexample}
4752
4753 \hrulefill
4754 \clearpage
4755 \hrulefill
4756
4757 Nichols chart
4758 \begin{LTXexample}[pos=l,hsep=20pt,width=0.5\textwidth]
4759 \NicholsZPK[samples=1000]
4760 {%
4761 z/{0,{-0.1,-0.5},{-0.1,0.5}},
4762 p/{{-0.5,-10},{-0.5,10}},
4763 k/10,
4764 d/0.01%
4765 }
4766 {0.001}
4767 {500}
4768 \end{LTXexample}
4769
4770 \hrulefill
4771
4772 Same Nichols chart in TF format (may show wrapping in |pgf| mode)
4773 \begin{LTXexample}[pos=r,hsep=20pt,width=0.5\textwidth]
4774 \NicholsTF[samples=1000]
4775 {%
4776 num/{10,2,2.6,0},
4777 den/{1,1,100.25},
4778 d/0.01%
4779 }
4780 {0.001}
4781 {500}
4782 \end{LTXexample}
4783
4784 \hrulefill
4785 \clearpage
4786 \hrulefill
4787
4788 Multiple Nichols charts with customization
4789 \begin{LTXexample}[pos=l,hsep=20pt,width=0.5\textwidth]
4790 \begin{NicholsChart}[%
4791 ytick distance=20,
4792 xtick distance=30
4793 ]
4794 {0.001}
4795 {100}
4796 \addNicholsZPKChart [red,samples=1000] {%
4797 z/{0,{-0.1,-0.5},{-0.1,0.5}},
4798 p/{{-0.5,-10},{-0.5,10}},
4799 k/10%
4800 }
4801 \addNicholsZPKChart [blue,samples=1000] {%
4802 z/{0,{-0.1,-0.5},{-0.1,0.5}},
4803 p/{{-0.5,-10},{-0.5,10}},
4804 k/5%
4805 }
4806 \end{NicholsChart}
4807 \end{LTXexample}
4808
4809 \hrulefill
4810
4811 Nyquist plot
4812 \begin{LTXexample}[pos=r,hsep=20pt,width=0.5\textwidth]
4813 \NyquistZPK[plot/{red,thick,samples=1000}]
4814 {%
4815 z/{0,{-0.1,-0.5},{-0.1,0.5}},
4816 p/{{-0.5,-10},{-0.5,10}},
4817 k/10%
4818 }
4819 {-30}
4820 {30}
4821 \end{LTXexample}
4822
4823 \hrulefill
4824
4825 Nyquist plot in TF format with arrows
4826 \begin{LTXexample}[pos=l,width=0.5\textwidth]
4827 \NyquistTF[%
4828 plot/{%
4829 samples=1000,
4830 postaction=decorate,
4831 decoration={%
4832 markings,
4833 mark=between positions 0.1 and 0.9 step 5em with {%
4834 \arrow{Stealth [length=2mm, blue]}
4835 }
4836 }
4837 }%
4838 ]
4839 {%
4840 num/{10,2,2.6,0},
4841 den/{1,1,100.25}%
4842 }
4843 {-30}
4844 {30}
4845 \end{LTXexample}
4846
4847 \hrulefill
4848 \clearpage
4849 \hrulefill
4850
4851 Multiple Nyquist plots with customization
4852
4853 \begin{LTXexample}[pos=r,hsep=20pt,width=0.5\textwidth]
4854 \begin{NyquistPlot}{-30}{30}
4855 \addNyquistZPKPlot [red,samples=1000] {%
4856 z/{0,{-0.1,-0.5},{-0.1,0.5}},
4857 p/{{-0.5,-10},{-0.5,10}},
4858 k/10%
4859 }
4860 \addNyquistZPKPlot [blue,samples=1000] {%
4861 z/{0,{-0.1,-0.5},{-0.1,0.5}},
4862 p/{{-0.5,-10},{-0.5,10}},
4863 k/5%
4864 }
4865 \end{NyquistPlot}
4866 \end{LTXexample}
4867
4868 \hrulefill
4869
4870 Nyquist plots with additional commands, using two different macros
4871
4872 \begin{minipage}[t]{0.48\textwidth}
4873 \begin{LTXexample}[pos=t,width=\columnwidth]
4874 \begin{NyquistPlot}[%
4875 tikz/{
4876 spy using outlines={%
4877 circle,
4878 magnification=3,
4879 connect spies,
4880 size=2cm
4881 }
4882 }%
4883 ]
4884 {-30}{30}
4885 \addNyquistZPKPlot [blue,samples=1000] {%
4886 z/{0,{-0.1,-0.5},{-0.1,0.5}},
4887 p/{{-0.5,-10},{-0.5,10}},
4888 k/0.5%
4889 }
4890 \coordinate (spyon) at (axis cs:0,0);
4891 \coordinate (spyat) at (axis cs:-22,5);
4892 \spy [green] on (spyon) in
4893 node [fill=white] at (spyat);
4894 \end{NyquistPlot}
4895 \end{LTXexample}
4896 \end{minipage}\hfill
4897 \begin{minipage}[t]{0.48\textwidth}
4898 \begin{LTXexample}[pos=t,width=\columnwidth]
4899 \NyquistZPK[%
4900 plot/{blue,samples=1000},
4901 tikz/{
4902 spy using outlines={%
4903 circle,
4904 magnification=3,
4905 connect spies,
4906 size=2cm
4907 }
4908 },
4909 commands/{
4910 \coordinate (spyon) at (axis cs:0,0);
4911 \coordinate (spyat) at (axis cs:-22,5);
4912 \spy [green] on (spyon) in
4913 node [fill=white] at (spyat);
4914 }%
4915 ]
4916 {%
4917 z/{0,{-0.1,-0.5},{-0.1,0.5}},
4918 p/{{-0.5,-10},{-0.5,10}},
4919 k/0.5%
4920 }
4921 {-30}
4922 {30}
4923 \end{LTXexample}
4924 \end{minipage}
4925
4926 \hrulefill
4927
4928 \clearpage
4929
4930 \hrulefill
4931
4932 Pole-zero map
4933
4934 \begin{LTXexample}[pos=l,hsep=20pt,width=0.5\textwidth]
4935 \PoleZeroMapZPK
4936 {%
4937 z/{0,{-0.1,-0.5},{-0.1,0.5}},
4938 p/{{-0.5,-10},{-0.5,10}},
4939 k/10%
4940 }
4941 \end{LTXexample}
4942
4943 \hrulefill
4944
4945 Pole-zero map (symmetric log scale)
4946
4947 \begin{LTXexample}[pos=r,width=0.5\textwidth]
4948 \PoleZeroMapZPK[scale/{log}]
4949 {%
4950 z/{0,{-0.1,-0.5},{-0.1,0.5}},
4951 p/{{-0.5,-10},{-0.5,10}},
4952 k/10%
4953 }
4954 \end{LTXexample}}
4955
4956 \hrulefill
4957
4958 \clearpage
4959
4960 % \iffalse
4961 %</ignore>
4962 % \fi
4963 % \Finale
4964 \endinput