clean up terminology and checks for "static" systems

murrayrm · murrayrm · commit ce77e6b3f72a · 2025-02-03T22:38:18.000-08:00
diff --git a/control/iosys.py b/control/iosys.py
@@ -757,10 +757,6 @@ def issiso(self):
         """Check to see if a system is single input, single output."""
         return self.ninputs == 1 and self.noutputs == 1
 
-    def _isstatic(self):
-        """Check to see if a system is a static system (no states)"""
-        return self.nstates == 0
-
 
 # Test to see if a system is SISO
 def issiso(sys, strict=False):
diff --git a/control/nlsys.py b/control/nlsys.py
@@ -181,7 +181,7 @@ def __call__(sys, u, params=None, squeeze=None):
 
         """
         # Make sure the call makes sense
-        if not sys._isstatic():
+        if sys.nstates != 0:
             raise TypeError(
                 "function evaluation is only supported for static "
                 "input/output systems")
@@ -199,7 +199,7 @@ def __call__(sys, u, params=None, squeeze=None):
     def __mul__(self, other):
         """Multiply two input/output systems (series interconnection)"""
         # Convert 'other' to an I/O system if needed
-        other = _convert_static_iosystem(other)
+        other = _convert_to_iosystem(other)
         if not isinstance(other, InputOutputSystem):
             return NotImplemented
 
@@ -231,7 +231,7 @@ def __mul__(self, other):
     def __rmul__(self, other):
         """Pre-multiply an input/output systems by a scalar/matrix"""
         # Convert other to an I/O system if needed
-        other = _convert_static_iosystem(other)
+        other = _convert_to_iosystem(other)
         if not isinstance(other, InputOutputSystem):
             return NotImplemented
 
@@ -263,7 +263,7 @@ def __rmul__(self, other):
     def __add__(self, other):
         """Add two input/output systems (parallel interconnection)"""
         # Convert other to an I/O system if needed
-        other = _convert_static_iosystem(other)
+        other = _convert_to_iosystem(other)
         if not isinstance(other, InputOutputSystem):
             return NotImplemented
 
@@ -284,7 +284,7 @@ def __add__(self, other):
     def __radd__(self, other):
         """Parallel addition of input/output system to a compatible object."""
         # Convert other to an I/O system if needed
-        other = _convert_static_iosystem(other)
+        other = _convert_to_iosystem(other)
         if not isinstance(other, InputOutputSystem):
             return NotImplemented
 
@@ -305,7 +305,7 @@ def __radd__(self, other):
     def __sub__(self, other):
         """Subtract two input/output systems (parallel interconnection)"""
         # Convert other to an I/O system if needed
-        other = _convert_static_iosystem(other)
+        other = _convert_to_iosystem(other)
         if not isinstance(other, InputOutputSystem):
             return NotImplemented
 
@@ -329,7 +329,7 @@ def __sub__(self, other):
     def __rsub__(self, other):
         """Parallel subtraction of I/O system to a compatible object."""
         # Convert other to an I/O system if needed
-        other = _convert_static_iosystem(other)
+        other = _convert_to_iosystem(other)
         if not isinstance(other, InputOutputSystem):
             return NotImplemented
         return other - self
@@ -355,6 +355,10 @@ def __truediv__(self, other):
         else:
             return NotImplemented
 
+    # Determine if a system is static (memoryless)
+    def _isstatic(self):
+        return self.nstates == 0
+
     def _update_params(self, params):
         # Update the current parameter values
         self._current_params = self.params.copy()
@@ -484,7 +488,7 @@ def feedback(self, other=1, sign=-1, params=None):
 
         """
         # Convert sys2 to an I/O system if needed
-        other = _convert_static_iosystem(other)
+        other = _convert_to_iosystem(other)
 
         # Make sure systems can be interconnected
         if self.noutputs != other.ninputs or other.noutputs != self.ninputs:
@@ -932,6 +936,7 @@ def _out(self, t, x, u):
         # Make the full set of subsystem outputs to system output
         return self.output_map @ ylist
 
+    # Find steady state (static) inputs and outputs
     def _compute_static_io(self, t, x, u):
         # Figure out the total number of inputs and outputs
         (ninputs, noutputs) = self.connect_map.shape
@@ -1711,8 +1716,8 @@ def ufun(t):
         dt = (t - T[idx-1]) / (T[idx] - T[idx-1])
         return U[..., idx-1] * (1. - dt) + U[..., idx] * dt
 
-    # Check to make sure this is not a static function
-    if sys._isstatic():
+    # Check to make sure see if this is a static function
+    if sys.nstates == 0:
         # Make sure the user gave a time vector for evaluation (or 'T')
         if t_eval is None:
             # User overrode t_eval with None, but didn't give us the times...
@@ -2924,8 +2929,8 @@ def _process_vector_argument(arg, name, size):
     return val, nelem
 
 
-# Utility function to create an I/O system from a static gain
-def _convert_static_iosystem(sys):
+# Utility function to create an I/O system (from number or array)
+def _convert_to_iosystem(sys):
     # If we were given an I/O system, do nothing
     if isinstance(sys, InputOutputSystem):
         return sys
diff --git a/control/statesp.py b/control/statesp.py
@@ -229,6 +229,9 @@ def __init__(self, *args, **kwargs):
         self.C = C
         self.D = D
 
+        # Determine if the system is static (memoryless)
+        static = (A.size == 0)
+
         #
         # Process keyword arguments
         #
@@ -242,7 +245,7 @@ def __init__(self, *args, **kwargs):
             {'inputs': B.shape[1], 'outputs': C.shape[0],
              'states': A.shape[0]}
         name, inputs, outputs, states, dt = _process_iosys_keywords(
-            kwargs, defaults, static=(A.size == 0))
+            kwargs, defaults, static=static)
 
         # Create updfcn and outfcn
         updfcn = lambda t, x, u, params: \
@@ -257,7 +260,7 @@ def __init__(self, *args, **kwargs):
             states=states, dt=dt, **kwargs)
 
         # Reset shapes if the system is static
-        if self._isstatic():
+        if static:
             A.shape = (0, 0)
             B.shape = (0, self.ninputs)
             C.shape = (self.noutputs, 0)
diff --git a/control/xferfcn.py b/control/xferfcn.py
@@ -219,16 +219,22 @@ def __init__(self, *args, **kwargs):
             raise ValueError("display_format must be 'poly' or 'zpk',"
                              " got '%s'" % self.display_format)
 
-        # Determine if the transfer function is static (needed for dt)
+        #
+        # Determine if the transfer function is static (memoryless)
+        #
+        # True if and only if all of the numerator and denominator
+        # polynomials of the (MIMO) transfer function are zeroth order.
+        #
         static = True
         for arr in [num, den]:
+            # Iterate using refs_OK since num and den are ndarrays of ndarrays
             for poly_ in np.nditer(arr, flags=['refs_ok']):
                 if poly_.item().size > 1:
                     static = False
                     break
             if not static:
                 break
-        self._static = static
+        self._static = static           # retain for later usage
 
         defaults = args[0] if len(args) == 1 else \
             {'inputs': num.shape[1], 'outputs': num.shape[0]}
@@ -1284,12 +1290,9 @@ def dcgain(self, warn_infinite=False):
         """
         return self._dcgain(warn_infinite)
 
+    # Determine if a system is static (memoryless)
     def _isstatic(self):
-        """returns True if and only if all of the numerator and denominator
-        polynomials of the (possibly MIMO) transfer function are zeroth order,
-        that is, if the system has no dynamics. """
-        # Check done at initialization
-        return self._static
+        return self._static             # Check done at initialization
 
     # Attributes for differentiation and delay
     #
diff --git a/doc/nlsys.rst b/doc/nlsys.rst
@@ -23,6 +23,11 @@ Discrete time systems are also supported and have dynamics of the form
    x[t+1] &= f(t, x[t], u[t], \theta), \\
    y[t] &= h(t, x[t], u[t], \theta).
 
+A nonlinear input/output model is said to be "static" if the output
+:math:`y(t)` at any given time :math:`t` depends only on the input
+:math:`u(t)` at that same time :math:`t` and not on past or future
+values of :math:`u`.
+
 
 .. _sec-nonlinear-models:
 
@@ -47,7 +52,9 @@ dynamics of the system can be in continuous or discrete time (use the
 The output function `outfcn` is used to specify the outputs of the
 system and has the same calling signature as `updfcn`.  If it is not
 specified, then the output of the system is set equal to the system
-state.  Otherwise, it should return an array of shape (p,).
+state.  Otherwise, it should return an array of shape (p,).  If a
+input/output system is static, the state `x` should still be passed to
+the output function, but the state is ignored.
 
 Note that the number of states, inputs, and outputs should generally
 be explicitly specified, although some operations can infer the
