control.bode_plot

control.bode_plot(data, omega=None, *fmt, ax=None, omega_limits=None, omega_num=None, plot=None, plot_magnitude=True, plot_phase=None, overlay_outputs=None, overlay_inputs=None, phase_label=None, magnitude_label=None, label=None, display_margins=None, margins_method='best', title=None, sharex=None, sharey=None, **kwargs)[source]

Bode plot for a system.

Plot the magnitude and phase of the frequency response over a (optional) frequency range.

Parameters
datalist of FrequencyResponseData or LTI

List of LTI systems or FrequencyResponseData objects. A single system or frequency response can also be passed.

omegaarray_like, optional

Set of frequencies in rad/sec to plot over. If not specified, this will be determined from the properties of the systems. Ignored if data is not a list of systems.

*fmtmatplotlib.pyplot.plot format string, optional

Passed to matplotlib as the format string for all lines in the plot. The omega parameter must be present (use omega=None if needed).

dBbool

If True, plot result in dB. Default is False.

Hzbool

If True, plot frequency in Hz (omega must be provided in rad/sec). Default value (False) set by config.defaults['freqplot.Hz'].

degbool

If True, plot phase in degrees (else radians). Default value (True) set by config.defaults['freqplot.deg'].

display_marginsbool or str

If True, draw gain and phase margin lines on the magnitude and phase graphs and display the margins at the top of the graph. If set to ‘overlay’, the values for the gain and phase margin are placed on the graph. Setting display_margins turns off the axes grid, unless grid is explicitly set to True.

**kwargsmatplotlib.pyplot.plot keyword properties, optional

Additional keywords passed to matplotlib to specify line properties.

Returns
cpltControlPlot object

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

cplt.linesArray of matplotlib.lines.Line2D objects

Array containing information on each line in the plot. The shape of the array matches the subplots shape and the value of the array is a list of Line2D objects in that subplot.

cplt.axes2D ndarray 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.

Other Parameters
axarray of matplotlib.axes.Axes, optional

The matplotlib axes to draw the figure on. If not specified, the axes for the current figure are used or, if there is no current figure with the correct number and shape of axes, a new figure is created. The shape of the array must match the shape of the plotted data.

freq_label, magnitude_label, phase_labelstr, optional

Labels to use for the frequency, magnitude, and phase axes. Defaults are set by config.defaults['freqplot.<keyword>'].

gridbool, optional

If True, plot grid lines on gain and phase plots. Default is set by config.defaults['freqplot.grid'].

initial_phasefloat, optional

Set the reference phase to use for the lowest frequency. If set, the initial phase of the Bode plot will be set to the value closest to the value specified. Units are in either degrees or radians, depending on the deg parameter. Default is -180 if wrap_phase is False, 0 if wrap_phase is True.

labelstr 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. If MIMO, strings required for each system, output, and input.

legend_maparray of str, optional

Location of the legend for multi-axes plots. Specifies an array of legend location strings matching the shape of the subplots, with each entry being either None (for no legend) or a legend location string (see legend).

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

margins_methodstr, optional

Method to use in computing margins (see stability_margins).

omega_limitsarray_like of two values

Set limits for plotted frequency range. If Hz=True the limits are in Hz otherwise in rad/s. Specifying omega as a list of two elements is equivalent to providing omega_limits. Ignored if data is not a list of systems.

omega_numint

Number of samples to use for the frequency range. Defaults to config.defaults['freqplot.number_of_samples']. Ignored if data is not a list of systems.

overlay_inputs, overlay_outputsbool, optional

If set to True, combine input and/or output signals onto a single plot and use line colors, labels, and a legend to distinguish them.

plotbool, optional

(legacy) If given, bode_plot returns the legacy return values of magnitude, phase, and frequency. If False, just return the values with no plot.

plot_magnitude, plot_phasebool, optional

If set to False, do not plot the magnitude or phase, respectively.

rcParamsdict

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

share_frequency, share_magnitude, share_phasestr or bool, optional

Determine whether and how axis limits are shared between the indicated variables. Can be set set to ‘row’ to share across all subplots in a row, ‘col’ to set across all subplots in a column, or False to allow independent limits. Note: if sharex is given, it sets the value of share_frequency; if sharey is given, it sets the value of both share_magnitude and share_phase. Default values are ‘row’ for share_magnitude and share_phase, ‘col’, for share_frequency, and can be set using config.defaults['freqplot.share_<axis>'].

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 an axis or legend_loc or legend_map has been specified.

titlestr, optional

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

title_framestr, optional

Set the frame of reference used to center the plot title. If set to ‘axes’ (default), the horizontal position of the title will be centered relative to the axes. If set to ‘figure’, it will be centered with respect to the figure (faster execution). The default value can be set using config.defaults['freqplot.title_frame'].

wrap_phasebool or float

If wrap_phase is False (default), then the phase will be unwrapped so that it is continuously increasing or decreasing. If wrap_phase is True the phase will be restricted to the range [-180, 180) (or [-\pi, \pi) radians). If wrap_phase is specified as a float, the phase will be offset by 360 degrees if it falls below the specified value. Default value is False and can be set using config.defaults['freqplot.wrap_phase'].

Notes

Starting with python-control version 0.10, bode_plot returns a ControlPlot object instead of magnitude, phase, and frequency. To recover the old behavior, call bode_plot with plot = True, which will force the legacy values (mag, phase, omega) to be returned (with a warning). To obtain just the frequency response of a system (or list of systems) without plotting, use the frequency_response command.

If a discrete-time model is given, the frequency response is plotted along the upper branch of the unit circle, using the mapping z = exp(1j * omega * dt) where omega ranges from 0 to pi/dt and dt is the discrete timebase. If timebase not specified (dt = True), dt is set to 1.

The default values for Bode plot configuration parameters can be reset using the config.defaults dictionary, with module name ‘bode’.

Examples

>>> G = ct.ss([[-1, -2], [3, -4]], [[5], [7]], [[6, 8]], [[9]])
>>> out = ct.bode_plot(G)