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
dataList of PoleZeroData objects or LTI systems

List of pole/zero response data objects generated by pzmap_response() or root_locus_map() that are to be plotted. If a list of systems is given, the poles and zeros of those systems will be plotted.

gridbool 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 additional lines. Default value is set by config.defaults['pzmap.grid'] or config.defaults['rlocus.grid'].

plotbool, 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.

Returns
cpltControlPlot object

Object containing the data that were plotted. See ControlPlot for more detailed information.

cplt.linesarray of list of matplotlib.lines.Line2D

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.axes2D array of matplotlib.axes.Axes

Axes for each subplot.

cplt.figurematplotlib.figure.Figure

Figure containing the plot.

cplt.legend2D array of matplotlib.legend.Legend

Legend object(s) contained in the plot.

poles, zeroslist of arrays

(legacy) If the plot keyword is given, the system poles and zeros are returned.

Other Parameters
axmatplotlib.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.

colormatplotlib color spec, optional

Specify the color of the markers and lines.

initial_gainfloat, optional

If given, the specified system gain will be marked on the plot.

interactivebool, optional

Turn off interactive mode for root locus plots.

labelstr 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_locint 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_colorstr, optional

Set the color of the markers used for poles and zeros.

marker_sizeint, optional

Set the size of the markers used for poles and zeros.

marker_widthint, optional

Set the line width of the markers used for poles and zeros.

rcParamsdict

Override the default parameters used for generating plots. Default is set by config.defaults['ctrlplot.rcParams'].

scalingstr 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_legendbool, 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.

titlestr, optional

Set the title of the plot. Defaults to plot type and system name(s).

xlimlist, optional

Set the limits for the x axis.

ylimlist, optional

Set the limits for the y axis.

Notes

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.

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.

The limits of the pole/zero plot are set based on the location features in the plot, including the location of poles, zeros, and local maxima of root locus curves. The locations of local maxima are expanded by a buffer factor set by config.defaults['phaseplot.buffer_factor'] that is applied to the locations of the local maxima. The final axis limits are set to by the largest features in the plot multiplied by an expansion factor set by config.defaults['phaseplot.expansion_factor']. The default value for the buffer factor is 1.05 (5% buffer around local maxima) and the default value for the expansion factor is 1.8 (80% increase in limits around the most distant features).