Accelerator Cache and Rebuilds – Everything you need to know

Posted by Guy Rouleau, October 18, 2023

73 views (last 30 days) | 0 Likes | 7 comments

In Simulink, the different simulation modes (accelerators) can save you a lot of time. There are, however, subtleties to what “time” you can save, and how we can achieve those savings. In this post, I will explain most of the cases you can encounter, and hopefully shed light on what simulation modes and options best align with your needs. 

First, let me introduce the way I think about the main phases that take time when simulating a model involving any of the accelerator modes:

If you start from scratch, without any existing cache, Simulink will do all 3 of those phases. However once you simulate the model, a Simulink Cache file gets created and can be reused for subsequent simulations.

On the above timeline, what I spend the most time explaining is the multiple subtleties that can cause the Checksum Analysis and Accelerator Target Generation to happen or not. I will try to summarize that here. 

There are differences for the three accelerator targets:

Top level Accelerator mode
Rapid Accelerator mode
Referenced models Accelerator mode

Let's look at each of them on by one.

Top Level Accelerator mode

As described here, in most cases, Accelerator mode uses Just-in-Time (JIT) acceleration to generate an execution engine in memory.

Let's take a simple model and simulate it in Accelerator mode with verbose build enabled.

mdl = 'vdp';

in = Simulink.SimulationInput(mdl);

in = setModelParameter(in,'SimulationMode','Accelerator');

in = setModelParameter(in,'AccelVerboseBuild','on');

out = sim(in);

If this is the first time you are simulating the model in a MATLAB session, 3 things can happen:

1 - No Cache Available

If no cache is available or if the model has changed structurally since the last time the cache file was generated, Simulink will perform the checksum analysis and generate the accelerator target. Artifacts will be stored in the cache file to be reused in subsequent simulations.

From the verbose build, you will see the following:

2 - Cache is available

If a cache is available and the model has not changed structurally since the cache was built, Simulink will extract information that will make the generation of the execution engine faster. Verbose build will display the following:

3 - Subsequent Runs

After simulating the model once, the accelerator mode execution engine will remain in memory. If the model has not changed structurally, nothing will be displayed in the verbose log.

In this case, for Accelerator mode, our timeline is reduced to those two phases:

Fast Restart

In the previous cases, Simulink had to analyze the model to detect if the accelerator execution engine needed to be rebuilt or not due to structural changes. For large models, this operation can take a non-negligible amount of time.

If you know that you will simulate the model multiple times without making structural changes, I recommend enabling Fast Restart.

With Fast Restart, after simulating, the model will remain in a compiled state, making editing impossible between runs. This reduces the initialization time (time spent in the first two phases) to practically zero. This reduces our timeline to only the execution phase:

Rapid Accelerator

Rapid Accelerator works differently. As described here, Rapid Accelerator generates a standalone executable:

Let’s go through the 3 possible scenarios and what happens in each: 

1 - No cache available, or cache is out of date

In Rapid Accelerator, a Build Summary is displayed, either in the Diagnostics Viewer if simulated using the play button, or at the MATLAB command prompt if using the sim command.

mdl = 'vdp';

in = Simulink.SimulationInput(mdl);

in = setModelParameter(in,'SimulationMode','Rapid');

out = sim(in);

If no cache exists, the build summary will say:

If a cache file exists but is out of date, the build summary will include the reason why it rebuilds:

In this case, Simulink went through the entire timeline.

2 - Cache is available

If a cache file exists and no structural changes have happened to the model sine the cache was built, you will see:

In this case, our timeline is:

3 - RapidAcceleratorUpToDateCheck

For Accelerator mode, I recommended using Fast Restart to skip the checksum analysis phase that decides if the accelerator target needs to be rebuilt. Fast Restart is not supported in Rapid Accelerator, but there is something you can do to skip the checksum analysis phase in this mode. For that, you can pass the option RapidAcceleratorUpToDateCheck to the sim command:

mdl = 'vdp';

in = Simulink.SimulationInput(mdl);

in = setModelParameter(in,'SimulationMode','Rapid');

in = setModelParameter(in,'RapidAcceleratorUpToDateCheck','off');

out = sim(in);

With this option, there is no build summary, because it is 100% sure that there will be no build.

One important difference compared to Accelerator mode with Fast Restart is that the RapidAcceleratorUpToDateCheck option can be used for the first simulation in a MATLAB session if a cache file is available. 

Coming back to our timeline, this option performs the execution phase only.

Referenced Model in Accelerator Mode

A referenced model in Accelerator mode is different than the two use cases above. First, the simulation mode is controlled from the Model block dialog or Property Inspector:

If you choose Accelerator mode, C code is being generated for the referenced model and compiled as a MEX-file. This offers a finer grain control when it comes to rebuild options.

If you look at the Model Referencing section of the Configuration set, you will see 4 options:

To learn more about those options, I recommend looking at this documentation page. Specifically, this diagram:

Here is how I interpret this diagram and the 4 rebuild options:

Always: This one is straightforward. Every time you simulate the model, Simulink ignores the cache, regenerate the accelerator target code and builds it. This is the most time consuming, and you get the full timeline:

If changes detected: This option is the safest way to avoid unnecessary rebuilds. Simulink will do a checksum analysis every time you simulate the model and regenerate code if a structural change is detected.

If changes in known dependencies detected: This option is usually the best tradeoff between safety and performance. Simulink will first look at the timestamp of the model and known dependencies and if they have not changed since the cache was built, the cache will be used. If Simulink detects that the model or known dependencies have a timestamp more recent that the cache, then a checksum analysis is triggered to determine if code needs to be regenerated. If a structural change is detected, code will be generated and rebuilt. The downside of this option is that some dependencies might be unknown, see the known dependencies documentation for more details on that. If the model has not changed structurally, our timeline can be one of those two. I describe below how to determine which one is happening for your model.

Never: This option is similar in nature to the RapidAcceleratorUpToDateCheck option for Rapid Accelerator mode. Simulink will close its eyes and blindly use the cache. This option comes with a diagnostic to detect if the cache should have been rebuilt. Setting this diagnostic to "None" is what will give you the fastest performance. Here is a screenshot:

Configured that way, we get the fastest timeline:

I have to admit, the command-line equivalents of the rebuild options are quite different sounding than the graphical version. To help with that, here is a table:

To get a clear understanding of what happened, I recommend enabling the accelerator verbose build. 

mdl = 'sldemo_mdlref_basic';

in = Simulink.SimulationInput(mdl);

in = setModelParameter(in,'UpdateModelReferenceTargets','IfOutOfDate');

in = setModelParameter(in,'AccelVerboseBuild','on');

out = sim(in);

In this case, I am using "If changes in known dependencies detected" and I have a cache file available. However, I made a minor non-structural change to the referenced model. The build log tells us that it checks for structural change, does not find any and consequently does not regenerate code. 

If I rerun the same code, but this time without any modification to the referenced model, the check for structural changes is skipped, which can speed up the initialization significantly:

Now it's your turn

Hopefully the above information will help you getting the best performance out of your simulations involving accelerator modes. Let us know in the comments below how you are leveraging those options. 

If your model is triggering checksum analysis and rebuilds more often than you think it should, reach out to technical support and we can help you with that.