control.nyquist_plot

control.nyquist_plot(syslist, omega=None, plot=True, omega_limits=None, omega_num=None, label_freq=0, color=None, return_contour=False, warn_encirclements=True, warn_nyquist=True, **kwargs)

Nyquist plot for a system

Plots a Nyquist plot for the system over a (optional) frequency range. The curve is computed by evaluating the Nyqist 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
  • syslist (list of LTI) – List of linear input/output systems (single system is OK). Nyquist curves for each system are plotted on the same graph.

  • plot (boolean) – If True, plot magnitude

  • omega (array_like) – Set of frequencies to be evaluated, in rad/sec.

  • omega_limits (array_like of two values) – Limits to the range of frequencies. Ignored if omega is provided, and auto-generated if omitted.

  • omega_num (int) – Number of frequency samples to plot. Defaults to config.defaults[‘freqplot.number_of_samples’].

  • color (string) – Used to specify the color of the line and arrowhead.

  • return_contour (bool, optional) – If ‘True’, return the contour used to evaluate the Nyquist plot.

  • **kwargs (matplotlib.pyplot.plot() keyword properties, optional) – Additional keywords (passed to matplotlib)

Returns

  • count (int (or list of int if len(syslist) > 1)) – Number of encirclements of the point -1 by the Nyquist curve. If multiple systems are given, an array of counts is returned.

  • contour (ndarray (or list of ndarray if len(syslist) > 1)), optional) – The contour used to create the primary Nyquist curve segment, returned if return_contour is Tue. To obtain the Nyquist curve values, evaluate system(s) along contour.

  • Additional Parameters

  • ———————

  • arrows (int 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.

  • arrow_size (float, optional) – Arrowhead width and length (in display coordinates). Default value is 8 and can be set using config.defaults[‘nyquist.arrow_size’].

  • arrow_style (matplotlib.patches.ArrowStyle, optional) – Define style used for Nyquist curve arrows (overrides arrow_size).

  • encirclement_threshold (float, 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_direction (str, optional) – For poles on the imaginary axis, set the direction of indentation to be ‘right’ (default), ‘left’, or ‘none’.

  • indent_points (int, optional) – Number of points to insert in the Nyquist contour around poles that are at or near the imaginary axis.

  • indent_radius (float, 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.

  • label_freq (int, optiona) – Label every nth frequency on the plot. If not specified, no labels are generated.

  • max_curve_magnitude (float, 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.

  • max_curve_offset (float, 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.

  • 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’].

  • 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’].

  • start_marker (str, 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_size (float, optional) – Start marker size (in display coordinates). Default value is 4 and can be set using config.defaults[‘nyquist.start_marker_size’].

  • warn_nyquist (bool, optional) – If set to ‘False’, turn off warnings about frequencies above Nyquist.

  • warn_encirclements (bool, optional) – If set to ‘False’, turn off warnings about number of encirclements not meeting the Nyquist criterion.

Notes

  1. If a discrete time model is given, the frequency response is computed along the upper branch of the unit circle, using the mapping z = exp(1j * omega * dt) where omega ranges from 0 to pi/dt and dt is the discrete timebase. If timebase not specified (dt=True), dt is set to 1.

  2. If a continuous-time system contains poles on or near the imaginary axis, a small indentation will be used to avoid the pole. The radius of the indentation is given by indent_radius and it is taken to the right of stable poles and the left of unstable poles. If a pole is exactly on the imaginary axis, the indent_direction parameter can be used to set the direction of indentation. Setting indent_direction to none will turn off indentation. If return_contour is True, the exact contour used for evaluation is returned.

Examples

>>> sys = ss([[1, -2], [3, -4]], [[5], [7]], [[6, 8]], [[9]])
>>> count = nyquist_plot(sys)