update response.rst and associated function docstrings

murrayrm · Feb 3, 2025 · Dec 28, 2024 · Dec 28, 2024 · Dec 21, 2024 · Dec 21, 2024
commit aa055377883a33b9ba7b76514f73cb1388eccf49
diff --git a/control/ctrlplot.py b/control/ctrlplot.py
@@ -1,7 +1,9 @@
 # ctrlplot.py - utility functions for plotting
 # Richard M. Murray, 14 Jun 2024
 #
-# Collection of functions that are used by various plotting functions.
+"""
+Collection of functions that are used by various plotting functions.
+"""
 
 # Code pattern for control system plotting functions:
 #
@@ -116,7 +118,7 @@
 #
 
 class ControlPlot(object):
-    """A class for returning control figures.
+    """A class for representing control figures.
 
     This class is used as the return type for control plotting functions.
     It contains the information required to access portions of the plot

diff --git a/doc/examples/.gitignore b/doc/examples/.gitignore
@@ -0,0 +1 @@
+.ipynb_checkpoints/
diff --git a/doc/response.rst b/doc/response.rst
@@ -3,7 +3,7 @@
 .. currentmodule:: control
 
 **********************************
-Input/output Response and Plotting
+Input/Output Response and Plotting
 **********************************
 
 The Python Control Systems Toolbox contains a number of functions for
@@ -160,7 +160,7 @@ which will compute the step response for each input/output pair.  See
 The input, output, and state elements of the response can be accessed using
 signal names in place of integer offsets::
 
-    plt.plot(response. time, response.states['x[1]']
+    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
@@ -202,18 +202,15 @@ data frame correspond to time and "cols" (DataSeries) correspond to signals.
 Time response plots
 -------------------
 
-.. todo:: Improve flow between previous section and this one
-
-Input/output time responses are produced one of several python-control
-functions: :func:`forced_response`,
+The input/output time response functions ( :func:`forced_response`,
 :func:`impulse_response`, :func:`initial_response`,
-:func:`input_output_response`, :func:`step_response`.
-Each of these return a :class:`TimeResponseData` object, which
-contains the time, input, state, and output vectors associated with the
-simulation. Time response data can be plotted with the
-:func:`time_response_plot` function, which is also available as
-the :func:`TimeResponseData.plot` method.  For example, the step
-response for a two-input, two-output can be plotted using the commands::
+:func:`input_output_response`, :func:`step_response`) return a
+:class:`TimeResponseData` object, which contains the time, input,
+state, and output vectors associated with the simulation, as described
+above. Time response data can be plotted with the
+:func:`time_response_plot` function, which is also available as the
+:func:`TimeResponseData.plot` method.  For example, the step response
+for a two-input, two-output can be plotted using the commands::
 
   sys_mimo = ct.tf2ss(
       [[[1], [0.1]], [[0.2], [1]]],
@@ -225,31 +222,17 @@ which produces the following plot:
 
 .. image:: figures/timeplot-mimo_step-default.png
 
-The  :class:`TimeResponseData` object can also be used to access
-the data from the simulation::
-
-  time, outputs, inputs = response.time, response.outputs, response.inputs
-  fig, axs = plt.subplots(2, 2)
-  for i in range(2):
-      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:`impulse_response` and :func:`step_response`
-commands, the inputs are not shown.  This behavior can be changed
-using the `plot_inputs` keyword.  It is also possible to combine
-multiple lines onto a single graph, using either the `overlay_signals`
-keyword (which puts all outputs out a single graph and all inputs on a
-single graph) or the `overlay_traces` keyword, which puts different
-traces (e.g., corresponding to step inputs in different channels) on
-the same graph, with appropriate labeling via a legend on selected
-axes.
+A number of options are available in the :func:`time_response_plot`
+function (and associated :func:`TimeResponseData.plot` method) to
+customize the appearance of input output data.  For data produced by
+the :func:`impulse_response` and :func:`step_response` commands, the
+inputs are not shown.  This behavior can be changed using the
+`plot_inputs` keyword.  It is also possible to combine multiple lines
+onto a single graph, using either the `overlay_signals` keyword (which
+puts all outputs out a single graph and all inputs on a single graph)
+or the `overlay_traces` keyword, which puts different traces (e.g.,
+corresponding to step inputs in different channels) on the same graph,
+with appropriate labeling via a legend on selected axes.
 
 For example, using `plot_input=True` and `overlay_signals=True` yields the
 following plot::