initialplot

Plot initial condition response of dynamic system

Description

The initialplot function plots the initial condition response of a dynamic system model and returns an InitialPlot 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 initial condition response data, use initial.

Creation

Syntax

ip = initialplot(sys,IC)

ip = initialplot(sys1,sys2,...,sysN,x0)

ip = initialplot(sys1,LineSpec1,...,sysN,LineSpecN,x0)

ip = initialplot(___,t)

ip = initialplot(sys,IC,t,p)

ip = initialplot(___,plotoptions)

ip = initialplot(parent,___)

Description

ip = initialplot(sys,IC) plots the initial condition response of dynamic system sys and returns the corresponding chart object.

ip = initialplot(sys1,sys2,...,sysN,x0) plots the initial condition response of multiple dynamic systems sys1,sys2,…,sysN on the same plot.

ip = initialplot(sys1,LineSpec1,...,sysN,LineSpecN,x0) sets the line style, marker type, and color for the initial condition response of each system.

ip = initialplot(___,t) simulates the response for the time steps specified by t. To define the time steps, you can specify:

• The final simulation time using a scalar value.

• The initial and final simulation times using a two-element vector. (since R2023b)

• All the time steps using a vector.

ip = initialplot(sys,IC,t,p) also specifies the parameter trajectory p for LPV models. (since R2023a)

ip = initialplot(___,plotoptions) plots the initial condition 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.

ip = initialplot(parent,___) plots the initial condition 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

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. You can only use state-space models of the following types:

• Continuous-time or discrete-time numeric ss models.

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

  • For tunable control design blocks, the function evaluates the model at its current value for both plotting and returning response data.

  • For uncertain control design blocks, the function plots the nominal value and random samples of the model. When you use output arguments, the function returns response data for the nominal model only.

• Sparse state-space models such as sparss and mechss models. You must specify final time tFinal for sparse state-space models.

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

If sys is an array of models, the function plots the 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

t — 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 step size 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.

IC — Initial condition

vector | RespConfig object | operating condition created with findop

Initial condition, specified as one of the following:

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

• Response configuration, specified as a RespConfig object. Use this object to specify initial state and parameter values for LPV models. (since R2024b)

• Operating condition, specified as an object created using findop. (since R2024b)

p — LPV model parameter trajectory

matrix | function handle

Since R2023a

Parameter trajectory of the LPV model, specified as a matrix or 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. An initial parameter value is required for this input method. To specify initial conditions, use the IC argument.

plotoptions — Time response plot options

timeoptions object

Time response plot options, specified as a timeoptions 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 InitialPlot Properties.

Responses — Model responses

InitialResponse object | array of InitialResponse objects

Model responses, specified as an InitialResponse 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 InitialResponse 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. You can only use state-space models of the following types:

• Continuous-time or discrete-time numeric ss models.

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

  • For tunable control design blocks, the function evaluates the model at its current value for both plotting and returning response data.

  • For uncertain control design blocks, the function plots the nominal value and random samples of the model. When you use output arguments, the function returns response data for the nominal model only.

• Sparse state-space models such as sparss and mechss models. You must specify final time tFinal for sparse state-space models.

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

If sys is an array of models, the function plots the responses of all models in the array on the same axes.

TimeSpec — Time values

scalar | 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 step size 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.

Bias — Baseline input signal value

0 (default) | scalar | vector | 'u0'

Baseline input signal value, specified as a scalar or vector.

• For single-input systems, Bias is a scalar value.

• For multi-input systems, Bias is a vector of length N_u, where N_u is the number of input channels. Each vector value corresponds to the signal value in that input channel. The functions compute the responses one input channel at a time.

• For state-space models with offsets, set Bias = 'u0' to set the baseline signal to the offsets u₀, u₀(t) of the LTV model, or u₀(t,p) of the LPV model. For LTV and LPV models, this is the u0 output of the data function. The total input signal is then u₀ + u(t).

InitialCondition — Initial condition

operating condition created using findop

Initial condition for response, specified as an operating condition created using findop.

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.

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

PeakResponse — Peak response

CharacteristicOption object

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

TransientTime — Transient time

CharacteristicOption object

Transient time, specified as a CharacteristicOption object with the following properties.

Threshold — Threshold for detecting steady state

0.02 (default) | scalar value between 0 and 1

Threshold for detecting steady state, specified as a scalar value between 0 and 1. For example, to measure when the response remains with 5% of the steady-state value, set a threshold value of 0.05.

Visible — Transient time visibility

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

Transient time 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.

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.

Normalize — Option to normalize plot

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

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

• "on", 1, or true — Normalize the plot.

• "off", 0, or false — Do not normalize the plot.

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

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.

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

Examples

Customize Initial Conditions Plot

Generate a random state-space model with 5 states and create the initial condition response plot chart object ip.

rng("default")
sys = rss(5);
x0 = [1,2,3,4,5];
ip = initialplot(sys,x0);

Change the time units to minutes and turn on the grid. To do so, edit properties of chart object.

ip.TimeUnit = "minutes";
grid on

The plot automatically updates when you modify the properties of the chart object.

Custom Initial Condition Plot of MIMO System

Consider the following two-input, two-output dynamic system.

$$sys(s)=\left[\begin{array}{cc}0& {\displaystyle \frac{3s}{s^2+s+10}}\\ {\displaystyle \frac{s+1}{s+5}}& {\displaystyle \frac{2}{s+6}}\end{array}\right].$$

Convert the sys to state-space form since initial condition plots are supported only for state-space models.

sys = ss([0, tf([3 0],[1 1 10]) ; tf([1 1],[1 5]), tf(2,[1 6])]);
size(sys)

State-space model with 2 outputs, 2 inputs, and 4 states.

The resultant state-space model has four states. Hence, provide an initial condition vector with four elements.

x0 = [0.3,0.25,1,4];

Plot the initial condition response. Turn on the grid and change the plot title.

ip = initialplot(sys,x0);
title("Initial Condition Plot of MIMO System sys(s)")
grid on

Initial Condition Plot with Specified Grid Color

For this example, consider a MIMO state-space model with 3 inputs, 3 outputs and 3 states. Create an initial condition plot with red colored grid lines.

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 an initial condition plot with chart object ip and display the grid.

x0 = [0.35,0.1,4];
ip = initialplot(sys_mimo,x0);
grid on

Set the grid color to red.

ip.AxesStyle.GridColor = [1 0 0];

The plot automatically updates when you modify the chart object. For MIMO models, initialplot produces a grid of plots, each plot displaying the initial condition response of one I/O pair.

Customized Initial Conditions Response Plot at Specified Time

For this example, examine the initial condition response of the following zero-pole-gain model and limit the plot to tFinal = 15 s. Use 15-point blue text for the title.

First, convert the zpk model to an ss model since initialplot only supports state-space models.

sys = ss(zpk(-1,[-0.2+3j,-0.2-3j],1)*tf([1 1],[1 0.05]));
tFinal = 15;
x0 = [4,2,3];

Create the initial conditions response plot and set the title properties of the chart object.

ip = initialplot(sys,x0,tFinal);
ip.Title.FontSize = 15;
ip.Title.Color = [0 0 1];

Plot Initial Condition Responses of Multiple Systems

For this example, plot the initial condition responses of three dynamic systems and use the plot handle to enable the grid.

First, create the three models and provide the initial conditions.

rng('default');
sys1 = rss(4); 
sys2 = rss(4);
sys3 = rss(4);
x0 = [1,1,1,1];

Plot the initial condition responses of the three models.

t = 0:0.1:5;
ip = initialplot(sys1,'r--',sys2,'b',sys3,'g-.',x0,t);
legend('sys1','sys2','sys3');
grid on

Version History

Introduced before R2006a