GeezerVison

This PR fixes a bug in the the way that the nyquist_plot command was implemented and introduces a bunch of enhancements, including some of the ideas in PR #671.

Bug fix: because of the new default parameter settings introduced in #534, it was possible for the indentation around an open-loop pole that was near the imaginary axis to exclude a region in the right half-plane that contained a closed-loop pole (so, for example, if you had a stable open-loop pole at -0.05 and an unstable closed-loop pole at 0.05, the default indentation of 0.1 would cause you to miss the encirclement). This has now been fixed by (1) generating a warning when the indented contour bypasses a closed loop pole and (2) implementing new functionality that allows the default indentation to be reduced (to 1e-4) while still keeping the magnitude of the Nyquist plot within reasonable limits.

Enhancements: in fixing the bug above, it was necessary to find a better balance between the size of the indentation and the magnitude of the Nyquist curve. This is also the goal of PR #671. The following changes have been done to implement this:

• There is now a max_curve_magnitude function that limits the size of the plotted Nyquist curve. The default value for this parameter is 20, which is small enough that that -1 point is still visible in the plot. All points on the curve that are greater than the maximum magnitude specified are scaled so that the angle of the curve is preserved, but the magnitude is limited. The value for this parameter can be passed as a keyword argument or set using ct.defaults.
• Portions of the Nyquist curve that have been scaled as well as portions of the curve corresponding to segments of the Nyquist contour that have been indented are now plotted in a different line style, so that it is more clear that these portions of the curve are not quantitatively accurate. The line styles can be set using the primary_linestyle and mirror_linestyle keywords and default to ['-', '-.'] and ['--', ':'].
• The logic for inserting indentations has been improved and the indentations are now done based on the location of near imaginary poles. This results in smoother curves near zero frequency and more accurate curves around near-imaginary poles.
• A new curve_offset keyword can be used so that overlapping sections of the Nyquist curve (typically at the limit values set by max_curve_magnitude are now separated out by a small amount (by adjusting the primary curve outward and the mirror curve inward by a small amount that is smooth at the end of the scaled sections).
• A marker is placed at the zero frequency point on the Nyquist curve, to help add in determining where the curve "starts". The type of marker is controlled by the start_marker keyword and the size of the marker is controlled with the start_marker_size keyword (default = a filled circle of size 4).
• Several warnings have been added for situations where the Nyquist plot may not be an accurate representation:
  • If the number of net encirclements is not an integer (i.e., the Nyquist curve is not closed). This warning can be turned off using warn_encirclements=False.
  • If an indention occurs around an open-loop pole that might cause a closed-loop pole to occur outside the (indented) Nyquist contour.
  • If there are open-loop poles on the imaginary access and indentation is turned off (which can result in an incorrect Nyquist curve).
  • If the Nyquist criterion is not met (number of encirclements does not match the stability of the closed-loop system, taking into account closed-loop poles).
• The original behavior (parameter settings) of v0.9.1 can be obtained using use_legacy_defaults('0.9.1').

The new features can be seen in the following example

sys = ct.tf([1], [1, 3, 2]) * ct.tf([1], [1, 0, 1])
count = ct.nyquist_plot(sys)

which produces the following plot:

Features to note:

• Use of dash-dot and dotted line styles to mark sections of the curve that have been scaled.
• Use of a marker at zero frequency
• Offset between the primary curve and mirror curve at large magnitudes (so that they don't completely overlap)

Comparisons between old and new Nyquist plots:

Old	New	Comments
		Better curves at zero frequency (with marker)
		Better default scaling for curves with large magnitude (and marking of scaled portion of curve)
		Better marking of scaled portion of the curve
		No change to "regular" Nyquist plots (except for the marker at zero frequency).