3. Reactis Simulator

3.1. rsSimOpen

Start a new Reactis Simulator session.

3.1.1. Syntax

simId = rsSimOpen(modelFilename)
simId = rsSimOpen(modelFilename, rsiFilename)

3.1.2. Description

simId = rsSimOpen(modelFilename)

starts a new Simulator session without an .rsi file (even if one exists with the default name). This means model-specific settings will have default values and there are no input constraints or configuration variables.

modelFilename

The name of the model file.

simId = rsSimOpen(modelFilename,rsiFilename)

starts a new Simulator session for the given model and .rsi file.

modelFilename

The name of the model file.

rsiFilename

The name of the file containing model-specific settings.

The return value simId is a scalar integer valued double that identifies the Simulator session when calling other API functions.

3.1.3. Examples

simId = rsSimOpen('cruise.slx', 'cruise.rsi');

3.1.4. See Also

rsSimClose, rsSimRunSuite, rsSimImportSuite, rsSimExportSuite, rsSimUpdateSuite

3.2. rsSimClose

Close a Reactis Simulator session.

3.2.1. Syntax

rsSimClose(simId)

3.2.2. Description

rsSimClose(simId)

closes a Reactis Simulator session.

simId

The identifier of a Simulator session returned by rsSimOpen.

3.2.3. See Also

rsSimOpen

3.3. rsSimExportSuite

Export a test suite to different formats.

3.3.1. Syntax

rsSimExportSuite(simId, suiteId, filename)
rsSimExportSuite(simId, suiteId, filename, parameters)

3.3.2. Description

rsSimExportSuite(simId,suiteId,filename)

exports the test suite identified by suiteId using the Simulator session identified by simId. The resulting data is written to file filename. The export format is automatically determined by the file extension:

csv

Export as a CSV (comma-separated value) file

m

Export as a .m (MATLAB script) file

mat

Export as a .mat (MATLAB binary) file

rsSimExportSuite(simId,suiteId,filename,parameters)

does the same as above with extra parameters given by the string parameters, which may contain any combination of the following:

-f format

Set export format. Use this to set the export format if it cannot be determined by the extension of your file name. Possible values are: csv, m, mat.

-w

Export to From Workspace block format. Use this in conjunction with mat format to export data that can be used in From Workspace blocks.

-C

When exporting to CSV format, specify this option to strip the leading ‘|’ character from configuration variable names.

-c

When exporting to CSV format, specify this option to omit test steps where no exported item (except simulation time) has changed from the previous step.

-s

When exporting to CSV format, specify this option to store the elements of vectors, matrices, and buses in separate columns.

-S

When exporting to CSV format, specify this option to store each test in a separate file.

-d N

When exporting to CSV format, specify this option to control the number of significant digits for floating-point values (e.g., -d 12 sets the number of significant digits to twelve).

-T tests

Use this option to select which tests are exported. The argument to this option is a comma-separated list of test numbers without any whitespace, e.g., ‘-T 1,3,4’ selects tests 1, 3, and 4 for export.

-F opts

Use this to enable miscellaneous export options. The argument to -F is a comma-separated list of names without whitespace.

When the export format is M, the following options are supported:

fixpoint

Export fixpoint values as fixpoint (‘fi’) objects. If absent, fixpoint values are exported as double values.

enum

Export enumerated values as enumeration objects. If absent, enumerated values are exported as integer values.

timeseries

Export test data as timeseries.

struct

Export test data as structures with time.

When the export format is MAT, the following are supported:

timeseries

Export test data as timeseries.

struct

Export test data as structures with time.

When the export format is CSV, the following are supported:

enum

Export enumerated values as enumeration names. If absent, enumerated values are exported as integer values.

boolAsInt

Export Boolean values as integer values. If absent, Boolean values are exported as double values.

fixAsInt

Export fixed-point values as stored integers. If absent, fixed-point values are exported as real-world values.

floatAsInt

Export floating-point values as hexadecimal integers that encode values in the IEEE 754 floating-point format. A single-precision value is a 32-bit integer with the prefix ‘0fx’. A double-precision value is a 64-bit integer with the prefix ‘0dx’. If absent, floating-point values are exported as real-world values.

indexBase0/indexBase1

If option -s is used to store the elements of vectors, matrices, and buses in separate columns, there is an option for export indices: 0-based (using indexBase0), 1-based (using indexBase1), or legacy (default, no argument needed). Legacy is available to be used for csv files created prior to the V2023.2 version, where Reactis used 0-based indexing for arrays (i.e. arrays of buses or array configuration variables) and 1-based indexing for non-bus vectors/matrices on input or output ports.

rsiRevision

Include the current revision of the .rsi file in a separate column.

testName

Export test name in a column with the header REACTIS_TEST_NAME.

testName=name

Export test name in a column with the header name.

tpHeaderName

Export test point column headers as names.

tpHeaderLocation

Export test point column headers as locations.

tpHeaderLegacy

Export test point column headers in legacy format.

3.3.3. Examples

rsSimExportSuite(rsim, suite, 'test.mat');

Exports to MAT format (determined by the .mat extension)

rsSimExportSuite(rsim, suite, 'test.xyz', '-f csv -c');

Exports to CSV format (determined by -f parameter) and compresses the file by omitting lines with no change.

3.3.4. See Also

rsSimOpen, rsSuiteOpen, rsSimImportSuite

3.4. rsSimImportSuite

Import test data to a Reactis test suite.

3.4.1. Syntax

suiteId = rsSimImportSuite(simId, filename)
suiteId = rsSimImportSuite(simId, filename, parameters)

3.4.2. Description

suiteId = rsSimImportSuite(simId,filename)

imports test data from the file named filename into a Reactis test suite. The return value suiteId is a test suite identifier (same as returned by rsSuiteOpen) that can be used to save the test suite by calling rsSuiteSave. The import format is automatically determined by the file name extension:

csv

Import a CSV (comma-separated value) file.

rst

Import a RST (Reactis test suite) file.

suiteId = rsSimImportSuite(simId,filename,parameters)

does the same as above with extra parameters given by the string parameters, which may contain any combination of the following:

-f format

Set import format. Use this to set the import format if it cannot be determined by the file extension. Possible values are: csv, rst.

-c

When importing CSV format, include this flag to automatically insert missing steps in the test data. If this flag is not given, the time values in the CSV file must match up exactly with the time steps in the model.

-s

When importing CSV format, specify this option if the elements of vectors, matrices, and buses are stored in separate columns.

-M

Check whether test suite matches model before import. Proceed with import only if the suite matches, otherwise produce an error. If this option is not given and one or more model input/outputs are not present in the test suite, then Reactis will substitute random values for any missing items in the imported data. Reactis can be instructed to use zero values for missing items by specifying the “unassigned=zero” option (see -F parameter below).

-S N

Specify this option to use configuration variable set number N during import. The configuration variable sets are enumerated starting at zero.

-F opts

Use this to enable miscellaneous import options. The argument to -F is a comma-separated list of names without whitespace.

unassigned=zero

If an input or output is not present in the imported data then use zero for the missing item. If this option is not given then Reactis will generated random values for missing items.

When the import format is CSV, the following are supported:

testName

Import test name in a column with the header REACTIS_TEST_NAME.

testName=name

Import test name in a column with the header name.

indexBase0/indexBase1

The options for import indices are 0-based (using indexBase0), 1-based (using indexBase1), or legacy (default, no argument needed). Legacy is available to be used for csv files created prior to the V2023.2 version, where Reactis used 0-based indexing for arrays (i.e. arrays of buses or array configuration variables) and 1-based indexing for non-bus vectors/matrices on input or output ports.

An error is raised if the import fails for any reason.

suiteId is a scalar integer valued double that identifies the test suite when calling other API functions (e.g. rsSimRunSuite).

3.4.3. Examples

suite = rsSimImportSuite(rsim, 'test.csv')

Imports CSV file ‘test.csv’ (CSV format determined by file extension)

suite = rsSimImportSuite(rsim, 'test.xyz', '-f csv')

Imports CSV file ‘test.xyz’ (CSV format determined by extra ‘-f’ parameter).

3.4.4. See Also

rsSimOpen, rsSuiteSave, rsSuiteClose, rsSimImportSuites, rsSimExportSuite

3.5. rsSimImportSuites

Import multiple files into a single Reactis test suite.

3.5.1. Syntax

suiteId = rsSimImportSuites(simId, filenames)

3.5.2. Description

suiteId = rsSimImportSuites(simId,filenames)

imports the set of test data files listed in filenames into a single Reactis test suite.

simId

The identifier of a Simulator session returned by rsSimOpen.

filenames

A cell array of strings containing the names of the test data files to import. The import format is automatically determined from the extension of each file name:

csv

Import a comma-separated value file.

rst

Import a Reactis test suite file. It may be necessary to import an .rst file (rather than open it) if the inputs, outputs, test points or configuration variables in the test suite do not match the model it is being imported for.

The return value suiteId is a unique number which identifies the test suite file when calling other API functions (e.g. rsSimRunSuite).

3.5.3. Examples

simId = rsSimOpen('cruise.slx', 'cruise.rsi');
ts    = rsSimImportSuites(simId, {'cruise_ts1.csv','cruise_ts2.csv'});

3.5.4. See Also

rsSimOpen, rsSuiteSave, rsSuiteClose, rsSimImportSuite, rsSimExportSuite

3.6. rsSimRunSuite

Run a test suite in a Reactis Simulator session.

3.6.1. Syntax

rsSimRunSuite(simId, suiteId)
rsSimRunSuite(simId, suiteId, reportFilename)
rsSimRunSuite(simId, suiteId, reportFilename, reportConfig)

3.6.2. Description

rsSimRunSuite(simId,suiteId)

runs a test suite. An error is raised if a simulation error occurs.

simId

The identifier of a Simulator session returned by rsSimOpen.

suiteId

The identifier of a test suite returned by rsSuiteOpen, rsSimImportSuite, rsSimImportSuites, or rsTesterGetSuite.

rsSimRunSuite(simId,suiteId,reportFilename)

runs a test suite and writes an HTML report. If a simulation error occurs, no error is raised, but all simulation errors are recorded in the generated report.

simId

The identifier of a Simulator session returned by rsSimOpen.

suiteId

The identifier of a test suite returned by rsSuiteOpen, rsSimImportSuite, rsSimImportSuites, or rsTesterGetSuite.

reportFilename

The name of the file to which the HTML report will be written.

rsSimRunSuite(simId,suiteId,reportFilename,reportConfig)

runs a test suite and writes an HTML report with customized contents. If a simulation error occurs, no error is raised, but all simulation errors are recorded in the generated report.

simId

The identifier of a Simulator session returned by rsSimOpen.

suiteId

The identifier of a test suite returned by rsSuiteOpen, rsSimImportSuite, rsSimImportSuites, or rsTesterGetSuite.

reportFilename

The name of the file to which the HTML report will be written.

reportConfig

A report configuration which was created by rsReportConfig.

After running a test suite, coverage information may be obtained by calling rsGetCoverageMetrics.

3.6.3. Examples

simId   = rsSimOpen('cruise.slx', 'cruise.rsi');
suiteId = rsSuiteOpen('cruise.rst');
rsSimRunSuite(simId, suiteId);

3.6.4. See Also

rsSimOpen, rsSuiteOpen, rsReportConfig, rsGetCoverageMetrics

3.7. rsSimUpdateOutputs

Update output and test point values in a test suite.

3.7.1. Syntax

rsSimUpdateOutputs(simId, suiteId, filename)

3.7.2. Description

This function is deprecated and may be removed in future versions of the API. Please use rsSimUpdateSuite instead.

rsSimUpdateOutputs(simId, suiteId, resultFilename)

runs a test suite and updates the test suite’s test point and output values to the values computed by the model.

simId

The identifier of a Simulator session returned by rsSimOpen.

suiteId

The identifier of a test suite returned by rsSuiteOpen, rsSimImportSuite, rsSimImportSuites, or rsTesterGetSuite.

resultFilename

The name of the file which will contain the test suite with updated outputs. This file name must be different from the name of the input test suite.

3.7.3. See Also

rsSimUpdateSuite

3.8. rsSimUpdateSuite

Update values in a test suite.

3.8.1. Syntax

rsSimUpdateSuite(simId, suiteId, resultFilename, parameters)

3.8.2. Description

rsSimUpdateSuite(simId, suiteId, resultFilename, params)

runs a test suite and updates the test suite’s data according to the flags given in the params string and the values computed by the model.

rsSimUpdateSuite(simId, suiteId, resultFilename)

runs a test suite and updates the test suite’s input values, configuration variables, test points and output values to the values computed by the model. Synonymous to: rsSimUpdateSuite(simId, suiteId, resultFilename, ‘-I -C -P -O’).

Arguments:

simId

The identifier of a Simulator session returned by rsSimOpen.

suiteId

The identifier of a test suite returned by rsSuiteOpen, rsSimImportSuite, rsSimImportSuites, or rsTesterGetSuite.

resultFilename

The name of the file which will contain the updated test suite. This file name must be different from the name of the input test suite.

params

String containing additional parameters for the update function. Use any combination of the following flags to specify which items in the test suite should be updated. Defaults to “-I -C -P -O” of not given.

-I

Adapt harness input port values to match constraints.

-S

Update inputs controlled by virtual sources.

-C

Adapt configuration variable values to match constraints.

-P

Update test points with values computed by model.

-O

Update outputs with values computed by model.

This function is especially helpful after importing test data which includes input data, but no output data.

3.8.3. Examples

simId   = rsSimOpen('cruise.slx', 'cruise.rsi');
suiteId = rsSuiteOpen('cruise.rst');
rsSimUpdateSuite(simId, suiteId, 'cruise_new.rst');

Creates a new test suite cruise_new.rst with updated data:

Input values and configuration variable values are identical to those from cruise.rst except for cases where values conflict with the constraints given in cruise.rsi. If there is a conflict then the input/configuration value will be adjusted (saturated) to comply with the constraint.

Test point and output values match what the cruise.slx model produces when running a simulation with the input data.

3.8.4. See Also

rsSimOpen, rsSuiteOpen, rsSimImportSuite, rsSimImportSuites, rsTesterGetSuite

3.9. rsSimExportCCoverageDetails

Export extended C coverage data to CSV format.

3.9.1. Syntax

rsSimExportCCoverageDetails(simId,coverageFile)
rsSimExportCCoverageDetails(simId,coverageFile,macroFile)

3.9.2. Description

rsSimExportCCoverageDetails(simId,coverageFile)

exports detailed information information about C code coverage.

simId

The identifier of a Simulator session returned by rsSimOpen.

coverageFile

The name of the file to which the coverage data will be written.

rsSimExportCCoverageDetails(simId,coverageFile,macroFile)

exports detailed information information about C code coverage and additional information about C macros.

simId

The identifier of a Simulator session returned by rsSimOpen.

coverageFile

The name of the file to which the coverage data will be written.

macroFile

The name of the file to which the macro data will be written.

The format of the generated CSV files is documented in the C Coverage Export Details section of the API documentation.

3.9.3. See Also

C Coverage Export Details, rsSimOpen