improve consistency in use of cplt as return type for plots

murrayrm · murrayrm · commit 8b7d3993b322 · 2024-08-08T14:54:49.000-07:00
diff --git a/control/ctrlplot.py b/control/ctrlplot.py
@@ -49,7 +49,7 @@ class ControlPlot(object):
     Attributes
     ----------
     lines : array of list of :class:`matplotlib:Line2D`
-        Array of Line2D objects for each line in the plot.  Generally, The
+        Array of Line2D objects for each line in the plot.  Generally, the
         shape of the array matches the subplots shape and the value of the
         array is a list of Line2D objects in that subplot.  Some plotting
         functions will return variants of this structure, as described in
diff --git a/control/pzmap.py b/control/pzmap.py
@@ -503,7 +503,7 @@ def _click_dispatcher(event):
         else:
             TypeError("system lists not supported with legacy return values")
 
-    return ControlPlot(out, np.asarray(axs), fig, legend=legend)
+    return ControlPlot(out, ax, fig, legend=legend)
 
 
 # Utility function to find gain corresponding to a click event
diff --git a/control/rlocus.py b/control/rlocus.py
@@ -198,13 +198,13 @@ def root_locus_plot(
         return responses.loci, responses.gains
 
     # Plot the root loci
-    ctrlplot = responses.plot(grid=grid, **kwargs)
+    cplt = responses.plot(grid=grid, **kwargs)
 
     # Legacy processing: return locations of poles and zeros as a tuple
     if plot is True:
         return responses.loci, responses.gains
 
-    return ControlPlot(ctrlplot.lines, ctrlplot.axes, ctrlplot.figure)
+    return ControlPlot(cplt.lines, cplt.axes, cplt.figure)
 
 
 def _default_gains(num, den, xlim, ylim):
diff --git a/control/tests/descfcn_test.py b/control/tests/descfcn_test.py
@@ -188,13 +188,13 @@ def test_describing_function_plot():
     assert len(response.intersections) == 1
     assert len(plt.gcf().get_axes()) == 0       # make sure there is no plot
 
-    out = response.plot()
+    cplt = response.plot()
     assert len(plt.gcf().get_axes()) == 1       # make sure there is a plot
-    assert len(out[0]) == 4 and len(out[1]) == 1
+    assert len(cplt.lines[0]) == 4 and len(cplt.lines[1]) == 1
 
     # Call plot directly
-    out = ct.describing_function_plot(H_larger, F_saturation, amp, omega)
-    assert len(out[0]) == 4 and len(out[1]) == 1
+    cplt = ct.describing_function_plot(H_larger, F_saturation, amp, omega)
+    assert len(cplt.lines[0]) == 4 and len(cplt.lines[1]) == 1
 
 
 def test_describing_function_exceptions():
diff --git a/control/tests/freqplot_test.py b/control/tests/freqplot_test.py
@@ -141,8 +141,8 @@ def test_response_plots(
 # Use the manaul response to verify that different settings are working
 def test_manual_response_limits():
     # Default response: limits should be the same across rows
-    out = manual_response.plot()
-    axs = ct.get_plot_axes(out)
+    cplt = manual_response.plot()
+    axs = ct.get_plot_axes(cplt)        # legacy usage OK
     for i in range(manual_response.noutputs):
         for j in range(1, manual_response.ninputs):
             # Everything in the same row should have the same limits
@@ -397,18 +397,18 @@ def test_gangof4_trace_labels():
     C = ct.rss(1, 1, 1, name='C')
 
     # Make sure default labels are as expected
-    out = ct.gangof4_response(P1, C).plot()
-    out = ct.gangof4_response(P2, C).plot()
-    axs = ct.get_plot_axes(out)
+    cplt = ct.gangof4_response(P1, C).plot()
+    cplt = ct.gangof4_response(P2, C).plot()
+    axs = ct.get_plot_axes(cplt)        # legacy usage OK
     legend = axs[0, 1].get_legend().get_texts()
     assert legend[0].get_text() == 'None'
     assert legend[1].get_text() == 'None'
     plt.close()
 
     # Override labels
-    out = ct.gangof4_response(P1, C).plot(label='xxx, line1, yyy')
-    out = ct.gangof4_response(P2, C).plot(label='xxx, line2, yyy')
-    axs = ct.get_plot_axes(out)
+    cplt = ct.gangof4_response(P1, C).plot(label='xxx, line1, yyy')
+    cplt = ct.gangof4_response(P2, C).plot(label='xxx, line2, yyy')
+    axs = ct.get_plot_axes(cplt)        # legacy usage OK
     legend = axs[0, 1].get_legend().get_texts()
     assert legend[0].get_text() == 'xxx, line1, yyy'
     assert legend[1].get_text() == 'xxx, line2, yyy'
@@ -426,8 +426,8 @@ def test_freqplot_line_labels(plt_fcn):
     ct.set_defaults('freqplot', suptitle_frame='figure')
 
     # Make sure default labels are as expected
-    out = plt_fcn([sys1, sys2])
-    axs = ct.get_plot_axes(out)
+    cplt = plt_fcn([sys1, sys2])
+    axs = ct.get_plot_axes(cplt)        # legacy usage OK
     if axs.ndim == 1:
         legend = axs[0].get_legend().get_texts()
     else:
@@ -437,8 +437,8 @@ def test_freqplot_line_labels(plt_fcn):
     plt.close()
 
     # Override labels all at once
-    out = plt_fcn([sys1, sys2], label=['line1', 'line2'])
-    axs = ct.get_plot_axes(out)
+    cplt = plt_fcn([sys1, sys2], label=['line1', 'line2'])
+    axs = ct.get_plot_axes(cplt)        # legacy usage OK
     if axs.ndim == 1:
         legend = axs[0].get_legend().get_texts()
     else:
@@ -448,9 +448,9 @@ def test_freqplot_line_labels(plt_fcn):
     plt.close()
 
     # Override labels one at a time
-    out = plt_fcn(sys1, label='line1')
-    out = plt_fcn(sys2, label='line2')
-    axs = ct.get_plot_axes(out)
+    cplt = plt_fcn(sys1, label='line1')
+    cplt = plt_fcn(sys2, label='line2')
+    axs = ct.get_plot_axes(cplt)        # legacy usage OK
     if axs.ndim == 1:
         legend = axs[0].get_legend().get_texts()
     else:
@@ -475,8 +475,8 @@ def test_line_labels_bode(kwargs, labels):
     with pytest.raises(ValueError, match="number of labels must match"):
         ct.bode_plot([sys1, sys2], label=['line1'])
 
-    out = ct.bode_plot([sys1, sys2], label=labels, **kwargs)
-    axs = ct.get_plot_axes(out)
+    cplt = ct.bode_plot([sys1, sys2], label=labels, **kwargs)
+    axs = ct.get_plot_axes(cplt)        # legacy usage OK
     legend_texts = axs[0, -1].get_legend().get_texts()
     for i, legend in enumerate(legend_texts):
         assert legend.get_text() == labels[i]
@@ -502,22 +502,22 @@ def test_freqplot_ax_keyword(plt_fcn, ninputs, noutputs):
     sys = ct.rss(4, ninputs, noutputs)
 
     # Create an initial figure
-    out1 = plt_fcn(sys)
+    cplt1 = plt_fcn(sys)
 
     # Draw again on the same figure, using array
-    axs = ct.get_plot_axes(out1)
-    out2 = plt_fcn(sys, ax=axs)
-    np.testing.assert_equal(ct.get_plot_axes(out1), ct.get_plot_axes(out2))
+    axs = ct.get_plot_axes(cplt1)       # legacy usage OK
+    cplt2 = plt_fcn(sys, ax=axs)
+    np.testing.assert_equal(cplt1.axes, cplt2.axes)
 
     # Pass things in as a list instead
     axs_list = axs.tolist()
-    out3 = plt_fcn(sys, ax=axs)
-    np.testing.assert_equal(ct.get_plot_axes(out1), ct.get_plot_axes(out3))
+    cplt3 = plt_fcn(sys, ax=axs)
+    np.testing.assert_equal(cplt1.axes, cplt3.axes)
 
     # Flatten the list
     axs_list = axs.squeeze().tolist()
-    out3 = plt_fcn(sys, ax=axs_list)
-    np.testing.assert_equal(ct.get_plot_axes(out1), ct.get_plot_axes(out3))
+    cplt4 = plt_fcn(sys, ax=axs_list)
+    np.testing.assert_equal(cplt1.axes, cplt4.axes)
 
 
 def test_mixed_systypes():
@@ -552,7 +552,7 @@ def test_suptitle():
     sys = ct.rss(2, 2, 2)
 
     # Default location: center of axes
-    out = ct.bode_plot(sys)
+    cplt = ct.bode_plot(sys)
     assert plt.gcf()._suptitle._x != 0.5
 
     # Try changing the the title
diff --git a/control/tests/nyquist_test.py b/control/tests/nyquist_test.py
@@ -399,17 +399,17 @@ def test_linestyle_checks():
     sys = ct.tf([100], [1, 1, 1])
 
     # Set the line styles
-    lines = ct.nyquist_plot(
+    cplt = ct.nyquist_plot(
         sys, primary_style=[':', ':'], mirror_style=[':', ':'])
-    assert all([line.get_linestyle() == ':' for line in lines[0]])
+    assert all([line.get_linestyle() == ':' for line in cplt.lines[0]])
 
     # Set the line colors
-    lines = ct.nyquist_plot(sys, color='g')
-    assert all([line.get_color() == 'g' for line in lines[0]])
+    cplt = ct.nyquist_plot(sys, color='g')
+    assert all([line.get_color() == 'g' for line in cplt.lines[0]])
 
     # Turn off the mirror image
-    lines = ct.nyquist_plot(sys, mirror_style=False)
-    assert lines[0][2:] == [None, None]
+    cplt = ct.nyquist_plot(sys, mirror_style=False)
+    assert cplt.lines[0][2:] == [None, None]
 
     with pytest.raises(ValueError, match="invalid 'primary_style'"):
         ct.nyquist_plot(sys, primary_style=False)
@@ -505,7 +505,7 @@ def test_nyquist_frd():
 
     # Computing Nyquist response w/ different frequencies OK if given as a list
     nyqresp = ct.nyquist_response([sys1, sys2])
-    out = nyqresp.plot()
+    cplt = nyqresp.plot()
 
     warnings.resetwarnings()
 
diff --git a/control/tests/pzmap_test.py b/control/tests/pzmap_test.py
@@ -119,7 +119,7 @@ def test_pzmap_raises():
 
 def test_pzmap_limits():
     sys = ct.tf([1, 2], [1, 2, 3])
-    out = ct.pole_zero_plot(sys, xlim=[-1, 1], ylim=[-1, 1])
-    ax = ct.get_plot_axes(out)[0, 0]
+    cplt = ct.pole_zero_plot(sys, xlim=[-1, 1], ylim=[-1, 1])
+    ax = cplt.axes[0, 0]
     assert ax.get_xlim() == (-1, 1)
     assert ax.get_ylim() == (-1, 1)
diff --git a/control/tests/rlocus_test.py b/control/tests/rlocus_test.py
@@ -204,8 +204,8 @@ def test_root_locus_documentation(savefigs=False):
 
     # TODO: generate event in order to generate real title
     plt.figure()
-    out = ct.root_locus_map(sys).plot(initial_gain=3.506)
-    ax = ct.get_plot_axes(out)[0, 0]
+    cplt = ct.root_locus_map(sys).plot(initial_gain=3.506)
+    ax = cplt.axes[0, 0]
     freqplot_rcParams = ct.config._get_param('freqplot', 'rcParams')
     with plt.rc_context(freqplot_rcParams):
         ax.set_title(
diff --git a/control/tests/timeplot_test.py b/control/tests/timeplot_test.py
diff --git a/control/timeplot.py b/control/timeplot.py
diff --git a/control/timeresp.py b/control/timeresp.py
diff --git a/doc/plotting.rst b/doc/plotting.rst
