Run Co-Simulation Components on Multiple Cores

Simulink^® supports co-simulation between components using local solvers or that involves simulation tools. For example, co-simulation can involve an S-function implemented as a co-simulation gateway between Simulink and third-party tools or custom code. It can also involve an FMU in co-simulation mode imported to Simulink.

To improve performance, consider running models that contain co-simulation blocks (components) on multiple threads if:

You are integrating multiple co-simulation components
Integration at the component level is computationally intense

This topic assumes that you are familiar with multithreaded programming and concepts.

Simulink lets you run C MEX S-functions and Co-Simulation FMU blocks on multiple threads if they satisfy these requirements:

The block is nondirect feedthrough.
The block is threadsafe, that is, the block can work with multiple threads accessing shared data, resources, and objects without any conflicts.

Note

Multithreaded co-simulation for Level-2 MATLAB S-Function blocks is not supported.

By default, Simulink configures all models to run on multiple threads. However, not all models have co-simulation components that can run on multiple threads, and not all models benefit from running on multiple threads. To see if a model has co-simulation components that can benefit from running on multiple threads, follow these steps:

Open your model.
Start the Performance Advisor tool (on the Debug tab, click Performance Advisor).
Select Simulation > Checks that Require Simulation to Run > Select multi-thread co-simulation setting on or off.
This check verifies that the model or block is optimally configured to take advantage of multithreaded or singlethreaded processing. If the configuration is not optimal, Performance Advisor shows the current setting and warns you that the model is not a good candidate to run on multiple threads.
Run the selected check.

Alternatively, you can manually measure the simulation of the model before and after changing the MultithreadedSim parameter. For example:

tic; sim('sfunction_components'); toc

Elapsed time is 2.323264 seconds.

get_param(gcs,'MultithreadedSim')

ans =
 'on'

set_param(gcs,'MultithreadedSim','off')

tic; sim('sfunction_components'); toc

Elapsed time is 4.112674 seconds.

For an example of running co-simulation components on multiple cores, see the slexCoSimPrimeExample model.

Using the `MultithreadedSim` Parameter

You can specify that an entire model run on multiple threads, or specify that particular blocks run on multiple threads, using the MultithreadedSim parameter. Specify that an entire model run on multiple threads if all the co-simulation blocks in the model are nondirect feedthrough and threadsafe. If some, but not all blocks, are nondirect feedthrough and threadsafe, identify only those blocks to run on multiple threads. The model and blocks use the MultithreadedSim parameter as follows.

Setting	Model	Block	Description
`'on'`			(Default) Model can run on multiple threads.
`'off'`			Disable the block or model from running on multiple threads.
`'auto'`			(Default) Let Simulink decide if the block can run on multiple threads.

Enabling the MultithreadedSim parameter does not mean that the block or model simulates on multiple threads. Simulation on multiple threads occurs when MultithreadedSim is enabled and:

The block and/or model operate at a single rate.
The block and/or model are threadsafe. (For example, they do not use static or global data).
The block and/or model are nondirect feedthrough.
- For S-function blocks, use the ssSetInputPortDirectFeedThrough function.
- For FMU blocks, leave the dependencies attribute in the FMU model description file for the FMU ModelStructure/Outputs and ModelStructure/InitialUnknowns field as empty. This attribute must be (" ").
The block and/or model is exception-free. For S-function blocks, use the ssSetOptions function to set SS_OPTION_EXCEPTION_FREE_CODE.

Multithreading does not allow solver reset checks, and therefore skips over any use of the ssSetSolverNeedsReset and ssBlockStateForSolverChangedAtMajorStep functions. Conversely, in accelerator mode, if these functions are used or there are continuous states, multithreading is automatically turned off.

Configuring S-Function Blocks to Run Single or Multithreaded

Whether an S-function block runs single or multithreaded depends on the MultithreadedSim parameter value and the ssSetRuntimeThreadSafetyCompliance function.

`MultithreadedSim` Setting	`ssSetRuntimeThreadSafetyCompliance` Setting	Single or Multithread
`'auto'`	`RUNTIME_THREAD_SAFETY_COMPLIANCE_UNKNOWN`	Single thread
`'auto'`	`RUNTIME_THREAD_SAFETY_COMPLIANCE_TRUE`	Multithread
`'auto'`	`RUNTIME_THREAD_SAFETY_COMPLIANCE_FALSE`	Single thread
`'off'`	—	The setting is ignored and the S-function block runs singlethreaded

Co-Simulation on Multiple Threads Limitations and Guidelines

The simulation runs on a single thread for accelerator and rapid accelerator modes. Multithreading is enabled when the simulation mode is normal.
Set model simulation mode to normal.
There is no code generation for co-simulation components.
When the block has these settings, it does not support co-simulation.
Multithreading is not activated for blocks with constant sample time.
Multithreading is not enabled when the Simulink debugger is on.
Turn off Simulink debugger.
A block that depends on a non-thread-safe block cannot be multithreaded. Consider breaking the dependency, for example, by using a Unit Delay block.

S-Function Block Limitations

Must have a single rate.
Consider revising your model to break down multirate components into individual single-rate components.
Multithreading is not enabled when an S-function has variable sample time.
Consider using a different sample time (see Specify Sample Time).
Multithreading is not enabled when an S-function has continuous states and solver is fixed-step, which together trigger a continuous states consistency check. To disable continuous states consistency checks, use the ssSetSkipContStatesConsistencyCheck function.
Must have no direct feedthrough ports — In ssSetInputPortDirectFeedThrough(SimStruct *S,int_T port,int_T dirFeed), dirFeed must be 0 for each input port.
Consider breaking the dependency between blocks, for example, by using a Unit Delay block.
Must be thread safe — In ssSetRuntimeThreadSafetyCompliance(SimStruct *S,int_T val), val must be RUNTIME_THREAD_SAFETY_COMPLIANCE_TRUE.
For more information, see Guidelines for Writing Thread-Safe S-Functions.
Must be exception-free — In ssSetOptions(SimStruct *S,uint_T options), options must include SS_OPTION_EXCEPTION_FREE_CODE.
For more information, see Guidelines for Writing Thread-Safe S-Functions.
Multithreading is not enabled when the S-function Analyzer is on. Try multithreading in normal mode.
Multithreading is not enabled when S-function has continuous sample time. Consider using a different sample time (see Specify Sample Time).
Multithreading concurrently runs output and update methods. The block must have an output or update method.

FMU Import Block Limitations

Must be in co-simulation mode.
Consider switching FMU mode from Model Exchange to Co-Simulation.
Must be thread-safe, for example, multiple FMUs must not access the same file at the same time.
Multithreading is not enabled when FMU block logging displays in the MATLAB^® command window. Redirect FMU block logging to a file using:
```
set_param(blockName,'FMUDebugLoggingRedirect','File')
```
Multithreading is not supported when FMU is running out-of-process. To disable this setting, use:
```
set_param(blockName,'DebugExecutionForFMUViaOutOfProcess','off')
```

Model Block Limitations

Multithreading is not enabled when a Model block has event ports.
Cannot be inside a For Each Subsystem block.
Consider moving the Model block out of the For Each Subsystem block.
Must be in accelerator mode.
Must have single rate.
Consider revising your model to break down multirate components into individual single-rate components.
Cannot use blocks with variable sample time.
Consider using a different sample time (see Specify Sample Time).
Cannot have continuous states.
Cannot have direct feedthrough on any input port.
Consider breaking the dependency between blocks, for example, by using a Unit Delay block.
Must have a fixed-step solver.
Cannot access any global data stores.
Multithreading is not enabled when a model contains a Simulink Function block.
Cannot use any Simulink functions or caller blocks.
Cannot contain To File blocks. For more information, see Export Simulation Data.
Cannot contain From File blocks.
Consider feeding data into the referenced model via an inport from the top-level model.