bodeplot

Plot Bode frequency response of dynamic system

Description

The `bodeplot` function plots the Bode magnitude and phase of a dynamic system model and returns a `BodePlot` chart object. To customize the plot, modify the properties of the chart object using dot notation. For more information, see Customize Linear Analysis Plots at Command Line (Control System Toolbox).

To obtain frequency response data, use `bode`.

Creation

Syntax

``bp = bodeplot(sys)``
``bp = bodeplot(sys1,sys2,...,sysN)``
``bp = bodeplot(sys1,LineSpec1,...,sysN,LineSpecN)``
``bp = bodeplot(___,w)``
``bp = bodeplot(___,plotoptions)``
``bp = bodeplot(parent,___)``

Description

````bp = bodeplot(sys)` plots the Bode magnitude and phase of the dynamic system model `sys` and returns the corresponding chart object.If `sys` is a multi-input, multi-output (MIMO) model, then `bodeplot` produces a grid of Bode plots with each plot displaying the frequency response of one input-output pair.If `sys` is a model with complex coefficients, then in:Log frequency scale, the plot shows two branches, one for positive frequencies and one for negative frequencies. The plot also shows arrows to indicate the direction of increasing frequency values for each branch.Linear frequency scale, the plot shows a single branch with a symmetric frequency range centered at a frequency value of zero.```

example

````bp = bodeplot(sys1,sys2,...,sysN)` plots the frequency response of multiple dynamic systems `sys1,sys2,…,sysN` on the same plot.```

example

````bp = bodeplot(sys1,LineSpec1,...,sysN,LineSpecN)` sets the line style, marker type, and color for the Bode response of each specified system.```

example

````bp = bodeplot(___,w)` plots responses for frequencies specified in `w`. You can specify a frequency range or a vector of frequencies. You can use `w` with any of the previous syntaxes.```

example

````bp = bodeplot(___,plotoptions)` plots the Bode frequency response with the plotting options specified in `plotoptions`. Settings you specify in `plotoptions` override the plotting preferences for the current MATLAB® session. This syntax is useful when you want to write a script to generate multiple plots that look the same regardless of the local preferences.```

example

````bp = bodeplot(parent,___)` plots the Bode response in the specified parent graphics container, such as a `Figure` or `TiledChartLayout`, and sets the `Parent` property. Use this syntax when you want to create a plot in a specified open figure or when creating apps in App Designer.```

Input Arguments

expand all

Dynamic system, specified as a SISO or MIMO dynamic system model or array of dynamic system models. Dynamic systems that you can use include:

• Continuous-time or discrete-time numeric LTI models, such as `tf` (Control System Toolbox), `zpk` (Control System Toolbox), or `ss` (Control System Toolbox) models.

• Sparse state-space models, such as `sparss` (Control System Toolbox) or `mechss` (Control System Toolbox) models. Frequency grid `w` must be specified for sparse models.

• Generalized or uncertain LTI models such as `genss` (Control System Toolbox) or `uss` (Robust Control Toolbox) models. Using uncertain models requires Robust Control Toolbox™ software.

• For tunable control design blocks, the function evaluates the model at its current value to plot the response.

• For uncertain control design blocks, the function plots the nominal value and random samples of the model.

• Frequency-response data models such as `frd` models. For such models, the function plots the response at the frequencies defined in the model.

• Identified LTI models, such as `idtf`, `idss`, or `idproc` models.

If `sys` is an array of models, the plot shows responses of all models in the array on the same axes.

Line style, marker, and color, specified as a string or character vector containing symbols. The symbols can appear in any order. You do not need to specify all three characteristics (line style, marker, and color). For example, if you omit the line style and specify the marker, then the plot shows only the marker and no line.

Example: `'--or'` is a red dashed line with circle markers

Line StyleDescription
`"-"`Solid line
`"--"`Dashed line
`":"`Dotted line
`"-."`Dash-dotted line
MarkerDescription
`"o"`Circle
`"+"`Plus sign
`"*"`Asterisk
`"."`Point
`"x"`Cross
`"_"`Horizontal line
`"|"`Vertical line
`"s"`Square
`"d"`Diamond
`"^"`Upward-pointing triangle
`"v"`Downward-pointing triangle
`">"`Right-pointing triangle
`"<"`Left-pointing triangle
`"p"`Pentagram
`"h"`Hexagram
ColorDescription
`"r"`red
`"g"`green
`"b"`blue
`"c"`cyan
`"m"`magenta
`"y"`yellow
`"k"`black
`"w"`white

Frequencies at which to compute the response, specified as one of the following:

• Cell array of the form `{wmin,wmax}` — Compute the response at frequencies in the range from `wmin` to `wmax`. If `wmax` is greater than the Nyquist frequency of `sys`, the response is computed only up to the Nyquist frequency.

• Vector of frequencies — Compute the response at each specified frequency. For example, use `logspace` to generate a row vector with logarithmically spaced frequency values. The vector `w` can contain both positive and negative frequencies.

• `[]` — Automatically select frequencies based on system dynamics.

For models with complex coefficients, if you specify a frequency range of [wmin,wmax] for your plot, then in:

• Log frequency scale, the plot frequency limits are set to [wmin,wmax] and the plot shows two branches, one for positive frequencies [wmin,wmax] and one for negative frequencies [–wmax,–wmin].

• Linear frequency scale, the plot frequency limits are set to [–wmax,wmax] and the plot shows a single branch with a symmetric frequency range centered at a frequency value of zero.

Specify frequencies in units of rad/`TimeUnit`, where `TimeUnit` is the `TimeUnit` property of the model.

Bode plot options, specified as a `bodeoptions` object. You can use these options to customize the Bode plot appearance. Settings you specify in `plotoptions` override the preference settings for the current MATLAB session.

Parent container of the chart, specified as one of the following objects:

• `Figure`

• `TiledChartLayout`

• `UIFigure`

• `UIGridLayout`

• `UIPanel`

• `UITab`

Properties

expand all

Note

The properties listed here are only a subset. For a complete list, see BodePlot Properties (Control System Toolbox).

Model responses, specified as a `BodeResponse` object or an array of such objects. Use this property to modify the dynamic system model or appearance for each response in the plot. Each `BodeResponse` object has the following fields.

Source data for the response, specified as a structure with the following fields.

Dynamic system, specified as a SISO or MIMO dynamic system model or array of dynamic system models.

When you initially create a plot, `Model` matches the value you specify for `sys`.

Frequencies at which to compute the response, specified as one of the following:

• Cell array of the form `{wmin,wmax}` — Compute the response at frequencies in the range from `wmin` to `wmax`.

• Vector of frequencies — Compute the response at each specified frequency. For example, use `logspace` to generate a row vector with logarithmically spaced frequency values. The vector `w` can contain both positive and negative frequencies.

• `[]` — Automatically select frequencies based on system dynamics.

Specify frequencies in units of rad/`TimeUnit`, where `TimeUnit` is the `TimeUnit` property of the model.

When you initially create a plot:

• `FrequencySpec` matches the value you specify for the `w` argument.

• If you do not specify `w`, `FrequencySpec` is empty and frequencies are selected based on the system dynamics.

Response name, specified as a string or character vector and stored as a string.

Response visibility, specified as one of the following logical on/off values:

• `"on"`, `1`, or `true` — Display the response in the plot.

• `"off"`, `0`, or `false` — Do not display the response in the plot.

The value is stored as an on/off logical value of type `matlab.lang.OnOffSwitchState`.

Option to list response in legend, specified as one of the following logical on/off values:

• `"on"`, `1`, or `true` — List the response in the legend.

• `"off"`, `0`, or `false` — Do not list the response in the legend.

The value is stored as an on/off logical value of type `matlab.lang.OnOffSwitchState`.

Marker style, specified as one of the following values.

MarkerDescription
`"none"`No marker
`"o"`Circle
`"+"`Plus sign
`"*"`Asterisk
`"."`Point
`"x"`Cross
`"_"`Horizontal line
`"|"`Vertical line
`"s"`Square
`"d"`Diamond
`"^"`Upward-pointing triangle
`"v"`Downward-pointing triangle
`">"`Right-pointing triangle
`"<"`Left-pointing triangle
`"p"`Pentagram
`"h"`Hexagram

Plot color, specified as an RGB triplet or a hexadecimal color code and stored as an RGB triplet.

Alternatively, you can specify some common colors by name. The following table lists these colors and their corresponding RGB triplets and hexadecimal color codes.

`"red"` or `"r"`

`[1 0 0]``#FF0000`

`"green"` or `"g"`

`[0 1 0]``#00FF00`

`"blue"` or `"b"`

`[0 0 1]``#0000FF`

`"cyan"` or `"c"`

`[0 1 1]``#00FFFF`

`"magenta"` or `"m"`

`[1 0 1]``#FF00FF`

`"yellow"` or `"y"`

`[1 1 0]``#FFFF00`

`"black"` or `"k"`

`[0 0 0]``#000000`

`"white"` or `"w"`

`[1 1 1]``#FFFFFF`

Line style, specified as one of the following values.

Line StyleDescription
`"-"`Solid line
`"--"`Dashed line
`":"`Dotted line
`"-."`Dash-dotted line

Marker size, specified as a positive scalar.

Line width, specified as a positive scalar.

Response characteristics to display in the plot, specified as a `CharacteristicsManager` object with the following properties.

Visibility of peak response in magnitude plot, specified as a structure with the following field.

Peak response visibility, specified as one of the following logical on/off values:

• `"on"`, `1`, or `true` — Display the peak response.

• `"off"`, `0`, or `false` — Do not display the peak response.

The value is stored as an on/off logical value of type `matlab.lang.OnOffSwitchState`.

Visibility of all stability margins, specified as a structure with the following field.

Margin visibility, specified as one of the following logical on/off values:

• `"on"`, `1`, or `true` — Display the margins.

• `"off"`, `0`, or `false` — Do not display the margins.

The value is stored as an on/off logical value of type `matlab.lang.OnOffSwitchState`.

Visibility of minimum stability margins, specified as a structure with the following field.

Margin visibility, specified as one of the following logical on/off values:

• `"on"`, `1`, or `true` — Display the margins.

• `"off"`, `0`, or `false` — Do not display the margins.

The value is stored as an on/off logical value of type `matlab.lang.OnOffSwitchState`.

Confidence region for identified models, specified as a `CharacteristicOption` object with the following properties.

Confidence region visibility, specified as one of the following logical on/off values:

• `"on"`, `1`, or `true` — Display the confidence region.

• `"off"`, `0`, or `false` — Do not display the confidence region.

The value is stored as an on/off logical value of type `matlab.lang.OnOffSwitchState`.

Number of standard deviations to display for the confidence region, specified as a positive scalar.

Dependencies

`ConfidenceRegion` is supported only for identified models.

Frequency units, specified as one of the following values:

• `"Hz"`

• `"rad/s"`

• `"rpm"`

• `"kHz"`

• `"MHz"`

• `"GHz"`

• `"rad/nanosecond"`

• `"rad/microsecond"`

• `"rad/millisecond"`

• `"rad/minute"`

• `"rad/hour"`

• `"rad/day"`

• `"rad/week"`

• `"rad/month"`

• `"rad/year"`

• `"cycles/nanosecond"`

• `"cycles/microsecond"`

• `"cycles/millisecond"`

• `"cycles/hour"`

• `"cycles/day"`

• `"cycles/week"`

• `"cycles/month"`

• `"cycles/year"`

Dependencies

By default, the response uses the frequency units of the plotted linear system. You can override the default units by specifying toolbox preferences. For more information, see Specify Toolbox Preferences for Linear Analysis Plots.

Frequency scale, specified as either `"log"` or `"linear"`.

Dependencies

The default frequency scale depends on the toolbox preferences. For more information, see Specify Toolbox Preferences for Linear Analysis Plots (Control System Toolbox).

Magnitude units, specified as one of the following:

• `"dB"` — Decibels

• `"abs"` — Absolute value

Dependencies

• If `MagnitudeScale` is `"log"` when you set `MagnitudeUnit` to `"dB"`, the software automatically changes `MagnitudeScale` to `"linear"`.

• The default magnitude units depend on the toolbox preferences. For more information, see Specify Toolbox Preferences for Linear Analysis Plots (Control System Toolbox).

Magnitude scale, specified as either `"log"` or `"linear"`.

Dependencies

• Setting `MagnitudeScale` to `"log"` is not supported when `MagnitudeUnit` is `"dB"`.

• The default magnitude scale depends on the toolbox preferences. For more information, see Specify Toolbox Preferences for Linear Analysis Plots (Control System Toolbox).

Phase units, specified as one of the following:

• `"deg"` — Degrees

• `"rad"` — Radians

Dependencies

The default phase units depend on the toolbox preferences. For more information, see Specify Toolbox Preferences for Linear Analysis Plots.

Option to display magnitude plot, specified as one of the following logical on/off values:

• `"on"`, `1`, or `true` — Display the magnitude plot.

• `"off"`, `0`, or `false` — Hide the magnitude plot.

The value is stored as an on/off logical value of type `matlab.lang.OnOffSwitchState`.

Option to display phase plot, specified as one of the following logical on/off values:

• `"on"`, `1`, or `true` — Display the phase plot.

• `"off"`, `0`, or `false` — Hide the phase plot.

The value is stored as an on/off logical value of type `matlab.lang.OnOffSwitchState`.

Option to enable phase wrapping, specified as one of the following logical on/off values:

• `"on"`, `1`, or `true` — Enable phase wrapping. The phase shown in the response wraps to remain in the range defined by `PhaseWrappingBranch`.

• `"off"`, `0`, or `false` — Disable phase wrapping.

The value is stored as an on/off logical value of type `matlab.lang.OnOffSwitchState`.

Dependencies

• The default phase-wrapping configuration depends on the toolbox preferences. For more information, see Specify Toolbox Preferences for Linear Analysis Plots.

• When both phase wrapping and phase matching are enabled, the software performs the phase matching followed by the phase wrapping.

Lower limit of phase-wrapping range, specified as a scalar value in degrees. The phase-wrapping range is [B,B+360), where B is equal to `PhaseWrappingBranch`.

Dependencies

Option to enable phase matching, specified as one of the following logical on/off values:

• `"on"`, `1`, or `true` — Enable phase matching such that the phase response matches the value specified in `PhaseMatchingValue` at the frequency specified in `PhaseMatchingFrequency`. The remaining phase response shifts to maintain the same phase profile.

• `"off"`, `0`, or `false` — Disable phase matching.

The value is stored as an on/off logical value of type `matlab.lang.OnOffSwitchState`.

Dependencies

When both phase wrapping and phase matching are enabled, the software performs the phase matching followed by the phase wrapping.

Phase matching frequency, specified as a scalar.

Dependencies

This value is ignored when `PhaseMatchingEnabled` is `"off"`.

Phase matching response value, specified as a scalar.

Dependencies

This value is ignored when `PhaseMatchingEnabled` is `"off"`.

Option to enable minimum gain for plotting, specified as one of the following logical on/off values:

• `"on"`, `1`, or `true` — Set the minimum gain for plotting to the `MinimumGainValue` property value.

• `"off"`, `0`, or `false` — Set the minimum gain for plotting automatically based on the system dynamics.

The value is stored as an on/off logical value of type `matlab.lang.OnOffSwitchState`.

Dependencies

The default minimum-gain configuration depends on the toolbox preferences. For more information, see Specify Toolbox Preferences for Linear Analysis Plots.

Minimum gain value for plotting, specified as a scalar.

Dependencies

Chart visibility, specified as one of the following logical on/off values:

• `"on"`, `1`, or `true` — Display the chart.

• `"off"`, `0`, or `false` — Hide the chart without deleting it. You still can access the properties of chart when it is not visible.

The value is stored as an on/off logical value of type `matlab.lang.OnOffSwitchState`.

Grouping of inputs and outputs pairs, specified as one of the following:

• `"none"` — Do not group inputs or outputs.

• `"inputs"` — Group only inputs.

• `"outputs"` — Group only outputs.

• `"all"` — Group all input-output pairs.

Option to display inputs, specified as one of the following logical on/off values or an array of such values:

• `"on"`, `1`, or `true` — Display the corresponding input.

• `"off"`, `0`, or `false` — Hide the corresponding input.

`InputVisible` is an array when the plotted system has multiple inputs. By default, all inputs are visible in the plot.

The value is stored as an on/off logical value of type `matlab.lang.OnOffSwitchState` or an array of such values.

Option to display outputs, specified as one of the following logical on/off values or an array of such values:

• `"on"`, `1`, or `true` — Display the corresponding output.

• `"off"`, `0`, or `false` — Hide the corresponding output.

`OutputVisible` is an array when the plotted system has multiple outputs. By default, all outputs are visible in the plot.

The value is stored as an on/off logical value of type `matlab.lang.OnOffSwitchState` or an array of such values.

Object Functions

 `addResponse` (Control System Toolbox) Add dynamic system response to existing response plot `showConfidence` Display confidence regions on response plots for identified models

Examples

collapse all

For this example, use the plot handle to change the frequency units to Hz and turn off the phase plot.

Generate a random state-space model with 5 states and create the Bode plot with chart object `bp`.

```rng("default") sys = rss(5); bp = bodeplot(sys);```

Change the units to Hz and suppress the phase plot by modifying the chart object.

```bp.FrequencyUnit = "Hz"; bp.PhaseVisible = "off";```

The Bode plot automatically updates when you modify the chart object.

For this example, create a Bode plot that uses 15-point red text for the title and sets a custom title. When you specify plot properties explicitly using `bodeoptions`, the specified properties override the MATLAB session preferences. Thus, the plot looks the same regardless of the preferences of the MATLAB session in which it is generated.

First, create a default options set using `bodeoptions`.

`opts = bodeoptions;`

Next, change the required properties of the options set `opts`. Because `opt.Title` is a structure, specify the properties of the plot title by specifying the fields and values of that structure.

```opts.Title.FontSize = 15; opts.Title.Color = [1 0 0]; opts.Title.String = 'System Frequency Response'; opts.FreqUnits = 'Hz';```

Now, create a Bode plot using the options set `opts`.

`bodeplot(tf(1,[1,1]),opts);`

Because `opts` begins with a fixed set of options, the plot result is independent of the toolbox preferences of the MATLAB session.

For this example, create a Bode plot of the following continuous-time SISO dynamic system. Then, turn the grid on, rename the plot and change the frequency scale.

`$sys\left(s\right)=\frac{{s}^{2}+0.1s+7.5}{{s}^{4}+0.12{s}^{3}+9{s}^{2}}.$`

Create the transfer function `sys`.

`sys = tf([1 0.1 7.5],[1 0.12 9 0 0]);`

Create the Bode plot. Specify plot properties by modifying the returned chart object.

```bp = bodeplot(sys); bp.FrequencyScale = "linear"; title("Bode Plot of Transfer Function"); grid on```

`bodeplot` automatically selects the plot range based on the system dynamics.

For this example, consider a MIMO state-space model with 3 inputs, 3 outputs and 3 states. Create a Bode plot with linear frequency scale, specify frequency units in Hz and turn the grid on.

Create the MIMO state-space model `sys_mimo`.

```J = [8 -3 -3; -3 8 -3; -3 -3 8]; F = 0.2*eye(3); A = -J\F; B = inv(J); C = eye(3); D = 0; sys_mimo = ss(A,B,C,D); size(sys_mimo)```
```State-space model with 3 outputs, 3 inputs, and 3 states. ```

Create a Bode plot and return the corresponding chart object.

`bp = bodeplot(sys_mimo);`

Customize the plot by updating properties of the chart object.

```bp.FrequencyScale = "linear"; bp.FrequencyUnit = "Hz"; grid on```

The Bode plot automatically updates when you modify the chart object properties. For MIMO models, `bodeplot` produces an array of Bode plots, each plot displaying the frequency response of one I/O pair.

For this example, match the phase of your system response such that the phase at 1 rad/sec is 150 degrees.

First, create a Bode plot of a transfer function system with chart object `bp`.

```sys = tf(1,[1 1]); bp = bodeplot(sys);```

Enable phase matching and set the phase matching frequency and value.

```bp.PhaseMatchingEnabled = "on"; bp.PhaseMatchingFrequency = 1; bp.PhaseMatchingValue = 150;```

The first bode plot has a phase of -45 degrees at a frequency of 1 rad/s. Setting the phase matching options so that at 1 rad/s the phase is near 150 degrees yields the second Bode plot. Note that, however, the phase can only be -45 + N*360, where N is an integer. So the plot is set to the nearest allowable phase, namely 315 degrees (or $1*360-45=31{5}^{o}$).

For this example, compare the frequency responses of two identified state-space models with 2 and 6 states along with their 2 $\sigma$ confidence regions.

Load the identified state-space model data and estimate the two models using `n4sid`. Using `n4sid` requires a System Identification Toolbox™ license.

```load iddata1 sys1 = n4sid(z1,2); sys2 = n4sid(z1,6);```

Create a Bode plot of the two systems.

```bodeplot(sys1,'r',sys2,'b'); legend('sys1','sys2');```

From the plot, observe that both models produce about 70% fit to data. However, `sys2` shows higher uncertainty in its frequency response, especially close to the Nyquist frequency. Now, use `linspace` to create a vector of frequencies and plot the Bode response using the frequency vector `w`.

```w = linspace(8,10*pi,256); bp = bodeplot(sys1,sys2,w); legend('sys1','sys2');```

Enable phase matching, specify the standard deviation of the confidence region, and display the confidence region.

```bp.PhaseMatchingEnabled = "on"; bp.Characteristics.ConfidenceRegion.NumberOfStandardDeviations = 2; bp.Characteristics.ConfidenceRegion.Visible = "on";```

Alternatively, you can use the `showconfidence` command to display the confidence regions on the Bode plot.

```showConfidence(bp) ```

For this example, compare the frequency response of a parametric model, identified from input/output data, to a non-parametric model identified using the same data. Identify parametric and non-parametric models based on the data.

Load the data and create the parametric and non-parametric models using `tfest` and `spa`, respectively.

```load iddata2 z2; w = linspace(0,10*pi,128); sys_np = spa(z2,[],w); sys_p = tfest(z2,2);```

`spa` and `tfest` require System Identification Toolbox™ software. The model `sys_np` is a non-parametric identified model while, `sys_p` is a parametric identified model.

Create a Bode plot that includes both systems. Enable phase macthing for this plot.

```bp = bodeplot(sys_p,sys_np,w); bp.PhaseMatchingEnabled = "on"; grid on legend('Parametric Model','Non-Parametric model');```

Algorithms

The software computes the frequency response as follows:

1. Compute the zero-pole-gain (`zpk` (Control System Toolbox)) representation of the dynamic system.

2. Evaluate the gain and phase of the frequency response based on the zero, pole, and gain data for each input/output channel of the system.

• For continuous-time systems, `bode` evaluates the frequency response on the imaginary axis s = and considers only positive frequencies.

• For discrete-time systems, `bode` evaluates the frequency response on the unit circle. To facilitate interpretation, the command parameterizes the upper half of the unit circle as:

`$z={e}^{j\omega {T}_{s}},\text{ }0\le \omega \le {\omega }_{N}=\frac{\pi }{{T}_{s}},$`

where Ts is the sample time and ωN is the Nyquist frequency. The equivalent continuous-time frequency ω is then used as the x-axis variable. Because $H\left({e}^{j\omega {T}_{s}}\right)$ is periodic with period 2ωN, `bode` plots the response only up to the Nyquist frequency ωN. If `sys` is a discrete-time model with unspecified sample time, `bode` uses Ts = 1.

Version History

Introduced before R2006a

expand all