control.nyquist_response

control.nyquist_response(sysdata, omega=None, omega_limits=None, omega_num=None, return_contour=False, warn_encirclements=True, warn_nyquist=True, _kwargs=None, _check_kwargs=True, **kwargs)

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

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

omegaarray_like, optional

Set of frequencies to be evaluated, in rad/sec.

Returns

responseslist of NyquistResponseData

For each system, a Nyquist response data object is returned. If sysdata is a single system, a single element is returned (not a list).

response.countint

Number of encirclements of the point -1 by the Nyquist curve. If multiple systems are given, an array of counts is returned.

response.contourndarray

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

Other Parameters

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’. The default value can be set using config.defaults['nyquist.indent_direction'].

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. The default value can be set using config.defaults['nyquist.indent_radius'].

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'].

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.

See also

nyquist_plot

Notes

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.

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.

For those portions of the Nyquist plot in which the contour is indented to avoid poles, resulting 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.

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
>>> cplt = response.plot()