update MATLAB interface to bode, nyquist

murrayrm · murrayrm · commit 6de5e91b4fd8 · 2021-02-10T22:02:09.000-08:00
* regularize argument parsing by using _parse_freqplot_args
* fix bug in exception handling (ControlArgument not defined)
* change printed warning to use warnings.warn
* add unit tests for exceptions, warnings
diff --git a/control/matlab/__init__.py b/control/matlab/__init__.py
@@ -70,7 +70,7 @@
 
 # Import MATLAB-like functions that can be used as-is
 from ..ctrlutil import *
-from ..freqplot import nyquist, gangof4
+from ..freqplot import gangof4
 from ..nichols import nichols
 from ..bdalg import *
 from ..pzmap import *
diff --git a/control/matlab/wrappers.py b/control/matlab/wrappers.py
@@ -1,15 +1,18 @@
 """
-Wrappers for the Matlab compatibility module
+Wrappers for the MATLAB compatibility module
 """
 
 import numpy as np
 from ..statesp import ss
 from ..xferfcn import tf
+from ..ctrlutil import issys
+from ..exception import ControlArgument
 from scipy.signal import zpk2tf
+from warnings import warn
 
-__all__ = ['bode', 'ngrid', 'dcgain']
+__all__ = ['bode', 'nyquist', 'ngrid', 'dcgain']
 
-def bode(*args, **keywords):
+def bode(*args, **kwargs):
     """bode(syslist[, omega, dB, Hz, deg, ...])
 
     Bode plot of the frequency response
@@ -36,7 +39,7 @@ def bode(*args, **keywords):
         If True, plot frequency in Hz (omega must be provided in rad/sec)
     deg : boolean
         If True, return phase in degrees (else radians)
-    Plot : boolean
+    plot : boolean
         If True, plot magnitude and phase
 
     Examples
@@ -53,19 +56,65 @@ def bode(*args, **keywords):
         * >>> bode(sys1, sys2, ..., sysN, w)
         * >>> bode(sys1, 'plotstyle1', ..., sysN, 'plotstyleN')
     """
+    from ..freqplot import bode_plot
 
-    # If the first argument is a list, then assume python-control calling format
-    from ..freqplot import bode as bode_orig
+    # If first argument is a list, assume python-control calling format
     if (getattr(args[0], '__iter__', False)):
-        return bode_orig(*args, **keywords)
+        return bode_plot(*args, **kwargs)
 
-    # Otherwise, run through the arguments and collect up arguments
-    syslist = []; plotstyle=[]; omega=None;
+    # Parse input arguments
+    syslist, omega, args, other = _parse_freqplot_args(*args)
+    kwargs.update(other)
+
+    # Call the bode command
+    return bode_plot(syslist, omega, *args, **kwargs)
+
+
+def nyquist(*args, **kwargs):
+    """nyquist(syslist[, omega])
+
+    Nyquist plot of the frequency response
+
+    Plots a Nyquist plot for the system over a (optional) frequency range.
+
+    Parameters
+    ----------
+    sys1, ..., sysn : list of LTI
+        List of linear input/output systems (single system is OK).
+    omega : array_like
+        Set of frequencies to be evaluated, in rad/sec.
+
+    Returns
+    -------
+    real : ndarray (or list of ndarray if len(syslist) > 1))
+        real part of the frequency response array
+    imag : ndarray (or list of ndarray if len(syslist) > 1))
+        imaginary part of the frequency response array
+    omega : ndarray (or list of ndarray if len(syslist) > 1))
+        frequencies in rad/s
+
+    """
+    from ..freqplot import nyquist_plot
+
+    # If first argument is a list, assume python-control calling format
+    if (getattr(args[0], '__iter__', False)):
+        return nyquist_plot(*args, **kwargs)
+
+    # Parse arguments
+    syslist, omega, args, other = _parse_freqplot_args(*args)
+    kwargs.update(other)
+
+    # Call the nyquist command
+    return nyquist_plot(syslist, omega, *args, **kwargs)
+
+
+def _parse_freqplot_args(*args):
+    """Parse arguments to frequency plot routines (bode, nyquist)"""
+    syslist, plotstyle, omega, other = [], [], None, {}
     i = 0;
     while i < len(args):
         # Check to see if this is a system of some sort
-        from ..ctrlutil import issys
-        if (issys(args[i])):
+        if issys(args[i]):
             # Append the system to our list of systems
             syslist.append(args[i])
             i += 1
@@ -79,11 +128,16 @@ def bode(*args, **keywords):
             continue
 
         # See if this is a frequency list
-        elif (isinstance(args[i], (list, np.ndarray))):
+        elif isinstance(args[i], (list, np.ndarray)):
             omega = args[i]
             i += 1
             break
 
+        # See if this is a frequency range
+        elif isinstance(args[i], tuple) and len(args[i]) == 2:
+            other['omega_limits'] = args[i]
+            i += 1
+
         else:
             raise ControlArgument("unrecognized argument type")
 
@@ -93,22 +147,30 @@ def bode(*args, **keywords):
 
     # Check to make sure we got the same number of plotstyles as systems
     if (len(plotstyle) != 0 and len(syslist) != len(plotstyle)):
-        raise ControlArgument("number of systems and plotstyles should be equal")
+        raise ControlArgument(
+            "number of systems and plotstyles should be equal")
 
     # Warn about unimplemented plotstyles
     #! TODO: remove this when plot styles are implemented in bode()
     #! TODO: uncomment unit test code that tests this out
     if (len(plotstyle) != 0):
-        print("Warning (matlab.bode): plot styles not implemented");
+        warn("Warning (matlab.bode): plot styles not implemented");
+
+    if len(syslist) == 0:
+        raise ControlArgument("no systems specified")
+    elif len(syslist) == 1:
+    # If only one system given, retun just that system (not a list)
+        syslist = syslist[0]
+
+    return syslist, omega, plotstyle, other
 
-    # Call the bode command
-    return bode_orig(syslist, omega, **keywords)
 
 from ..nichols import nichols_grid
 def ngrid():
     return nichols_grid()
 ngrid.__doc__ = nichols_grid.__doc__
 
+
 def dcgain(*args):
     '''
     Compute the gain of the system in steady state.
diff --git a/control/tests/matlab_test.py b/control/tests/matlab_test.py
@@ -27,7 +27,7 @@
 from control.matlab import pade
 from control.matlab import unwrap, c2d, isctime, isdtime
 from control.matlab import connect, append
-
+from control.exception import ControlArgument
 
 from control.frdata import FRD
 from control.tests.conftest import slycotonly
@@ -802,6 +802,28 @@ def test_tf_string_args(self):
         np.testing.assert_array_almost_equal(G.den, [[[1, 2, 1]]])
         assert isdtime(G, strict=True)
 
+    def test_matlab_wrapper_exceptions(self):
+        """Test out exceptions in matlab/wrappers.py"""
+        sys = tf([1], [1, 2, 1])
+
+        # Extra arguments in bode
+        with pytest.raises(ControlArgument, match="not all arguments"):
+            bode(sys, 'r-', [1e-2, 1e2], 5.0)
+
+        # Multiple plot styles
+        with pytest.warns(UserWarning, match="plot styles not implemented"):
+            bode(sys, 'r-', sys, 'b--', [1e-2, 1e2])
+
+        # Incorrect number of arguments to dcgain
+        with pytest.raises(ValueError, match="needs either 1, 2, 3 or 4"):
+            dcgain(1, 2, 3, 4, 5)
+
+    def test_matlab_freqplot_passthru(self):
+        """Test nyquist and bode to make sure the pass arguments through"""
+        sys = tf([1], [1, 2, 1])
+        bode((sys,))            # Passing tuple will call bode_plot
+        nyquist((sys,))         # Passing tuple will call nyquist_plot
+
 
 #! TODO: not yet implemented
 #    def testMIMOtfdata(self):
