addResponse

Add dynamic system response to existing response plot

Since R2024b

Syntax

addResponse(rp,sys)

addResponse(rp, sys1,sys2,...,sysN)

addResponse(___,Name=Value)

Description

addResponse(rp,sys) adds the response for dynamic system model sys to the existing response plot associated with chart object rp.

• The time and frequency specifications for the added response are computed automatically.

• The line width and color for the response are assigned automatically.

addResponse(rp, sys1,sys2,...,sysN) add the responses for multiple dynamic system models.

addResponse(___,Name=Value) configures added responses using one or more name-value arguments. For example, addResponse(rp,sys,LineWidth=1) adds the response for model sys and sets the plot line width to 1.

When adding responses for multiple systems, the specified name-value arguments apply to all responses.

Examples

Plot Multiple Step Responses

Create a second-order transfer function with a damping ratio of 0.5.

wn = 2;
zeta = 0.5;
sys = tf(wn^2,[1,2*zeta*wn,wn^2]);

Plot the step response of this system.

sp = stepplot(sys);

Create a transfer function with a lower damping ratio and add it to the step plot.

zetaL = 0.25;
sysL = tf(wn^2,[1,2*zetaL*wn,wn^2]);
addResponse(sp,sysL);

Create a transfer function with a higher damping ratio and add it to the step plot.

zetaH = 0.75;
sysH = tf(wn^2,[1,2*zetaH*wn,wn^2]);
addResponse(sp,sysH);

Add a legend to the plot.

legend("zeta = 0.5","zeta = 0.25","zeta = 0.75",...
    Location="southeast");

Input Arguments

rp — Response plot chart

impulseplot object | initialplot object | stepplot object | lsimplot object | bodeplot object | nicholsplot object | nyquistplot object | sigmaplot object | pzplot object | iopzplot object | rlocusplot object

Response plot chart, specified as an object created using one of these functions:

• impulseplot — Impulse response

• initialplot — Initial condition response

• stepplot — Step response

• lsimplot — Simulated time response to arbitrary input

• bodeplot — Bode frequency response

• nicholsplot — Nichols frequency response

• nyquistplot — Nyquist response

• sigmaplot — Singular values for frequency response

• pzplot — Pole-zero map

• iopzplot — Plot pole-zero map for input-output pairs

• rlocusplot — Root locus plot

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.

• 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), or idproc (System Identification Toolbox) models. Using identified models requires System Identification Toolbox™ software.

• Linear time-varying (ltvss) and linear parameter-varying (lpvss) models.

Dependencies

The supported models depend on the type of chart object specified in rp.

• Frequency-response data models are supported only for bodeplot, nicholsplot, nyquistplot, and sigmaplot chart objects.

• Linear time-varying and linear parameter-varying models are supported only for stepplot, impulseplot, initialplot, and lsimplot chart objects.

• For rlocusplot chart objects, only SISO models are supported.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: addResponse(rp,sys,Color="red") adds a response and sets its color to red.

Plot Appearance

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 these 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 the response in the legend, specified as one of these 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.

MarkerStyle — Marker style

"none" | "o" | "+" | "*" | "." | ...

Marker style, specified as one of these values. Specifying a marker style using a name-value argument overrides any marker style that you specify using LineSpec.

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

Dependencies

The MarkerStyle argument is not supported for pzplot or iopzplot responses.

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

LineStyle — Line style

"-" | "--" | ":" | "-."

Line style, specified as one of these values.

Line Style	Description
"-"	Solid line
"--"	Dashed line
":"	Dotted line
"-."	Dash-dotted line
"none"	No line

Dependencies

The LineStyle argument is not supported for pzplot or iopzplot responses.

MarkerSize — Marker size

positive scalar

Marker size, specified as a positive scalar.

LineWidth — Line width

positive scalar

Line width, specified as a positive scalar.

SeriesIndex — Series index

positive integer | "none"

Series index, specified as a positive integer or "none".

By default, the SeriesIndex property is a number that corresponds to the order in which the response was added to the chart, starting at 1. MATLAB^® uses the number to calculate indices for automatically assigning color, line style, or markers for responses. Any responses in the chart that have the same SeriesIndex number also have the same color, line style, and markers.

A SeriesIndex value of "none" indicates that a response does not participate in the indexing scheme.

Options — Plot options

timeoptions object | bodeoptions object | object | nicholsoptions object | nyquistoptions object | sigmaoptions object | pzoptions object

Plot options, specified as one of the following objects, depending on the type of chart object specified in rp.

Options Object	Chart Object rp
timeoptions	impulseplot, initialplot, stepplot, and lsimplot
bodeoptions	bodeplot
nicholsoptions	nicholsplot
nyquistoptions	nyquistplot
sigmaoptions	sigmapplot
pzoptions	pzplot, iopzplot, and rlocusplot

Time-Domain Response

Time — Time steps

positive scalar | two-element vector | vector | []

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

• Positive scalar tFinal— Compute the response from t = 0 to t = tFinal.

• Two-element vector [t0 tFinal] — Compute the response from t = t0 to t = tFinal. (since R2023b)

• Vector Ti:dt:Tf— Compute the response for the time points specified in t.

  • For continuous-time systems, dt is the sample time of a discrete approximation to the continuous system.

  • For discrete-time systems with a specified sample time, dt must match the sample time property Ts of sys.

  • For discrete-time systems with an unspecified sample time (Ts = -1), dt must be 1.

• [] — Automatically select time values based on system dynamics.

When you specify a time range using either tFinal or [t0 tFinal]:

• For continuous-time systems, the function automatically determines the size of the time step and number of points based on the system dynamics.

• For discrete-time systems with a specified sample time, the function uses the sample time of sys as the step size.

• For discrete-time systems with unspecified sample time (Ts = -1), the function interprets tFinal as the number of sampling periods to simulate with a sample time of 1 second.

Express t using the time units specified in the TimeUnit property of sys.

If you specified a step delay td using Config, the function applies the step at t = t0+td.

Dependencies

This argument is supported only when rp is one of the following objects:

• stepplot

• impulseplot

• initialplot

• lsimplot

Parameter — LPV model parameter trajectory

matrix | function handle

Parameter trajectory of the LPV model, specified as a matrix or a function handle.

• For exogenous or explicit trajectories, specify p as a matrix with dimensions N-by-Np, where N is the number of time samples and Np is the number of parameters.

  Thus, the row vector p(i,:) contains the parameter values at the ith time step.

• For endogenous or implicit trajectories, specify p as a function handle of the form p = F(t,x,u) in continuous time and p = F(k,x,u) in discrete time that gives parameters as a function of time t or time sample k, state x, and input u.

  This option is useful when you want to simulate quasi-LPV models. For an example, see Step Response of LPV Model.

Dependencies

This argument is supported only when sys is an LPV model and rp is a stepplot object or an impulseplot object.

Dependencies

This argument is supported only when rp is one of the following objects:

• stepplot

• impulseplot

• initialplot

• lsimplot

Config — Response configuration

RespConfig object

Configuration of the applied signal, specified as a RespConfig object. By default, step applies an input that goes from 0 to 1 at time t = 0. Use this input argument to change the configuration of the step input. See Response to Custom Step Input for an example.

For lpvss and ltvss models with offsets (x₀(t),u₀(t)), you can use RespConfig to define the input relative to u₀(t,p) and initialize the simulation with the state x₀(t,p).

This argument is supported only when rp is a stepplot object or an impulse object.

Dependencies

This argument is supported only when rp is a stepplot object or an impulseplot object.

InitialCondition — Initial condition

vector of zeros (default) | vector | operating condition created using findop

Initial conditions for simulating a state-space model, specified as one these values. Specifying initial conditions using a name-value argument overrides the initial conditions that you specify using IC.

• Initial state values, specified as a vector with length equal to the number of states in the model.

• Response configuration, specified as a RespConfig object.

• Operating condition, specified as an operating point object created using findop. An operating point object allows you to start the simulation from a steady-state operating condition with nonzero past u, w, and y values. For example, to start a simulation from nonzero y value, you can specify:

  op = findop(sys,y=3);
  y = lsim(sys,u,t,op)

If you do not specify an initial condition, then the simulation starts from an all-zero initial condition.

Dependencies

This argument is supported only when rp is an initialplot object or an lsimplot object.

InterpolationMethod — Discretization interpolation method

"zoh" | "foh"

Discretization interpolation method for sampling continuous-time models, specified as one of the following.

• "zoh" — Zero-order hold

• "foh" — First-order hold

When sys is a continuous-time model, lsimplot computes the time response by discretizing the model using a sample time equal to the time step dT = t(2)-t(1) of t. If you do not specify a discretization method, then lsimplot selects the method automatically based on the smoothness of the signal u. For more information about these two discretization methods, see Continuous-Discrete Conversion Methods.

Dependencies

This argument is supported only when rp is an lsimplot object.

Frequency-Domain Response

Frequency — 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 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 [w_min,w_max] for your plot, then in:

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

• Linear frequency scale, the plot frequency limits are set to [–w_max,w_max] 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.

Dependencies

This argument is supported only when rp is a bodeplot,nicholsplot, nyquistplot, or sigmaplot object.

SingularValueType — 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 of sys.

• 2 — Plot the singular values of the frequency response I+H.

• 3 — Plot the singular values of the frequency response I+H^-1.

Dependencies

• This argument is supported only when rp is a sigmaplot object.

• You can specify SingularValueType only when sys has the same number of inputs and outputs.

Root Locus Plot

FeedbackGains — Feedback gain values

vector

Feedback gain values that pertain to pole locations, specified as a vector. The feedback gains define the trajectory of the poles thereby affecting the shape of the root locus plot.

Dependencies

This argument is supported only when rp is an rlocusplot object.

Version History

Introduced in R2024b