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);

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

For complete details of the sim command syntax, see the sim reference page. For information about the configuration parameters, see Configuration Parameters Dialog Box.

Back to Top

Examples of Implementing the sim Command

Following are examples that demonstrate 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.

mdl = 'vdp';
load_system(mdl)
simMode = get_param(mdl, 'SimulationMode');
set_param(mdl, 'SimulationMode', 'rapid')
cs = getActiveConfigSet(mdl);
mdl_cs = cs.copy;
set_param(mdl_cs,'AbsTol','1e-5',...
         'SaveState','on','StateSaveName','xoutNew',...
         'SaveOutput','on','OutputSaveName','youtNew')
simOut = sim(mdl, mdl_cs);
set_param(mdl, '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.

Back to Top

Calling sim from within parfor

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

Back to Top

Backwards Compatible Syntax

The following syntax is now obsolete but will be maintained 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 defaults.

If you do not specify any left-hand side arguments, then Simulink determines what data to log based on the workspace I/O settings of the Data Import/Export pane of the Configuration Parameters dialog box.

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.

Back to Top

About Programmatic Simulation

Using the set_param Command

Related Products & Applications

• Simulink
• Control Design
• Signal Processing & Communications
• Model-Based Design
• Physical Modeling
• Verification & Validation

Get Simulink trial software

Learn more about Simulink through this collection of videos, articles, technical literature and the Getting Started with Simulink Guide.

Get this Simulink Kit