Run Simulation Using the sim Command

Single-Output Syntax for the sim Command

The general form of the command syntax for running a simulation is:

SimOut = sim('model', Parameters)

where model is the name of the block diagram and Parameters can be a list of parameter name-value pairs, a structure containing parameter settings, or a configuration set. The sim command returns, SimOut, a single Simulink.SimulationOutput object that contains all of the simulation outputs (logged time, states, and signals). This syntax is the "single-output format" of the sim command.

SimOut = sim('model', 'Param1', Value1, 'Param2', Value2...);
SimOut = sim('model', ParameterStruct);
SimOut = sim('model', ConfigSet);

    Note:   The output of the sim command will always be returned to SimOut, the single simulation output object and not to the workspace.

During simulation, the specified parameters override the values in the block diagram configuration set. The original configuration values are restored at the end of simulation. If you wish to simulate the model without overriding any parameters, and you want the simulation results returned in the single-output format, then you must do one of the following:

  • select Save simulation output as single object on the Data Import/Export pane of the Configuration Parameters dialog box

  • specify the ReturnWorkspaceOutputs parameter value as 'on' in the sim command:

SimOut = sim('model', 'ReturnWorkspaceOutputs', 'on');

To log the model time, states, or outputs, use the Configuration Parameters Data Import/Export dialog box. To specify the time span for a simulation, you must specify the StartTime and StopTime parameters. To log signals, either use a block such as the To Workspace block or the Scope block, or use the Signal and Scope Manager to log results directly.

To stop a simulation in progress, press Ctrl+C. The sim command does not allow you to pause a simulation in progress.

For complete details of the sim command syntax, see the sim reference page.

Examples of Implementing the sim Command

Following are examples that show the application of each of the three formats for specifying parameter values using the single-output format of the sim command.

Specifying Parameter Name-Value Pairs

In the following example, the sim syntax specifies the model name, vdp, followed by consecutive pairs of parameter name and parameter value. For example, the value of the SimulationMode parameter is rapid.

simOut = sim('vdp','SimulationMode','rapid','AbsTol','1e-5',...
            'SaveState','on','StateSaveName','xoutNew',...
            'SaveOutput','on','OutputSaveName','youtNew');
simOutVars = simOut.who;
yout = simOut.get('youtNew');

Specifying a Parameter Structure

The following example shows how to specify parameter name-value pairs as a structure to the sim command.

paramNameValStruct.SimulationMode = 'rapid';
paramNameValStruct.AbsTol         = '1e-5';
paramNameValStruct.SaveState      = 'on';
paramNameValStruct.StateSaveName  = 'xoutNew';
paramNameValStruct.SaveOutput     = 'on';
paramNameValStruct.OutputSaveName = 'youtNew';
simOut = sim('vdp',paramNameValStruct);

Specifying a Configuration Set

The following example shows how to create a configuration set and use it with the sim syntax.

model = 'vdp';
load_system(model)
simMode = get_param(model, 'SimulationMode');
set_param(model, 'SimulationMode', 'rapid')
cs = getActiveConfigSet(model);
model_cs = cs.copy;
set_param(model_cs,'AbsTol','1e-5',...
         'SaveState','on','StateSaveName','xoutNew',...
         'SaveOutput','on','OutputSaveName','youtNew')
simOut = sim(model, model_cs);
set_param(model, 'SimulationMode', simMode)

The block diagram parameter, SimulationMode, is not part of the configuration set, but is associated with the model. Therefore, the set_param command saves and restores the original simulation mode by passing the model rather than the configuration set.

Calling sim from Within parfor

For information on how to run simultaneous simulations by calling sim from within parfor, see Run Parallel Simulations.

Backwards Compatible Syntax

Use this syntax only for backwards compatibility with Simulink® Versions 7.3 or earlier releases.

[T,X,Y] =sim('model',Timespan, Options, UT)
[T,X,Y1,...,Yn] =sim('model',Timespan, Options, UT)

If only one right-hand side argument exists, then Simulink automatically saves the time, the state and the output to the specified left-hand side arguments. You can explicitly switch to the single-output format by changing the setting for Data Import/Export > Save options > Save simulation output as a single object in Model Configuration Parameters.

If you do not specify any left-hand side arguments, then Simulink determines what data to log based on the settings for Data Import/Export > Save to workspace in Model Configuration Parameters. Simulink stores the simulation output either in the current workspace or in the variable ans, based on the setting for Save simulation output as a single object in the Data Import/Export pane.

  
T

The time vector returned.

X

The state returned in matrix or structure format. The state matrix contains continuous states followed by discrete states.

Y

The output returned in matrix or structure format. For block diagram models, this variable contains all root-level blocks.

Y1,...,Yn

The outports, which can only be specified for diagram models. Here n must be the number of root-level blocks. Each outport will be returned in the Y1,...,Yn variables.

'model'

The name of a block diagram model.

Timespan

The timespan can be one of the following: TFinal, [TStart TFinal], or [TStart OutputTimes TFinal]. Output times are time points which will be returned in T, but in general T will include additional time points.

Options

Optional simulation parameters created in a structure by the simset command using name-value pairs.

UT

Optional external inputs. For supported expressions, see Enable Data Import.

Simulink only requires the first parameter. Simulink takes all defaults from the block diagram, including unspecified options. If you specify any optional arguments, your specified settings override the settings in the block diagram.

Specifying the right-hand side argument of sim as the empty matrix, [ ], causes Simulink to use the default for the argument.

To specify the single-output format for sim('model', Timespan, Options, UT), set the 'ReturnWorkspaceOutputs' option of the options structure to 'on'.

See also simset and simget.

Was this topic helpful?