control.nyquist_response

control.nyquist_response(sysdata, omega=None, plot=None, omega_limits=None, omega_num=None, return_contour=False, warn_encirclements=True, warn_nyquist=True, check_kwargs=True, **kwargs)[source]

Nyquist response for a system.

Computes a Nyquist contour for the system over a (optional) frequency range and evaluates the number of net encirclements. 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

  • sysdata (LTI or list of LTI) – List of linear input/output systems (single system is OK). Nyquist curves for each system are plotted on the same graph.

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

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

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

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

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

Returns

  • responses (list of NyquistResponseData) – For each system, a Nyquist response data object is returned. If sysdata is a single system, a single elemeent is returned (not a list). For each response, the following information is available:

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

  • response.contour (ndarray) – The contour used to create the primary Nyquist curve segment. To obtain the Nyquist curve values, evaluate system(s) along contour.

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.

  3. For those portions of the Nyquist plot in which the contour is indented to avoid poles, resuling in a scaling of the Nyquist plot, the line styles are according to the settings of the primary_style and mirror_style keywords. By default the scaled portions of the primary curve use a dotted line style and the scaled portion of the mirror image use a dashdot line style.

  4. If the legacy keyword return_contour is specified as True, the response object can be iterated over to return count, contour. This behavior is deprecated and will be removed in a future release.

Examples

>>> G = ct.zpk([], [-1, -2, -3], gain=100)
>>> response = ct.nyquist_response(G)
>>> count = response.count
>>> lines = response.plot()