PlottingMixin

class pysmithchart.plotting.PlottingMixin[source]

Bases: object

Mixin class providing plotting methods for SmithAxes.

This class is designed to be used as a mixin with matplotlib.axes.Axes via multiple inheritance. Attributes like _current_zorder are provided by the SmithAxes class through the AxesCore mixin.

Methods Summary

`annotate`(text, xy[, xytext, xycoords, ...])	Add an annotation (text with optional arrow) to the Smith chart.
`legend`(_args, *kwargs)	Create and display a legend for the Smith chart, filtering duplicate entries.
`plot`(args, *kwargs)	Plot data on the Smith Chart.
`plot_constant_conductance`(norm_conductance, ...)	Plot a constant conductance circle on the Smith chart (admittance chart).
`plot_constant_reactance`(norm_reactance, *args)	Plot a constant reactance arc on the Smith chart.
`plot_constant_resistance`(norm_resistance, *args)	Plot a constant resistance circle on the Smith chart.
`plot_constant_susceptance`(norm_susceptance, ...)	Plot a constant susceptance arc on the Smith chart (admittance chart).
`plot_rotation_path`(Z_start, Z_end, *args[, ...])	Plot a physically realizable impedance matching path.
`plot_vswr`(vswr, *args[, angle_range, ...])	Plot a constant VSWR circle on the Smith chart.
`scatter`(x[, y, domain])	Create a scatter plot on the Smith Chart.
`text`(x[, y, s, domain])	Add text to the Smith chart at the specified coordinates.

Methods Documentation

annotate(text, xy, xytext=None, xycoords='data', textcoords=None, domain=None, domain_text=None, arrowprops=None, annotation_clip=None, **kwargs)[source]

Add an annotation (text with optional arrow) to the Smith chart.

Parameters:

text (str) – The text of the annotation.
xy (tuple) – The point (x, y) to annotate.
xytext (tuple, optional) – Position (x, y) for the text. If None, text is placed at xy.
xycoords (str or Transform, optional) – Coordinate system for xy. Default is ‘data’. Can be ‘data’, ‘axes’, ‘figure’, or a Transform. Only ‘data’ coordinates are transformed according to domain.
textcoords (str or Transform, optional) – Coordinate system for xytext. Defaults to xycoords value.
domain (str, optional) – Coordinate type for xy (IMPEDANCE, ADMITTANCE, or REFLECTION domain). Only used when xycoords is ‘data’ or not specified.
domain_text (str, optional) – Coordinate type for xytext. Only used when textcoords is ‘data’. Defaults to domain value.
arrowprops (dict, optional) – Arrow properties.
annotation_clip (bool, optional) – Whether to clip annotation.
**kwargs – Additional matplotlib annotate parameters.

Returns:

matplotlib.text.Annotation – The annotation object.

legend(*_args, **kwargs)[source]

Create and display a legend for the Smith chart, filtering duplicate entries.

This method filters out duplicate legend labels, keeping only the first occurrence.

Parameters:

*args – Positional arguments passed directly to matplotlib.axes.Axes.legend.
**kwargs – Keyword arguments for configuring the legend. Includes all standard arguments supported by matplotlib.axes.Axes.legend, such as:
- loc: Location of the legend (e.g., ‘upper right’, ‘lower left’).
- fontsize: Font size for the legend text.
- ncol: Number of columns in the legend.
- title: Title for the legend.
- framealpha: Transparency of the legend background (default: 1.0 for opaque).
See the Matplotlib documentation for more details.

Returns:

matplotlib.legend.Legend – The legend instance created for the Smith chart.

plot(*args, **kwargs)[source]

Plot data on the Smith Chart.

This method extends the functionality of matplotlib.axes.Axes.plot() to support Smith Chart-specific features, including handling of complex data and additional keyword arguments for customization.

Parameters:

*args – Positional arguments for the data to plot. Supports real and complex data. Complex data should either be of type complex or a numpy.ndarray with dtype=complex.
**kwargs – Keyword arguments for customization. Includes all arguments supported by matplotlib.axes.Axes.plot(), along with the following:

domain (str, optional):
Specifies the input data format - Z_DOMAIN: (default) Impedance in Ohms. - R_DOMAIN: Gamma or scattering parameters - NORM_Z_DOMAIN: Normalized impedance. - Y_DOMAIN: Admittance in Siemens - NORM_Y_DOMAIN: Normalized admittance.

interpolate (bool or int, optional):
If True, interpolates the given data linearly with a default step size. If an integer, specifies the number of interpolation steps. Defaults to False.

equipoints (bool or int, optional):
If True, interpolates the data to equidistant points. If an integer, specifies the number of equidistant points. Cannot be used with interpolate. Defaults to False.

arrow (str, bool, or dict, optional):
Add directional arrow(s) to the curve. - None/False: No arrows (default) - True/’end’: Arrow at end of line - ‘start’: Arrow at start of line - ‘both’: Arrows at both ends - dict: {‘position’: ‘end’/’start’/’both’, ‘style’: ‘->’, ‘size’: 15}

Returns:

list[matplotlib.lines.Line2D] – A list of line objects representing the plotted data.

Examples

Plot impedance data on a Smith Chart:

>>> import matplotlib.pyplot as plt
>>> import pysmithchart
>>> ZL = [30 + 30j, 50 + 50j, 100 + 100j]
>>> plt.subplot(1, 1, 1, projection="smith")
>>> plt.plot(ZL, "b", marker="o", markersize=10, domain=pysmithchart.Z_DOMAIN)
>>> plt.show()

Plot with arrow showing direction:

>>> ZL = [30 + 30j, 50 + 50j, 100 + 100j]
>>> plt.subplot(1, 1, 1, projection="smith")
>>> plt.plot(ZL, "r-", arrow='end', linewidth=2)
>>> plt.show()

plot_constant_conductance(norm_conductance, *args, range=None, num_points=500, arrow=None, **kwargs)[source]

Plot a constant conductance circle on the Smith chart (admittance chart).

Constant conductance forms a circle on an admittance Smith chart, just as constant resistance forms a circle on an impedance Smith chart.

Parameters:

norm_conductance (float or complex) – Normalized conductance value (g = G×Z₀, unitless). For example, g=1.0 represents Y₀ (where Y₀=1/Z₀). If complex, only the real part is used.
*args – Optional format string (e.g., ‘r-’, ‘b–’, ‘go’).
range (tuple, optional) – The (min, max) normalized susceptance range to plot. If None, draws a complete circle. If range values are complex, only the imaginary parts are used.
num_points (int, optional) – Number of points to use for the circle (default: 500).
arrow (str, bool, or dict, optional) – Add directional arrow(s) to the curve. - None/False: No arrows (default) - True/’end’: Arrow at end - ‘start’: Arrow at start - ‘both’: Arrows at both ends - dict: {‘position’: ‘end’/’start’/’both’, ‘style’: ‘->’, ‘size’: 15}
**kwargs – Additional keyword arguments passed to plot() (e.g., color, linestyle, label).

Returns:

list[matplotlib.lines.Line2D] – The plotted line objects.

Examples

>>> # Plot g=1.0 constant conductance circle (matches Y₀)
>>> ax.plot_constant_conductance(1.0, 'r-', label='g = 1.0')

>>> # Plot g=2.0 with arrow
>>> ax.plot_constant_conductance(2.0, 'b-', arrow='end', label='g = 2.0')

>>> # Plot with custom susceptance range
>>> ax.plot_constant_conductance(0.5, 'g--', range=(-2, 2))

>>> # Plot g=0.5 (half of Y₀)
>>> ax.plot_constant_conductance(0.5, color='orange', linewidth=2)

>>> # Plot using complex admittance (only real part used)
>>> ax.plot_constant_conductance(1.5+0.8j, 'g-')  # Plots g=1.5

Notes

On an admittance Smith chart, constant conductance forms a circle, just like constant resistance on an impedance chart. The circle is parametrized by varying susceptance from -∞ to +∞.

All values are normalized (unitless). To plot physical values in Siemens: norm_conductance = G × Z₀, where G is in Siemens and Z₀ is in Ohms.

plot_constant_reactance(norm_reactance, *args, range=None, num_points=200, arrow=None, **kwargs)[source]

Plot a constant reactance arc on the Smith chart.

Parameters:

norm_reactance (float or complex) – Normalized reactance value (x = X/Z₀, unitless). Positive for inductive reactance, negative for capacitive reactance. If complex, only the imaginary part is used.
*args – Optional format string (e.g., ‘r-’, ‘b–’, ‘go’).
range (tuple, optional) – The (min, max) normalized resistance range to plot. If None, automatically determines range to show the full arc. If range values are complex, only the real parts are used.
num_points (int, optional) – Number of points to use for the arc (default: 200).
arrow (str, bool, or dict, optional) – Add directional arrow(s) to the curve. - None/False: No arrows (default) - True/’end’: Arrow at end - ‘start’: Arrow at start - ‘both’: Arrows at both ends - dict: {‘position’: ‘end’/’start’/’both’, ‘style’: ‘->’, ‘size’: 15}
**kwargs – Additional keyword arguments passed to plot() (e.g., color, linestyle, label).

Returns:

list[matplotlib.lines.Line2D] – The plotted line objects.

Examples

>>> # Plot x=+1.0 constant reactance arc (inductive)
>>> ax.plot_constant_reactance(1.0, 'r-', label='x = +1.0 (inductive)')

>>> # Plot x=-1.0 arc (capacitive)
>>> ax.plot_constant_reactance(-1.0, 'b-', label='x = -1.0 (capacitive)')

>>> # Plot with custom resistance range
>>> ax.plot_constant_reactance(0.5, 'g--', range=(0, 5))

>>> # Plot with arrow
>>> ax.plot_constant_reactance(2.0, color='orange', arrow='end')

>>> # Plot using complex impedance (only imaginary part used)
>>> ax.plot_constant_reactance(0.8+1.5j, 'm-')  # Plots x=1.5

Notes

On a Smith chart, constant reactance forms circular arcs. The arcs are parametrized by varying the resistance from 0 to ∞. Positive reactance (inductive) appears in the upper half of the chart, negative reactance (capacitive) in the lower half.

All values are normalized (unitless). To plot physical values in Ohms, divide by Z₀.

plot_constant_resistance(norm_resistance, *args, range=None, num_points=500, arrow=None, **kwargs)[source]

Plot a constant resistance circle on the Smith chart.

Parameters:

norm_resistance (float or complex) – Normalized resistance value (r = R/Z₀, unitless). For example, r=1.0 represents Z₀, r=2.0 represents 2×Z₀, etc. If complex, only the real part is used.
*args – Optional format string (e.g., ‘r-’, ‘b–’, ‘go’).
range (tuple, optional) – The (min, max) normalized reactance range to plot. If None, draws a complete circle. If specified, draws an arc between the min and max reactance values (in normalized units). If range values are complex, only the imaginary parts are used.
num_points (int, optional) – Number of points to use for the circle (default: 500).
arrow (str, bool, or dict, optional) – Add directional arrow(s) to the curve. - None/False: No arrows (default) - True/’end’: Arrow at end - ‘start’: Arrow at start - ‘both’: Arrows at both ends - dict: {‘position’: ‘end’/’start’/’both’, ‘style’: ‘->’, ‘size’: 15}
**kwargs – Additional keyword arguments passed to plot() (e.g., color, linestyle, label).

Returns:

list[matplotlib.lines.Line2D] – The plotted line objects.

Examples

>>> # Plot r=1.0 constant resistance circle (matches Z₀)
>>> ax.plot_constant_resistance(1.0, 'r-', label='r = 1.0')

>>> # Plot r=2.0 with arrow showing direction
>>> ax.plot_constant_resistance(2.0, 'b-', arrow='end', label='r = 2.0')

>>> # Plot arc with limited reactance range
>>> ax.plot_constant_resistance(0.5, 'g--', range=(-1, 1), arrow='both')

>>> # Plot r=0.5 (half of Z₀)
>>> ax.plot_constant_resistance(0.5, color='orange', linewidth=2)

>>> # Plot using complex impedance (only real part used)
>>> ax.plot_constant_resistance(1.5+0.8j, 'g-')  # Plots r=1.5

Notes

On a Smith chart, constant resistance forms a circle. The circle is parametrized by varying the reactance from -∞ to +∞. For a complete circle, the function uses angular parametrization. For a partial arc, it uses the specified reactance range.

All values are normalized (unitless). To plot physical values in Ohms, divide by Z₀.

plot_constant_susceptance(norm_susceptance, *args, range=None, num_points=200, arrow=None, **kwargs)[source]

Plot a constant susceptance arc on the Smith chart (admittance chart).

Constant susceptance forms an arc on an admittance Smith chart, just as constant reactance forms an arc on an impedance Smith chart.

Parameters:

norm_susceptance (float or complex) – Normalized susceptance value (b = B×Z₀, unitless). Positive for capacitive susceptance, negative for inductive susceptance. If complex, only the imaginary part is used.
*args – Optional format string (e.g., ‘r-’, ‘b–’, ‘go’).
range (tuple, optional) – The (min, max) normalized conductance range to plot. If None, automatically determines range to show the full arc. If range values are complex, only the real parts are used.
num_points (int, optional) – Number of points to use for the arc (default: 200).
arrow (str, bool, or dict, optional) – Add directional arrow(s) to the curve. - None/False: No arrows (default) - True/’end’: Arrow at end - ‘start’: Arrow at start - ‘both’: Arrows at both ends - dict: {‘position’: ‘end’/’start’/’both’, ‘style’: ‘->’, ‘size’: 15}
**kwargs – Additional keyword arguments passed to plot() (e.g., color, linestyle, label).

Returns:

list[matplotlib.lines.Line2D] – The plotted line objects.

Examples

>>> # Plot b=+1.0 constant susceptance arc (capacitive)
>>> ax.plot_constant_susceptance(1.0, 'r-', label='b = +1.0 (capacitive)')

>>> # Plot b=-1.0 arc (inductive)
>>> ax.plot_constant_susceptance(-1.0, 'b-', label='b = -1.0 (inductive)')

>>> # Plot with custom conductance range
>>> ax.plot_constant_susceptance(0.5, 'g--', range=(0, 5))

>>> # Plot with arrow
>>> ax.plot_constant_susceptance(2.0, color='orange', arrow='end')

>>> # Plot using complex admittance (only imaginary part used)
>>> ax.plot_constant_susceptance(0.8+1.5j, 'm-')  # Plots b=1.5

Notes

On an admittance Smith chart, constant susceptance forms circular arcs. The arcs are parametrized by varying conductance from 0 to ∞. Positive susceptance (capacitive) appears in the upper half, negative susceptance (inductive) in the lower half.

Note: The sign convention is opposite to reactance - positive susceptance is capacitive, while positive reactance is inductive.

All values are normalized (unitless). To plot physical values in Siemens: norm_susceptance = B × Z₀, where B is in Siemens and Z₀ is in Ohms.

plot_rotation_path(Z_start, Z_end, *args, domain=None, num_points=100, arrow=None, **kwargs)[source]

Plot a physically realizable impedance matching path.

For impedances at the same VSWR: Draws a single arc along the constant-VSWR circle.

For impedances at different VSWR: Draws a two-step path:

Step 1: Rotate along constant-VSWR circle (transmission line)
Step 2: Move toward center (reactive element)

Parameters:

Z_start – Starting impedance (complex number).
Z_end – Ending impedance (complex number).
*args – Optional format string (e.g., ‘r-’, ‘b–‘).
domain – Domain for the impedances (Z_DOMAIN, NORM_Z_DOMAIN, Y_DOMAIN, R_DOMAIN). Default: uses plot.default.domain from configuration.
num_points (int) – Number of points for smooth path (default: 100).
arrow (str, bool, or dict, optional) – Add directional arrow(s). - For single arc (same VSWR): Arrow added to the arc - For two-step path: Arrows added to both steps - None/False: No arrows (default) - True/’end’: Arrow at end of each segment - ‘start’: Arrow at start - ‘both’: Arrows at both ends - dict: {‘position’: ‘end’/’start’/’both’, ‘style’: ‘->’, ‘size’: 15}
**kwargs – Additional plot arguments (color, linestyle, label, etc.).

Returns:

list – List of line objects. Single line for same VSWR, two lines otherwise.

Examples

>>> # Same VSWR - single arc with arrow (impedance in Ohms)
>>> ax.plot_rotation_path(75+50j, 100+50j, 'r-', arrow='end', label='Rotation')

>>> # Different VSWR - two-step path (normalized impedance)
>>> ax.plot_rotation_path(1.5+1j, 1+0j, 'b--', domain=NORM_Z_DOMAIN, arrow='end')

>>> # Admittance-based matching
>>> ax.plot_rotation_path(0.02+0.01j, 0.02+0j, 'g-', domain=Y_DOMAIN, arrow='end')

Notes

For same VSWR: Represents traveling along a lossless transmission line. For different VSWR: Represents a matching network with transmission line + reactive element.

All coordinate transformations are handled by _apply_domain_transform().

plot_vswr(vswr, *args, angle_range=None, num_points=200, arrow=None, **kwargs)[source]

Plot a constant VSWR circle on the Smith chart.

A constant VSWR circle represents all impedances with the same voltage standing wave ratio. The circle is centered at the chart center with radius \(|\\Gamma|\).

Parameters:

vswr (float) – The VSWR value to plot. Must be >= 1.0. VSWR = 1.0 is a perfect match (center point). VSWR = ∞ is the outer edge of the Smith chart.
*args – Optional format string (e.g., ‘r-’, ‘b–’, ‘go’).
angle_range (tuple, optional) – The (start_angle, end_angle) in degrees to plot. If None, plots the full circle (0° to 360°). Angles are measured counterclockwise from the positive real axis.
num_points (int, optional) – Number of points to use for the circle (default: 200).
arrow (str, bool, or dict, optional) – Add directional arrow(s) to the curve. - None/False: No arrows (default) - True/’end’: Arrow at end - ‘start’: Arrow at start - ‘both’: Arrows at both ends - dict: {‘position’: ‘end’/’start’/’both’, ‘style’: ‘->’, ‘size’: 15}
**kwargs – Additional keyword arguments passed to plot() (e.g., color, linestyle, label).

Returns:

list[matplotlib.lines.Line2D] – The plotted line objects.

Raises:

ValueError – If vswr < 1.0.

Examples

>>> # Plot VSWR = 2.0 circle
>>> ax.plot_vswr(2.0, 'r-', label='VSWR = 2.0')

>>> # Plot partial arc from 0° to 180°
>>> ax.plot_vswr(1.5, 'b--', angle_range=(0, 180))

>>> # Plot VSWR = 3.0 with custom styling
>>> ax.plot_vswr(3.0, color='green', linestyle='--', linewidth=2)

scatter(x, y=None, domain=None, **kwargs)[source]

Create a scatter plot on the Smith Chart.

Parameters:

x – X coordinates (real part) or complex impedance/admittance values.
y – Y coordinates (imaginary part). Ignored if x is complex.
domain (str, optional) – Specifies the input data format - Z_DOMAIN: (default) Impedance in Ohms. - R_DOMAIN: Gamma or scattering parameters - NORM_Z_DOMAIN: Normalized impedance. - Y_DOMAIN: Admittance in Siemens - NORM_Y_DOMAIN: Normalized admittance.
**kwargs – Additional arguments passed to matplotlib.axes.Axes.scatter (s, c, marker, etc.).

Returns:

PathCollection – The scatter plot collection.

Examples

>>> # Recommended: use keyword arguments
>>> ax.scatter(50+25j, s=50, c='red', marker='o')

>>> # Also works: passing real and imaginary parts separately
>>> ax.scatter(50, 25, s=50, c='red', marker='o')

text(x, y=None, s=None, domain=None, **kwargs)[source]

Add text to the Smith chart at the specified coordinates.

Parameters:

x (float or complex) – X-coordinate or complex coordinate.
y (float, optional) – Y-coordinate. Not needed if x is complex.
s (str, optional) – Text string to display.
domain (str, optional) – Coordinate domain (Z_DOMAIN, Y_DOMAIN, etc.). Defaults to plot.default.domain from configuration.
transform (Transform, optional) – Matplotlib transform to use. If None or ‘data’, uses Smith chart transformation. Otherwise uses the specified transform (e.g., transAxes).
**kwargs – Additional arguments passed to matplotlib.axes.Axes.text().

Returns:

matplotlib.text.Text – The created text object.

Examples

>>> # Text at impedance coordinates (default behavior)
>>> ax.text(50, 25, "Point A")  # Real and imaginary parts
>>> ax.text(50+25j, "Point A")  # Complex impedance

>>> # Text in axes coordinates (0-1 range, no transformation)
>>> ax.text(0.5, 0.95, "Title", transform=ax.transAxes, ha='center')

>>> # Text with styling
>>> ax.text(75+50j, "Load", fontsize=12, color='red', ha='left')