diff --git a/control/nichols.py b/control/nichols.py index a643d8580..69546678b 100644 --- a/control/nichols.py +++ b/control/nichols.py @@ -51,6 +51,8 @@ import numpy as np import matplotlib.pyplot as plt +import matplotlib.transforms + from .ctrlutil import unwrap from .freqplot import _default_frequency_range from . import config @@ -119,7 +121,18 @@ def nichols_plot(sys_list, omega=None, grid=None): nichols_grid() -def nichols_grid(cl_mags=None, cl_phases=None, line_style='dotted'): +def _inner_extents(ax): + # intersection of data and view extents + # if intersection empty, return view extents + _inner = matplotlib.transforms.Bbox.intersection(ax.viewLim, ax.dataLim) + if _inner is None: + return ax.ViewLim.extents + else: + return _inner.extents + + +def nichols_grid(cl_mags=None, cl_phases=None, line_style='dotted', ax=None, + label_cl_phases=True): """Nichols chart grid Plots a Nichols chart grid on the current axis, or creates a new chart @@ -136,17 +149,36 @@ def nichols_grid(cl_mags=None, cl_phases=None, line_style='dotted'): line_style : string, optional :doc:`Matplotlib linestyle \ ` + ax : matplotlib.axes.Axes, optional + Axes to add grid to. If ``None``, use ``plt.gca()``. + label_cl_phases: bool, optional + If True, closed-loop phase lines will be labelled. + Returns + ------- + cl_mag_lines: list of `matplotlib.line.Line2D` + The constant closed-loop gain contours + cl_phase_lines: list of `matplotlib.line.Line2D` + The constant closed-loop phase contours + cl_mag_labels: list of `matplotlib.text.Text` + mcontour labels; each entry corresponds to the respective entry + in ``cl_mag_lines`` + cl_phase_labels: list of `matplotlib.text.Text` + ncontour labels; each entry corresponds to the respective entry + in ``cl_phase_lines`` """ + if ax is None: + ax = plt.gca() + # Default chart size ol_phase_min = -359.99 ol_phase_max = 0.0 ol_mag_min = -40.0 ol_mag_max = default_ol_mag_max = 50.0 - # Find bounds of the current dataset, if there is one. - if plt.gcf().gca().has_data(): - ol_phase_min, ol_phase_max, ol_mag_min, ol_mag_max = plt.axis() + if ax.has_data(): + # Find extent of intersection the current dataset or view + ol_phase_min, ol_mag_min, ol_phase_max, ol_mag_max = _inner_extents(ax) # M-circle magnitudes. if cl_mags is None: @@ -165,19 +197,22 @@ def nichols_grid(cl_mags=None, cl_phases=None, line_style='dotted'): ol_mag_min + cl_mag_step, cl_mag_step) cl_mags = np.concatenate((extended_cl_mags, key_cl_mags)) + # a minimum 360deg extent containing the phases + phase_round_max = 360.0*np.ceil(ol_phase_max/360.0) + phase_round_min = min(phase_round_max-360, + 360.0*np.floor(ol_phase_min/360.0)) + # N-circle phases (should be in the range -360 to 0) if cl_phases is None: - # Choose a reasonable set of default phases (denser if the open-loop - # data is restricted to a relatively small range of phases). - key_cl_phases = np.array([-0.25, -45.0, -90.0, -180.0, -270.0, - -325.0, -359.75]) - if np.abs(ol_phase_max - ol_phase_min) < 90.0: - other_cl_phases = np.arange(-10.0, -360.0, -10.0) - else: - other_cl_phases = np.arange(-10.0, -360.0, -20.0) - cl_phases = np.concatenate((key_cl_phases, other_cl_phases)) - else: - assert ((-360.0 < np.min(cl_phases)) and (np.max(cl_phases) < 0.0)) + # aim for 9 lines, but always show (-360+eps, -180, -eps) + # smallest spacing is 45, biggest is 180 + phase_span = phase_round_max - phase_round_min + spacing = np.clip(round(phase_span / 8 / 45) * 45, 45, 180) + key_cl_phases = np.array([-0.25, -359.75]) + other_cl_phases = np.arange(-spacing, -360.0, -spacing) + cl_phases = np.unique(np.concatenate((key_cl_phases, other_cl_phases))) + elif not ((-360 < np.min(cl_phases)) and (np.max(cl_phases) < 0.0)): + raise ValueError('cl_phases must between -360 and 0, exclusive') # Find the M-contours m = m_circles(cl_mags, phase_min=np.min(cl_phases), @@ -196,27 +231,57 @@ def nichols_grid(cl_mags=None, cl_phases=None, line_style='dotted'): # over the range -360 < phase < 0. Given the range # the base chart is computed over, the phase offset should be 0 # for -360 < ol_phase_min < 0. - phase_offset_min = 360.0*np.ceil(ol_phase_min/360.0) - phase_offset_max = 360.0*np.ceil(ol_phase_max/360.0) + 360.0 - phase_offsets = np.arange(phase_offset_min, phase_offset_max, 360.0) + phase_offsets = 360 + np.arange(phase_round_min, phase_round_max, 360.0) + + cl_mag_lines = [] + cl_phase_lines = [] + cl_mag_labels = [] + cl_phase_labels = [] for phase_offset in phase_offsets: # Draw M and N contours - plt.plot(m_phase + phase_offset, m_mag, color='lightgray', - linestyle=line_style, zorder=0) - plt.plot(n_phase + phase_offset, n_mag, color='lightgray', - linestyle=line_style, zorder=0) + cl_mag_lines.extend( + ax.plot(m_phase + phase_offset, m_mag, color='lightgray', + linestyle=line_style, zorder=0)) + cl_phase_lines.extend( + ax.plot(n_phase + phase_offset, n_mag, color='lightgray', + linestyle=line_style, zorder=0)) # Add magnitude labels for x, y, m in zip(m_phase[:][-1] + phase_offset, m_mag[:][-1], cl_mags): align = 'right' if m < 0.0 else 'left' - plt.text(x, y, str(m) + ' dB', size='small', ha=align, - color='gray') + cl_mag_labels.append( + ax.text(x, y, str(m) + ' dB', size='small', ha=align, + color='gray', clip_on=True)) + + # phase labels + if label_cl_phases: + for x, y, p in zip(n_phase[:][0] + phase_offset, + n_mag[:][0], + cl_phases): + if p > -175: + align = 'right' + elif p > -185: + align = 'center' + else: + align = 'left' + cl_phase_labels.append( + ax.text(x, y, f'{round(p)}\N{DEGREE SIGN}', + size='small', + ha=align, + va='bottom', + color='gray', + clip_on=True)) + # Fit axes to generated chart - plt.axis([phase_offset_min - 360.0, phase_offset_max - 360.0, - np.min(cl_mags), np.max([ol_mag_max, default_ol_mag_max])]) + ax.axis([phase_round_min, + phase_round_max, + np.min(np.concatenate([cl_mags,[ol_mag_min]])), + np.max([ol_mag_max, default_ol_mag_max])]) + + return cl_mag_lines, cl_phase_lines, cl_mag_labels, cl_phase_labels # # Utility functions diff --git a/control/tests/nichols_test.py b/control/tests/nichols_test.py index 4cdfcaa65..90ea74cf7 100644 --- a/control/tests/nichols_test.py +++ b/control/tests/nichols_test.py @@ -3,9 +3,11 @@ RMM, 31 Mar 2011 """ +import matplotlib.pyplot as plt + import pytest -from control import StateSpace, nichols_plot, nichols +from control import StateSpace, nichols_plot, nichols, nichols_grid, pade, tf @pytest.fixture() @@ -26,3 +28,68 @@ def test_nichols(tsys, mplcleanup): def test_nichols_alias(tsys, mplcleanup): """Test the control.nichols alias and the grid=False parameter""" nichols(tsys, grid=False) + + +@pytest.mark.usefixtures("mplcleanup") +class TestNicholsGrid: + def test_ax(self): + # check grid is plotted into gca, or specified axis + fig, axs = plt.subplots(2,2) + plt.sca(axs[0,1]) + + cl_mag_lines = nichols_grid()[1] + assert cl_mag_lines[0].axes is axs[0, 1] + + cl_mag_lines = nichols_grid(ax=axs[1,1])[1] + assert cl_mag_lines[0].axes is axs[1, 1] + # nichols_grid didn't change what the "current axes" are + assert plt.gca() is axs[0, 1] + + + def test_cl_phase_label_control(self): + # test label_cl_phases argument + cl_mag_lines, cl_phase_lines, cl_mag_labels, cl_phase_labels \ + = nichols_grid() + assert len(cl_phase_labels) > 0 + + cl_mag_lines, cl_phase_lines, cl_mag_labels, cl_phase_labels \ + = nichols_grid(label_cl_phases=False) + assert len(cl_phase_labels) == 0 + + + def test_labels_clipped(self): + # regression test: check that contour labels are clipped + mcontours, ncontours, mlabels, nlabels = nichols_grid() + assert all(ml.get_clip_on() for ml in mlabels) + assert all(nl.get_clip_on() for nl in nlabels) + + + def test_minimal_phase(self): + # regression test: phase extent is minimal + g = tf([1],[1,1]) * tf([1],[1/1, 2*0.1/1, 1]) + nichols(g) + ax = plt.gca() + assert ax.get_xlim()[1] <= 0 + + + def test_fixed_view(self): + # respect xlim, ylim set by user + g = (tf([1],[1/1, 2*0.01/1, 1]) + * tf([1],[1/100**2, 2*0.001/100, 1]) + * tf(*pade(0.01, 5))) + + # normally a broad axis + nichols(g) + + assert(plt.xlim()[0] == -1440) + assert(plt.ylim()[0] <= -240) + + nichols(g, grid=False) + + # zoom in + plt.axis([-360,0,-40,50]) + + # nichols_grid doesn't expand limits + nichols_grid() + assert(plt.xlim()[0] == -360) + assert(plt.ylim()[1] >= -40)