diff --git a/control/freqplot.py b/control/freqplot.py index 35a5ee503..1b7f43c33 100644 --- a/control/freqplot.py +++ b/control/freqplot.py @@ -1104,7 +1104,7 @@ def gen_zero_centered_series(val_min, val_max, period): 'nyquist.arrow_size': 8, # pixel size for arrows 'nyquist.encirclement_threshold': 0.05, # warning threshold 'nyquist.indent_radius': 1e-4, # indentation radius - 'nyquist.indent_direction': 'right', # indentation direction + 'nyquist.indent_direction': None, # automatic indentation 'nyquist.indent_points': 200, # number of points to insert 'nyquist.max_curve_magnitude': 15, # rescale large values 'nyquist.blend_fraction': 0.15, # when to start scaling @@ -1240,10 +1240,13 @@ def nyquist_response( Define the threshold for generating a warning if the number of net encirclements is a non-integer value. Default value is 0.05 and can be set using `config.defaults['nyquist.encirclement_threshold']`. - indent_direction : str, optional - For poles on the imaginary axis, set the direction of indentation to - be 'right' (default), 'left', or 'none'. The default value can - be set using `config.defaults['nyquist.indent_direction']`. + indent_direction : str or None, optional + Direction to indent around poles within `indent_radius` of the + imaginary axis: 'right', 'left', or 'none' (disable indentation). + The default, None, indents to the right of stable poles and poles + exactly on the imaginary axis, and to the left of unstable poles. + The default value can be set using + `config.defaults['nyquist.indent_direction']`. indent_points : int, optional Number of points to insert in the Nyquist contour around poles that are at or near the imaginary axis. @@ -1277,10 +1280,18 @@ def nyquist_response( If a continuous-time system contains poles on or near the imaginary axis, a small indentation will be used to avoid the pole. The radius of the indentation is given by `indent_radius` and it is taken to the - right of stable poles and the left of unstable poles. If a pole is - exactly on the imaginary axis, the `indent_direction` parameter can be - used to set the direction of indentation. Setting `indent_direction` - to 'none' will turn off indentation. + right of stable poles and the left of unstable poles by default. Poles + exactly on the imaginary axis are indented to the right. Setting + `indent_direction` to 'left' or 'right' overrides this choice for all + poles within `indent_radius` of the axis; 'none' turns off indentation. + Explicit directions can change which open-loop poles are enclosed by + the contour, and hence the number of encirclements. + + When `omega` is supplied, no extra points are added for indentations. + The frequencies must resolve each detour sufficiently. Automatic + frequency selection adds `indent_points` around nearby poles. A forced + detour around the far side of an off-axis pole can change both the real + and imaginary parts of the corresponding contour points. For those portions of the Nyquist plot in which the contour is indented to avoid poles, resulting in a scaling of the Nyquist plot, the line @@ -1312,8 +1323,6 @@ def nyquist_response( # Use existing dictionary, to keep track of processed keywords _kwargs |= kwargs - indent_direction_arg = 'indent_direction' in _kwargs - # Get values for params omega_num_given = omega_num is not None omega_num = config._get_param('freqplot', 'number_of_samples', omega_num) @@ -1322,11 +1331,16 @@ def nyquist_response( encirclement_threshold = config._get_param( 'nyquist', 'encirclement_threshold', _kwargs, _nyquist_defaults, pop=True) - indent_direction = config._get_param( - 'nyquist', 'indent_direction', _kwargs, _nyquist_defaults, pop=True) + # Unlike most configuration parameters, None explicitly selects automatic + # indentation, even if the configured default specifies a direction. + indent_direction = _kwargs.pop('indent_direction', config._get_param( + 'nyquist', 'indent_direction', defval=_nyquist_defaults)) indent_points = config._get_param( 'nyquist', 'indent_points', _kwargs, _nyquist_defaults, pop=True) + if indent_direction not in (None, 'left', 'right', 'none'): + raise ValueError("unknown value for indent_direction") + if _check_kwargs and _kwargs: raise TypeError("unrecognized keywords: ", str(_kwargs)) @@ -1401,26 +1415,26 @@ def nyquist_response( # # Check to make sure indent radius is small enough # - # If there is a closed loop pole that is near the imaginary axis - # at a point that is near an open loop pole, it is possible that + # If there is a closed loop pole inside an indentation circle, # indentation might skip or create an extraneous encirclement. + # Forced detours can reach past the imaginary-axis strip of + # width indent_radius, so check proximity to the indented poles. # We check for that situation here and generate a warning if that # could happen. # + indent_poles = splane_poles[abs(splane_poles.real) < indent_radius] for p_cl in splane_cl_poles: - # See if any closed loop poles are near the imaginary axis - if abs(p_cl.real) <= indent_radius: + if len(indent_poles) > 0: # See if any open loop poles are close to closed loop poles - if len(splane_poles) > 0: - p_ol = splane_poles[ - (np.abs(splane_poles - p_cl)).argmin()] + p_ol = indent_poles[ + (np.abs(indent_poles - p_cl)).argmin()] - if abs(p_ol - p_cl) <= indent_radius and \ - warn_encirclements: - warnings.warn( - "indented contour may miss closed loop pole; " - "consider reducing indent_radius to below " - f"{abs(p_ol - p_cl):5.2g}", stacklevel=2) + if abs(p_ol - p_cl) <= indent_radius and \ + warn_encirclements: + warnings.warn( + "indented contour may miss closed loop pole; " + "consider reducing indent_radius to below " + f"{abs(p_ol - p_cl):5.2g}", stacklevel=2) # # See if we should add some frequency points near imaginary poles @@ -1428,16 +1442,26 @@ def nyquist_response( for p in splane_poles: # See if we need to process this pole (skip if on the negative # imaginary axis or not near imaginary axis + user override) - if p.imag < 0 or abs(p.real) > indent_radius or \ + if p.imag < 0 or abs(p.real) >= indent_radius or \ omega_range_given: continue + # Find the circle's intersections with the imaginary axis. + half_height = np.sqrt(indent_radius**2 - p.real**2) + start_freq = max(0, p.imag - half_height) + end_freq = p.imag + half_height + side = 1 if indent_direction == 'right' or ( + indent_direction is None and p.real <= 0) else -1 + if side * p.real > 0 and p.imag < indent_radius: + # A major arc crossing the real axis starts there, so that + # the primary contour still joins its mirror image. + start_freq = 0 + # Find the frequencies before the pole frequency below_points = np.argwhere( - splane_contour.imag - abs(p.imag) < -indent_radius) + splane_contour.imag < start_freq) if below_points.size > 0: first_point = below_points[-1].item() - start_freq = p.imag - indent_radius else: # Add the points starting at the beginning of the contour assert splane_contour[0] == 0 @@ -1446,7 +1470,7 @@ def nyquist_response( # Find the frequencies after the pole frequency above_points = np.argwhere( - splane_contour.imag - abs(p.imag) > indent_radius) + splane_contour.imag > end_freq) last_point = above_points[0].item() # Add points for half/quarter circle around pole frequency @@ -1454,7 +1478,7 @@ def nyquist_response( splane_contour = np.concatenate(( splane_contour[0:first_point+1], (1j * np.linspace( - start_freq, p.imag + indent_radius, indent_points)), + start_freq, end_freq, indent_points)), splane_contour[last_point:])) # Indent points that are too close to a pole @@ -1462,41 +1486,45 @@ def nyquist_response( for i, s in enumerate(splane_contour): # Find the nearest pole p = splane_poles[(np.abs(splane_poles - s)).argmin()] + if s.imag == 0 and p.imag < 0: + p = p.conjugate() - # See if we need to indent around it - if abs(s - p) < indent_radius: - # Figure out how much to offset (simple trigonometry) - offset = np.sqrt( - indent_radius ** 2 - (s - p).imag ** 2) \ - - (s - p).real - - # Figure out which way to offset the contour point - if indent_direction_arg: - if indent_direction == 'right': - # Indent to the right - splane_contour[i] += offset - - elif indent_direction == 'left': - # Indent to the left - splane_contour[i] -= offset - - else: - raise ValueError( - "unknown value for indent_direction") - - elif p.real < 0 or (p.real == 0 and - indent_direction == 'right'): - # Indent to the right - splane_contour[i] += offset - - elif p.real > 0 or (p.real == 0 and - indent_direction == 'left'): - # Indent to the left - splane_contour[i] -= offset + side = 1 if indent_direction == 'right' or ( + indent_direction is None and p.real <= 0) else -1 + major_arc = side * p.real > 0 + crosses_origin = major_arc and 0 <= p.imag < indent_radius + # See if we need to indent around it + if abs(p.real) >= indent_radius: + continue + half_height = np.sqrt(indent_radius**2 - p.real**2) + if abs(s - p) < indent_radius or ( + crosses_origin and + 0 <= s.imag <= p.imag + half_height): + if major_arc: + # The far side of an off-axis pole requires a major + # arc to join the imaginary axis continuously. + angle = np.arccos(-side * p.real / indent_radius) + start_freq = max(0, p.imag - half_height) + start_angle = -angle + if crosses_origin: + start_freq = 0 + start_angle = -np.arcsin( + p.imag / indent_radius) + fraction = (s.imag - start_freq) / ( + p.imag + half_height - start_freq) + theta = start_angle + fraction * ( + angle - start_angle) + splane_contour[i] = p + indent_radius * ( + side * np.cos(theta) + 1j * np.sin(theta)) + if s.imag == 0: + splane_contour[i] = splane_contour[i].real else: - raise ValueError( - "unknown value for indent_direction") + # Preserve the frequencies on the near-side arc. + offset = np.sqrt( + indent_radius**2 - (s - p).imag**2) + splane_contour[i] = ( + p.real + side * offset + 1j * s.imag) # change contour to z-plane if necessary if sys.isctime(): @@ -1536,18 +1564,22 @@ def nyquist_response( if isinstance(sys, (StateSpace, TransferFunction)): # Count the number of open/closed loop RHP poles if sys.isctime(): - if indent_direction == 'right': - P = (sys.poles().real > 0).sum() - else: - P = (sys.poles().real >= 0).sum() + P = (sys.poles().real >= 0).sum() Z = (sys.feedback().poles().real >= 0).sum() else: - if indent_direction == 'right': - P = (np.abs(sys.poles()) > 1).sum() - else: - P = (np.abs(sys.poles()) >= 1).sum() + P = (np.abs(sys.poles()) >= 1).sum() Z = (np.abs(sys.feedback().poles()) >= 1).sum() + if indent_direction != 'none': + # Explicit directions can include stable poles or exclude + # unstable poles. Use the mapped poles for discrete systems + # so the pole count and the contour use the same boundary. + enclosed = splane_poles.real > 0 + if indent_direction is not None: + enclosed[abs(splane_poles.real) < indent_radius] = ( + indent_direction == 'left') + P = enclosed.sum() + # Check to make sure the results make sense; warn if not if Z != count + P and warn_encirclements: warnings.warn( @@ -1662,9 +1694,10 @@ def nyquist_plot( Define the threshold for generating a warning if the number of net encirclements is a non-integer value. Default value is 0.05 and can be set using `config.defaults['nyquist.encirclement_threshold']`. - indent_direction : str, optional - For poles on the imaginary axis, set the direction of indentation to - be 'right' (default), 'left', or 'none'. + indent_direction : str or None, optional + Direction to indent around poles on or near the imaginary axis: + 'right', 'left', or 'none' (disable indentation). The default, None, + selects the side automatically; see `nyquist_response`. indent_points : int, optional Number of points to insert in the Nyquist contour around poles that are at or near the imaginary axis. @@ -1761,11 +1794,13 @@ def nyquist_plot( If a continuous-time system contains poles on or near the imaginary axis, a small indentation will be used to avoid the pole. The radius of the indentation is given by `indent_radius` and it is taken to the - right of stable poles and the left of unstable poles. If a pole is - exactly on the imaginary axis, the `indent_direction` parameter can be - used to set the direction of indentation. Setting `indent_direction` - to 'none' will turn off indentation. If `return_contour` is True, - the exact contour used for evaluation is returned. + right of stable poles and the left of unstable poles by default. Poles + exactly on the imaginary axis are indented to the right. Setting + `indent_direction` to 'left' or 'right' overrides this choice for all + poles within `indent_radius` of the axis; 'none' turns off indentation. + Explicit directions can change which open-loop poles are enclosed by + the contour, and hence the number of encirclements. If `return_contour` + is True, the exact contour used for evaluation is returned. For those portions of the Nyquist plot in which the contour is indented to avoid poles, resulting in a scaling of the Nyquist plot, the line diff --git a/control/tests/nyquist_test.py b/control/tests/nyquist_test.py index 6beb68ef2..cfef355df 100644 --- a/control/tests/nyquist_test.py +++ b/control/tests/nyquist_test.py @@ -395,6 +395,131 @@ def test_nyquist_indent_near_imaginary_axis(): assert contour_left[pole_index].real < 0 +@pytest.mark.parametrize( + 'direction', ['default', None, 'left', 'right', 'none']) +@pytest.mark.parametrize('distance', [-2, -1, -.99, -.5, -1e-10, + 0, 1e-10, .5, .99, 1, 2]) +@pytest.mark.parametrize('dt', [0, .1]) +def test_nyquist_indent_geometry(direction, distance, dt): + """Indentations are circles centered on the pole, on the chosen side.""" + radius = .1 + pole = distance * radius + if dt: + pole = np.exp(pole * dt) + sys = ct.tf([1], [1, -pole], dt) + pole = np.log(complex(pole)).real / dt if dt else pole + if abs(distance) == 1: + # Make this a tangent circle in the mapped plane as well. + radius = abs(pole) + omega = np.linspace(0, .2, 101) + kwargs = {} if direction == 'default' else {'indent_direction': direction} + if direction == 'none' and distance == 0: + with pytest.raises( + RuntimeError, match='attempt to evaluate at a pole'): + ct.nyquist_response(sys, omega, **kwargs) + return + response = ct.nyquist_response( + sys, omega, indent_radius=radius, warn_encirclements=False, **kwargs) + contour = np.log(response.contour) / dt if dt else response.contour + + # At/outside the radius, and with 'none', do not change the contour. + if abs(pole) >= radius or direction == 'none': + np.testing.assert_allclose(contour, 1j * omega, atol=1e-14) + return + + side = -1 if direction == 'left' or ( + direction in ['default', None] and pole > 0) else 1 + indented = abs(contour.real) > 1e-14 + assert np.any(indented) + assert np.all(side * contour[indented].real > 0) + np.testing.assert_allclose(abs(contour[indented] - pole), radius) + np.testing.assert_allclose(contour[0], pole + side * radius, atol=1e-14) + + +@pytest.mark.parametrize('direction', [None, 'left', 'right']) +@pytest.mark.parametrize('distance', [-.999, -.5, -1e-10, 0, 1e-10, .5, .999]) +@pytest.mark.parametrize('frequency', [0, .05, 1]) +@pytest.mark.parametrize('dt', [0, .1]) +def test_nyquist_indent_generated_contour(direction, distance, frequency, dt): + """Automatic sampling resolves the full detour, including major arcs.""" + radius = .1 + real = distance * radius + sys = ct.tf([1], [1, -real]) if frequency == 0 else ct.tf( + [1, 1], [1, -2 * real, real**2 + frequency**2]) + if dt: + sys = ct.c2d(sys, dt) + poles = np.log(sys.poles()) / dt if dt else sys.poles() + pole = poles[np.argmin(abs(poles - (real + 1j * frequency)))] + with warnings.catch_warnings(): + warnings.simplefilter('error') + response = ct.nyquist_response( + sys, indent_radius=radius, indent_direction=direction) + + contour = np.log(response.contour) / dt if dt else response.contour + local = contour[abs(contour - pole) <= radius * (1+1e-9)] + assert len(local) >= 40 + np.testing.assert_allclose(abs(local - pole), radius) + assert np.max(abs(np.diff(local))) < radius / 2 + assert response.contour[0].imag == 0 + + # Count the open-loop poles enclosed by the actual indented contour. + enclosed = direction == 'left' or (direction is None and pole.real > 0) + assert response.count == -(1 if frequency == 0 else 2) * enclosed + + +@pytest.mark.parametrize('configured', [None, 'left', 'right', 'none']) +@pytest.mark.parametrize( + 'explicit', ['default', None, 'left', 'right', 'none']) +def test_nyquist_indent_configuration(configured, explicit, editsdefaults): + """Keyword arguments override configuration, including explicit None.""" + ct.defaults['nyquist.indent_direction'] = configured + sys = ct.tf([1], [1, -.05]) + kwargs = {} if explicit == 'default' else {'indent_direction': explicit} + contour = ct.nyquist_response( + sys, [0, .2, 1], indent_radius=.1, + warn_encirclements=False, **kwargs).contour + direction = configured if explicit == 'default' else explicit + expected = {'left': -.05, 'right': .15, 'none': 0, None: -.05}[direction] + np.testing.assert_allclose(contour[0], expected) + + +@pytest.mark.parametrize('omega', [None, [0, 1, 10]]) +def test_nyquist_indent_invalid_direction(omega): + """Validate the direction even when no poles need indentation.""" + with pytest.raises(ValueError, match='unknown value for indent_direction'): + ct.nyquist_response(ct.tf([1], [1, 1]), omega, indent_direction='up') + + +@pytest.mark.parametrize('representation', ['tf', 'ss']) +def test_nyquist_indent_issue1191(representation): + """Roundoff in imaginary poles must not override an explicit direction.""" + sys = ct.tf([1, 11, 10], [.01, 1, .01, 1]) + if representation == 'ss': + sys = ct.ss(sys) + responses = [ct.nyquist_response( + sys, indent_radius=.2, indent_direction=direction) + for direction in ['right', 'left']] + for response, side in zip(responses, [1, -1]): + indented = (abs(response.contour.real) > 1e-10) & ( + abs(response.contour.imag - 1) <= .2 + 1e-10) + assert np.all(side * response.contour[indented].real > 0) + phase = np.unwrap(np.angle(response.response[indented])) + # A simple pole reverses the direction of the s-plane detour. + assert side * (phase[-1] - phase[0]) < 0 + assert responses[0].count == responses[1].count + 2 + + +def test_nyquist_indent_forced_closed_loop_pole_warning(): + """A forced far-side detour can also cross a stable closed-loop pole.""" + sys = ct.tf([.08], [1, .05]) + with pytest.warns(UserWarning) as record: + ct.nyquist_response(sys, indent_radius=.1, indent_direction='left') + assert len(record) == 2 + assert re.search('indented contour may miss closed loop pole', + str(record[0].message)) + assert 'does not match Nyquist criterion' in str(record[1].message) + + def test_nyquist_exceptions(): # MIMO not implemented sys = ct.rss(2, 2, 2) diff --git a/doc/config.rst b/doc/config.rst index 9313fdded..277259643 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -410,11 +410,14 @@ Plotting parameters warning if the number of net encirclements is a non-integer value. .. py:data:: nyquist.indent_direction - :type: str - :value: 'right' + :type: str or None + :value: None Set the direction of indentation in :func:`nyquist_response` for poles - on the imaginary axis. Valid values are 'right', 'left', or 'none'. + on or near the imaginary axis. None selects the side automatically: + right of stable poles and poles exactly on the axis, left of unstable + poles. 'right' and 'left' force that direction for all poles within + ``indent_radius`` of the axis; 'none' disables indentation. .. py:data:: nyquist.indent_points :type: int