refactoring of nyquist into response/plot + updated unit tests, examples

murrayrm · Sep 16, 2023 · Jul 1, 2023 · Jul 4, 2023 · Jul 4, 2023 · Jul 7, 2023
commit e5360dc0d8073e75481b379ea7c44b6c9a9fb150
diff --git a/control/ctrlutil.py b/control/ctrlutil.py
@@ -86,18 +86,9 @@ def unwrap(angle, period=2*math.pi):
     return angle
 
 def issys(obj):
-    """Return True if an object is a Linear Time Invariant (LTI) system,
-    otherwise False.
+    """Deprecated function to check if an object is an LTI system.
 
-    Examples
-    --------
-    >>> G = ct.tf([1], [1, 1])
-    >>> ct.issys(G)
-    True
-
-    >>> K = np.array([[1, 1]])
-    >>> ct.issys(K)
-    False
+    Use isinstance(obj, ct.LTI)
 
     """
     warnings.warn("issys() is deprecated; use isinstance(obj, ct.LTI)",

diff --git a/control/descfcn.py b/control/descfcn.py
@@ -18,7 +18,7 @@
 import scipy
 from warnings import warn
 
-from .freqplot import nyquist_plot
+from .freqplot import nyquist_response
 
 __all__ = ['describing_function', 'describing_function_plot',
            'DescribingFunctionNonlinearity', 'friction_backlash_nonlinearity',
@@ -259,10 +259,11 @@ def describing_function_plot(
         warn = omega is None
 
     # Start by drawing a Nyquist curve
-    count, contour = nyquist_plot(
-        H, omega, plot=True, return_contour=True,
-        warn_encirclements=warn, warn_nyquist=warn, **kwargs)
-    H_omega, H_vals = contour.imag, H(contour)
+    response = nyquist_response(
+        H, omega, warn_encirclements=warn, warn_nyquist=warn,
+        check_kwargs=False, **kwargs)
+    response.plot(**kwargs)
+    H_omega, H_vals = response.contour.imag, H(response.contour)
 
     # Compute the describing function
     df = describing_function(F, A)

diff --git a/control/freqplot.py b/control/freqplot.py
diff --git a/control/lti.py b/control/lti.py
@@ -13,7 +13,7 @@
 from .iosys import InputOutputSystem
 
 __all__ = ['poles', 'zeros', 'damp', 'evalfr', 'frequency_response',
-           'freqresp', 'dcgain', 'bandwidth']
+           'freqresp', 'dcgain', 'bandwidth', 'LTI']
 
 
 class LTI(InputOutputSystem):
@@ -466,10 +466,8 @@ def frequency_response(
         if sys_.isdtime(strict=True):
             nyquistfrq = math.pi / sys_.dt
             if not omega_range_given:
-                # limit up to and including nyquist frequency
-                # TODO: make this optional?
-                omega_sys = np.hstack((
-                    omega_sys[omega_sys < nyquistfrq], nyquistfrq))
+                # Limit up to the Nyquist frequency
+                omega_sys = omega_sys[omega_sys < nyquistfrq]
 
         # Compute the frequency response
         responses.append(sys_.frequency_response(omega_sys, squeeze=squeeze))

diff --git a/control/matlab/wrappers.py b/control/matlab/wrappers.py
@@ -90,7 +90,7 @@ def bode(*args, **kwargs):
     return retval
 
 
-def nyquist(*args, **kwargs):
+def nyquist(*args, plot=True, **kwargs):
     """nyquist(syslist[, omega])
 
     Nyquist plot of the frequency response.
@@ -114,7 +114,7 @@ def nyquist(*args, **kwargs):
         frequencies in rad/s
 
     """
-    from ..freqplot import nyquist_plot
+    from ..freqplot import nyquist_response, nyquist_plot
 
     # If first argument is a list, assume python-control calling format
     if hasattr(args[0], '__iter__'):
@@ -125,8 +125,10 @@ def nyquist(*args, **kwargs):
     kwargs.update(other)
 
     # Call the nyquist command
-    kwargs['return_contour'] = True
-    _, contour = nyquist_plot(syslist, omega, *args, **kwargs)
+    response = nyquist_response(syslist, omega, *args, **kwargs)
+    contour = response.contour
+    if plot:
+        nyquist_plot(response, *args, **kwargs)
 
     # Create the MATLAB output arguments
     freqresp = syslist(contour)

diff --git a/control/tests/kwargs_test.py b/control/tests/kwargs_test.py
@@ -110,6 +110,8 @@ def test_kwarg_search(module, prefix):
       (lambda x, u, params: None, lambda zflag, params: None), {}),
      (control.InputOutputSystem, 0, 0, (),
       {'inputs': 1, 'outputs': 1, 'states': 1}),
+     (control.LTI, 0, 0, (),
+      {'inputs': 1, 'outputs': 1, 'states': 1}),
      (control.flatsys.LinearFlatSystem, 1, 0, (), {}),
      (control.NonlinearIOSystem.linearize, 1, 0, (0, 0), {}),
      (control.StateSpace.sample, 1, 0, (0.1,), {}),
@@ -156,26 +158,32 @@ def test_matplotlib_kwargs(function, nsysargs, moreargs, kwargs, mplcleanup):
     function(*args, **kwargs)
 
     # Now add an unrecognized keyword and make sure there is an error
-    with pytest.raises(AttributeError,
-                       match="(has no property|unexpected keyword)"):
+    with pytest.raises(
+            (AttributeError, TypeError),
+            match="(has no property|unexpected keyword|unrecognized keyword)"):
         function(*args, **kwargs, unknown=None)
 
 
 @pytest.mark.parametrize(
-    "data_fcn, plot_fcn", [
-        (control.step_response, control.time_response_plot),
-        (control.step_response, control.TimeResponseData.plot),
-        (control.frequency_response, control.FrequencyResponseData.plot),
-        (control.frequency_response, control.bode),
-        (control.frequency_response, control.bode_plot),
+    "data_fcn, plot_fcn, mimo", [
+        (control.step_response, control.time_response_plot, True),
+        (control.step_response, control.TimeResponseData.plot, True),
+        (control.frequency_response, control.FrequencyResponseData.plot, True),
+        (control.frequency_response, control.bode, True),
+        (control.frequency_response, control.bode_plot, True),
+        (control.nyquist_response, control.nyquist_plot, False),
     ])
-def test_response_plot_kwargs(data_fcn, plot_fcn):
+def test_response_plot_kwargs(data_fcn, plot_fcn, mimo):
     # Create a system for testing
-    response = data_fcn(control.rss(4, 2, 2))
+    if mimo:
+        response = data_fcn(control.rss(4, 2, 2))
+    else:
+        response = data_fcn(control.rss(4, 1, 1))
 
     # Make sure that calling the data function with unknown keyword errs
-    with pytest.raises((AttributeError, TypeError),
-                       match="(has no property|unexpected keyword)"):
+    with pytest.raises(
+            (AttributeError, TypeError),
+            match="(has no property|unexpected keyword|unrecognized keyword)"):
         data_fcn(control.rss(2, 1, 1), unknown=None)
 
     # Call the plotting function normally and make sure it works
@@ -216,6 +224,7 @@ def test_response_plot_kwargs(data_fcn, plot_fcn):
     'lqr': test_unrecognized_kwargs,
     'nlsys': test_unrecognized_kwargs,
     'nyquist': test_matplotlib_kwargs,
+    'nyquist_response': test_response_plot_kwargs,
     'nyquist_plot': test_matplotlib_kwargs,
     'pzmap': test_unrecognized_kwargs,
     'rlocus': test_unrecognized_kwargs,
@@ -245,6 +254,7 @@ def test_response_plot_kwargs(data_fcn, plot_fcn):
         frd_test.TestFRD.test_unrecognized_keyword,
     'FrequencyResponseData.plot': test_response_plot_kwargs,
     'InputOutputSystem.__init__': test_unrecognized_kwargs,
+    'LTI.__init__': test_unrecognized_kwargs,
     'flatsys.LinearFlatSystem.__init__': test_unrecognized_kwargs,
     'NonlinearIOSystem.linearize': test_unrecognized_kwargs,
     'InterconnectedSystem.__init__':