Documentation

About Rapid Simulation Data Setup

The format and setup of input data for a rapid simulation depends on your requirements.

The RSim target requires that MAT-files used as input for From File and Inport blocks contain data. The grt target inserts MAT-file data directly into the generated code, which is then compiled and linked as an executable. In contrast, RSim allows you to replace data sets for each successive simulation. A MAT-file containing From File or Inport block data must be present if a From File block or Inport block exists in your model.

Create a MAT-File That Includes a Model Parameter Structure

To create a MAT-file that includes a model global parameter structure (model_P),

If you want to run simulations over varying data sets, consider converting the parameter structure to a cell array and saving the parameter variations to a single MAT-file.

Get the Parameter Structure for a Model.  Get the global parameter structure (model_P) for a model by calling the function rsimgetrtp.

param_struct = rsimgetrtp('model')

The rsimgetrtp function forces an update diagram action for the specified model and returns a structure that contains the following fields.

The parameter structure contains the following information.

The code generator reports a tunable fixed-point parameter according to its stored value. For example, an sfix(16) parameter value of 1.4 with a scaling of 2^-8 has a value of 358 as an int16.

In the following example, rsimgetrtp returns the parameter structure for the example model rtwdemo_rsimtf to param_struct.

param_struct = rsimgetrtp('rtwdemo_rsimtf')

param_struct = 

    modelChecksum: [1.7165e+009 3.0726e+009 2.6061e+009 2.3064e+009]
       parameters: [1x1 struct]

Save the Parameter Structure to a MAT-File.  After you issue a call to rsimgetrtp, save the return value of the function call to a MAT-file. Using a command-line option, you can then specify that MAT-file as input for rapid simulations.

The following example saves the parameter structure returned for rtwdemo_rsimtf to the MAT-file myrsimdemo.mat.

save myrsimdemo.mat param_struct;

For information on using command-line options to specify required files, see Run Rapid Simulations.

Convert the Parameter Structure for Running Simulations on Varying Data Sets.  To use rapid simulations to test changes to specific parameters, you can convert the model parameter structure to a cell array. You can then access a specific parameter set by using the @ operator to specify the index for a specific parameter set in the file.

To convert the structure to a cell array:

Alternatively, you can modify the block parameters in the model, and use rsimgetrtp to create multiple parameter sets:

For more information on how to specify each parameter set when you run the simulations, see Change Block Parameters for an RSim Simulation.

Create a MAT-File for a From File Block

You can use a MAT-file as the input data source for a From File block. The format of the data in the MAT-file must match the data format expected by that block. For example, if you are using a matrix as an input for the MAT file, this cannot be different from the matrix size for the executable.

To create a MAT-file for a From File block:

Create a MAT-File for an Inport Block

You can use a MAT-file as the input data source for an Inport block.

The format of the data in the MAT-file must adhere to one of the three column-based formats listed in the following table. The table lists the formats in order from least flexible to most flexible.

The supported formats and the following procedure are illustrated in rtwdemo_rsim_i.

To create a MAT-file for an Inport block:

Rapid Simulations

Using the RSim target, you can build a model once and run multiple simulations to study effects of varying parameter settings and input signals. You can run a simulation directly from your operating system command line, redirect the command from the MATLAB command line by using the bang (!) character, or execute commands from a script.

From the operating system command line, use

rtwdemo_rsimtf

From the MATLAB command line, use

!rtwdemo_rsimtf

The following table lists ways you can use RSim target command-line options to control a simulation.

The following sections use the rtwdemo_rsimtf example model in examples to illustrate some of these command-line options. In each case, the example assumes you have already done the following:

Requirements for Running Rapid Simulations

The following requirements apply to both fixed and variable step executables.

Set a Clock Time Limit for a Rapid Simulation

If a model experiences frequent zero crossings and the model's minor step size is small, consider setting a time limit for a rapid simulation. To set a time limit, specify the -L option with a positive integer value. The simulation aborts after running for the specified amount of clock time (not simulation time). For example,

  !rtwdemo_rsimtf -L 20

Based on your clock, after the executable runs for 20 seconds, the program terminates. You see a message similar to one of the following:

You do not need to do anything to your model or to its configuration to use this option.

Override a Model Simulation Stop Time

By default, a rapid simulation runs until the simulation time reaches the time specified the Configuration Parameters dialog box, on the Solver pane. You can override the model simulation stop time by using the -tf option. For example, the following simulation runs until the time reaches 6.0 seconds.

!rtwdemo_rsimtf -tf 6.0

The RSim target stops and logs output data using MAT-file data logging rules.

If the model includes a From File block, the end of the simulation is regulated by the stop time setting specified in the Configuration Parameters dialog box, on the Solver pane, or with the RSim target option -tf. The values in the block's time vector are ignored. However, if the simulation time exceeds the endpoints of the time and signal matrix (if the final time is greater than the final time value of the data matrix), the signal data is extrapolated to the final time value.

Read the Parameter Vector into a Rapid Simulation

To read the model parameter vector into a rapid simulation, you must first create a MAT-file that includes the parameter structure as described in Create a MAT-File That Includes a Model Parameter Structure. You can then specify the MAT-file in the command line with the -p option.

For example:

Specify New Signal Data File for a From File Block

If your model's input data source is a From File block, you can feed the block with input data during simulation from a single MAT-file or you can change the MAT-file from one simulation to the next. Each MAT-file must adhere to the format described in Create a MAT-File for a From File Block.

To change the MAT-file after an initial simulation, you specify the executable with the -f option and an oldfile.mat=newfile.mat parameter, as shown in the following example.

From File blocks require input data of type double. If you need to import signal data of a data type other than double, use an Inport block (see Create a MAT-File for an Inport Block) or a From Workspace block with the data specified as a structure.

Workspace data must be in the format:

variable.time
variable.signals.values

If you have more than one signal, use the following format:

variable.time
variable.signals(1).values
variable.signals(2).values

Specify Signal Data File for an Inport Block

If your model's input data source is an Inport block, you can feed the block with input data during simulation from a single MAT-file or you can change the MAT-file from one simulation to the next. Each MAT-file must adhere to one of the three formats described in Create a MAT-File for an Inport Block.

To specify the MAT-file after a simulation, you specify the executable with the -i option and the name of the MAT-file that contains the input data. For example:

Change Block Parameters for an RSim Simulation

As described in Create a MAT-File That Includes a Model Parameter Structure, after you alter one or more parameters in a Simulink block diagram, you can extract the parameter vector, model_P, for the entire model. You can then save the parameter vector, along with a model checksum, to a MAT-file. This MAT-file can be read directly by the standalone RSim executable, allowing you to replace the entire parameter vector or individual parameter values, for running studies of variations of parameter values representing coefficients, new data for input signals, and so on.

RSim can read the MAT-file and replace the entire model_P structure whenever you change one or more parameters, without recompiling the entire model.

For example, assume that you changed one or more parameters in your model, generated the new model_P vector, and saved model_P to a new MAT-file called mymatfile.mat. To run the same rtwdemo_rsimtf model and use these new parameter values, use the -p option, as shown in the following example:

!rtwdemo_rsimtf -p mymatfile.mat
load rtwdemo_rsimtf 
plot(rt_yout)

If you have converted the parameter structure to a cell array for running simulations on varying data sets, as described in Convert the Parameter Structure for Running Simulations on Varying Data Sets, you must add an @n suffix to the MAT-file specification. n is the element of the cell array that contains the specific input that you want to use for the simulation.

The following example converts param_struct to a cell array, changes parameter values, saves the changes to MAT-file mymatfile.mat, and then runs the executable using the parameter values in the second element of the cell array as input.

param_struct = rsimgetrtp('rtwdemo_rsimtf');
param_struct = rsimsetrtpparam(param_struct,2);
param_struct.parameters{1}

ans = 

       dataTypeName: 'double'
         dataTypeId: 0
            complex: 0
         dtTransIdx: 0
             values: [-140 -4900 0 4900]
                map: []
    structParamInfo: []

param_struct.parameters{2}.values=[-150 -5000 0 4950];
save mymatfile.mat param_struct;
!rtwdemo_rsimtf -p mymatfile.mat@2 -o rsim2.mat

Specify a New Output File Name for a Simulation

If you have specified one or more of the Save to Workspace parameters — Time, States, Outputs, or Final States — in the Configuration Parameters dialog box, on the Data Import/Export pane, the default is to save simulation logging results to the file model.mat. For example, the example model rtwdemo_rsimtf normally saves data to rtwdemo_rsimtf.mat, as follows:

!rtwdemo_rsimtf
created rtwdemo_rsimtf.mat

You can specify a new output file name for data logging by using the -o option when you run an executable.

!rtwdemo_rsimtf -o rsim1.mat

In this case, the set of parameters provided at the time of code generation, including From File block data parameters, is run.

Specify New Output File Names for To File Blocks

In much the same way as you can specify a new system output file name, you can also provide new output file names for data saved from one or more To File blocks. To do this, specify the original file name at the time of code generation with a new name, as shown in the following example:

!rtwdemo_rsimtf -t rtwdemo_rsimtf_data.mat=mynewrsimdata.mat

In this case, assume that the original model wrote data to the output file rtwdemo_rsimtf_data.mat. Specifying a new file name forces RSim to write to the file mynewrsimdata.mat. With this technique, you can avoid overwriting an existing simulation run.