rename 'type' keyword

bnavigator · murrayrm · commit c03b77178233 · 2023-03-18T10:33:23.000-07:00
diff --git a/control/statefbk.py b/control/statefbk.py
@@ -42,6 +42,7 @@
 # External packages and modules
 import numpy as np
 import scipy as sp
+import warnings
 
 from . import statesp
 from .mateqn import care, dare, _check_shape
@@ -597,10 +598,10 @@ def dlqr(*args, **kwargs):
 
 # Function to create an I/O sytems representing a state feedback controller
 def create_statefbk_iosystem(
-        sys, gain, integral_action=None, estimator=None, type=None,
+        sys, gain, integral_action=None, estimator=None, controller_type=None,
         xd_labels='xd[{i}]', ud_labels='ud[{i}]', gainsched_indices=None,
         gainsched_method='linear', name=None, inputs=None, outputs=None,
-        states=None):
+        states=None, **kwargs):
     """Create an I/O system using a (full) state feedback controller
 
     This function creates an input/output system that implements a
@@ -684,7 +685,7 @@ def create_statefbk_iosystem(
         hull of the scheduling points, the gain at the nearest point is
         used.
 
-    type : 'linear' or 'nonlinear', optional
+    controller_type : 'linear' or 'nonlinear', optional
         Set the type of controller to create. The default for a linear gain
         is a linear controller implementing the LQR regulator. If the type
         is 'nonlinear', a :class:NonlinearIOSystem is created instead, with
@@ -728,6 +729,18 @@ def create_statefbk_iosystem(
     if not isinstance(sys, InputOutputSystem):
         raise ControlArgument("Input system must be I/O system")
 
+    # Process (legacy) keywords
+    if kwargs.get('type') is not None:
+        warnings.warn(
+            "keyword 'type' is deprecated; use 'controller_type'",
+            DeprecationWarning)
+        if controller_type is not None:
+            raise ControlArgument(
+                "duplicate keywords 'type` and 'controller_type'")
+        controller_type = kwargs.pop('type')
+    if kwargs:
+        raise TypeError("unrecognized keywords: ", str(kwargs))
+
     # See whether we were give an estimator
     if estimator is not None:
         # Check to make sure the estimator is the right size
@@ -781,13 +794,14 @@ def create_statefbk_iosystem(
         raise ControlArgument("gain must be an array or a tuple")
 
     # Decide on the type of system to create
-    if gainsched and type == 'linear':
+    if gainsched and controller_type == 'linear':
         raise ControlArgument(
-            "type 'linear' not allowed for gain scheduled controller")
-    elif type is None:
-        type = 'nonlinear' if gainsched else 'linear'
-    elif type not in {'linear', 'nonlinear'}:
-        raise ControlArgument(f"unknown type '{type}'")
+            "controller_type 'linear' not allowed for"
+            " gain scheduled controller")
+    elif controller_type is None:
+        controller_type = 'nonlinear' if gainsched else 'linear'
+    elif controller_type not in {'linear', 'nonlinear'}:
+        raise ControlArgument(f"unknown controller_type '{controller_type}'")
 
     # Figure out the labels to use
     if isinstance(xd_labels, str):
@@ -845,7 +859,7 @@ def _compute_gain(mu):
             return K
 
     # Define the controller system
-    if type == 'nonlinear':
+    if controller_type == 'nonlinear':
         # Create an I/O system for the state feedback gains
         def _control_update(t, states, inputs, params):
             # Split input into desired state, nominal input, and current state
@@ -879,7 +893,7 @@ def _control_output(t, states, inputs, params):
             _control_update, _control_output, name=name, inputs=inputs,
             outputs=outputs, states=states, params=params)
 
-    elif type == 'linear' or type is None:
+    elif controller_type == 'linear' or controller_type is None:
         # Create the matrices implementing the controller
         if isctime(sys):
             # Continuous time: integrator
@@ -898,7 +912,7 @@ def _control_output(t, states, inputs, params):
             inputs=inputs, outputs=outputs, states=states)
 
     else:
-        raise ControlArgument(f"unknown type '{type}'")
+        raise ControlArgument(f"unknown controller_type '{controller_type}'")
 
     # Define the closed loop system
     closed = interconnect(
diff --git a/control/tests/statefbk_test.py b/control/tests/statefbk_test.py
@@ -6,6 +6,7 @@
 import numpy as np
 import pytest
 import itertools
+import warnings
 from math import pi, atan
 
 import control as ct
@@ -569,7 +570,12 @@ def test_statefbk_iosys(
 
         # Create an I/O system for the controller
         ctrl, clsys = ct.create_statefbk_iosystem(
-            sys, K, integral_action=C_int, estimator=est, type=type)
+            sys, K, integral_action=C_int, estimator=est,
+            controller_type=type, name=type)
+
+        # Make sure the name got set correctly
+        if type is not None:
+            assert ctrl.name == type
 
         # If we used a nonlinear controller, linearize it for testing
         if type == 'nonlinear':
@@ -763,8 +769,20 @@ def test_statefbk_errors(self):
         with pytest.raises(ControlArgument, match="gain must be an array"):
             ctrl, clsys = ct.create_statefbk_iosystem(sys, "bad argument")
 
-        with pytest.raises(ControlArgument, match="unknown type"):
-            ctrl, clsys = ct.create_statefbk_iosystem(sys, K, type=1)
+        with pytest.warns(DeprecationWarning, match="'type' is deprecated"):
+            ctrl, clsys = ct.create_statefbk_iosystem(sys, K, type='nonlinear')
+
+        with pytest.raises(ControlArgument, match="duplicate keywords"):
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore")
+                ctrl, clsys = ct.create_statefbk_iosystem(
+                    sys, K, type='nonlinear', controller_type='nonlinear')
+
+        with pytest.raises(TypeError, match="unrecognized keywords"):
+            ctrl, clsys = ct.create_statefbk_iosystem(sys, K, typo='nonlinear')
+
+        with pytest.raises(ControlArgument, match="unknown controller_type"):
+            ctrl, clsys = ct.create_statefbk_iosystem(sys, K, controller_type=1)
 
         # Errors involving integral action
         C_int = np.eye(2, 4)
