tweak grid processing, add documentation, interactive by default

murrayrm · murrayrm · commit 0d23598ce89b · 2023-12-28T12:41:09.000-08:00
diff --git a/control/grid.py b/control/grid.py
@@ -146,8 +146,8 @@ def sgrid(scaling=None):
 def _final_setup(ax, scaling=None):
     ax.set_xlabel('Real')
     ax.set_ylabel('Imaginary')
-    ax.axhline(y=0, color='black', lw=0.5)
-    ax.axvline(x=0, color='black', lw=0.5)
+    ax.axhline(y=0, color='black', lw=0.25)
+    ax.axvline(x=0, color='black', lw=0.25)
 
     # Set up the scaling for the axes
     scaling = 'equal' if scaling is None else scaling
diff --git a/control/pzmap.py b/control/pzmap.py
@@ -39,7 +39,7 @@
 
 # Define default parameter values for this module
 _pzmap_defaults = {
-    'pzmap.grid': False,                # Plot omega-damping grid
+    'pzmap.grid': None,                 # Plot omega-damping grid
     'pzmap.marker_size': 6,             # Size of the markers
     'pzmap.marker_width': 1.5,          # Width of the markers
     'pzmap.expansion_factor': 1.8,      # Amount to scale plots beyond features
@@ -111,20 +111,28 @@ def pole_zero_map(sysdata):
 def pole_zero_plot(
         data, plot=None, grid=None, title=None, marker_color=None,
         marker_size=None, marker_width=None, legend_loc='upper right',
-        xlim=None, ylim=None, interactive=False, ax=None, scaling=None,
+        xlim=None, ylim=None, interactive=None, ax=None, scaling=None,
         initial_gain=None, **kwargs):
     # TODO: update docstring (see other response/plot functions for style)
     """Plot a pole/zero map for a linear system.
 
+    If the system data include root loci, a root locus diagram for the
+    system is plotted.  When the root locus for a single system is plotted,
+    clicking on a location on the root locus will mark the gain on all
+    branches of the diagram and show the system gain and damping for the
+    given pole in the axes title.  Set to False to turn off this behavior.
+
     Parameters
     ----------
-    sysdata: List of PoleZeroData objects or LTI systems
+    sysdata : List of PoleZeroData objects or LTI systems
         List of pole/zero response data objects generated by pzmap_response
         or rootlocus_response() that are to be plotted.  If a list of systems
         is given, the poles and zeros of those systems will be plotted.
-    grid: boolean (default = False)
-        If True plot omega-damping grid.
-    plot: bool, optional
+    grid : boolean (default = None)
+        If True plot omega-damping grid, otherwise show imaginary axis for
+        continuous time systems, unit circle for discrete time systems.  If
+        `False`, do not draw any additonal lines.
+    plot : bool, optional
         (legacy) If ``True`` a graph is generated with Matplotlib,
         otherwise the poles and zeros are only computed and returned.
         If this argument is present, the legacy value of poles and
@@ -145,16 +153,42 @@ def pole_zero_plot(
         (legacy) If the `plot` keyword is given, the system poles and zeros
         are returned.
 
-    Notes (TODO: update, including scaling)
+    Other Parameters
+    ----------------
+    scaling : str or list, optional
+        Set the type of axis scaling.  Can be 'equal' (default), 'auto', or
+        a list of the form [xmin, xmax, ymin, ymax].
+    title : str, optional
+        Set the title of the plot.  Defaults plot type and system name(s).
+    marker_color : str, optional
+        Set the color of the markers used for poles and zeros.
+    marker_color : int, optional
+        Set the size of the markers used for poles and zeros.
+    marker_width : int, optional
+        Set the line width of the markers used for poles and zeros.
+    legend_loc : str, optional
+        For plots with multiple lines, a legend will be included in the
+        given location.  Default is 'center right'.  Use False to supress.
+    xlim : list, optional
+        Set the limits for the x axis.
+    ylim : list, optional
+        Set the limits for the y axis.
+    interactive : bool, optional
+        Turn off interactive mode for root locus plots.
+    initial_gain : float, optional
+        If given, the specified system gain will be marked on the plot.
+
+    Notes
     -----
-    The pzmap function calls matplotlib.pyplot.axis('equal'), which means
-    that trying to reset the axis limits may not behave as expected.  To
-    change the axis limits, use matplotlib.pyplot.gca().axis('auto') and
-    then set the axis limits to the desired values.
+    By default, the pzmap function calls matplotlib.pyplot.axis('equal'),
+    which means that trying to reset the axis limits may not behave as
+    expected.  To change the axis limits, use the `scaling` keyword of use
+    matplotlib.pyplot.gca().axis('auto') and then set the axis limits to
+    the desired values.
 
     """
     # Get parameter values
-    grid = config._get_param('pzmap', 'grid', grid, False)
+    grid = config._get_param('pzmap', 'grid', grid, None)
     marker_size = config._get_param('pzmap', 'marker_size', marker_size, 6)
     marker_width = config._get_param('pzmap', 'marker_width', marker_width, 1.5)
     xlim_user, ylim_user = xlim, ylim
@@ -177,6 +211,11 @@ def pole_zero_plot(
     else:
         raise TypeError("unknown system data type")
 
+    # Turn on interactive mode by default, if allowed
+    if interactive is None and len(pzmap_responses) == 1 \
+       and pzmap_responses[0].sys is not None:
+        interactive = True
+
     # Legacy return value processing
     if plot is not None:
         warnings.warn(
@@ -217,11 +256,14 @@ def pole_zero_plot(
                 ValueError(
                     "incompatible time responses; don't know how to grid")
         elif len(axs) == 0:
-            # use first response timebase
-            ax, fig = nogrid(data[0].dt, scaling=scaling)
+            if grid is False:
+                # Leave off grid entirely
+                ax = plt.axes()
+            else:
+                # use first response timebase
+                ax, fig = nogrid(data[0].dt, scaling=scaling)
         else:
             # Use the existing axes and any grid that is there
-            # TODO: allow axis to be overriden via parameter
             ax = axs[0]
 
     # Handle color cycle manually as all root locus segments
