control.root_locus

control.root_locus(sysdata, gains=None, grid=None, plot=None, **kwargs)[source]

Root locus plot.

Calculate the root locus by finding the roots of 1 + k * G(s) where G is a linear system and k varies over a range of gains.

Parameters

  • sysdata (PoleZeroMap or LTI object or list) – Linear input/output systems (SISO only, for now).

  • gains (array_like, optional) – Gains to use in computing plot of closed-loop poles. If not given, gains are chosen to include the main features of the root locus map.

  • xlim (tuple or list, optional) – Set limits of x axis, normally with tuple (see matplotlib.axes).

  • ylim (tuple or list, optional) – Set limits of y axis, normally with tuple (see matplotlib.axes).

  • plot (bool, optional) – (legacy) If given, root_locus_plot returns the legacy return values of roots and gains. If False, just return the values with no plot.

  • 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[‘rlocus.grid’].

  • initial_gain (float, optional) – Mark the point on the root locus diagram corresponding to the given gain.

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

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

  • label (str or array_like of str, optional) – If present, replace automatically generated label(s) with the given label(s). If sysdata 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 ‘center right’, with no legend for a single response. Use False to suppress legend.

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

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, 3) where nsys is the number of systems or responses passed to the function. The second index specifies the object type:

      • lines[idx, 0]: poles

      • lines[idx, 1]: zeros

      • lines[idx, 2]: loci

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

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

    See ControlPlot for more detailed information.

  • roots, gains (ndarray) – (legacy) If the plot keyword is given, returns the closed-loop root locations, arranged such that each row corresponds to a gain, and the array of gains (same as gains keyword argument if provided).

Notes

The root_locus_plot 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.