control.pole_zero_plot

control.pole_zero_plot(data, plot=None, grid=None, title=None, color=None, marker_size=None, marker_width=None, xlim=None, ylim=None, interactive=None, ax=None, scaling=None, initial_gain=None, label=None, **kwargs)[source]

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

  • data (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 (bool or str, optional) – If True plot omega-damping grid, if False show imaginary axis for continuous time systems, unit circle for discrete time systems. If empty, do not draw any additonal lines. Default value is set by config.default[‘pzmap.grid’] or config.default[‘rlocus.grid’].

  • 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 zeros is returned.

  • ax (matplotlib.axes.Axes, optional) – The matplotlib axes to draw the figure on. If not specified and the current figure has a single axes, that axes is used. Otherwise, a new figure is created.

  • color (matplotlib color spec, optional) – Specify the color of the markers and lines.

  • initial_gain (float, optional) – If given, the specified system gain will be marked on the plot.

  • interactive (bool, optional) – Turn off interactive mode for root locus plots.

  • label (str or array_like of str, optional) – If present, replace automatically generated label(s) with given label(s). If data is a list, strings should be specified for each system.

  • legend_loc (int or str, optional) – Include a legend in the given location. Default is ‘upper right’, with no legend for a single response. Use False to suppress legend.

  • marker_color (str, optional) – Set the color of the markers used for poles and zeros.

  • marker_size (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.

  • rcParams (dict) – Override the default parameters used for generating plots. Default is set by config.default[‘ctrlplot.rcParams’].

  • 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].

  • show_legend (bool, optional) – Force legend to be shown if True or hidden if False. If None, then show legend when there is more than one line on the plot or legend_loc has been specified.

  • title (str, optional) – Set the title of the plot. Defaults to plot type and system name(s).

  • xlim (list, optional) – Set the limits for the x axis.

  • ylim (list, optional) – Set the limits for the y axis.

Returns

  • cplt (ControlPlot object) –

    Object containing the data that were plotted:

    • cplt.lines: Array of matplotlib.lines.Line2D objects for each set of markers in the plot. The shape of the array is given by (nsys, 2) where nsys is the number of systems or responses passed to the function. The second index specifies the pzmap object type:

      • lines[idx, 0]: poles

      • lines[idx, 1]: zeros

    • cplt.axes: 2D array of matplotlib.axes.Axes for the plot.

    • cplt.figure: matplotlib.figure.Figure containing the plot.

    • cplt.legend: legend object(s) contained in the plot

    See ControlPlot for more detailed information.

  • poles, zeros (list of arrays) – (legacy) If the plot keyword is given, the system poles and zeros are returned.

Notes

  1. 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.

  2. Pole/zero plots that use the continuous time omega-damping grid do not work with the ax keyword argument, due to the way that axes grids are implemented. The grid argument must be set to False or 'empty' when using the ax keyword argument.