add signal_table function, test against show_names

sawyerbfuller · sawyerbfuller · commit 614de832ad90 · 2023-07-24T15:16:28.000-07:00
diff --git a/control/nlsys.py b/control/nlsys.py
@@ -31,7 +31,7 @@
 
 __all__ = ['NonlinearIOSystem', 'InterconnectedSystem', 'nlsys',
            'input_output_response', 'find_eqpt', 'linearize',
-           'interconnect']
+           'interconnect', 'signal_table']
 
 
 class NonlinearIOSystem(InputOutputSystem):
@@ -1020,7 +1020,7 @@ def signal_table(self, show_names=False):
         >>> P = ct.ss(1,1,1,0, inputs='u', outputs='y')
         >>> C = ct.tf(10, [.1, 1], inputs='e', outputs='u')
         >>> L = ct.interconnect([C, P], inputs='e', outputs='y')
-        >>> L.signal_table()
+        >>> L.signal_table() # doctest: +SKIP
         signal    | source                  | destination
         --------------------------------------------------------------
         e         | input                   | system 0
@@ -2563,3 +2563,36 @@ def _convert_static_iosystem(sys):
         return NonlinearIOSystem(
             None, lambda t, x, u, params: sys @ u,
             outputs=sys.shape[0], inputs=sys.shape[1])
+
+def signal_table(sys, **kwargs):
+    """Print table of signal names, sources, and destinations.
+
+    Intended primarily for systems that have been connected implicitly
+    using signal names.
+
+    Parameters
+    ----------
+    sys : :class:`InterconnectedSystem`
+        Interconnected system object
+    show_names : bool (optional)
+        Instead of printing out the system number, print out the name of
+        each system. Default is False because system name is not usually
+        specified when performing implicit interconnection using
+        :func:`interconnect`.
+
+    Examples
+    --------
+    >>> P = ct.ss(1,1,1,0, inputs='u', outputs='y')
+    >>> C = ct.tf(10, [.1, 1], inputs='e', outputs='u')
+    >>> L = ct.interconnect([C, P], inputs='e', outputs='y')
+    >>> ct.signal_table(L) # doctest: +SKIP
+    signal    | source                  | destination
+    --------------------------------------------------------------
+    e         | input                   | system 0
+    u         | system 0                | system 1
+    y         | system 1                | output
+    """
+    assert isinstance(sys, InterconnectedSystem), "system must be"\
+        "an InterconnectedSystem."
+
+    sys.signal_table(**kwargs)
diff --git a/control/tests/interconnect_test.py b/control/tests/interconnect_test.py
@@ -201,24 +201,37 @@ def test_interconnect_docstring():
     np.testing.assert_almost_equal(T.C @ T. A @ T.B, T_ss.C @ T_ss.A @ T_ss.B)
     np.testing.assert_almost_equal(T.D, T_ss.D)
 
-def test_signal_table(capsys):
-    P = ct.ss(1,1,1,0, inputs='u', outputs='y')
-    C = ct.tf(10, [.1, 1], inputs='e', outputs='u')
+@pytest.mark.parametrize("show_names", (True, False))
+def test_signal_table(capsys, show_names):
+    P = ct.ss(1,1,1,0, inputs='u', outputs='y', name='P')
+    C = ct.tf(10, [.1, 1], inputs='e', outputs='u', name='C')
     L = ct.interconnect([C, P], inputs='e', outputs='y')
-    L.signal_table()
-    captured = capsys.readouterr().out
+    L.signal_table(show_names=show_names)
+    captured_from_method = capsys.readouterr().out
+
+    ct.signal_table(L, show_names=show_names)
+    captured_from_function = capsys.readouterr().out
 
     # break the following strings separately because the printout order varies
-    # because signals are stored as a dict
+    # because signal names are stored as a set
     mystrings = \
     ["signal    | source                  | destination",
-     "-------------------------------------------------------------",
-     "e         | input                   | system 0",
-     "u         | system 0                | system 1",
-     "y         | system 1                | output"]
+     "-------------------------------------------------------------"]
+    if show_names:
+        mystrings += \
+            ["e         | input                   | C",
+             "u         | C                       | P",
+             "y         | P                       | output"]
+    else:
+        mystrings += \
+            ["e         | input                   | system 0",
+             "u         | system 0                | system 1",
+             "y         | system 1                | output"]
 
     for str_ in mystrings:
-        assert str_ in captured
+        assert str_ in captured_from_method
+        assert str_ in captured_from_function
+
 
 def test_interconnect_exceptions():
     # First make sure the docstring example works
diff --git a/doc/control.rst b/doc/control.rst
@@ -36,6 +36,7 @@ System interconnections
     negate
     parallel
     series
+    signal_table
 
 
 Frequency domain plotting
