allow renaming of system/signal names in bdalg functions

murrayrm · murrayrm · commit 8b8574732bc3 · 2024-06-30T07:59:18.000-07:00
diff --git a/control/bdalg.py b/control/bdalg.py
@@ -54,17 +54,19 @@
 """
 
 from functools import reduce
-import numpy as np
 from warnings import warn
-from . import xferfcn as tf
-from . import statesp as ss
+
+import numpy as np
+
 from . import frdata as frd
+from . import statesp as ss
+from . import xferfcn as tf
 from .iosys import InputOutputSystem
 
 __all__ = ['series', 'parallel', 'negate', 'feedback', 'append', 'connect']
 
 
-def series(sys1, *sysn):
+def series(sys1, *sysn, **kwargs):
     r"""series(sys1, sys2, [..., sysn])
 
     Return the series connection (`sysn` \* ...\  \*) `sys2` \* `sys1`.
@@ -117,10 +119,12 @@ def series(sys1, *sysn):
     (2, 1, 5)
 
     """
-    return reduce(lambda x, y: y * x, sysn, sys1)
+    sys = reduce(lambda x, y: y * x, sysn, sys1)
+    sys.update_names(**kwargs)
+    return sys
 
 
-def parallel(sys1, *sysn):
+def parallel(sys1, *sysn, **kwargs):
     r"""parallel(sys1, sys2, [..., sysn])
 
     Return the parallel connection `sys1` + `sys2` (+ ...\  + `sysn`).
@@ -171,10 +175,11 @@ def parallel(sys1, *sysn):
     (3, 4, 7)
 
     """
-    return reduce(lambda x, y: x + y, sysn, sys1)
-
+    sys = reduce(lambda x, y: x + y, sysn, sys1)
+    sys.update_names(**kwargs)
+    return sys
 
-def negate(sys):
+def negate(sys, **kwargs):
     """
     Return the negative of a system.
 
@@ -208,11 +213,12 @@ def negate(sys):
     np.float64(-2.0)
 
     """
-    return -sys
+    sys = -sys
+    sys.update_names(**kwargs)
+    return sys
 
 #! TODO: expand to allow sys2 default to work in MIMO case?
-#! TODO: allow renaming of signals (for all bdalg operations)
-def feedback(sys1, sys2=1, sign=-1):
+def feedback(sys1, sys2=1, sign=-1, **kwargs):
     """Feedback interconnection between two I/O systems.
 
     Parameters
@@ -261,7 +267,7 @@ def feedback(sys1, sys2=1, sign=-1):
     # Allow anything with a feedback function to call that function
     # TODO: rewrite to allow __rfeedback__
     try:
-        return sys1.feedback(sys2, sign)
+        return sys1.feedback(sys2, sign, **kwargs)
     except (AttributeError, TypeError):
         pass
 
@@ -284,9 +290,11 @@ def feedback(sys1, sys2=1, sign=-1):
         else:
             sys1 = ss._convert_to_statespace(sys1)
 
-    return sys1.feedback(sys2, sign)
+    sys = sys1.feedback(sys2, sign)
+    sys.update_names(**kwargs)
+    return sys
 
-def append(*sys):
+def append(*sys, **kwargs):
     """append(sys1, sys2, [..., sysn])
 
     Group LTI state space models by appending their inputs and outputs.
@@ -327,6 +335,7 @@ def append(*sys):
     s1 = ss._convert_to_statespace(sys[0])
     for s in sys[1:]:
         s1 = s1.append(s)
+    s1.update_names(**kwargs)
     return s1
 
 def connect(sys, Q, inputv, outputv):
diff --git a/control/iosys.py b/control/iosys.py
@@ -6,10 +6,12 @@
 # FrequencyResponseData, InterconnectedSystem and other similar classes
 # that allow naming of signals.
 
-import numpy as np
+import re
 from copy import deepcopy
 from warnings import warn
-import re
+
+import numpy as np
+
 from . import config
 
 __all__ = ['InputOutputSystem', 'issiso', 'timebase', 'common_timebase',
@@ -366,6 +368,44 @@ def find_states(self, name_list):
         lambda self: list(self.state_index.keys()),     # getter
         set_states)                                     # setter
 
+    def update_names(self, **kwargs):
+        """Update signal and system names for an I/O system.
+
+        Parameters
+        ----------
+        inputs : int, list of str, or None
+            Description of the system inputs.
+        outputs : int, list of str, or None
+            Description of the system outputs.
+        states : int, list of str, or None
+            Description of the system states.
+
+        """
+        self.name = kwargs.pop('name', self.name)
+        if kwargs.get('inputs', None):
+            ninputs, input_index = _process_signal_list(
+                kwargs.pop('inputs'), prefix=kwargs.pop('input_prefix', 'u'))
+            if self.ninputs and self.ninputs != ninputs:
+                raise ValueError("number of inputs does not match system size")
+            self.input_index = input_index
+        if kwargs.get('outputs', None):
+            noutputs, output_index = _process_signal_list(
+                kwargs.pop('outputs'), prefix=kwargs.pop('output_prefix', 'y'))
+            if self.noutputs and self.noutputs != noutputs:
+                raise ValueError("number of outputs does not match system size")
+            self.output_index = output_index
+        if kwargs.get('states', None):
+            nstates, state_index = _process_signal_list(
+                kwargs.pop('states'), prefix=kwargs.pop('state_prefix', 'x'))
+            if self.nstates != nstates:
+                raise ValueError("number of states does not match system size")
+            self.state_index = state_index
+
+        # Make sure we processed all of the arguments
+        if kwargs:
+            raise TypeError("unrecognized keywords: ", str(kwargs))
+
+
     def isctime(self, strict=False):
         """
         Check to see if a system is a continuous-time system.
@@ -825,6 +865,7 @@ def _process_labels(labels, name, default):
 #
 import re
 
+
 def _parse_spec(syslist, spec, signame, dictname=None):
     """Parse a signal specification, returning system and signal index."""
 
diff --git a/control/tests/bdalg_test.py b/control/tests/bdalg_test.py
@@ -316,3 +316,49 @@ def testConnect(self, tsys):
                 connect(sys, Q, [2], [1, 0])
             with pytest.raises(IndexError):
                 connect(sys, Q, [2], [1, -1])
+
+
+@pytest.mark.parametrize(
+    "op, nsys, ninputs, noutputs, nstates", [
+        (ctrl.series, 2, 1, 1, 4),
+        (ctrl.parallel, 2, 1, 1, 4),
+        (ctrl.feedback, 2, 1, 1, 4),
+        (ctrl.append, 2, 2, 2, 4),
+        (ctrl.negate, 1, 1, 1, 2),
+    ])
+def test_bdalg_update_names(op, nsys, ninputs, noutputs, nstates):
+    syslist = [ctrl.rss(2, 1, 1), ctrl.rss(2, 1, 1)]
+    inputs = ['in1', 'in2']
+    outputs = ['out1', 'out2']
+    states = ['x1', 'x2', 'x3', 'x4']
+
+    newsys = op(
+        *syslist[:nsys], name='newsys', inputs=inputs[:ninputs],
+        outputs=outputs[:noutputs], states=states[:nstates])
+    assert newsys.name == 'newsys'
+    assert newsys.ninputs == ninputs
+    assert newsys.input_labels == inputs[:ninputs]
+    assert newsys.noutputs == noutputs
+    assert newsys.output_labels == outputs[:noutputs]
+    assert newsys.nstates == nstates
+    assert newsys.state_labels == states[:nstates]
+
+
+def test_bdalg_udpate_names_errors():
+    sys1 = ctrl.rss(2, 1, 1)
+    sys2 = ctrl.rss(2, 1, 1)
+
+    with pytest.raises(ValueError, match="number of inputs does not match"):
+        sys = ctrl.series(sys1, sys2, inputs=2)
+
+    with pytest.raises(ValueError, match="number of outputs does not match"):
+        sys = ctrl.series(sys1, sys2, outputs=2)
+
+    with pytest.raises(ValueError, match="number of states does not match"):
+        sys = ctrl.series(sys1, sys2, states=2)
+
+    with pytest.raises(ValueError, match="number of states does not match"):
+        sys = ctrl.series(ctrl.tf(sys1), ctrl.tf(sys2), states=2)
+
+    with pytest.raises(TypeError, match="unrecognized keywords"):
+        sys = ctrl.series(sys1, sys2, dt=1)
diff --git a/control/tests/iosys_test.py b/control/tests/iosys_test.py
@@ -2122,7 +2122,7 @@ def test_find_size():
         lambda t, x, u, params: -x + u,
         lambda t, x, u, params: x[:1],
         inputs=2, states=2)
-    
+
     with pytest.raises(ValueError, match="inconsistent .* size of X0"):
         resp = ct.input_output_response(sys, timepts, [0, 1], X0=[0, 0, 1])
 
@@ -2135,4 +2135,35 @@ def test_find_size():
             lambda t, x, u, params: x[:1],
             inputs=2, states=2, outputs=2)
         resp = ct.input_output_response(sys, timepts, [0, 1], X0=[0, 0])
-    
+
+
+def test_update_names():
+    sys = ct.rss(['x1', 'x2'], 2, 2)
+    sys.update_names(
+        name='new', states=2, inputs=['u1', 'u2'],
+        outputs=2, output_prefix='yy')
+    assert sys.name == 'new'
+    assert sys.ninputs == 2
+    assert sys.input_labels == ['u1', 'u2']
+    assert sys.ninputs == 2
+    assert sys.output_labels == ['yy[0]', 'yy[1]']
+    assert sys.state_labels == ['x[0]', 'x[1]']
+
+    # Generate some error conditions
+    with pytest.raises(ValueError, match="number of inputs does not match"):
+        sys.update_names(inputs=3)
+
+    with pytest.raises(ValueError, match="number of outputs does not match"):
+        sys.update_names(outputs=3)
+
+    with pytest.raises(ValueError, match="number of states does not match"):
+        sys.update_names(states=3)
+
+    with pytest.raises(ValueError, match="number of states does not match"):
+        ct.tf(sys).update_names(states=2)
+
+    with pytest.raises(TypeError, match="unrecognized keywords"):
+        sys.update_names(dt=1)
+
+    with pytest.raises(TypeError, match=".* takes 1 positional argument"):
+        sys.update_names(5)
diff --git a/control/tests/kwargs_test.py b/control/tests/kwargs_test.py
@@ -92,20 +92,25 @@ def test_kwarg_search(module, prefix):
 
 @pytest.mark.parametrize(
     "function, nsssys, ntfsys, moreargs, kwargs",
-    [(control.dlqe, 1, 0, ([[1]], [[1]]), {}),
+    [(control.append, 2, 0, (), {}),
+     (control.dlqe, 1, 0, ([[1]], [[1]]), {}),
      (control.dlqr, 1, 0, ([[1, 0], [0, 1]], [[1]]), {}),
      (control.drss, 0, 0, (2, 1, 1), {}),
+     (control.feedback, 2, 0, (), {}),
      (control.flatsys.flatsys, 1, 0, (), {}),
      (control.input_output_response, 1, 0, ([0, 1, 2], [1, 1, 1]), {}),
      (control.lqe, 1, 0, ([[1]], [[1]]), {}),
      (control.lqr, 1, 0, ([[1, 0], [0, 1]], [[1]]), {}),
      (control.linearize, 1, 0, (0, 0), {}),
+     (control.negate, 1, 0, (), {}),
      (control.nlsys, 0, 0, (lambda t, x, u, params: np.array([0]),), {}),
+     (control.parallel, 2, 0, (), {}),
      (control.pzmap, 1, 0, (), {}),
      (control.rlocus, 0, 1, (), {}),
      (control.root_locus, 0, 1, (), {}),
      (control.root_locus_plot, 0, 1, (), {}),
      (control.rss, 0, 0, (2, 1, 1), {}),
+     (control.series, 2, 0, (), {}),
      (control.set_defaults, 0, 0, ('control',), {'default_dt': True}),
      (control.ss, 0, 0, (0, 0, 0, 0), {'dt': 1}),
      (control.ss2io, 1, 0,  (), {}),
@@ -122,6 +127,7 @@ def test_kwarg_search(module, prefix):
      (control.LTI, 0, 0, (),
       {'inputs': 1, 'outputs': 1, 'states': 1}),
      (control.flatsys.LinearFlatSystem, 1, 0, (), {}),
+     (control.InputOutputSystem.update_names, 1, 0, (), {}),
      (control.NonlinearIOSystem.linearize, 1, 0, (0, 0), {}),
      (control.StateSpace.sample, 1, 0, (0.1,), {}),
      (control.StateSpace, 0, 0,
@@ -232,6 +238,7 @@ def test_response_plot_kwargs(data_fcn, plot_fcn, mimo):
 #
 
 kwarg_unittest = {
+    'append': test_unrecognized_kwargs,
     'bode': test_response_plot_kwargs,
     'bode_plot': test_response_plot_kwargs,
     'create_estimator_iosystem': stochsys_test.test_estimator_errors,
@@ -242,6 +249,7 @@ def test_response_plot_kwargs(data_fcn, plot_fcn, mimo):
     'dlqe': test_unrecognized_kwargs,
     'dlqr': test_unrecognized_kwargs,
     'drss': test_unrecognized_kwargs,
+    'feedback': test_unrecognized_kwargs,
     'flatsys.flatsys': test_unrecognized_kwargs,
     'frd': frd_test.TestFRD.test_unrecognized_keyword,
     'gangof4': test_matplotlib_kwargs,
@@ -252,19 +260,22 @@ def test_response_plot_kwargs(data_fcn, plot_fcn, mimo):
     'linearize': test_unrecognized_kwargs,
     'lqe': test_unrecognized_kwargs,
     'lqr': test_unrecognized_kwargs,
+    'negate': test_unrecognized_kwargs,
     'nichols_plot': test_matplotlib_kwargs,
     'nichols': test_matplotlib_kwargs,
     'nlsys': test_unrecognized_kwargs,
     'nyquist': test_matplotlib_kwargs,
     'nyquist_response': test_response_plot_kwargs,
     'nyquist_plot': test_matplotlib_kwargs,
     'phase_plane_plot': test_matplotlib_kwargs,
+    'parallel': test_unrecognized_kwargs,
     'pole_zero_plot': test_unrecognized_kwargs,
     'pzmap': test_unrecognized_kwargs,
     'rlocus': test_unrecognized_kwargs,
     'root_locus': test_unrecognized_kwargs,
     'root_locus_plot': test_unrecognized_kwargs,
     'rss': test_unrecognized_kwargs,
+    'series': test_unrecognized_kwargs,
     'set_defaults': test_unrecognized_kwargs,
     'singular_values_plot': test_matplotlib_kwargs,
     'ss': test_unrecognized_kwargs,
@@ -292,6 +303,7 @@ def test_response_plot_kwargs(data_fcn, plot_fcn, mimo):
     'DescribingFunctionResponse.plot':
         descfcn_test.test_describing_function_exceptions,
     'InputOutputSystem.__init__': test_unrecognized_kwargs,
+    'InputOutputSystem.update_names': test_unrecognized_kwargs,
     'LTI.__init__': test_unrecognized_kwargs,
     'flatsys.LinearFlatSystem.__init__': test_unrecognized_kwargs,
     'NonlinearIOSystem.linearize': test_unrecognized_kwargs,
