document and fix {input,output,state}_prefix parameters

murrayrm · murrayrm · commit 7a79342f6aa7 · 2024-12-20T11:59:25.000-08:00
diff --git a/control/flatsys/flatsys.py b/control/flatsys/flatsys.py
@@ -236,6 +236,12 @@ def flatsys(*args, updfcn=None, outfcn=None, **kwargs):
     sys: :class:`FlatSystem`
         Flat system.
 
+    Other Parameters
+    ----------------
+    input_prefix, output_prefix, state_prefix : string, optional
+        Set the prefix for input, output, and state signals.  Defaults =
+        'u', 'y', 'x'.
+
     """
     from .linflat import LinearFlatSystem
     from ..statesp import StateSpace
diff --git a/control/frdata.py b/control/frdata.py
@@ -299,9 +299,9 @@ def __init__(self, *args, **kwargs):
 
         # Process signal names
         name, inputs, outputs, states, dt = _process_iosys_keywords(
-                kwargs, defaults, end=True)
+                kwargs, defaults)
         InputOutputSystem.__init__(
-            self, name=name, inputs=inputs, outputs=outputs, dt=dt)
+            self, name=name, inputs=inputs, outputs=outputs, dt=dt, **kwargs)
 
         # create interpolation functions
         if smooth:
@@ -972,6 +972,8 @@ def frd(*args, **kwargs):
         List of strings that name the individual signals of the transformed
         system.  If not given, the inputs and outputs are the same as the
         original system.
+    input_prefix, output_prefix : string, optional
+        Set the prefix for input and output signals.  Defaults = 'u', 'y'.
     name : string, optional
         System name. If unspecified, a generic name <sys[id]> is generated
         with a unique integer id.
diff --git a/control/nlsys.py b/control/nlsys.py
@@ -1285,6 +1285,12 @@ def nlsys(updfcn, outfcn=None, **kwargs):
     sys : :class:`NonlinearIOSystem`
         Nonlinear input/output system.
 
+    Other Parameters
+    ----------------
+    input_prefix, output_prefix, state_prefix : string, optional
+        Set the prefix for input, output, and state signals.  Defaults =
+        'u', 'y', 'x'.
+
     See Also
     --------
     ss, tf
diff --git a/control/statesp.py b/control/statesp.py
@@ -1577,7 +1577,6 @@ def ss(*args, **kwargs):
     out: StateSpace
         Linear input/output system.
 
->>>>>>> 1f609a56 (updated iosys class/factory function documentation + docstring unit testing)
     Raises
     ------
     ValueError
diff --git a/control/tests/docstrings_test.py b/control/tests/docstrings_test.py
@@ -281,7 +281,13 @@ def test_deprecated_functions(module, prefix):
     ct.TransferFunction: ct.tf,
 }
 
+#
 # List of arguments described in class docstrings
+#
+# These are the minimal arguments needed to initialized the class.  Optional
+# arguments should be documented in the factory functions and do not need
+# to be duplicated in the class documentation.
+#
 class_args = {
     fs.FlatSystem: ['forward', 'reverse'],
     ct.FrequencyResponseData: ['response', 'omega', 'dt'],
@@ -291,15 +297,27 @@ def test_deprecated_functions(module, prefix):
     ct.TransferFunction: ['num', 'den', 'dt'],
 }
 
-# List of attributes defined for all I/O systems
+#
+# List of attributes described in class docstrings
+#
+# This is the list of attributes for the class that are not already listed
+# as parameters used to inialize the class.  These should all be defined
+# in the class docstring.
+#
+# Attributes that are part of all I/O system classes should be listed in
+# `std_class_attributes`.  Attributes that are not commonly needed are
+# defined as part of a parent class can just be documented there, and
+# should be listed in `iosys_parent_attributes` (these will be searched
+# using the MRO).
+
 std_class_attributes = [
     'ninputs', 'noutputs', 'input_labels', 'output_labels', 'name', 'shape']
 
 # List of attributes defined for specific I/O systems
 class_attributes = {
     fs.FlatSystem: [],
     ct.FrequencyResponseData: [],
-    ct.NonlinearIOSystem: [],
+    ct.NonlinearIOSystem: ['nstates', 'state_labels'],
     ct.StateSpace: ['nstates', 'state_labels'],
     ct.TransferFunction: [],
 }
@@ -312,13 +330,22 @@ def test_deprecated_functions(module, prefix):
     'params', 'outfcn', 'updfcn'                        # NL I/O, SS overlap
 ]
 
+#
 # List of arguments described (only) in factory function docstrings
-std_factory_args = ['inputs', 'outputs', 'name']
+#
+# These lists consist of the arguments that should be documented in the
+# factory functions and should not be duplicated in the class
+# documentation, even though in some cases they are actually processed in
+# the class __init__ function.
+#
+std_factory_args = [
+    'inputs', 'outputs', 'name', 'input_prefix', 'output_prefix']
+
 factory_args = {
-    fs.flatsys: [],
+    fs.flatsys: ['states', 'state_prefix'],
     ct.frd: ['sys'],
-    ct.nlsys: [],
-    ct.ss: ['sys', 'states'],
+    ct.nlsys: ['state_prefix'],
+    ct.ss: ['sys', 'states', 'state_prefix'],
     ct.tf: ['sys'],
 }
 
@@ -343,7 +370,7 @@ def test_iosys_primary_classes(cls, fcn, args):
             f"{cls.__name__} does not reference factory function "
             f"{fcn.__name__}")
 
-    # Make sure we don't reference parameters in the factory function
+    # Make sure we don't reference parameters from the factory function
     for argname in factory_args[fcn]:
         if re.search(f"[\\s]+{argname}(, .*)*[\\s]*:", docstring) is not None:
             pytest.fail(
@@ -448,7 +475,7 @@ def test_iosys_factory_functions(fcn):
         list(class_factory_function.values()).index(fcn)]
 
     # Make sure we reference parameters in class and factory function docstring
-    for argname in class_args[cls] + factory_args[fcn]:
+    for argname in class_args[cls] + std_factory_args + factory_args[fcn]:
         _check_parameter_docs(fcn.__name__, argname, docstring)
 
     # Make sure we don't reference any class attributes
@@ -516,4 +543,3 @@ def _check_parameter_docs(
         pytest.fail(f"{funcname} '{argname}' documented twice")
 
     return True
-
diff --git a/control/tests/iosys_test.py b/control/tests/iosys_test.py
@@ -2303,3 +2303,37 @@ def test_relabeling(fcn):
     if sys.nstates:
         assert sys.state_labels == ['x']
     assert sys.name == 'new'
+
+
+@pytest.mark.parametrize("fcn", [ct.ss, ct.tf, ct.frd, ct.nlsys, fs.flatsys])
+def test_signal_prefixing(fcn):
+    sys = ct.rss(2, 1, 1)
+
+    # Recreate the system in different forms, with non-standard prefixes
+    match fcn:
+        case ct.ss:
+            sys = ct.ss(
+                sys.A, sys.B, sys.C, sys.D, state_prefix='xx',
+                input_prefix='uu', output_prefix='yy')
+        case ct.tf:
+            sys = ct.tf(sys)
+            sys = fcn(sys.num, sys.den, input_prefix='uu', output_prefix='yy')
+        case ct.frd:
+            freq = [0.1, 1, 10]
+            data = [sys(w * 1j) for w in freq]
+            sys = fcn(data, freq, input_prefix='uu', output_prefix='yy')
+        case ct.nlsys:
+            sys = ct.nlsys(sys)
+            sys = fcn(
+                sys.updfcn, sys.outfcn, inputs=1, outputs=1, states=2,
+                state_prefix='xx', input_prefix='uu', output_prefix='yy')
+        case fs.flatsys:
+            sys = fs.flatsys(sys)
+            sys = fcn(
+                sys.forward, sys.reverse, inputs=1, outputs=1, states=2,
+                state_prefix='xx', input_prefix='uu', output_prefix='yy')
+
+    assert sys.input_labels == ['uu[0]']
+    assert sys.output_labels == ['yy[0]']
+    if sys.nstates:
+        assert sys.state_labels == ['xx[0]', 'xx[1]']
diff --git a/control/xferfcn.py b/control/xferfcn.py
@@ -20,9 +20,9 @@
 
 import numpy as np
 import scipy as sp
-from numpy import angle, array, delete, empty, exp, finfo, ndarray, nonzero, \
-    ones, pi, poly, polyadd, polymul, polyval, real, roots, sqrt, squeeze, \
-    where, zeros
+from numpy import angle, array, delete, empty, exp, finfo, float64, ndarray, \
+    nonzero, ones, pi, poly, polyadd, polymul, polyval, real, roots, sqrt, \
+    squeeze, where, zeros
 from scipy.signal import TransferFunction as signalTransferFunction
 from scipy.signal import cont2discrete, tf2zpk, zpk2tf
 
@@ -1595,6 +1595,8 @@ def tf(*args, **kwargs):
         List of strings that name the individual signals of the transformed
         system.  If not given, the inputs and outputs are the same as the
         original system.
+    input_prefix, output_prefix : string, optional
+        Set the prefix for input and output signals.  Defaults = 'u', 'y'.
     name : string, optional
         System name. If unspecified, a generic name <sys[id]> is generated
         with a unique integer id.
