add NamedSignal documentation + tweak control classes figure

murrayrm · murrayrm · commit bba4f580deec · 2025-07-04T12:10:52.000-04:00
diff --git a/control/iosys.py b/control/iosys.py
@@ -46,6 +46,24 @@ class NamedSignal(np.ndarray):
     This class modifies the `numpy.ndarray` class and allows signals to
     be accessed using the signal name in addition to indices and slices.
 
+    Signals can be either a 2D array, index by signal and time, or a 3D
+    array, indexed by signal, trace, and time.
+
+    Attributes
+    ----------
+    signal_labels : list of str
+        Label names for each of the signal elements in the signal.
+    trace_labels : list of str, optional
+        Label names for each of the traces in the signal (if multi-trace).
+
+    Examples
+    --------
+    >>> sys = ct.rss(
+    ...     states=['p1', 'p2', 'p3'], inputs=['u1', 'u2'], outputs=['y'])
+    >>> resp = ct.step_response(sys)
+    >>> resp.states['p1', 'u1']  # Step response from u1 to p1
+    NamedSignal(...)
+
     """
     def __new__(cls, input_array, signal_labels=None, trace_labels=None):
         # See https://numpy.org/doc/stable/user/basics.subclassing.html
diff --git a/doc/_templates/extended-class-template.rst b/doc/_templates/extended-class-template.rst
@@ -0,0 +1,9 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :no-members:
+   :show-inheritance:
+   :no-inherited-members:
+   :no-special-members:
diff --git a/doc/classes.rst b/doc/classes.rst
@@ -14,10 +14,10 @@ systems (both linear time-invariant and nonlinear).  They are usually
 created from factory functions such as :func:`tf` and :func:`ss`, so the
 user should normally not need to instantiate these directly.
 
-The following figure illustrates the relationship between the classes.
+The following figure illustrates the relationship between the classes:
 
-.. image:: figures/classes.pdf
-   :width: 800
+.. figure:: figures/classes.pdf
+   :width: 480
    :align: center
 
 .. autosummary::
@@ -34,6 +34,17 @@ The following figure illustrates the relationship between the classes.
    InterconnectedSystem
    LinearICSystem
 
+The time response of an input/output system is represented using a
+special :class:`NamedSignal` class that allows the individual signal
+elements to be access using signal names in palce of integer offsets:
+
+.. autosummary::
+   :toctree: generated/
+   :template: extended-class-template.rst
+   :nosignatures:
+
+   NamedSignal
+
 
 Response and Plotting Classes
 =============================
diff --git a/doc/figures/classes.fig b/doc/figures/classes.fig
@@ -1,4 +1,5 @@
-#FIG 3.2  Produced by xfig version 3.2.8b
+#FIG 3.2  Produced by xfig version 3.2.9
+#encoding: UTF-8
 Landscape
 Center
 Inches
@@ -37,12 +38,13 @@ Single
 2 1 0 2 1 7 50 -1 -1 0.000 0 0 7 0 1 2
 	1 0 1.00 60.00 90.00
 	 6525 1950 7050 2550
-4 1 1 50 -1 16 12 0.0000 4 210 2115 4050 3675 InterconnectedSystem\001
-4 1 1 50 -1 16 12 0.0000 4 165 1605 7950 3675 TransferFunction\001
-4 1 1 50 -1 0 12 0.0000 4 150 345 7050 2775 LTI\001
-4 1 1 50 -1 16 12 0.0000 4 210 1830 5175 2775 NonlinearIOSystem\001
-4 1 1 50 -1 16 12 0.0000 4 210 1095 6150 3675 StateSpace\001
-4 1 1 50 -1 16 12 0.0000 4 210 1500 5175 4575 LinearICSystem\001
-4 2 1 50 -1 16 12 0.0000 4 210 1035 3375 3225 FlatSystem\001
-4 0 1 50 -1 16 12 0.0000 4 165 420 8400 3225 FRD\001
-4 1 1 50 -1 16 12 0.0000 4 210 1770 6300 1875 InputOutputSystem\001
+4 1 1 50 -1 16 12 0.0000 4 191 1958 4050 3675 InterconnectedSystem\001
+4 1 1 50 -1 16 12 0.0000 4 151 1496 7950 3675 TransferFunction\001
+4 1 1 50 -1 0 12 0.0000 4 133 305 7050 2775 LTI\001
+4 1 1 50 -1 16 12 0.0000 4 191 1705 5175 2775 NonlinearIOSystem\001
+4 1 1 50 -1 16 12 0.0000 4 190 1016 6150 3675 StateSpace\001
+4 1 1 50 -1 16 12 0.0000 4 191 1394 5175 4575 LinearICSystem\001
+4 2 1 50 -1 16 12 0.0000 4 191 970 3375 3225 FlatSystem\001
+4 0 1 50 -1 16 12 0.0000 4 145 384 8400 3225 FRD\001
+4 1 1 50 -1 16 12 0.0000 4 191 1681 6300 1875 InputOutputSystem\001
+4 1 7 50 -1 16 12 0.0000 4 22 21 5175 4800 .\001
diff --git a/doc/figures/classes.pdf b/doc/figures/classes.pdf
