corrected comments on time responses, with the "input" parameter to be

repagh · repagh · commit a38edfcb70e5 · 2014-07-08T10:59:01.000Z
ignored on initial response calculation; initial response does not depend
on input!
diff --git a/src/matlab.py b/src/matlab.py
@@ -1103,15 +1103,18 @@ def rlocus(sys, klist = None, **keywords):
     """Root locus plot
 
     The root-locus plot has a callback function that prints pole location, 
-    gain and damping to the Python consol on mouseclicks on the root-locus 
-    graph.
+    gain and damping to the Python console on mouseclicks on the root-locus 
+    graph. 
 
     Parameters
     ----------
     sys: StateSpace or TransferFunction 
         Linear system
     klist: 
         optional list of gains
+
+    Keyword parameters
+    ------------------
     xlim : control of x-axis range, normally with tuple, for
         other options, see matplotlib.axes
     ylim : control of y-axis range
@@ -1165,7 +1168,7 @@ def margin(*args):
     margin: no magnitude crossings found
     
     .. todo:: 
-        better ecample system!
+        better example system!
         
         #>>> gm, pm, wg, wp = margin(mag, phase, w)
     """
@@ -1178,7 +1181,7 @@ def margin(*args):
         raise ValueError("Margin needs 1 or 3 arguments; received %i." 
             % len(args))
             
-    return margin[0], margin[1], margin[4], margin[3]
+    return margin[0], margin[1], margin[3], margin[4]
 
 def dcgain(*args):
     '''
@@ -1279,10 +1282,11 @@ def step(sys, T=None, X0=0., input=0, output=None, **keywords):
     '''
     Step response of a linear system
     
-    If the system has multiple inputs or outputs (MIMO), one input and one 
-    output have to be selected for the simulation. The parameters `input` 
-    and `output` do this. All other inputs are set to 0, all other outputs 
-    are ignored.
+    If the system has multiple inputs or outputs (MIMO), one input has
+    to be selected for the simulation.  Optionally, one output may be
+    selected. If no selection is made for the output, all outputs are
+    given. The parameters `input` and `output` do this. All other
+    inputs are set to 0, all other outputs are ignored.
     
     Parameters
     ----------
@@ -1301,7 +1305,7 @@ def step(sys, T=None, X0=0., input=0, output=None, **keywords):
         Index of the input that will be used in this simulation.
 
     output: int
-        Index of the output that will be used in this simulation.
+        If given, index of the output that is returned by this simulation.
 
     **keywords:
         Additional keyword arguments control the solution algorithm for the 
@@ -1326,19 +1330,21 @@ def step(sys, T=None, X0=0., input=0, output=None, **keywords):
     Examples
     --------
     >>> yout, T = step(sys, T, X0)
+
     '''
     T, yout = timeresp.step_response(sys, T, X0, input, output, 
-                                   transpose = True, **keywords)
+                                     transpose=True, **keywords)
     return yout, T
 
-def impulse(sys, T=None, input=0, output=0, **keywords):
+def impulse(sys, T=None, input=0, output=None, **keywords):
     '''
     Impulse response of a linear system
     
-    If the system has multiple inputs or outputs (MIMO), one input and
-    one output must be selected for the simulation. The parameters
-    `input` and `output` do this. All other inputs are set to 0, all
-    other outputs are ignored.
+    If the system has multiple inputs or outputs (MIMO), one input has
+    to be selected for the simulation.  Optionally, one output may be
+    selected. If no selection is made for the output, all outputs are
+    given. The parameters `input` and `output` do this. All other
+    inputs are set to 0, all other outputs are ignored.
     
     Parameters
     ----------
@@ -1381,14 +1387,13 @@ def impulse(sys, T=None, input=0, output=0, **keywords):
                                    transpose = True, **keywords)
     return yout, T
 
-def initial(sys, T=None, X0=0., input=0, output=0, **keywords):
+def initial(sys, T=None, X0=0., input=None, output=None, **keywords):
     '''
     Initial condition response of a linear system
     
-    If the system has multiple inputs or outputs (MIMO), one input and one 
-    output have to be selected for the simulation. The parameters `input` 
-    and `output` do this. All other inputs are set to 0, all other outputs 
-    are ignored.
+    If the system has multiple outputs (?IMO), optionally, one output
+    may be selected. If no selection is made for the output, all
+    outputs are given.
     
     Parameters
     ----------
@@ -1404,10 +1409,11 @@ def initial(sys, T=None, X0=0., input=0, output=0, **keywords):
         Numbers are converted to constant arrays with the correct shape.
 
     input: int
-        Index of the input that will be used in this simulation.
+        This input is ignored, but present for compatibility with step
+        and impulse.
 
     output: int
-        Index of the output that will be used in this simulation.
+        If given, index of the output that is returned by this simulation.
 
     **keywords:
         Additional keyword arguments control the solution algorithm for the 
@@ -1432,9 +1438,10 @@ def initial(sys, T=None, X0=0., input=0, output=0, **keywords):
     Examples
     --------
     >>> T, yout = initial(sys, T, X0)
+
     '''
-    T, yout = timeresp.initial_response(sys, T, X0, input, output, 
-                                   transpose = True, **keywords)
+    T, yout = timeresp.initial_response(sys, T, X0, output=output, 
+                                        transpose=True, **keywords)
     return yout, T
 
 def lsim(sys, U=0., T=None, X0=0., **keywords):
diff --git a/src/timeresp.py b/src/timeresp.py
@@ -389,7 +389,8 @@ def f_dot(x, t):
 def step_response(sys, T=None, X0=0., input=0, output=None,
                   transpose = False, **keywords):
     #pylint: disable=W0622
-    """Step response of a linear system
+    """
+    Step response of a linear system
     
     If the system has multiple inputs or outputs (MIMO), one input has
     to be selected for the simulation. Optionally, one output may be
@@ -468,15 +469,14 @@ def step_response(sys, T=None, X0=0., input=0, output=None,
     return T, yout
 
 
-def initial_response(sys, T=None, X0=0., input=0, output=None, transpose=False,
-                     **keywords):
+def initial_response(sys, T=None, X0=0., input=None, output=None, 
+                     transpose=False, **keywords):
     #pylint: disable=W0622
     """Initial condition response of a linear system
     
-    If the system has multiple inputs or outputs (MIMO), one input and one 
-    output have to be selected for the simulation. The parameters `input` 
-    and `output` do this. All other inputs are set to 0, all other outputs 
-    are ignored.
+    If the system has multiple outputs (?IMO), optionally, one output
+    may be selected. If no selection is made for the output, all
+    outputs are given.
     
     For information on the **shape** of parameters `T`, `X0` and 
     return values `T`, `yout` see: :ref:`time-series-convention`
@@ -495,7 +495,8 @@ def initial_response(sys, T=None, X0=0., input=0, output=None, transpose=False,
         Numbers are converted to constant arrays with the correct shape.
 
     input: int
-        Index of the input that will be used in this simulation.
+        Ignored, has no meaning in initial condition calculation. Parameter
+        ensures compatibility with step_response and impulse_response
 
     output: int
         Index of the output that will be used in this simulation. Set to None
@@ -531,9 +532,9 @@ def initial_response(sys, T=None, X0=0., input=0, output=None, transpose=False,
     """
     sys = _convertToStateSpace(sys) 
     if output == None:
-        sys = _mimo2simo(sys, input, warn_conversion=False)
+        sys = _mimo2simo(sys, 0, warn_conversion=False)
     else:
-        sys = _mimo2siso(sys, input, output, warn_conversion=False)
+        sys = _mimo2siso(sys, 0, output, warn_conversion=False)
 
     # Create time and input vectors; checking is done in forced_response(...)
     # The initial vector X0 is created in forced_response(...) if necessary
@@ -549,12 +550,13 @@ def initial_response(sys, T=None, X0=0., input=0, output=None, transpose=False,
 def impulse_response(sys, T=None, X0=0., input=0, output=None,
                     transpose=False, **keywords):
     #pylint: disable=W0622
-    """Impulse response of a linear system
+    """
+    Impulse response of a linear system
     
-    If the system has multiple inputs or outputs (MIMO), one input and one 
-    output have to be selected for the simulation. The parameters `input` 
-    and `output` do this. All other inputs are set to 0, all other outputs 
-    are ignored.
+    If the system has multiple inputs or outputs (MIMO), one input has
+    to be selected for the simulation. Optionally, one output may be
+    selected. The parameters `input` and `output` do this. All other
+    inputs are set to 0, all other outputs are ignored.
     
     For information on the **shape** of parameters `T`, `X0` and 
     return values `T`, `yout` see: :ref:`time-series-convention`
diff --git a/tests/matlab_test.py b/tests/matlab_test.py
@@ -190,8 +190,8 @@ def testInitial(self):
         #Test MIMO system, which contains ``siso_ss1`` twice
         sys = self.mimo_ss1
         x0 = np.matrix(".5; 1.; .5; 1.")
-        y_00, _t = initial(sys, T=t, X0=x0, input=0, output=0)
-        y_11, _t = initial(sys, T=t, X0=x0, input=1, output=1)
+        y_00, _t = initial(sys, T=t, X0=x0, output=0)
+        y_11, _t = initial(sys, T=t, X0=x0, output=1)
         np.testing.assert_array_almost_equal(y_00, youttrue, decimal=4)
         np.testing.assert_array_almost_equal(y_11, youttrue, decimal=4)
 
diff --git a/tests/timeresp_test.py b/tests/timeresp_test.py
@@ -109,8 +109,8 @@ def test_initial_response(self):
         #Test MIMO system, which contains ``siso_ss1`` twice
         sys = self.mimo_ss1
         x0 = np.matrix(".5; 1.; .5; 1.")
-        _t, y_00 = initial_response(sys, T=t, X0=x0, input=0, output=0)
-        _t, y_11 = initial_response(sys, T=t, X0=x0, input=1, output=1)
+        _t, y_00 = initial_response(sys, T=t, X0=x0, output=0)
+        _t, y_11 = initial_response(sys, T=t, X0=x0, output=1)
         np.testing.assert_array_almost_equal(y_00, youttrue, decimal=4)
         np.testing.assert_array_almost_equal(y_11, youttrue, decimal=4)
         
