Real-Time Workshop Rapid Simulation Target (Real-Time Workshop)

Real-Time Workshop

Running a Rapid Simulation

The rapid simulation target lets you run a simulation similar to the generic real-time (GRT) target provided by Real-Time Workshop. This simulation does not use timer interrupts, and therefore is a nonreal-time simulation environment. The difference between GRT and rsim simulations is that

rsim supports variable step solvers, and
rsim allows you to change parameter values or input signals at the start of a simulation without the need to generate code or recompile.

The GRT target, on the other hand, is a starting point for targeting a new processor.

A single build of your model can be used to study effects from varying parameters or input signals. Command line arguments provide the necessary mechanism to specify new data for your simulation. This table lists all available command line options.

Table 11-1: rsim Command Line Options
Command Line Option
Description

model -f old.mat=new.mat

Read From File block input signal data from a replacement MAT-file.

model -o newlogfile.mat
Write MAT-file logging data to a file named newlogfile.mat.

model -p filename.mat
Read a new (replacement) parameter vector from a file named filename.mat.

model -tf <stoptime>
Run the simulation until the time value <stoptime> is reached.

model -t old.mat=new.mat
The original model specified saving signals to the output file old.mat. For this run use the file new.mat for saving signal data.

model -v
Run in verbose mode.

model -h
Display a help message listing options.

**Table 11-1: rsim Command Line Options**
Command Line Option	Description
`model -f old.mat=new.mat`	Read From File block input signal data from a replacement MAT-file.
`model -o newlogfile.mat`	Write MAT-file logging data to a file named `newlogfile.mat`.
`model -p filename.mat`	Read a new (replacement) parameter vector from a file named `filename.mat`.
`model -tf <stoptime>`	Run the simulation until the time value `<stoptime>` is reached.
`model -t old.mat=new.mat`	The original model specified saving signals to the output file `old.mat`. For this run use the file `new.mat` for saving signal data.
`model -v`	Run in verbose mode.
`model -h`	Display a help message listing options.

Note On Solaris platforms, to run the rsim executable created for a model that uses variable step solvers in a seperate shell, the LD_LIBRARY_PATH environment variable is needed to indicate the path to the MATLAB installation directory, as follows:
% setenv LD_LIBRARY_PATH /apps/matlab/bin/sol2:$LD_LIBRARY_PATH

Obtaining the Parameter Structure from Your Model

To obtain a parameter structure for the current model settings you may use the rsimgetrtp function, with the following syntax:

```
rtP = rsimgetrtp(`model', options)
```

The rtP structure is designed to be used with the Rapid Simulation target. Getting it via rsimgetrtp forces an update diagram action. In addition to the current model tunable block parameter settings, the rtP structure contains a structural checksum. This checksum is used to ensure that the model structure hasn't changed since the rsim executable was generated.

Options to rsimgetrtp are passed as parameter-value pairs. Currently there is one option, AddTunableParamInfo, which has two states, on and off:

rtP = rsimgetrtp(`model',`AddTunableParamInfo','on')
rtP = rsimgetrtp(`model',`AddTunableParamInfo','on')

The AddTunableParamInfo option causes Real-Time Workshop to generate code that extract tunable parameter information from your model and places it in the return argument (rtP). This information gives you a mapping between the parameter structure and the tunable parameters.

To use the AddTunableParamInfo option, you must have selected the Inline Parameters checkbox in the Advanced pane of the Simulation Parameters dialog box. Exercising this option also creates, then deletes a model.rtw file in your current working directory.

Tunable Fixed-Point parameters are reported according to their stored value. For example, an sfix(16) parameter value of 1.4 with a scaling of 2^-8 will have a value of 358 as an int16.

Example 1. Create an rsim executable and pass a different parameter structure:

Set the Real-Time Workshop target configuration to Rapid Simulation Target using the Target File Browser
Create an rsim executable for the model by clicking the Build button or by typing rtwbuild('model').
Modify parameters in your model and save the rtP structure:

rtP = rsimgetrtp('model')
save myrtp.mat rtP

Run the generate executable with the new parameter set:

```
!model -p myrtp.mat
```

Load the results in to Matlab

```
load model.mat
```

Example 2. Create an rtP with the tunable parameter mapping information:

Create rtP with the tunable parameter information:

rtP = rsimgetrtp('model','AddTunableParamInfo','on')

The rtP structure contains:

modelChecksum: 1x4 vector that encodes the structure of the model
parameters: A structure of the tunable parameters in the model

The parameters structure contains the following member fields:

dataTypeName: The data type name, e.g., 'double'
dataTypeId: Internal data type identifier for use by Real-Time Workshop
complex: 0 if real, 1 if complex

Specifying a New Signal Data File for a From File Block

To understand how to specify new signal data for a From File block, create a working directory and connect to that directory. Open the model rsimtfdemo by typing

```
rsimtfdemo
```

at the MATLAB prompt. Type

```
w = 100;
zeta = 0.5;
```

to set parameters. rsimtfdemo requires a data file, rsim_tfdata.mat. Make a local copy of matlabroot/toolbox/rtw/rtwdemos/rsim_tfdata.mat in your working directory.

Be sure to specify rsim.tlc as the system target file and rsim_default_tmf as the template makefile. Then press the Build button on the Real-Time Workshop pane to create the rsim executable.

!rsimtfdemo
load rsimtfdemo
plot(rt_yout)

The resulting plot shows simulation results using the default input data.

Replacing Input Signal Data. New data for a From File block can be placed in a standard MATLAB MAT-file. As in Simulink, the From File block data must be stored in a matrix with the first row containing the time vector while subsequent rows contain u vectors as input signals. After generating and compiling your code, you can type the model name rsimtfdemo at a DOS prompt to run the simulation. In this case, the file rsim_tfdata.mat provides the input data for your simulation.

For the next simulation, create a new data file called newfrom.mat and use this to replace the original file (rsim_tfdat.mat) and run an rsim simulation with this new data. This is done by typing

t=[0:.001:1];
u=sin(100*t.*t);
tu=[t;u];
save newfrom.mat tu;
!rsimtfdemo -f rsim_tfdata.mat=newfrom.mat

at the MATLAB prompt. Now you can load the data and plot the new results by typing

```
load rsimtfdemo
plot(rt_yout)
```

This picture shows the resulting plot.

As a result the new data file is read and the simulation progresses to the stop time specified in the Solver page of the Simulation Parameters dialog box. It is possible to have multiple instances of From File blocks in your Simulink model.

Since rsim does not place signal data into generated code, it reduces code size and compile time for systems with large numbers of data points that originate in From File blocks. The From File block requires the time vector and signals to be data of type double. If you need to import signal data of a data type other than double, use a From Workspace block with the data specified as a structure.

The workspace data must be in the format

```
variable.time
variable.signals.values
```

If you have more than one signal, the format must be

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

Specifying a New Output Filename for the Simulation

If you have specified Save to Workspace options (that is, checked Time, States, Outputs, or Final States check boxes on the Workspace I/O page of the Simulation Parameters dialog box), the default is to save simulation logging results to the file model.mat. You can now specify a replacement filename for subsequent simulations. In the case of the model rsimtfdemo, by typing

```
!rsimtfdemo
```

at the MATLAB prompt, a simulation runs and data is normally saved to rsimtfdemo.mat.

```
!rsimtfdemo
created rsimtfdemo.mat
```

You can specify a new output filename for data logging by typing

```
!rsimtfdemo -o sim1.mat
```

In this case, the set of parameters provided at the time of code generation, including any From File block data, is run. You can combine a variety of rsim flags to provide new data, parameters, and output files to your simulation. Note that the MAT-file containing data for the From File blocks is required. This differs from the grt operation, which inserts MAT-file data directly into the generated C code that is then compiled and linked as an executable. In contrast, rsim allows you to provide new or replacement data sets for each successive simulation. A MAT-file containing From File or From Workspace data must be present, if any From File or From Workspace blocks exist in your model.

Changing Block Parameters for an rsim Simulation

Once you have altered one or more parameter in the Simulink block diagram, you can extract the parameter vector, rtP, for the entire model. The rtP vector, along with a model checksum, can then be saved to a MATLAB MAT-file. This MAT-file can be read in directly by the stand-alone rsim executable, allowing you to replace the entire parameter vector quickly, for running studies of variations of parameter values where you are adjusting model parameters or coefficients or importing new data for use as input signals.

The model checksum provides a safety check to ensure that any parameter changes are only applied to rsim models that have the same model structure. If any block is deleted, or a new block added, then when generating a new rtP vector, the new checksum will no longer match the original checksum. The rsim executable will detect this incompatibility in parameter vectors and exit to avoid returning incorrect simulation results. In this case, where model structure has changed, you must regenerate the code for the model.

The rsim target allows you to alter any model parameter, including parameters that include side-effects functions. An example of a side-effects function is a simple Gain block that includes the following parameter entry in a dialog box.

```
gain value:   2 * a
```

In general, Real-Time Workshop evaluates side-effects functions prior to generating code. The generated code for this example retains only one memory location entry, and the dependence on parameter a is no longer visible in the generated code. The rsim target overcomes the problem of handling side-effects functions by replacing the entire parameter structure, rtP. You must create this new structure by using rsimgetrtp.m. and then save it in a MAT-file. For the rsimtfdemo example, type

zeta = .2;
myrtp = rsimgetrtp('modelname');
save myparamfile myrtp;

at the MATLAB prompt.

In turn, rsim can read the MAT-file and replace the entire rtP structure whenever you need to change one or more parameters -- without recompiling the entire model.

For example, assume that you have changed one or more parameters in your model, generated the new rtP vector, and saved rtP to a new MAT-file called myparamfile.mat. In order to run the same rsimtfdemo model and use these new parameter values, execute the model by typing

!rsimtfdemo -p myparamfile.mat
load rsimtfdemo 
plot(rt_yout)

Note that the p is lower-case and represents "Parameter file."

Specifying a New Stop Time for an rsim Simulation

If a new stop time is not provided, the simulation will run until reaching the value specified in the Solver page at the time of code generation. You can specify a new stop time value as follows.

```
!rsimtfdemo -tf 6.0
```

In this case, the simulation will run until it reaches 6.0 seconds. At this point it will stop and log the data according to the MAT-file data logging rules as described above.

If your model includes From File blocks that also include a time vector in the first row of the time and signal matrix, the end of the simulation is still regulated by the original setting in the Solver page of the Simulation Parameters dialog box or from the -s option as described above. However, if the simulation time exceeds the end points of the time and signal matrix (that is, if the final time is greater than the final time value of the data matrix), then the signal data will be extrapolated out to the final time value as specified above.

Specifying New Output Filenames for To File Blocks

In much the same way as you can specify a new system output filename, you can also provide new output filenames for data saved from one or more To File blocks. This is done by specifying the original filename at the time of code generation with a new name as follows.

!mymodel -t original.mat=replacement.mat

In this case, assume that the original model wrote data to the output file called original.mat. Specifying a new filename forces rsim to write to the file replacement.mat. This technique allows you to avoid over-writing an existing simulation run.

Building for the Rapid Simulation Target Simulation Performance