sigmaplot
Plot singular values for frequency response of dynamic system
Description
The sigmaplot
function plots the singular values for the
frequency response of a dynamic system model and returns a SigmaPlot
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.
To obtain singular-value data, use sigma
.
Creation
Syntax
Description
plots the singular values (SVs) of the frequency response of the dynamic system model
sp
= sigmaplot(sys
)sys
and returns the corresponding chart object.
plots singular values for frequencies specified in sp
= sigmaplot(___,w
)w
. You can
specify a frequency range or a vector of frequencies. If you omit w
,
frequencies are selected based on the system dynamics. You can use
w
with any of the previous syntaxes.
plots the singular values using the plotting options specified in
sp
= sigmaplot(___,plotoptions
)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.
plots the singular values in the specified parent graphics container, such as a
sp
= sigmaplot(parent
,___)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
sys
— Dynamic system
dynamic system model | model array
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
,zpk
, orss
models.Sparse state-space models, such as
sparss
ormechss
models. Frequency gridw
must be specified for sparse models.Generalized or uncertain LTI models such as
genss
oruss
(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
(System Identification Toolbox),idss
(System Identification Toolbox), oridproc
(System Identification Toolbox) models. Using identified models requires System Identification Toolbox™ software.
If sys
is an array of models, the plot shows responses of all models in
the array on the same axes.
LineSpec
— Line style, marker, and color
string | character vector
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 Style | Description |
---|---|
"-" | Solid line |
"--" | Dashed line |
":" | Dotted line |
"-." | Dash-dotted line |
Marker | Description |
---|---|
"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 |
Color | Description |
---|---|
"r" | red |
"g" | green |
"b" | blue |
"c" | cyan |
"m" | magenta |
"y" | yellow |
"k" | black |
"w" | white |
w
— Frequencies
{wmin,wmax}
| vector | []
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 fromwmin
towmax
. Ifwmax
is greater than the Nyquist frequency ofsys
, 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 vectorw
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.
type
— Type of modified singular values
1
| 2
| 3
Type of modified singular values to plot, specified as one of the following values.
1
— Plot the singular values of the frequency response H-1, where H is the frequency response ofsys
.2
— Plot the singular values of the frequency response I+H.3
— Plot the singular values of the frequency response I+H-1.
Dependencies
You can specify type
only when sys
has the same number of inputs and outputs.
plotoptions
— Singular-value plot options
sigmaoptions
object
Singular-value plot options, specified as a sigmaoptions
object. You can use these options to customize the plot
appearance. Settings you specify in plotoptions
override the
preference settings for the current MATLAB session.
parent
— Parent container
Figure
object (default) | TiledChartLayout
object | UIFigure
object | UIGridLayout
object | UIPanel
object | UITab
object
Parent container of the chart, specified as one of the following objects:
Figure
TiledChartLayout
UIFigure
UIGridLayout
UIPanel
UITab
Properties
Note
The properties listed here are only a subset. For a complete list, see SigmaPlot Properties.
Responses
— Model responses
SigmaResponse
object | array of SigmaResponse
objects
Model responses, specified as a SigmaResponse
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 SigmaResponse
object has the following fields.
SourceData
— Source data
structure
Source data for the response, specified as a structure with the following fields.
Model
— Dynamic system
dynamic system model | model array
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
.
FrequencySpec
— Frequencies
{wmin,wmax}
| vector | []
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 fromwmin
towmax
.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 vectorw
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 thew
argument.If you do not specify
w
,FrequencySpec
is empty and frequencies are selected based on the system dynamics.
SingularValueType
— Type of singular values
0
(default) | 1
| 2
| 3
Type of singular values to plot, specified as one of the following values.
0
— Plot singular values of H, which is the frequency response ofModel
.1
— Plot modified singular values of the frequency response H-1, where H is the frequency response ofsys
.2
— Plot modified singular values of the frequency response I+H.3
— Plot modified singular values of the frequency response I+H-1.
When you initially create a plot:
SingularValueType
matches the value you specify for thetype
argument.If you do not specify
type
,SingularValueType
is0
.
Dependencies
You can specify type
as 1
, 2
, or 3
only when Model
has the same number of inputs and outputs.
Name
— Response name
string | character vector
Response name, specified as a string or character vector and stored as a string.
Visible
— Response visibility
"on"
(default) | on/off logical value
Response visibility, specified as one of the following logical on/off values:
"on"
,1
, ortrue
— Display the response in the plot."off"
,0
, orfalse
— Do not display the response in the plot.
The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState
.
LegendDisplay
— Option to list response in legend
"on"
(default) | on/off logical value
Option to list response in legend, specified as one of the following logical on/off values:
"on"
,1
, ortrue
— List the response in the legend."off"
,0
, orfalse
— Do not list the response in the legend.
The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState
.
MarkerStyle
— Marker style
"none"
| "o"
| "+"
| "*"
| "."
| ...
Marker style, specified as one of the following values.
Marker | Description |
---|---|
"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 |
Color
— Plot color
RGB triplet | hexadecimal color code | color name
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.
Color Name | RGB Triplet | Hexadecimal Color Code |
---|---|---|
| [1 0 0] | #FF0000 |
| [0 1 0] | #00FF00 |
| [0 0 1] | #0000FF |
| [0 1 1] | #00FFFF |
| [1 0 1] | #FF00FF |
| [1 1 0] | #FFFF00 |
| [0 0 0] | #000000 |
| [1 1 1] | #FFFFFF |
LineStyle
— Line style
"-"
| "--"
| ":"
| "-."
Line style, specified as one of the following values.
Line Style | Description |
---|---|
"-" | Solid line |
"--" | Dashed line |
":" | Dotted line |
"-." | Dash-dotted line |
MarkerSize
— Marker size
positive scalar
Marker size, specified as a positive scalar.
LineWidth
— Line width
positive scalar
Line width, specified as a positive scalar.
Characteristics
— Response characteristics
CharacteristicsManager
object
Response characteristics to display in the plot, specified as a
CharacteristicsManager
object with the following property.
SigmaPeakResponse
— Peak response
CharacteristicOption
object
Visibility of peak response in plot, specified as a CharacteristicOption
object with the following property.
Visible
— Peak response visibility
"off"
(default) | on/off logical value
Peak response visibility, specified as one of the following logical on/off values:
"on"
,1
, ortrue
— Display the peak response."off"
,0
, orfalse
— Do not display the peak response.
The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState
.
FrequencyUnit
— Frequency units
"rad/s"
| "Hz"
| "rpm"
| ...
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.
FrequencyScale
— Frequency scale
"log"
| "linear"
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.
MagnitudeUnit
— Magnitude units
"dB"
| "abs"
Magnitude units, specified as one of the following:
"dB"
— Decibels"abs"
— Absolute value
Dependencies
If
MagnitudeScale
is"log"
when you setMagnitudeUnit
to"dB"
, the software automatically changesMagnitudeScale
to"linear"
.The default magnitude units depend on the toolbox preferences. For more information, see Specify Toolbox Preferences for Linear Analysis Plots.
MagnitudeScale
— Magnitude scale
"log"
| "linear"
Magnitude scale, specified as either "log"
or "linear"
.
Dependencies
Setting
MagnitudeScale
to"log"
is not supported whenMagnitudeUnit
is"dB"
.The default magnitude scale depends on the toolbox preferences. For more information, see Specify Toolbox Preferences for Linear Analysis Plots.
Visible
— Chart visibility
"on"
(default) | on/off logical value
Chart visibility, specified as one of the following logical on/off values:
"on"
,1
, ortrue
— Display the chart."off"
,0
, orfalse
— 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
.
Object Functions
addResponse | Add dynamic system response to existing response plot |
showConfidence (System Identification Toolbox) | Display confidence regions on response plots for identified models |
Examples
Customize Sigma Plot
For this example, use the plot handle to change the frequency units to Hz and turn on the grid.
Generate a random state-space model with 5 states and create the sigma plot with chart object sp
.
rng("default")
sys = rss(5);
sp = sigmaplot(sys);
Change the units to Hz and turn on the grid.
sp.FrequencyUnit = "Hz"; grid on
Alternatively, you can also use the sigmaoptions
command to specify the required plot options. First, create an options set based on the toolbox preferences.
p = sigmaoptions('cstprefs');
Change properties of the options set by setting the frequency units to Hz and enable the grid.
p.FreqUnits = 'Hz'; p.Grid = 'on'; sigmaplot(sys,p);
Depending on your own toolbox preferences, the plot you obtain might look different from this plot. Only the properties that you set explicitly, in this example Grid
and FreqUnits
, override the toolbox preferences.
Custom Sigma Plot Settings Independent of Preferences
For this example, create a sigma plot that uses 15-point red text for the title. This plot should look the same, regardless of the preferences of the MATLAB session in which it is generated.
First, create a default options set using sigmaoptions
.
plotoptions = sigmaoptions;
Next, change the required properties of the options set plotoptions
.
plotoptions.Title.FontSize = 15; plotoptions.Title.Color = [1 0 0]; plotoptions.FreqUnits = 'Hz'; plotoptions.Grid = 'on';
Now, create a sigma plot using the options set plotoptions
.
h = sigmaplot(tf(1,[1,1]),plotoptions);
Because plotoptions
begins with a fixed set of options, the plot result is independent of the toolbox preferences of the MATLAB session.
Customized Sigma Plot of Transfer Function
For this example, create a sigma plot of the following continuous-time SISO dynamic system. Then, turn the grid on, rename the plot and change the frequency scale.
Create the transfer function sys
.
sys = tf([1 0.1 7.5],[1 0.12 9 0 0]);
Next, create the options set using sigmaoptions
and change the required plot properties.
plotoptions = sigmaoptions; plotoptions.Grid = 'on'; plotoptions.FreqScale = 'linear'; plotoptions.Title.String = 'Singular Value Plot of Transfer Function';
Now, create the sigma plot with the custom option set plotoptions
.
h = sigmaplot(sys,plotoptions);
sigmaplot
automatically selects the plot range based on the system dynamics.
Sigma Plot with Specified Frequency Scale and Units
For this example, consider a MIMO state-space model with 3 inputs, 3 outputs and 3 states. Create a sigma plot with linear frequency scale, 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 sigma plot with with chart object sp
.
sp = sigmaplot(sys_mimo);
Update the plot by modifying the chart object.
sp.FrequencyScale = 'linear'; sp.FrequencyUnit = 'Hz'; grid on;
The sigma plot automatically updates when you modify the chart object
Singular Value Plot of Identified Parametric and Nonparametric Models
For this example, compare the SV for the frequencies 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 an options set to turn the grid on. Then, create a sigma plot that includes both systems using this options set.
plotoptions = sigmaoptions; plotoptions.Grid = 'on'; h = sigmaplot(sys_p,'b--',sys_np,'r--',w,plotoptions); legend('Parametric Model','Non-Parametric model');
Modified Singular Value Plot of MIMO System
Consider the following two-input, two-output dynamic system.
Plot the singular value responses of H(s) and I + H(s). Set appropriate titles using the plot option set.
H = [0, tf([3 0],[1 1 10]) ; tf([1 1],[1 5]), tf(2,[1 6])]; opts1 = sigmaoptions; opts1.Grid = 'on'; opts1.Title.String = 'Singular Value Plot of H(s)'; h1 = sigmaplot(H,opts1);
Use input 2 to plot the modified SV of type, I + H(s).
opts2 = sigmaoptions; opts2.Grid = 'on'; opts2.Title.String = 'Singular Value Plot of I+H(s)'; h2 = sigmaplot(H,[],2,opts2);
Version History
Introduced before R2006aR2024b: Improved customization workflows and integration with MATLAB plotting tools
Starting in R2024b, sigmaplot
returns a SigmaPlot
chart object. Previously, the sigmaplot
function returned a handle to the
resulting plot.
The new chart object allows you to customize your plot using dot notation.
The new chart object also improves integration with MATLAB plotting tools. For example:
You can now add singular-value plots to tiled chart layouts.
Saving and loading a parent figure now maintains full plot interactivity.
You can add a response you your singular-value plot using the new
addResponse
function.
The following functionality changes might require updates to your code.
The
gca
function now returns the chart object rather than an axes within the plot.You can no longer access the graphics objects within a singular-value plot using the
Children
property of its parent figure.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)