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 orLTI
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']
orconfig.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.
- dataList of
- Returns
- cplt
ControlPlot
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.figure
matplotlib.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.
- cplt
- Other Parameters
- 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.
- 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.
- ax
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. Thegrid
argument must be set to False or ‘empty’ when using theax
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 byconfig.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).