Main Content

lsimplot

Plot simulated time response of dynamic system to arbitrary inputs

expand all in page

    Description

    The lsimplot function plots the simulated time response of a dynamic system model to arbitrary inputs and returns an LSimPlot 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 time response data, use lsim.

    Creation

    Syntax

    lp = lsimplot(sys,u,t)
    lp = lsimplot(sys1,sys2,...,sysN,u,t)
    lp = lsimplot(sys1,LineSpec1,...,sysN,LineSpecN,u,t)
    lp = lsimplot(___,IC)
    y = lsim(sys,u,t,IC,p)
    lp = lsimplot(___,plotoptions)
    lp = lsimplot(parent,___)
    lp = lsimplot(sys)
    lp = lsimplot(sys1,sys2,...,sysN)
    lp = lsimplot(sys1,LineSpec1,...,sysN,LineSpecN)

    Description

    lp = lsimplot(sys,u,t) plots the simulated time response of the model sys for input signal u and corresponding time vector t, returning the corresponding chart object.

    example

    lp = lsimplot(sys1,sys2,...,sysN,u,t) plots the simulated response of multiple dynamic systems sys1,sys2,…,sysN using the input on the same plot.

    example

    lp = lsimplot(sys1,LineSpec1,...,sysN,LineSpecN,u,t) sets the line style, marker type, and color for the simulated response of each specified system.

    example

    lp = lsimplot(___,IC) further specifies the initial condition IC at t(1), when sys is a state-space model.

    example

    y = lsim(sys,u,t,IC,p) specifies the parameter trajectory p when sys is an LPV model. (since R2023a)

    lp = lsimplot(___,method) specifies how lsimplot interpolates the input values between samples, when sys is a continuous-time model.

    example

    lp = lsimplot(___,plotoptions) plots the simulated 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

    lp = lsimplot(parent,___) plots the simulated 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.

    lp = lsimplot(sys) opens the Linear Simulation Tool for simulating sys. For more information about using this tool for linear analysis, see Working with the Linear Simulation Tool.

    lp = lsimplot(sys1,sys2,...,sysN) opens the Linear Simulation Tool for simulating multiple dynamic systems.

    lp = lsimplot(sys1,LineSpec1,...,sysN,LineSpecN) opens the Linear Simulation Tool and sets the line style, marker type, and color for the response of each specified system.

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

    • Identified LTI models, such as idtf, idss, or idproc models. For such models, the function can also plot confidence intervals and return standard deviations of the frequency response. See Step Responses of Identified Models with Confidence Regions. (Using identified models requires System Identification Toolbox™ software.)

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

    This function does not support frequency-response data models such as frd, genfrd, or idfrd models.

    If sys is an array of models, the function plots the responses of all models in the array on the same axes. See Step Response of Systems in a Model Array.

    Input signal for simulation, specified as one of the following:

    • For single-input systems, u is a vector of the same length as t.

    • For multi-input systems, u is an array with as many rows as there are time samples (length(t)) and as many columns as there are inputs to sys. In other words, each row u(i,:) represents the values applied at the inputs of sys at time t(i). Each column u(:,j) is the signal applied to the jth input of sys.

    Time samples at which to compute the response, specified as a vector of the form T0:dT:Tf. The lsim command interprets t as having the units specified in the TimeUnit property of the model sys.

    For continuous-time sys, the lsim command uses the time step dT to discretize the model. If dT is too large relative to the system dynamics (undersampling), lsim issues a warning recommending a faster sampling time. For further discussion of the impact of sampling time on simulation, see Effect of Sample Time on Simulation.

    For discrete-time sys, the time step dT must equal the sample time of sys. Alternatively, you can omit t or set it to []. In that case, lsim sets t to a vector of the same length as u that begins at 0 with a time step equal to sys.Ts.

    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

    Since R2024b

    Initial conditions for simulating a state-space model, specified as one of the following:

    • A vector xinit having one entry for each state in sys.

    • An operating condition 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 omit this argument, then the simulation starts from the all-zero initial condition.

    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.

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

    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 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 LSimPlot Properties.

    Model responses, specified as anLinearSimulationResponse 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 LinearSimulationResponse 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.

    Time samples at which to compute the response, specified as a vector of the form 0:dT:Tf. The time vector must be real, finite, and must contain monotonically increasing and evenly spaced time samples. lsimplot interprets t as having the units specified in the TimeUnit property of the model Model.

    For continuous-time systems, the model is discretized using time step dT. If dT is too large relative to the system dynamics (undersampling), lsimplot generates a warning.

    For discrete-time systems, the time step dT must equal the sample time of Model. Alternatively, you can set t to []. In that case, lsimplot sets t to a vector of the same length as u that begins at 0 with a time step equal to Model.Ts.

    Input signal for simulation, specified as the following:

    • For single-input systems, specify u as a vector of the same length as t.

    • For multi-input systems, specify Model as an array with as many rows as there are time samples and as many columns as there are inputs to sys. In other words, each row u(i,:) represents the values applied at the inputs of Model at time t(i). Each column u(:,j) is the signal applied to the jth input of Model.

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

    Interpolation method for discretizing continuous-time models, specified as one of the following values:

    • "zoh" — Zero-order hold

    • "foh" — First-order hold

    • "auto" — Automatically select the discretization method based on smoothness of the input signal.

    For more information about these two discretization methods, see Continuous-Discrete Conversion Methods.

    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.

    Color NameRGB TripletHexadecimal 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

    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.

    Peak response, specified as a CharacteristicOption object with the following property.

    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.

    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.

    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.

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

    • "on", 1, or true — Plot the input signal.

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

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

    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.

    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

    addResponseAdd dynamic system response to existing response plot

    Examples

    collapse all

    Open Live Script

    For this example, change time units to minutes and turn the grid on for the simulated response plot. Consider the following transfer function.

    sys = tf(3,[1 2 3]);

    To compute the response of this system to an arbitrary input signal, provide lsimplot with a vector of the times t at which you want to compute the response and a vector u containing the corresponding signal values. For instance, plot the system response to a ramping step signal that starts at 0 at time t = 0, ramps from 0 at t = 1 to 1 at t = 2, and then holds steady at 1. Define t and compute the values of u.

    t = 0:0.04:8;
u = max(0,min(t-1,1));

    Use lsimplot plot the system response to the signal with chart object lp.

    lp = lsimplot(sys,u,t);
grid on

    MATLAB figure

    The plot shows the applied input (u,t) in gray and the system response in blue.

    Modify the chart object to change the time units to minutes.

    lp.TimeUnit = "minutes";

    MATLAB figure

    The plot automatically updates when you modify the chart object.

    Alternatively, you can also use the timeoptions command to specify the required plot options. First, create an options set based on the toolbox preferences.

    plotoptions = timeoptions('cstprefs');

    Change properties of the options set by setting the time units to minutes and enabling the grid.

    plotoptions.TimeUnits = 'minutes';
plotoptions.Grid = 'on';
lsimplot(sys,u,t,plotoptions);

    MATLAB figure

    Open Live Script

    lsimplot allows you to plot the simulated responses of multiple dynamic systems on the same axis. For instance, compare the closed-loop response of a system with a PI controller and a PID controller. Then, customize the plot by enabling normalization and turning the grid on.

    First, create a transfer function of the system and tune the controllers.

    H = tf(4,[1 10 25]);
C1 = pidtune(H,'PI');
C2 = pidtune(H,'PID');

    Form the closed-loop systems.

    sys1 = feedback(H*C1,1);
sys2 = feedback(H*C2,1);

    Plot the responses of both systems to a square wave with a period of 4 s. 

    [u,t] = gensig("square",4,12);
lp1 = lsimplot(sys1,sys2,u,t);
legend("PI","PID");

    MATLAB figure

    Enable normalization and turn on the grid.

    lp1.Normalize = "on";
grid on

    MATLAB figure

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

    By default, lsimplot chooses distinct colors for each system that you plot. You can specify colors and line styles using the LineSpec input argument. The first LineSpec "r--" specifies a dashed red line for the response with the PI controller. The second LineSpec "b" specifies a solid blue line for the response with the PID controller. The legend reflects the specified colors and line styles.

    lp2 = lsimplot(sys1,"r--",sys2,"b",u,t);
legend("PI","PID");
lp2.Normalize = "on";
grid on

    MATLAB figure

    Open Live Script

    By default, lsimplot simulates the model assuming all states are zero at the start of the simulation. When simulating the response of a state-space model, use the optional x0 input argument to specify nonzero initial state values. Consider the following two-state SISO state-space model.

    A = [-1.5 -3;
      3   -1];
B = [1.3; 0];
C = [1.15 2.3];
D = 0;
sys = ss(A,B,C,D);

    Suppose that you want to allow the system to evolve from a known set of initial states with no input for 2 s, and then apply a unit step change. Specify the vector x0 of initial state values, and create the input vector. 

    x0 = [-0.2 0.3];
t = 0:0.05:8;
u = zeros(length(t),1);
u(t>=2) = 1;

    First, create a default options set using timeoptions.

    plotoptions = timeoptions;

    Next change the required properties of the options set plotoptions and plot the simulated response with the zero order hold option.

    plotoptions.Title.FontSize = 15;
plotoptions.Title.Color = [0 0 1];
plotoptions.Grid = 'on';
h = lsimplot(sys,u,t,x0,plotoptions,'zoh');
hold on
title('Simulated Time Response with Initial Conditions')

    MATLAB figure

    The first half of the plot shows the free evolution of the system from the initial state values [-0.2 0.3]. At t = 2 there is a step change to the input, and the plot shows the system response to this new signal beginning from the state values at that time. Because plotoptions begins with a fixed set of options, the plot result is independent of the toolbox preferences of the MATLAB session.

    Version History

    Introduced before R2006a

    See Also

    |

    Topics