add documentation for indexing by name + update docstrings

murrayrm · murrayrm · commit df330028059c · 2024-12-01T11:37:52.000-08:00
diff --git a/control/frdata.py b/control/frdata.py
@@ -35,8 +35,8 @@ class FrequencyResponseData(LTI):
 
     The FrequencyResponseData (FRD) class is used to represent systems in
     frequency response data form.  It can be created manually using the
-    class constructor, using the :func:~~control.frd` factory function
-    (preferred), or via the :func:`~control.frequency_response` function.
+    class constructor, using the :func:`~control.frd` factory function or
+    via the :func:`~control.frequency_response` function.
 
     Parameters
     ----------
@@ -67,6 +67,28 @@ class constructor, using the :func:~~control.frd` factory function
         frequency point.
     dt : float, True, or None
         System timebase.
+    squeeze : bool
+        By default, if a system is single-input, single-output (SISO) then
+        the outputs (and inputs) are returned as a 1D array (indexed by
+        frequency) and if a system is multi-input or multi-output, then the
+        outputs are returned as a 2D array (indexed by output and
+        frequency) or a 3D array (indexed by output, trace, and frequency).
+        If ``squeeze=True``, access to the output response will remove
+        single-dimensional entries from the shape of the inputs and outputs
+        even if the system is not SISO. If ``squeeze=False``, the output is
+        returned as a 3D array (indexed by the output, input, and
+        frequency) even if the system is SISO. The default value can be set
+        using config.defaults['control.squeeze_frequency_response'].
+    ninputs, noutputs, nstates : int
+        Number of inputs, outputs, and states of the underlying system.
+    input_labels, output_labels : array of str
+        Names for the input and output variables.
+    sysname : str, optional
+        Name of the system.  For data generated using
+        :func:`~control.frequency_response`, stores the name of the system
+        that created the data.
+    title : str, optional
+        Set the title to use when plotting.
 
     See Also
     --------
@@ -259,24 +281,72 @@ def __init__(self, *args, **kwargs):
 
     @property
     def magnitude(self):
+        """Magnitude of the frequency response.
+
+        Magnitude of the frequency response, indexed by either the output
+        and frequency (if only a single input is given) or the output,
+        input, and frequency (for multi-input systems).  See
+        :attr:`FrequencyResponseData.squeeze` for a description of how this
+        can be modified using the `squeeze` keyword.
+
+        Input and output signal names can be used to index the data in
+        place of integer offsets.
+
+        :type: 1D, 2D, or 3D array
+
+        """
         return NamedSignal(
             np.abs(self.fresp), self.output_labels, self.input_labels)
 
     @property
     def phase(self):
+        """Phase of the frequency response.
+
+        Phase of the frequency response in radians/sec, indexed by either
+        the output and frequency (if only a single input is given) or the
+        output, input, and frequency (for multi-input systems).  See
+        :attr:`FrequencyResponseData.squeeze` for a description of how this
+        can be modified using the `squeeze` keyword.
+
+        Input and output signal names can be used to index the data in
+        place of integer offsets.
+
+        :type: 1D, 2D, or 3D array
+
+        """
         return NamedSignal(
             np.angle(self.fresp), self.output_labels, self.input_labels)
 
     @property
     def frequency(self):
+        """Frequencies at which the response is evaluated.
+
+        :type: 1D array
+
+        """
         return self.omega
 
     @property
     def response(self):
+        """Complex value of the frequency response.
+
+        Value of the frequency response as a complex number, indexed by
+        either the output and frequency (if only a single input is given)
+        or the output, input, and frequency (for multi-input systems).  See
+        :attr:`FrequencyResponseData.squeeze` for a description of how this
+        can be modified using the `squeeze` keyword.
+
+        Input and output signal names can be used to index the data in
+        place of integer offsets.
+
+        :type: 1D, 2D, or 3D array
+
+        """
         return NamedSignal(
             self.fresp, self.output_labels, self.input_labels)
 
     def __str__(self):
+
         """String representation of the transfer function."""
 
         mimo = self.ninputs > 1 or self.noutputs > 1
diff --git a/control/timeresp.py b/control/timeresp.py
@@ -228,16 +228,12 @@ class TimeResponseData:
        t, y = step_response(sys)
        t, y, x = step_response(sys, return_x=True)
 
-     When using this (legacy) interface, the state vector is not affected
-     by the `squeeze` parameter.
+    Similarly, the class has ``__getitem__`` and ``__len__`` methods that
+    allow the return value to be indexed:
 
-    For backward compatibility with earlier version of python-control, this
-    class has ``__getitem__`` and ``__len__`` methods that allow the return
-    value to be indexed:
-
-       response[0]: returns the time vector
-       response[1]: returns the output vector
-       response[2]: returns the state vector
+    * response[0]: returns the time vector
+    * response[1]: returns the output vector
+    * response[2]: returns the state vector
 
     When using this (legacy) interface, the state vector is not affected
     by the `squeeze` parameter.
@@ -580,6 +576,10 @@ def outputs(self):
         (for multiple traces).  See :attr:`TimeResponseData.squeeze` for a
         description of how this can be modified using the `squeeze` keyword.
 
+        Input and output signal names can be used to index the data in
+        place of integer offsets, with the input signal names being used to
+        access multi-input data.
+
         :type: 1D, 2D, or 3D array
 
         """
@@ -600,6 +600,10 @@ def states(self):
         for a description of how this can be modified using the `squeeze`
         keyword.
 
+        Input and output signal names can be used to index the data in
+        place of integer offsets, with the input signal names being used to
+        access multi-input data.
+
         :type: 2D or 3D array
 
         """
@@ -639,6 +643,10 @@ def inputs(self):
         the two.  If a 3D vector is passed, then it represents a multi-trace,
         multi-input signal, indexed by input, trace, and time.
 
+        Input and output signal names can be used to index the data in
+        place of integer offsets, with the input signal names being used to
+        access multi-input data.
+
         See :attr:`TimeResponseData.squeeze` for a description of how the
         dimensions of the input vector can be modified using the `squeeze`
         keyword.
diff --git a/doc/conventions.rst b/doc/conventions.rst
@@ -98,6 +98,20 @@ argument::
 
     mag, phase, omega = response(squeeze=False)
 
+Frequency response objects are also available as named properties of the
+`response` object: `response.magnitude`, `response.phase`, and
+`response.response` (for the complex response).  For MIMO systems, these
+elements of the frequency response can be accessed using the names of the
+inputs and outputs::
+
+  response.magnitude['y[0]', 'u[1]']
+
+where the signal names are based on the system that generated the frequency
+response.
+
+Note: The `fresp` data member is stored as a NumPy array and cannot be
+accessed with signal names.  Use `response.response` to access the complex
+frequency response using signal names.
 
 Discrete time systems
 ---------------------
@@ -132,6 +146,21 @@ constructor for the desired data type using the original system as the sole
 argument or using the explicit conversion functions :func:`ss2tf` and
 :func:`tf2ss`.
 
+Subsystems
+----------
+Subsets of input/output pairs for LTI systems can be obtained by indexing
+the system using either numerical indices (including slices) or signal
+names::
+
+    subsys = sys[[0, 2], 0:2]
+    subsys = sys[['y[0]', 'y[2]'], ['u[0]', 'u[1]']]
+
+Signal names for an indexed subsystem are preserved from the original
+system and the subsystem name is set according to the values of
+`control.config.defaults['iosys.indexed_system_name_prefix'] and
+`control.config.defaults['iosys.indexed_system_name_suffix'].  The default
+subsystem name is the original system name with '$indexed' appended.
+
 Simulating LTI systems
 ======================
 
@@ -233,7 +262,7 @@ properties::
 
     sys = ct.rss(4, 1, 1)
     response = ct.step_response(sys)
-    plot(response.time, response.outputs)
+    plt.plot(response.time, response.outputs)
 
 The dimensions of the response properties depend on the function being
 called and whether the system is SISO or MIMO.  In addition, some time
@@ -242,6 +271,17 @@ such as the :func:`step_response` function applied to a MIMO system,
 which will compute the step response for each input/output pair.  See
 :class:`TimeResponseData` for more details.
 
+The input, output, and state elements of the response can be access using
+signal names in place of integer offsets::
+
+    plt.plot(response. time, response.states['x[1]']
+
+For multi-trace systems generated by :func:`step_response` and
+:func:`impulse_response`, the input name used to generate the trace can be
+used to access the appropriate input output pair::
+
+    plt.plot(response.time, response.outputs['y[0]', 'u[1]'])
+
 The time response functions can also be assigned to a tuple, which extracts
 the time and output (and optionally the state, if the `return_x` keyword is
 used).  This allows simple commands for plotting::
diff --git a/doc/plotting.rst b/doc/plotting.rst
@@ -79,6 +79,11 @@ the data from the simulation::
       for j in range(2):
           axs[i, j].plot(time, outputs[i, j])
 
+In addition to accessing time response data via integer indices, signal
+names can allow be used::
+
+  plt.plot(response.time, response.outputs['y[0]', 'u[1]'])
+
 A number of options are available in the `plot` method to customize
 the appearance of input output data.  For data produced by the
 :func:`~control.impulse_response` and :func:`~control.step_response`
@@ -278,6 +283,19 @@ maximum frequencies in the (log-spaced) frequency range::
 The number of (log-spaced) points in the frequency can be specified using
 the ``omega_num`` keyword parameter.
 
+Frequency response data can also be accessed directly and plotted manually::
+
+  sys = ct.rss(4, 2, 2, strictly_proper=True)  # 2x2 MIMO system
+  fresp = ct.frequency_response(sys)
+  plt.loglog(fresp.omega, fresp.magnitude['y[1]', 'u[0]'])
+
+Access to frequency response data is available via the attributes
+``omega``, ``magnitude``,` `phase``, and ``response``, where ``response``
+represents the complex value of the frequency response at each frequency.
+The ``magnitude``,` `phase``, and ``response`` arrays can be indexed using
+either input/output indices or signal names, with the first index
+corresponding to the output signal and the second input corresponding to
+the input signal.
 
 Pole/zero data
 ==============
