change name to summing_junction + updated documentation and examples

murrayrm · murrayrm · commit cd3e4b65649b · 2021-01-24T10:01:43.000-08:00
diff --git a/control/iosys.py b/control/iosys.py
@@ -3,16 +3,11 @@
 # RMM, 28 April 2019
 #
 # Additional features to add
-#   * Improve support for signal names, specially in operator overloads
-#       - Figure out how to handle "nested" names (icsys.sys[1].x[1])
-#       - Use this to implement signal names for operators?
 #   * Allow constant inputs for MIMO input_output_response (w/out ones)
 #   * Add support for constants/matrices as part of operators (1 + P)
 #   * Add unit tests (and example?) for time-varying systems
 #   * Allow time vector for discrete time simulations to be multiples of dt
 #   * Check the way initial outputs for discrete time systems are handled
-#   * Rename 'connections' as 'conlist' to match 'inplist' and 'outlist'?
-#   * Allow signal summation in InterconnectedSystem diagrams (via new output?)
 #
 
 """The :mod:`~control.iosys` module contains the
@@ -44,7 +39,7 @@
 __all__ = ['InputOutputSystem', 'LinearIOSystem', 'NonlinearIOSystem',
            'InterconnectedSystem', 'LinearICSystem', 'input_output_response',
            'find_eqpt', 'linearize', 'ss2io', 'tf2io', 'interconnect',
-           'summation_block']
+           'summing_junction']
 
 # Define module default parameter values
 _iosys_defaults = {
@@ -1982,17 +1977,26 @@ def interconnect(syslist, connections=None, inplist=[], outlist=[],
     Example
     -------
     >>> P = control.LinearIOSystem(
-    >>>        ct.rss(2, 2, 2, strictly_proper=True), name='P')
+    >>>        control.rss(2, 2, 2, strictly_proper=True), name='P')
     >>> C = control.LinearIOSystem(control.rss(2, 2, 2), name='C')
-    >>> S = control.InterconnectedSystem(
+    >>> T = control.interconnect(
     >>>     [P, C],
     >>>     connections = [
-    >>>       ['P.u[0]', 'C.y[0]'], ['P.u[1]', 'C.y[0]'],
+    >>>       ['P.u[0]', 'C.y[0]'], ['P.u[1]', 'C.y[1]'],
     >>>       ['C.u[0]', '-P.y[0]'], ['C.u[1]', '-P.y[1]']],
     >>>     inplist = ['C.u[0]', 'C.u[1]'],
     >>>     outlist = ['P.y[0]', 'P.y[1]'],
     >>> )
 
+    For a SISO system, this example can be simplified by using the
+    :func:`~control.summing_block` function and the ability to automatically
+    interconnect signals with the same names:
+
+    >>> P = control.tf2io(control.tf(1, [1, 0]), inputs='u', outputs='y')
+    >>> C = control.tf2io(control.tf(10, [1, 1]), inputs='e', outputs='u')
+    >>> sumblk = control.summing_junction(inputs=['r', '-y'], output='e')
+    >>> T = control.interconnect([P, C, sumblk], inplist='r', outlist='y')
+
     Notes
     -----
     If a system is duplicated in the list of systems to be connected,
@@ -2101,9 +2105,9 @@ def interconnect(syslist, connections=None, inplist=[], outlist=[],
     return newsys
 
 
-# Summation block
-def summation_block(inputs, output='y', dimension=None, name=None, prefix='u'):
-    """Create a summation block as an input/output system.
+# Summing junction
+def summing_junction(inputs, output='y', dimension=None, name=None, prefix='u'):
+    """Create a summing junction as an input/output system.
 
     This function creates a static input/output system that outputs the sum of
     the inputs, potentially with a change in sign for each individual input.
@@ -2113,15 +2117,15 @@ def summation_block(inputs, output='y', dimension=None, name=None, prefix='u'):
     Parameters
     ----------
     inputs : int, string or list of strings
-        Description of the inputs to the summation block.  This can be given
+        Description of the inputs to the summing junction.  This can be given
         as an integer count, a string, or a list of strings. If an integer
         count is specified, the names of the input signals will be of the form
         `u[i]`.
     output : string, optional
         Name of the system output.  If not specified, the output will be 'y'.
     dimension : int, optional
-        The dimension of the summing block.  If the dimension is set to a
-        positive integer, a multi-input, multi-output summation block will be
+        The dimension of the summing junction.  If the dimension is set to a
+        positive integer, a multi-input, multi-output summing junction will be
         created.  The input and output signal names will be of the form
         `<signal>[i]` where `signal` is the input/output signal name specified
         by the `inputs` and `output` keywords.  Default value is `None`.
@@ -2137,7 +2141,14 @@ def summation_block(inputs, output='y', dimension=None, name=None, prefix='u'):
     -------
     sys : static LinearIOSystem
         Linear input/output system object with no states and only a direct
-        term that implements the summation block.
+        term that implements the summing junction.
+
+    Example
+    -------
+    >>> P = control.tf2io(ct.tf(1, [1, 0]), inputs='u', outputs='y')
+    >>> C = control.tf2io(ct.tf(10, [1, 1]), inputs='e', outputs='u')
+    >>> sumblk = control.summing_junction(inputs=['r', '-y'], output='e')
+    >>> T = control.interconnect((P, C, sumblk), inplist='r', outlist='y')
 
     """
     # Utility function to parse input and output signal lists
diff --git a/control/statesp.py b/control/statesp.py
@@ -223,15 +223,15 @@ def __init__(self, *args, **kwargs):
 
         The default constructor is StateSpace(A, B, C, D), where A, B, C, D
         are matrices or equivalent objects.  To create a discrete time system,
-        use StateSpace(A, B, C, D, dt) where 'dt' is the sampling time (or
+        use StateSpace(A, B, C, D, dt) where `dt` is the sampling time (or
         True for unspecified sampling time).  To call the copy constructor,
         call StateSpace(sys), where sys is a StateSpace object.
 
         The `remove_useless_states` keyword can be used to scan the A, B, and
         C matrices for rows or columns of zeros.  If the zeros are such that a
         particular state has no effect on the input-output dynamics, then that
         state is removed from the A, B, and C matrices.  If not specified, the
-        value is read from `config.defaults['statesp.remove_useless_states']
+        value is read from `config.defaults['statesp.remove_useless_states']`
         (default = False).
 
         """
diff --git a/control/tests/interconnect_test.py b/control/tests/interconnect_test.py
@@ -30,10 +30,10 @@
     ['u',          'y',     2,    [[1, 0], [0, 1]] ],
     [['r', '-y'],  ['e'],   2,    [[1, 0, -1, 0], [0, 1, 0, -1]] ],
 ])
-def test_summation_block(inputs, output, dimension, D):
+def test_summing_junction(inputs, output, dimension, D):
     ninputs = 1 if isinstance(inputs, str) else \
         inputs if isinstance(inputs, int) else len(inputs)
-    sum = ct.summation_block(
+    sum = ct.summing_junction(
         inputs=inputs, output=output, dimension=dimension)
     dim = 1 if dimension is None else dimension
     np.testing.assert_array_equal(sum.A, np.ndarray((0, 0)))
@@ -45,15 +45,15 @@ def test_summation_block(inputs, output, dimension, D):
 def test_summation_exceptions():
     # Bad input description
     with pytest.raises(ValueError, match="could not parse input"):
-        sumblk = ct.summation_block(None, 'y')
+        sumblk = ct.summing_junction(None, 'y')
 
     # Bad output description
     with pytest.raises(ValueError, match="could not parse output"):
-        sumblk = ct.summation_block('u', None)
+        sumblk = ct.summing_junction('u', None)
 
     # Bad input dimension
     with pytest.raises(ValueError, match="unrecognized dimension"):
-        sumblk = ct.summation_block('u', 'y', dimension=False)
+        sumblk = ct.summing_junction('u', 'y', dimension=False)
 
 
 def test_interconnect_implicit():
@@ -83,8 +83,8 @@ def test_interconnect_implicit():
     np.testing.assert_almost_equal(Tio_exp.C, Tss.C)
     np.testing.assert_almost_equal(Tio_exp.D, Tss.D)
 
-    # Construct the interconnection via a summation block
-    sumblk = ct.summation_block(inputs=['r', '-y'], output='e', name="sum")
+    # Construct the interconnection via a summing junction
+    sumblk = ct.summing_junction(inputs=['r', '-y'], output='e', name="sum")
     Tio_sum = ct.interconnect(
         (C, P, sumblk), inplist=['r'], outlist=['y'])
 
@@ -108,6 +108,17 @@ def test_interconnect_implicit():
     np.testing.assert_almost_equal(Tio_sum.C, Tss.C)
     np.testing.assert_almost_equal(Tio_sum.D, Tss.D)
 
+    # TODO: interconnect a MIMO system using implicit connections
+    # P = control.ss2io(
+    #     control.rss(2, 2, 2, strictly_proper=True),
+    #     input_prefix='u', output_prefix='y', name='P')
+    # C = control.ss2io(
+    #     control.rss(2, 2, 2),
+    #     input_prefix='e', output_prefix='u', name='C')
+    # sumblk = control.summing_junction(
+    #     inputs=['r', '-y'], output='e', dimension=2)
+    # S = control.interconnect([P, C, sumblk], inplist='r', outlist='y')
+
     # Make sure that repeated inplist/outlist names generate an error
     # Input not unique
     Cbad = ct.tf2io(ct.tf(10, [1, 1]), inputs='r', outputs='x', name='C')
@@ -129,3 +140,35 @@ def test_interconnect_implicit():
     with pytest.raises(ValueError, match="could not find"):
         Tio_sum = ct.interconnect(
             (C, P, sumblk), inplist=['r'], outlist=['x'])
+
+def test_interconnect_docstring():
+    """Test the examples from the interconnect() docstring"""
+
+    # MIMO interconnection (note: use [C, P] instead of [P, C] for state order)
+    P = ct.LinearIOSystem(
+           ct.rss(2, 2, 2, strictly_proper=True), name='P')
+    C = ct.LinearIOSystem(ct.rss(2, 2, 2), name='C')
+    T = ct.interconnect(
+        [C, P],
+        connections = [
+          ['P.u[0]', 'C.y[0]'], ['P.u[1]', 'C.y[1]'],
+          ['C.u[0]', '-P.y[0]'], ['C.u[1]', '-P.y[1]']],
+        inplist = ['C.u[0]', 'C.u[1]'],
+        outlist = ['P.y[0]', 'P.y[1]'],
+    )
+    T_ss = ct.feedback(P * C, ct.ss([], [], [], np.eye(2)))
+    np.testing.assert_almost_equal(T.A, T_ss.A)
+    np.testing.assert_almost_equal(T.B, T_ss.B)
+    np.testing.assert_almost_equal(T.C, T_ss.C)
+    np.testing.assert_almost_equal(T.D, T_ss.D)
+
+    # Implicit interconnection (note: use [C, P, sumblk] for proper state order)
+    P = ct.tf2io(ct.tf(1, [1, 0]), inputs='u', outputs='y')
+    C = ct.tf2io(ct.tf(10, [1, 1]), inputs='e', outputs='u')
+    sumblk = ct.summing_junction(inputs=['r', '-y'], output='e')
+    T = ct.interconnect([C, P, sumblk], inplist='r', outlist='y')
+    T_ss = ct.feedback(P * C, 1)
+    np.testing.assert_almost_equal(T.A, T_ss.A)
+    np.testing.assert_almost_equal(T.B, T_ss.B)
+    np.testing.assert_almost_equal(T.C, T_ss.C)
+    np.testing.assert_almost_equal(T.D, T_ss.D)
diff --git a/doc/control.rst b/doc/control.rst
@@ -144,6 +144,7 @@ Nonlinear system support
    linearize
    input_output_response
    ss2io
+   summing_junction
    tf2io
    flatsys.point_to_point
 
diff --git a/doc/iosys.rst b/doc/iosys.rst
@@ -156,7 +156,8 @@ The input to the controller is `u`, consisting of the vector of hare and lynx
 populations followed by the desired lynx population.
 
 To connect the controller to the predatory-prey model, we create an
-:class:`~control.InterconnectedSystem`:
+:class:`~control.InterconnectedSystem` using the :func:`~control.interconnect`
+function:
 
 .. code-block:: python
 
@@ -189,13 +190,83 @@ Finally, we simulate the closed loop system:
   plt.legend(['input'])
   plt.show(block=False)
 
+Additional features
+===================
+
+The I/O systems module has a number of other features that can be used to
+simplify the creation of interconnected input/output systems.
+
+Summing junction
+----------------
+
+The :func:`~control.summing_junction` function can be used to create an
+input/output system that takes the sum of an arbitrary number of inputs.  For
+ezample, to create an input/output system that takes the sum of three inputs,
+use the command
+
+.. code-block:: python
+
+  sumblk = ct.summing_junction(3)
+
+By default, the name of the inputs will be of the form ``u[i]`` and the output
+will be ``y``.  This can be changed by giving an explicit list of names::
+
+  sumblk = ct.summing_junction(inputs=['a', 'b', 'c'], output='d')
+
+A more typical usage would be to define an input/output system that compares a
+reference signal to the output of the process and computes the error::
+
+  sumblk = ct.summing_junction(inputs=['r', '-y'], output='e')
+
+Note the use of the minus sign as a means of setting the sign of the input 'y'
+to be negative instead of positive.
+
+It is also possible to define "vector" summing blocks that take
+multi-dimensional inputs and produce a multi-dimensional output.  For example,
+the command
+
+.. code-block:: python
+
+  sumblk = ct.summing_junction(inputs=['r', '-y'], output='e', dimension=2)
+
+will produce an input/output block that implements ``e[0] = r[0] - y[0]`` and
+``e[1] = r[1] - y[1]``.
+
+Automatic connections using signal names
+----------------------------------------
+
+The :func:`~control.interconnect` function allows the interconnection of
+multiple systems by using signal names of the form ``sys.signal``.  In many
+situations, it can be cumbersome to explicitly connect all of the appropriate
+inputs and outputs.  As an alternative, if the ``connections`` keyword is
+omitted, the :func:`~control.interconnect` function will connect all signals
+of the same name to each other.  This can allow for simplified methods of
+interconnecting systems, especially when combined with the
+:func:`~control.summing_junction` function.  For example, the following code
+will create a unity gain, negative feedback system::
+
+  P = control.tf2io(control.tf(1, [1, 0]), inputs='u', outputs='y')
+  C = control.tf2io(control.tf(10, [1, 1]), inputs='e', outputs='u')
+  sumblk = control.summing_junction(inputs=['r', '-y'], output='e')
+  T = control.interconnect([P, C, sumblk], inplist='r', outlist='y')
+
+If a signal name appears in multiple outputs then that signal will be summed
+when it is interconnected.  Similarly, if a signal name appears in multiple
+inputs then all systems using that signal name will receive the same input.
+The :func:`~control.interconnect` function will generate an error if an signal
+listed in ``inplist`` or ``outlist`` (corresponding to the inputs and outputs
+of the interconnected system) is not found, but inputs and outputs of
+individual systems that are not connected to other systems are left
+unconnected (so be careful!).
+
+
 Module classes and functions
 ============================
 
 Input/output system classes
 ---------------------------
 .. autosummary::
-   
+
    ~control.InputOutputSystem
    ~control.InterconnectedSystem
    ~control.LinearICSystem
@@ -211,5 +282,5 @@ Input/output system functions
    ~control.input_output_response
    ~control.interconnect
    ~control.ss2io
+   ~control.summing_junction
    ~control.tf2io
-
