update squeeze processing for time responses + doc updates

murrayrm · murrayrm · commit 47bbf169b3c2 · 2021-01-19T08:58:11.000-08:00
diff --git a/control/config.py b/control/config.py
@@ -18,6 +18,7 @@
     'control.default_dt': 0,
     'control.squeeze_frequency_response': None,
     'control.squeeze_time_response': True,
+    'control.squeeze_time_response': None,
     'forced_response.return_x': False,
 }
 defaults = dict(_control_defaults)
@@ -236,4 +237,7 @@ def use_legacy_defaults(version):
         # forced_response no longer returns x by default
         set_defaults('forced_response', return_x=True)
 
+        # time responses are only squeezed if SISO
+        set_defaults('control', squeeze_time_response=True)
+
     return (major, minor, patch)
diff --git a/control/iosys.py b/control/iosys.py
@@ -450,6 +450,10 @@ def find_state(self, name):
         """Find the index for a state given its name (`None` if not found)"""
         return self.state_index.get(name, None)
 
+    def issiso(self):
+        """Check to see if a system is single input, single output"""
+        return self.ninputs == 1 and self.noutputs == 1
+
     def feedback(self, other=1, sign=-1, params={}):
         """Feedback interconnection between two input/output systems
 
@@ -1373,18 +1377,22 @@ def input_output_response(sys, T, U=0., X0=0, params={}, method='RK45',
     return_x : bool, optional
         If True, return the values of the state at each time (default = False).
     squeeze : bool, optional
-        If True and if the system has a single output, return the
-        system output as a 1D array rather than a 2D array.  Default
-        value (True) set by config.defaults['control.squeeze_time_response'].
+        If True and if the system has a single output, return the system
+        output as a 1D array rather than a 2D array.  If False, return the
+        system output as a 2D array even if the system is SISO.  Default value
+        set by config.defaults['control.squeeze_time_response'].
 
     Returns
     -------
     T : array
         Time values of the output.
     yout : array
-        Response of the system.
+        Response of the system.  If the system is SISO and squeeze is not
+        True, the array is 1D (indexed by time).  If the system is not SISO or
+        squeeze is False, the array is 2D (indexed by the output number and
+        time).
     xout : array
-        Time evolution of the state vector (if return_x=True)
+        Time evolution of the state vector (if return_x=True).
 
     Raises
     ------
diff --git a/control/tests/iosys_test.py b/control/tests/iosys_test.py
@@ -158,7 +158,7 @@ def test_nonlinear_iosys(self, tsys):
         nlout = lambda t, x, u, params: \
             np.reshape(np.dot(linsys.C, np.reshape(x, (-1, 1)))
                        + np.dot(linsys.D, u), (-1,))
-        nlsys = ios.NonlinearIOSystem(nlupd, nlout)
+        nlsys = ios.NonlinearIOSystem(nlupd, nlout, inputs=1, outputs=1)
 
         # Make sure that simulations also line up
         T, U, X0 = tsys.T, tsys.U, tsys.X0
diff --git a/control/tests/timeresp_test.py b/control/tests/timeresp_test.py
@@ -723,26 +723,22 @@ def test_time_series_data_convention_2D(self, siso_ss1):
         assert y.ndim == 1  # SISO returns "scalar" output
         assert t.shape == y.shape  # Allows direct plotting of output
 
+    @pytest.mark.usefixtures("editsdefaults")
     @pytest.mark.parametrize("fcn", [ct.ss, ct.tf, ct.ss2io])
     @pytest.mark.parametrize("nstate, nout, ninp, squeeze, shape", [
         [1, 1, 1, None, (8,)],
         [2, 1, 1, True, (8,)],
         [3, 1, 1, False, (1, 8)],
-#       [4, 1, 1, 'siso', (8,)],        # Use for later 'siso' implementation
         [3, 2, 1, None, (2, 8)],
         [4, 2, 1, True, (2, 8)],
         [5, 2, 1, False, (2, 8)],
-#       [6, 2, 1, 'siso', (2, 8)],      # Use for later 'siso' implementation
-        [3, 1, 2, None, (8,)],
+        [3, 1, 2, None, (1, 8)],
         [4, 1, 2, True, (8,)],
         [5, 1, 2, False, (1, 8)],
-#       [6, 1, 2, 'siso', (1, 8)],      # Use for later 'siso' implementation
         [4, 2, 2, None, (2, 8)],
         [5, 2, 2, True, (2, 8)],
         [6, 2, 2, False, (2, 8)],
-#       [7, 2, 2, 'siso', (2, 8)],      # Use for later 'siso' implementation
     ])
-    @pytest.mark.usefixtures("editsdefaults")
     def test_squeeze(self, fcn, nstate, nout, ninp, squeeze, shape):
         # Figure out if we have SciPy 1+
         scipy0 = StrictVersion(sp.__version__) < '1.0'
@@ -789,7 +785,6 @@ def test_squeeze(self, fcn, nstate, nout, ninp, squeeze, shape):
         _, yvec = ct.step_response(
             sys, tvec, input=ninp-1, output=nout-1, squeeze=squeeze)
         # Possible code if we implemenet a squeeze='siso' option
-        # if squeeze is False or (squeeze == 'siso' and not sys.issiso()):
         if squeeze is False:
             # Shape should be unsqueezed
             assert yvec.shape == (1, 8)
@@ -836,3 +831,33 @@ def test_squeeze_exception(self, fcn):
         sys = fcn(ct.rss(2, 1, 1))
         with pytest.raises(ValueError, match="unknown squeeze value"):
             step_response(sys, squeeze=1)
+
+    @pytest.mark.usefixtures("editsdefaults")
+    @pytest.mark.parametrize("nstate, nout, ninp, squeeze, shape", [
+        [1, 1, 1, None, (8,)],
+        [2, 1, 1, True, (8,)],
+        [3, 1, 1, False, (1, 8)],
+        [1, 2, 1, None, (2, 8)],
+        [2, 2, 1, True, (2, 8)],
+        [3, 2, 1, False, (2, 8)],
+        [1, 1, 2, None, (8,)],
+        [2, 1, 2, True, (8,)],
+        [3, 1, 2, False, (1, 8)],
+        [1, 2, 2, None, (2, 8)],
+        [2, 2, 2, True, (2, 8)],
+        [3, 2, 2, False, (2, 8)],
+    ])
+    def test_squeeze_0_8_4(self, nstate, nout, ninp, squeeze, shape):
+        # Set defaults to match release 0.8.4
+        ct.config.use_legacy_defaults('0.8.4')
+        ct.config.use_numpy_matrix(False)
+
+        # Generate system, time, and input vectors
+        sys = ct.rss(nstate, nout, ninp, strictly_proper=True)
+        tvec = np.linspace(0, 1, 8)
+        uvec = np.dot(
+            np.ones((sys.inputs, 1)),
+            np.reshape(np.sin(tvec), (1, 8)))
+
+        _, yvec = ct.initial_response(sys, tvec, 1, squeeze=squeeze)
+        assert yvec.shape == shape
diff --git a/control/timeresp.py b/control/timeresp.py
@@ -242,19 +242,27 @@ def forced_response(sys, T=None, U=0., X0=0., transpose=False,
         return only the time and output vectors.
 
     squeeze : bool, optional
-        If True (default), remove single-dimensional entries from the shape
-        of the output.  For single output systems, this converts the output
-        response to a 1D array.  The default value can be set using
+        By default, if a system is single-input, single-output (SISO) then
+        the output response is returned as a 1D array (indexed by time).  If
+        squeeze=True, remove single-dimensional entries from the shape of
+        the output even if the system is not SISO. If squeeze=False, keep
+        the output as a 2D array (indexed by the output number and time)
+        even if the system is SISO. The default value can be set using
         config.defaults['control.squeeze_time_response'].
 
     Returns
     -------
     T : array
         Time values of the output.
+
     yout : array
-        Response of the system.
+        Response of the system.  If the system is SISO and squeeze is not
+        True, the array is 1D (indexed by time).  If the system is not SISO or
+        squeeze is False, the array is 2D (indexed by the output number and
+        time).
+
     xout : array
-        Time evolution of the state vector.
+        Time evolution of the state vector. Not affected by squeeze.
 
     See Also
     --------
@@ -459,11 +467,9 @@ def _process_time_response(sys, tout, yout, xout, transpose=None,
         yout = np.squeeze(yout)
     elif squeeze is False:      # squeeze no dimensions
         pass
-    # Possible code if we implement a squeeze='siso' option
-    # elif squeeze == 'siso':     # squeeze signals if SISO
-    #     yout = yout[0] if sys.issiso() else yout
+    elif squeeze is None:       # squeeze signals if SISO
+        yout = yout[0] if sys.issiso() else yout
     else:
-        # In preparation for more complicated values for squeeze
         raise ValueError("unknown squeeze value")
 
     # See if we need to transpose the data back into MATLAB form
@@ -481,13 +487,17 @@ def _get_ss_simo(sys, input=None, output=None, squeeze=None):
 
     If input is not specified, select first input and issue warning
     """
+    # If squeeze was not specified, figure out the default
+    if squeeze is None:
+        squeeze = config.defaults['control.squeeze_time_response']
+
     sys_ss = _convert_to_statespace(sys)
     if sys_ss.issiso():
         return squeeze, sys_ss
-    # Possible code if we implement a squeeze='siso' option
-    # elif squeeze == 'siso':
-    #     # Don't squeeze outputs if resulting system turns out to be siso
-    #     squeeze = False
+    elif squeeze == None and (input is None or output is None):
+        # Don't squeeze outputs if resulting system turns out to be siso
+        # Note: if we expand input to allow a tuple, need to update this check
+        squeeze = False
 
     warn = False
     if input is None:
@@ -531,32 +541,34 @@ def step_response(sys, T=None, X0=0., input=None, output=None, T_num=None,
         many simulation steps.
 
     X0 : array_like or float, optional
-        Initial condition (default = 0)
-
-        Numbers are converted to constant arrays with the correct shape.
+        Initial condition (default = 0). Numbers are converted to constant
+        arrays with the correct shape.
 
-    input : int
+    input : int, optional
         Index of the input that will be used in this simulation.  Default = 0.
 
-    output : int
+    output : int, optional
         Index of the output that will be used in this simulation. Set to None
         to not trim outputs
 
     T_num : int, optional
         Number of time steps to use in simulation if T is not provided as an
         array (autocomputed if not given); ignored if sys is discrete-time.
 
-    transpose : bool
+    transpose : bool, optional
         If True, transpose all input and output arrays (for backward
         compatibility with MATLAB and :func:`scipy.signal.lsim`)
 
-    return_x : bool
+    return_x : bool, optional
         If True, return the state vector (default = False).
 
     squeeze : bool, optional
-        If True (default), remove single-dimensional entries from the shape
-        of the output.  For single output systems, this converts the output
-        response to a 1D array.  The default value can be set using
+        By default, if a system is single-input, single-output (SISO) then the
+        output response is returned as a 1D array (indexed by time).  If
+        squeeze=True, remove single-dimensional entries from the shape of the
+        output even if the system is not SISO. If squeeze=False, keep the
+        output as a 2D array (indexed by the output number and time) even if
+        the system is SISO. The default value can be set using
         config.defaults['control.squeeze_time_response'].
 
     Returns
@@ -565,10 +577,13 @@ def step_response(sys, T=None, X0=0., input=None, output=None, T_num=None,
         Time values of the output
 
     yout : array
-        Response of the system
+        Response of the system.  If the system is SISO and squeeze is not
+        True, the array is 1D (indexed by time).  If the system is not SISO or
+        squeeze is False, the array is 2D (indexed by the output number and
+        time).
 
     xout : array, optional
-        Individual response of each x variable (if return_x is True)
+        Individual response of each x variable (if return_x is True).
 
     See Also
     --------
@@ -722,19 +737,27 @@ def initial_response(sys, T=None, X0=0., input=0, output=None, T_num=None,
         If True, return the state vector (default = False).
 
     squeeze : bool, optional
-        If True (default), remove single-dimensional entries from the shape
-        of the output.  For single output systems, this converts the output
-        response to a 1D array.  The default value can be set using
+        By default, if a system is single-input, single-output (SISO) then the
+        output response is returned as a 1D array (indexed by time).  If
+        squeeze=True, remove single-dimensional entries from the shape of the
+        output even if the system is not SISO. If squeeze=False, keep the
+        output as a 2D array (indexed by the output number and time) even if
+        the system is SISO. The default value can be set using
         config.defaults['control.squeeze_time_response'].
 
     Returns
     -------
     T : array
         Time values of the output
+
     yout : array
-        Response of the system
+        Response of the system.  If the system is SISO and squeeze is not
+        True, the array is 1D (indexed by time).  If the system is not SISO or
+        squeeze is False, the array is 2D (indexed by the output number and
+        time).
+
     xout : array, optional
-        Individual response of each x variable (if return_x is True)
+        Individual response of each x variable (if return_x is True).
 
     See Also
     --------
@@ -789,10 +812,10 @@ def impulse_response(sys, T=None, X0=0., input=None, output=None, T_num=None,
 
         Numbers are converted to constant arrays with the correct shape.
 
-    input : int
+    input : int, optional
         Index of the input that will be used in this simulation.  Default = 0.
 
-    output : int
+    output : int, optional
         Index of the output that will be used in this simulation. Set to None
         to not trim outputs
 
@@ -804,23 +827,31 @@ def impulse_response(sys, T=None, X0=0., input=None, output=None, T_num=None,
         If True, transpose all input and output arrays (for backward
         compatibility with MATLAB and :func:`scipy.signal.lsim`)
 
-    return_x : bool
+    return_x : bool, optional
         If True, return the state vector (default = False).
 
     squeeze : bool, optional
-        If True (default), remove single-dimensional entries from the shape
-        of the output.  For single output systems, this converts the output
-        response to a 1D array.  The default value can be set using
+        By default, if a system is single-input, single-output (SISO) then the
+        output response is returned as a 1D array (indexed by time).  If
+        squeeze=True, remove single-dimensional entries from the shape of the
+        output even if the system is not SISO. If squeeze=False, keep the
+        output as a 2D array (indexed by the output number and time) even if
+        the system is SISO. The default value can be set using
         config.defaults['control.squeeze_time_response'].
 
     Returns
     -------
     T : array
         Time values of the output
+
     yout : array
-        Response of the system
+        Response of the system.  If the system is SISO and squeeze is not
+        True, the array is 1D (indexed by time).  If the system is not SISO or
+        squeeze is False, the array is 2D (indexed by the output number and
+        time).
+
     xout : array, optional
-        Individual response of each x variable (if return_x is True)
+        Individual response of each x variable (if return_x is True).
 
     See Also
     --------
