Manual for Package pgfplots
2D/3D Plots in LATeX, Version 1.18.1
http://sourceforge.net/projects/pgfplots

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.

The \begin{smithchart} environment draws Smith charts. It accepts the same options as \begin{axis}. In fact, it is equivalent to \begin{axis}[options,axis type=smithchart].

The example above visualizes three data points using the initial configuration of Smith charts; the data points are interpreted as complex numbers \(z = x + j y\) and are mapped using \(r(z)\).

Here, the \(x\)-coordinate refers to the cycles described by the horizontal line whereas the \(y\)-coordinate refers to the cycles described by the tick labels on the outside.

Since pgfplots can draw two axes on top of each other, a combined Impedance/Admittance Smith chart is also possible.

Since such a chart easily becomes crowded, it should be tuned manually by means of “suitable” appearance options (if you feel that there is a “suitable default”, let me know).

Details for show origin, yticklabel around circle, and yticklabel around circle* can be found later in this section.

This produces the output of the example above – it constitutes the initial configuration for Smith chart which has a width of less than 14cm.

The few smithchart ticks style is defined by:

Note that few smithchart ticks contains syntactical overhead to distinguish between “default ticks” and final tick positions: it does not assign xtick and ytick directly. Instead, it provides them as separate default xtick style arguments. The purpose of this distinction is to mark them as “default” arguments – the underlying styles smithchart/every default xtick is used if and only if there is no xtick value given.

In case you want to override this default, you can either

• • copy–paste the definition above and adjust it or

• • omit all the default smithchart xtick/.style stuff and write xtick={your list} directly.

As mentioned, the only purpose of the default smithchart xtick/.style overhead is to distinguish between \begin{smithchart}[xtick={user defined}] and default arguments (see the documentation of default smithchart xtick/.style for more about this technical detail).

For fine tuning of the scaling decisions, see the smith chart ticks by size key.

The many smithchart ticks style is used for every Smith chart whose width exceeds 14cm although it is less than 20cm:

We see that many smithchart ticks has different placement and alignment options than few smithchart ticks: it uses sloped tick labels inside of the unit circle for the \(y\) descriptions (imaginary axis).

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. The initial configuration can be changed individually (see the end of this section for examples). The initial configuration is:

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

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

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:

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

The default smithchart xtick style is installed if and only if you do not provide xtick manually.

Similarly, the default smithchart ytick style is installed if and only if you do not provide ytick manually.

Finally, the default smithchart xytick style is installed if and only if you provide neither xtick nor ytick.

These styles are usually defined in few smithchart ticks and its variants, see above.

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:

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

Allows to place an extra description at the point \((0,0)\) to mark the origin.

This style draws Smith chart tick labels for imaginary components (the ytick arguments) inside of the circle.

It installs transformations to rotate and shift tick labels. See the many smithchart ticks style for an example.

The initial configuration for this style is

This style draws Smith chart tick labels for imaginary components (the ytick arguments) outside of the circle, but rotated to fit the slope of the circle.

The initial configuration for this style is

A variant of yticklabel around circle which exchanges the anchors:

If you have two Smith charts in the same figure, you can overlay them if the first uses yticklabel around circle and the second uses yticklabel around circle* (see the beginning of this section for an example).

The initial configuration for this style is

This style is installed for every Smith chart. It is defined as

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:

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 list of stop entries 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 y coord:number. This means to let only each number’s \(x\) grid line pass the designated \(y\) grid line. The third syntax also allows to write if < x value. It means the entry is considered only for \(x\) grid lines which are less than x value. 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.

As you may already have guessed, this is the \(y\) counterpart of xgrid each nth passes y. It restricts the arcs for \(y\) grid lines by provided \(x\) ticks:

The syntax is exactly the same as explained for xgrid each nth passes y. The only difference is that the if < syntax uses absolute values \(|y|\) (to maintain symmetry).

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.

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 y coord:x stop point:

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\)).