iopzplot

Plot pole-zero map for input-output pairs of dynamic system

Description

The iopzplot function plots the pole-zero map for input-output pairs of a dynamic system model and returns an IOPZPlot 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 pole and zero locations, use iopzmap.

Creation

Syntax

iopzp = iopzplot(sys)

iopzp = iopzplot(sys1,sys2,...,sysN)

iopzp = iopzplot(sys1,ColorSpec1,...,sysN,ColorSpecN)

iopzp = iopzplot(___,plotoptions)

iopzp = iopzplot(parent,___)

Description

iopzp = iopzplot(sys) plots the poles and zeros of each input/output pair of the dynamic system model sys and returns the corresponding chart object. In the plot, x and o represent poles and zeros, respectively.

iopzp = iopzplot(sys1,sys2,...,sysN) displays the poles and zeros of multiple models on a single plot.

iopzp = iopzplot(sys1,ColorSpec1,...,sysN,ColorSpecN) sets the line style, marker type, and color for the plot of each system.

iopzp = iopzplot(___,plotoptions) plots the poles and zeros with the plotting options specified in plotoptions. Settings you specify in plotoptions override the plotting preferences for the current MATLAB^® session.

iopzp = iopzplot(parent,___) plots the poles and zeros 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

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, or ss models.

• Sparse state-space models, such as sparss or mechss models.

• Generalized or uncertain LTI models such as genss 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.

• Identified LTI models, such as idtf (System Identification Toolbox), idss (System Identification Toolbox), or idproc (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.

ColorSpec — Color

"r" | "g" | "b" | ...

Color, specified as one of the following values.

Color	Description
"r"	red
"g"	green
"b"	blue
"c"	cyan
"m"	magenta
"y"	yellow
"k"	black
"w"	white

plotoptions — Pole-zero plot options

pzoptions object

Pole-zero plot options, specified as a pzoptions object. You can use these options to customize the PZ 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 IOPZPlot Properties.

Responses — Model responses

IOPZResponse object | array of IOPZResponse objects

Model responses, specified as an IOPZResponse 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 IOPZResponse 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.

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

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

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
"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

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.

ConfidenceRegion — Confidence region

CharacteristicOption object

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

Visible — Confidence region visibility

"off" (default) | on/off logical value

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.

NumberOfStandardDeviations — Number of standard deviations

1 (default) | positive scalar

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

Dependencies

ConfidenceRegion is supported only for identified models, which require System Identification Toolbox software.

TimeUnit — Time units

"seconds" | "milliseconds" | "minutes" | ...

Time units, specified as one of the following values:

• "nanoseconds"

• "microseconds"

• "milliseconds"

• "seconds"

• "minutes"

• "hours"

• "days"

• "weeks"

• "months"

• "years"

Dependencies

By default, the response uses the time 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.

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.

Visible — Chart visibility

"on" (default) | on/off logical value

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.

IOGrouping — Grouping of inputs and outputs pairs

"none" (default) | "inputs" | "outputs" | "all"

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.

InputVisible — Option to display inputs

on/off logical value | array of on/off logical values

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.

OutputVisible — Option to display outputs

on/off logical value | array of on/off logical 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	Add dynamic system response to existing response plot
showConfidence (System Identification Toolbox)	Display confidence regions on response plots for identified models

Examples

Change I/O Grouping on Pole/Zero Map

Create a pole/zero map of a two-input, two-output dynamic system.

sys = rss(3,2,2);
ip = iopzplot(sys);

By default, the plot displays the poles and zeros of each I/O pair on its own axis. Modify the chart object to view all I/Os on a single axis.

ip.IOGrouping = "all";

Use Pole-Zero Map to Examine Identified Model

View the poles and zeros of a sixth-order state-space model estimated from input-output data. Use the plot handle to display the confidence intervals of the identified model's pole and zero locations.

load iddata1
sys = ssest(z1,6,ssestOptions('focus','simulation'));
h = iopzplot(sys);
showConfidence(h)

There is at least one pair of complex-conjugate poles whose locations overlap with those of a complex zero, within the 1-σ confidence region. This suggests their redundancy. Hence, a lower (4th) order model might be more robust for the given data.

sys2 = ssest(z1,4,ssestOptions('focus','simulation'));
h = iopzplot(sys,sys2);
showConfidence(h)
legend('6th-order','4th-order')
axis([-20, 10 -30 30])

The fourth-order model sys2 shows less variability in the pole-zero locations.

Tips

• Use sgrid or zgrid to plot lines of constant damping ratio and natural frequency in the s-plane or z-plane, respectively.

Version History

Introduced before R2006a

R2024b: Improved customization workflows and integration with MATLAB plotting tools

Starting in R2024b, iopzplot returns an IOPZPlot chart object. Previously, the iopzplot 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 PZ plots to tiled chart layouts.

• Saving and loading a parent figure now maintains full plot interactivity.

• You can add a response your PZ 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 PZ plot using the Children property of its parent figure.