update params docstrings + warnings per @sawyerbfuller suggestion

murrayrm · murrayrm · commit a9a62267923a · 2022-11-12T23:22:47.000-08:00
diff --git a/control/iosys.py b/control/iosys.py
@@ -376,12 +376,12 @@ def dynamics(self, t, x, u, params=None):
         right hand side of the dynamical system. If the system is continuous,
         returns the time derivative
 
-            dx/dt = f(t, x, u, params)
+            dx/dt = f(t, x, u[, params])
 
         where `f` is the system's (possibly nonlinear) dynamics function.
         If the system is discrete-time, returns the next value of `x`:
 
-            x[t+dt] = f(t, x[t], u[t], params)
+            x[t+dt] = f(t, x[t], u[t][, params])
 
         where `t` is a scalar.
 
diff --git a/control/statesp.py b/control/statesp.py
@@ -1389,7 +1389,7 @@ def dcgain(self, warn_infinite=False):
         """
         return self._dcgain(warn_infinite)
 
-    def dynamics(self, t, x, u=None):
+    def dynamics(self, t, x, u=None, params=None):
         """Compute the dynamics of the system
 
         Given input `u` and state `x`, returns the dynamics of the state-space
@@ -1423,6 +1423,9 @@ def dynamics(self, t, x, u=None):
         dx/dt or x[t+dt] : ndarray
 
         """
+        if params is not None:
+            warn("params keyword ignored for StateSpace object")
+
         x = np.reshape(x, (-1, 1))  # force to a column in case matrix
         if np.size(x) != self.nstates:
             raise ValueError("len(x) must be equal to number of states")
@@ -1435,7 +1438,7 @@ def dynamics(self, t, x, u=None):
             return (self.A @ x).reshape((-1,)) \
                 + (self.B @ u).reshape((-1,))  # return as row vector
 
-    def output(self, t, x, u=None):
+    def output(self, t, x, u=None, params=None):
         """Compute the output of the system
 
         Given input `u` and state `x`, returns the output `y` of the
@@ -1465,6 +1468,9 @@ def output(self, t, x, u=None):
         -------
         y : ndarray
         """
+        if params is not None:
+            warn("params keyword ignored for StateSpace object")
+
         x = np.reshape(x, (-1, 1))  # force to a column in case matrix
         if np.size(x) != self.nstates:
             raise ValueError("len(x) must be equal to number of states")
diff --git a/control/tests/statesp_test.py b/control/tests/statesp_test.py
@@ -1158,3 +1158,15 @@ def test_linfnorm_ct_mimo(self, ct_siso):
         gpeak, fpeak = linfnorm(sys)
         np.testing.assert_allclose(gpeak, refgpeak)
         np.testing.assert_allclose(fpeak, reffpeak)
+
+
+# Make sure that using params for StateSpace objects generates a warning
+def test_params_warning():
+    sys = StateSpace(-1, 1, 1, 0)
+
+    with pytest.warns(UserWarning, match="params keyword ignored"):
+        sys.dynamics(0, [0], [0], {'k': 5})
+
+    with pytest.warns(UserWarning, match="params keyword ignored"):
+        sys.output(0, [0], [0], {'k': 5})
+
