tikz.dev / PGFplots Manual

Manual for Package pgfplots
2D/3D Plots in LA, Version 1.18.1

Related Libraries

\(\newcommand{\footnotename}{footnote}\) \(\def \LWRfootnote {1}\) \(\newcommand {\footnote }[2][\LWRfootnote ]{{}^{\mathrm {#1}}}\) \(\newcommand {\footnotemark }[1][\LWRfootnote ]{{}^{\mathrm {#1}}}\) \(\let \LWRorighspace \hspace \) \(\renewcommand {\hspace }{\ifstar \LWRorighspace \LWRorighspace }\) \(\newcommand {\mathnormal }[1]{{#1}}\) \(\newcommand \ensuremath [1]{#1}\) \(\newcommand {\LWRframebox }[2][]{\fbox {#2}} \newcommand {\framebox }[1][]{\LWRframebox } \) \(\newcommand {\setlength }[2]{}\) \(\newcommand {\addtolength }[2]{}\) \(\newcommand {\setcounter }[2]{}\) \(\newcommand {\addtocounter }[2]{}\) \(\newcommand {\arabic }[1]{}\) \(\newcommand {\number }[1]{}\) \(\newcommand {\noalign }[1]{\text {#1}\notag \\}\) \(\newcommand {\cline }[1]{}\) \(\newcommand {\directlua }[1]{\text {(directlua)}}\) \(\newcommand {\luatexdirectlua }[1]{\text {(directlua)}}\) \(\newcommand {\protect }{}\) \(\def \LWRabsorbnumber #1 {}\) \(\def \LWRabsorbquotenumber "#1 {}\) \(\newcommand {\LWRabsorboption }[1][]{}\) \(\newcommand {\LWRabsorbtwooptions }[1][]{\LWRabsorboption }\) \(\def \mathchar {\ifnextchar "\LWRabsorbquotenumber \LWRabsorbnumber }\) \(\def \mathcode #1={\mathchar }\) \(\let \delcode \mathcode \) \(\let \delimiter \mathchar \) \(\def \oe {\unicode {x0153}}\) \(\def \OE {\unicode {x0152}}\) \(\def \ae {\unicode {x00E6}}\) \(\def \AE {\unicode {x00C6}}\) \(\def \aa {\unicode {x00E5}}\) \(\def \AA {\unicode {x00C5}}\) \(\def \o {\unicode {x00F8}}\) \(\def \O {\unicode {x00D8}}\) \(\def \l {\unicode {x0142}}\) \(\def \L {\unicode {x0141}}\) \(\def \ss {\unicode {x00DF}}\) \(\def \SS {\unicode {x1E9E}}\) \(\def \dag {\unicode {x2020}}\) \(\def \ddag {\unicode {x2021}}\) \(\def \P {\unicode {x00B6}}\) \(\def \copyright {\unicode {x00A9}}\) \(\def \pounds {\unicode {x00A3}}\) \(\let \LWRref \ref \) \(\renewcommand {\ref }{\ifstar \LWRref \LWRref }\) \( \newcommand {\multicolumn }[3]{#3}\) \(\require {textcomp}\) \( \newcommand {\meta }[1]{\langle \textit {#1}\rangle } \) \(\newcommand {\toprule }[1][]{\hline }\) \(\let \midrule \toprule \) \(\let \bottomrule \toprule \) \(\def \LWRbooktabscmidruleparen (#1)#2{}\) \(\newcommand {\LWRbooktabscmidrulenoparen }[1]{}\) \(\newcommand {\cmidrule }[1][]{\ifnextchar (\LWRbooktabscmidruleparen \LWRbooktabscmidrulenoparen }\) \(\newcommand {\morecmidrules }{}\) \(\newcommand {\specialrule }[3]{\hline }\) \(\newcommand {\addlinespace }[1][]{}\) \(\require {colortbl}\) \(\let \LWRorigcolumncolor \columncolor \) \(\renewcommand {\columncolor }[2][named]{\LWRorigcolumncolor [#1]{#2}\LWRabsorbtwooptions }\) \(\let \LWRorigrowcolor \rowcolor \) \(\renewcommand {\rowcolor }[2][named]{\LWRorigrowcolor [#1]{#2}\LWRabsorbtwooptions }\) \(\let \LWRorigcellcolor \cellcolor \) \(\renewcommand {\cellcolor }[2][named]{\LWRorigcellcolor [#1]{#2}\LWRabsorbtwooptions }\) \(\newcommand {\intertext }[1]{\text {#1}\notag \\}\) \(\let \Hat \hat \) \(\let \Check \check \) \(\let \Tilde \tilde \) \(\let \Acute \acute \) \(\let \Grave \grave \) \(\let \Dot \dot \) \(\let \Ddot \ddot \) \(\let \Breve \breve \) \(\let \Bar \bar \) \(\let \Vec \vec \) \(\newcommand {\nicefrac }[3][]{\mathinner {{}^{#2}\!/\!_{#3}}}\)

5.11Smith Charts

  • \usepgfplotslibrary{smithchart} % and plain

  • \usepgfplotslibrary[smithchart] % Cont

  • \usetikzlibrary{pgfplots.smithchart} % and plain

  • \usetikzlibrary[pgfplots.smithchart] % Cont

  • A library to draw Smith charts.

    A Smith chart maps the complex half plane with positive real parts to the unit circle. The smithchart library allows pgfplots to visualize Smith charts: it visualizes two-dimensional input coordinates \(z \in \mathbb {C} \) of the form \(z = x+ j y \in \mathbb {C}\) (\(j\) being the imaginary unit, \(j^2=-1\)) with \(x \ge 0\) using the map

    \[ r\colon [0,\infty ] \times [-\infty ,\infty ] \to \{ a+j b \;\vert \; a^2 + b^2 = 1 \}, \quad r(z) = \frac {z-1}{z+1} \]

    using complex number division. The result is always in the unit circle.

    The main application for Smith charts is in the area of electrical and electronics engineers specializing in radio frequency: to show the reflection coefficient \(r(z)\) for normalised impedance \(z\). It is beyond the scope of this manual to delve into the radio frequency techniques; for us, it is important to note that the smithchart library supports

    • the data map \(r(z)\) shown above,

    • an axis class which interprets \(x\) as the real components and \(y\) as the imaginary components,

    • a visualization of grid lines as arcs,

    • the possibility to stop grid lines to allow uniform spacing in Smith charts,

    • a large set of the pgfplots axis fine tuning parameters,

    • input of already mapped coordinates \(r(z)\) (i.e. Cartesian coordinates in the unit circle),

    • many of the pgfplots plot handlers.

5.11.1Smith Chart Axes
5.11.2Size Control

A Smith chart can be resized by providing either width or height as argument to the axis. If you provide both, the Chart is drawn as an ellipsis.

The tick and grid positions for smithchart axes are realized by means of three manually tuned sets of grid lines: one for small-sized plots, one for medium-sized plots and one for huge plots. The actual parameters for width or height are considered to select one of the following sets:

  • /pgfplots/dense smithchart ticks(style, no value)

  • The dense smithchart ticks style assigns the set of tick positions for every Smith chart whose width is at least 20cm:

    (-tikz- diagram)

    % Preamble: \pgfplotsset{width=7cm,compat=1.18}\usepgfplotslibrary{smithchart} \begin{tikzpicture}[scale=0.75] \begin{smithchart}[ title=Huge Smith Chart (rescaled), width=20cm, ] \addplot coordinates {(0.5,0.2) (1,0.8) (2,2)}; \end{smithchart} \end{tikzpicture}

    Attention: This style might change in future versions!

    Similarly to many smithchart ticks (see above), the initial configuration is realized by means of two separate styles: one which defines only the tick positions (the many smithchart ticks* style) and one which also changes placement and alignment options:

    \pgfplotsset{ dense smithchart ticks*/.style={ default smithchart xtick/.style={ xtick={ 0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8,0.9,1,1.2,1.4,1.6,1.8,2,3,4,5,10,20% }, minor xtick={% 0.01,0.02,0.03,0.04,0.05,0.06,0.07,0.08,0.09,0.11,0.12,0.13,0.14,0.15,0.16,0.17, 0.18,0.19,0.22,0.24,0.26,0.28,0.32,0.34,0.36,0.38,0.42,0.44,0.46,0.48,% 0.52,% This is sub-optimal and will (hopefully) be improved in the future. 0.55,0.65,0.75,0.85,0.95,% % 0.6,0.7,0.8,0.9,% 1.1,1.3,1.5,1.7,1.9,% 2.2,2.4,2.6,2.8,3.2,3.4,3.6,3.8,4.5,6,7,8,9,50}, }, default smithchart ytick/.style={ ytick={% 0,% 0.1,0.2,...,1,1.2,1.4,1.6,1.8,2,3,4,5,10,20,% -0.1,-0.2,...,-1,-1.2,-1.4,-1.6,-1.8,-2,-3,-4,-5,-10,-20% }, minor ytick={% 0.01,0.02,0.03,0.04,0.05,0.06,0.07,0.08,0.09,0.11,0.12,0.13,0.14,0.15,0.16,0.17, 0.18,0.19,0.22,0.24,0.26,0.28,0.32,0.34,0.36,0.38,0.42,0.44,0.46,0.48,% 0.55,0.65,0.75,0.85,0.95,% 1.1,1.3,1.5,1.7,1.9,2.2,2.4,2.6,2.8,3.2,3.4,3.6,3.8,4.5,6,7,8,9,50,% -0.01,-0.02,-0.03,-0.04,-0.05,-0.06,-0.07,-0.08,-0.09,-0.11,-0.12,-0.13,-0.14, -0.15,-0.16,-0.17,-0.18,-0.19,-0.22,-0.24,-0.26,-0.28,-0.32,-0.34,-0.36,-0.38, -0.42,-0.44,-0.46,-0.48,-0.55,-0.65,-0.75,-0.85,-0.95,% -1.1,-1.3,-1.5,-1.7,-1.9,-2.2,-2.4,-2.6,-2.8,-3.2,-3.4,-3.6,-3.8,-4.5,-6,-7,-8, -9,-50% }, }, default smithchart xytick/.style={ xgrid each nth passes y={0.2 if < 0.2001,0.5 if < 0.50001,1 if < 1.001,2,4,5,10,20}, ygrid each nth passes x={0.2 if < 0.2001,0.52 if < 0.52001,1 if < 1.001,2,3,5,10:3,20:3}, }, }, dense smithchart ticks/.style={ yticklabel in circle, dense smithchart ticks*, show origin=true, every major grid/.style={black!60}, }, }

    See the documentation for few smithchart ticks for an explanation of the default smithchart xtick/.style overhead.

5.11.3Working with Prepared Data
  • /pgfplots/is smithchart cs=true|false (initially false)

  • Occasionally, you may already have input data transformed into unit circle Cartesian coordinate \(r(z) = (x,y)\).

    You can provide them to pgfplots with the is smithchart cs key:

    (-tikz- diagram)

    % Preamble: \pgfplotsset{width=7cm,compat=1.18}\usepgfplotslibrary{smithchart} \begin{tikzpicture} \begin{smithchart} % smithchart_data.dat contains % 0.78395 -0.40845 % 0.78165 -0.41147 % 0.77934 -0.41466 % 0.77774 -0.41869 % ... \addplot [ blue, is smithchart cs, ] file {plotdata/smithchart_data.dat}; \end{smithchart} \end{tikzpicture}

    Using is smithchart cs tells pgfplots to skip the transformation \(r(z)\).

5.11.4Appearance Control and Styles
5.11.5Controlling Arcs and Their Stop Points

This section allows advanced control over Smith chart arcs (grid lines). The two features xgrid each nth passes y and xgrid stop at y (and their counterparts for \(y\)) allow to draw only partial arcs in order to get a more uniform appearance.

  • /pgfplots/xgrid each nth passes y={(math image)list of stop entries(math image)} (initially empty)

  • This key constitutes the main idea to draw only partial arcs: you provide a couple of \(y\) tick coordinates which constitute “boundaries”. Then, only each (say) second \(x\) grid line is allowed to pass these boundaries:

    (-tikz- diagram)

    % Preamble: \pgfplotsset{width=7cm,compat=1.18}\usepgfplotslibrary{smithchart} \begin{tikzpicture} \begin{smithchart}[ xtick={0.2,0.5,1,2,5}, ytick={ 0, 0.2, 0.5, 1, 2, 5, -0.2,-0.5,-1,-2,-5 }, xgrid each nth passes y={1,2}, ] \end{smithchart} \end{tikzpicture}

    The example overwrites the default smithchart ticks to define a new layout: now, every ytick uses the complete arc, but some of the grid lines for xtick stop at \(y=1\) and, if they pass, they may stop at \(y=2\).

    The argument (math image)list of stop entries(math image) is a comma-separated list of entries. Each entry is, in the simplest case, a \(y\)-coordinate (it should be a coordinate which appears in the ytick list). This simplest case means “only each second \(x\) grid line may pass the grid line for this \(y\)”. The second syntax allows to provide a natural number, using (math image)y coord(math image):(math image)number(math image). This means to let only each (math image)number(math image)’s \(x\) grid line pass the designated \(y\) grid line. The third syntax also allows to write if < (math image)x value(math image). It means the entry is considered only for \(x\) grid lines which are less than (math image)x value(math image). To summarize: there are the three possible forms of entries

    • 1. single \(y\)-coordinates, for example xgrid each nth passes y={1,2} or

    • 2. the same as above, followed by an integer, for example xgrid each nth passes y={1:3,2:2} or

    • 3. an additional restriction clause like xgrid each nth passes y={0.2 if <0.3}.

      In this case, the all \(x\) grid lines which fulfill \(x \le 0.3\) will be checked if they are allowed to pass \(y=0.2\). All \(x\) grid lines with \(x > 0.3\) are not affected by the constraint. See the dense smithchart ticks style for an application example.

    Note that xgrid each nth passes y always employs symmetry; you do not need to provide \(y\) and \(-y\) (if you want to, you may use the xgrid stop at y key to overrule the “each nth” strategy).

    In order to check if a given xtick argument is the “\(n\)th” grid line, pgfplots collects all xtick and minor xtick arguments into one large array and sorts it. Then, it uses the resulting sequence to assign the indices. Consequently, you can freely intermix minor and major ticks; it will still work. The only way to affect the counting is the xgrid each nth passes y start key, see below.

Now, we know how to use xgrid each nth passes y and the corresponding ygrid each nth passes x separately. Can we use both keys at the same time? Yes – but it may happen that lines end in white space! pgfplots applies some logic to avoid arcs ending in white space by extending them to the next feasible stopping point. The result of mixing both of these keys is thus corrected automatically.

  • /pgfplots/xgrid each nth passes y start={(math image)integer(math image)} (initially 0)

  • /pgfplots/ygrid each nth passes x start={(math image)integer(math image)} (initially 0)

  • Allows to modify where the “each \(n\)th” counting starts. The argument can be considered as a shift. I consider this key to be more or less experimental – in the hope it may be useful. Try it out.

  • /pgfplots/xgrid stop at y={(math image)list(math image)} (initially empty)

  • /pgfplots/ygrid stop at x={(math image)list(math image)} (initially empty)

  • These keys allow to provide individual stop points for explicitly chosen tick positions. These explicit stop points have higher precedence over the each nth features described above.

    The ygrid stop at x key accepts a comma-separated list of entries (math image)y coord(math image):(math image)x stop point(math image):

    (-tikz- diagram)

    % Preamble: \pgfplotsset{width=7cm,compat=1.18}\usepgfplotslibrary{smithchart} \begin{tikzpicture} \begin{smithchart}[ ygrid stop at x={0.5:0.5,-0.2:0.2} ] \end{smithchart} \end{tikzpicture}

    In this example, the \(y=0.5\) arc stops at the \(x=0.5\) arc whereas the \(y=-0.2\) arc stops at \(x=0.2\).

    The ygrid stop at x key allows asymmetric layouts (different stop points for \(y\) and \(-y\)).