control.nyquist_plot

control.nyquist_plot(data, omega=None, plot=None, label_freq=0, color=None, label=None, return_contour=None, title=None, ax=None, unit_circle=False, mt_circles=None, ms_circles=None, **kwargs)[source]

Nyquist plot for a system.

Generates a Nyquist plot for the system over a (optional) frequency range. The curve is computed by evaluating the Nyquist segment along the positive imaginary axis, with a mirror image generated to reflect the negative imaginary axis. Poles on or near the imaginary axis are avoided using a small indentation. The portion of the Nyquist contour at infinity is not explicitly computed (since it maps to a constant value for any system with a proper transfer function).

Parameters

datalist of LTI or NyquistResponseData: List of linear input/output systems (single system is OK) or Nyquist responses (computed using nyquist_response). Nyquist curves for each system are plotted on the same graph.
omegaarray_like, optional: Set of frequencies to be evaluated, in rad/sec. Specifying omega as a list of two elements is equivalent to providing omega_limits.
unit_circlebool, optional: If True, display the unit circle, to read gain crossover frequency. The circle style is determined by config.defaults['nyquist.circle_style'].
mt_circlesarray_like, optional: Draw circles corresponding to the given magnitudes of sensitivity.
ms_circlesarray_like, optional: Draw circles corresponding to the given magnitudes of complementary sensitivity.
**kwargsmatplotlib.pyplot.plot keyword properties, optional: Additional keywords passed to matplotlib to specify line properties.

Returns

cpltControlPlot object

Object containing the data that were plotted. See ControlPlot for more detailed information.

cplt.lines2D array of matplotlib.lines.Line2D

Array containing information on each line in the plot. The shape of the array is given by (nsys, 4) where nsys is the number of systems or Nyquist responses passed to the function. The second index specifies the segment type:

lines[idx, 0]: unscaled portion of the primary curve

lines[idx, 1]: scaled portion of the primary curve

lines[idx, 2]: unscaled portion of the mirror curve

lines[idx, 3]: scaled portion of the mirror curve

cplt.axes2D array of matplotlib.axes.Axes

Axes for each subplot.

cplt.figurematplotlib.figure.Figure

Figure containing the plot.

cplt.legend2D array of matplotlib.legend.Legend

Legend object(s) contained in the plot.

Other Parameters

arrowsint or 1D/2D array of floats, optional: Specify the number of arrows to plot on the Nyquist curve. If an integer is passed. that number of equally spaced arrows will be plotted on each of the primary segment and the mirror image. If a 1D array is passed, it should consist of a sorted list of floats between 0 and 1, indicating the location along the curve to plot an arrow. If a 2D array is passed, the first row will be used to specify arrow locations for the primary curve and the second row will be used for the mirror image. Default value is 2 and can be set using config.defaults['nyquist.arrows'].
arrow_sizefloat, optional: Arrowhead width and length (in display coordinates). Default value is 8 and can be set using config.defaults['nyquist.arrow_size'].
arrow_stylematplotlib.patches.ArrowStyle, optional: Define style used for Nyquist curve arrows (overrides arrow_size).
axmatplotlib.axes.Axes, optional: The matplotlib axes to draw the figure on. If not specified and the current figure has a single axes, that axes is used. Otherwise, a new figure is created.
encirclement_thresholdfloat, optional: Define the threshold for generating a warning if the number of net encirclements is a non-integer value. Default value is 0.05 and can be set using config.defaults['nyquist.encirclement_threshold'].
indent_directionstr, optional: For poles on the imaginary axis, set the direction of indentation to be ‘right’ (default), ‘left’, or ‘none’.
indent_pointsint, optional: Number of points to insert in the Nyquist contour around poles that are at or near the imaginary axis.
indent_radiusfloat, optional: Amount to indent the Nyquist contour around poles on or near the imaginary axis. Portions of the Nyquist plot corresponding to indented portions of the contour are plotted using a different line style.
labelstr or array_like of str, optional: If present, replace automatically generated label(s) with the given label(s). If sysdata is a list, strings should be specified for each system.
label_freqint, optional: Label every nth frequency on the plot. If not specified, no labels are generated.
legend_locint or str, optional: Include a legend in the given location. Default is ‘upper right’, with no legend for a single response. Use False to suppress legend.
max_curve_magnitudefloat, optional: Restrict the maximum magnitude of the Nyquist plot to this value. Portions of the Nyquist plot whose magnitude is restricted are plotted using a different line style. The default value is 20 and can be set using config.defaults['nyquist.max_curve_magnitude'].
max_curve_offsetfloat, optional: When plotting scaled portion of the Nyquist plot, increase/decrease the magnitude by this fraction of the max_curve_magnitude to allow any overlaps between the primary and mirror curves to be avoided. The default value is 0.02 and can be set using config.defaults['nyquist.max_curve_magnitude'].
mirror_style[str, str] or False: Linestyles for mirror image of the Nyquist curve. The first element is used for unscaled portions of the Nyquist curve, the second element is used for portions that are scaled (using max_curve_magnitude). If False then omit completely. Default linestyle ([‘–’, ‘:’]) is determined by config.defaults['nyquist.mirror_style'].
omega_limitsarray_like of two values: Set limits for plotted frequency range. If Hz=True the limits are in Hz otherwise in rad/s. Specifying omega as a list of two elements is equivalent to providing omega_limits.
omega_numint, optional: Number of samples to use for the frequency range. Defaults to config.defaults['freqplot.number_of_samples']. Ignored if data is not a list of systems.
plotbool, optional: (legacy) If given, nyquist_plot returns the legacy return values of (counts, contours). If False, return the values with no plot.
primary_style[str, str], optional: Linestyles for primary image of the Nyquist curve. The first element is used for unscaled portions of the Nyquist curve, the second element is used for portions that are scaled (using max_curve_magnitude). Default linestyle ([‘-‘, ‘-.’]) is determined by config.defaults['nyquist.mirror_style'].
rcParamsdict: Override the default parameters used for generating plots. Default is set by config.defaults['ctrlplot.rcParams'].
return_contourbool, optional: (legacy) If True, return the encirclement count and Nyquist contour used to generate the Nyquist plot.
show_legendbool, optional: Force legend to be shown if True or hidden if False. If None, then show legend when there is more than one line on the plot or legend_loc has been specified.
start_markerstr, optional: Matplotlib marker to use to mark the starting point of the Nyquist plot. Defaults value is ‘o’ and can be set using config.defaults['nyquist.start_marker'].
start_marker_sizefloat, optional: Start marker size (in display coordinates). Default value is 4 and can be set using config.defaults['nyquist.start_marker_size'].
titlestr, optional: Set the title of the plot. Defaults to plot type and system name(s).
title_framestr, optional: Set the frame of reference used to center the plot title. If set to ‘axes’ (default), the horizontal position of the title will centered relative to the axes. If set to ‘figure’, it will be centered with respect to the figure (faster execution).
warn_nyquistbool, optional: If set to False, turn off warnings about frequencies above Nyquist.
warn_encirclementsbool, optional: If set to False, turn off warnings about number of encirclements not meeting the Nyquist criterion.