A simulation target, or SIM target, is a MEX-file that implements a referenced model that executes in accelerator mode. Simulink® invokes the simulation target as needed during simulation to compute the behavior and outputs of the referenced model. Simulink uses the same simulation target for all accelerator mode instances of a given referenced model anywhere in a reference hierarchy.
If you have a Simulink Coder™ license, be careful not to confuse the simulation target of a referenced model with any of these other types of target:
Hardware target — A platform for which Simulink Coder generates code
System target — A file that tells Simulink Coder how to generate code for particular purpose
Rapid Simulation target (RSim) — A system target file supplied with Simulink Coder
Model reference target — A library module that contains Simulink Coder code for a referenced model
Simulink creates a simulation target only for a referenced model that has one or more accelerator mode instances in a reference hierarchy. A referenced model that executes only in normal mode always executes interpretively and does not use a simulation target. When one or more instances of a referenced model executes in normal mode, and one or more instances executes in accelerator mode:
Simulink creates a simulation target for the accelerator mode instances.
The normal mode instances do not use that simulation target.
Because accelerator mode requires code generation, it imposes some requirements and limitations that do not apply to normal mode. Aside from these constraints, you can generally ignore simulation targets and their details when you execute a referenced model in accelerator mode. For details, see Choose Simulation Modes for Model Hierarchies.
Simulink by default generates the needed target from the referenced model:
If a simulation target does not exist at the beginning of a simulation
When you perform an update diagram for a parent model
If the simulation target exists, then by default Simulink checks whether the referenced model has structural changes since the target was last generated. If so, Simulink regenerates the target to reflect changes in the model. For details about how Simulink detects whether to rebuild a model reference target, see the Rebuild parameter documentation.
You can change this default behavior to modify the rebuild criteria or specify that Simulink always or never rebuilds targets. See Rebuild for details.
To generate simulation targets interactively for accelerator mode referenced models, do one of these steps:
Update the diagram on a model that directly or indirectly references the model that is in accelerator mode
Execute the slbuild
command with appropriate
arguments at the MATLAB® command line
While generating a simulation target, Simulink displays status messages at the MATLAB command line to enable you to monitor the target generation process. Target generation entails generating and compiling code and linking the compiled target code with compiled code from standard code libraries to create an executable file.
You can reduce the time that Simulink spends checking whether any or all simulation targets require rebuilding by setting configuration parameter values as follows:
In all referenced models throughout the hierarchy, set the Signal
resolution configuration parameter to Explicit
only
or None
. (See Signal resolution.)
To minimize change detection time, consider setting the Rebuild
options configuration parameter to If any changes in
known dependencies detected
on the top model. See Rebuild.
These parameter values exist in the configuration set of a referenced model, not in the individual Model block. Setting either value for any instance of a referenced model sets it for all instances of that model.
To use custom C code with Stateflow® or with MATLAB Function blocks when building a model reference simulation target, use the Include custom code for referenced models configuration parameter.
Using custom C code for referenced models in accelerator mode can produce different results than when you simulate the model without using the custom code. If the custom code includes declarations of structures for buses or enumerations, the simulation target generation fails if the build results in duplicate declarations of those structures. Also, if custom code uses a structure representing a bus or enumeration, you can get unexpected simulation results.
Simulink creates simulation targets in the slprj
subfolder of
the working folder. If slprj
does not exist, Simulink creates it.
Simulink Coder code generation also uses the slprj
folder.
Subfolders in slprj
provide separate places for simulation code,
Simulink
Coder code, and other files. For details, see Manage Build Process Folders (Simulink Coder).
By default, files generated by Simulink diagram updates and model builds are placed in a build folder, the root of
which is the current working folder (pwd
). You can place generated
files in a root folder outside the current working folder. This option allows you
to:
Store generated files separate from the models and other source materials used to generate them.
Reuse or share previously built simulation targets without having to set the current working folder back to a previous working folder.
You can separate generated simulation artifacts from generated production code.
To control the output locations for files generated by diagram updates and model builds, specify the build folder for these files separately. The simulation cache folder is the root folder in which to place artifacts used for simulation.
To specify the simulation cache folder, use one of these approaches:
Use the CacheFolder
MATLAB session parameter.
In the Simulink Preferences > General dialog box, use the Simulation cache folder preference. This preference provides the initial defaults for the MATLAB session parameters.
To control the output location for files generated by Simulink diagram updates, in the Simulink Preferences > General dialog box, use the Simulation cache folder preference. To specify the root folder location for files generated by Simulink diagram updates, set the preference value by entering or browsing to a folder path, for example:
The folder path that you specify provides the initial default for the MATLAB session parameter CacheFolder
. When you initiate a
Simulink diagram update, generated files are placed in a build folder at the
root location specified by CacheFolder
, rather than in the current
working folder (pwd
).
For example, using a 32-bit (Windows trademark) host platform, if you set the
Simulation cache folder to
'C:\Work\mymodelsimcache'
and then simulate the model
rtwdemo_capi
,
files are generated into the specified folder as follows:
As an alternative to using the Simulink preferences to set Simulation cache folder,
you also can get and set the preference value from the command line using
get_param
and set_param
. For example,
>> get_param(0, 'CacheFolder') ans = '' >> set_param(0, 'CacheFolder', fullfile('C:','Work','mymodelsimcache')) >> get_param(0, 'CacheFolder') ans = C:\Work\mymodelsimcache
Also, you can choose to override the Simulation cache folder preference value for the current MATLAB session.
The Simulink preferences Simulation cache folder and
Code generation folder provide the initial defaults for
the MATLAB session parameters CacheFolder
and
CodeGenFolder
, which determine where files generated by
Simulink diagram updates and model builds are placed. However, you can override
these build folder settings during the current MATLAB session, using the Simulink.fileGenControl
function.
This function allows you to manipulate the MATLAB session parameters (for example, overriding or restoring the initial
default values) directly. The values you set using
Simulink.fileGenControl
expire at the end of the current
MATLAB session.
In a parallel computing environment, you can increase the speed of diagram updates for models containing large model reference hierarchies by building referenced models that are configured in accelerator mode in parallel whenever conditions allow. For example, if you have Parallel Computing Toolbox™ software, updating of each referenced model can be distributed across the cores of a multicore host computer. Also, if you have MATLAB Parallel Server™ software, updating of each referenced model can be distributed across remote workers in your MATLAB Parallel Server configuration.
The performance gain realized by using parallel builds for updating referenced models depends on several factors, including:
How many models can be built in parallel for a given model referencing hierarchy
The size of the referenced models
The parallel computing resources, such as number of local or remote workers available and the hardware attributes of the local and remote machines (amount of RAM, number of cores, and so on)
For configuration requirements that can apply to your parallel computing environment, see Parallel Building Configuration Requirements.
For a description of the general workflow for building referenced models in parallel whenever conditions allow, see Update Models in a Parallel Computing Environment.
These requirements apply to using parallel builds for updating model reference hierarchies:
For local pools, the host machine needs an appropriate amount of RAM available for supporting
the number of local workers (MATLAB sessions) that you plan to use. For example, using
parpool(4)
to create a parallel pool with four workers
results in five MATLAB sessions on your machine, each using approximately 120 MB of
memory at startup.
Remote MATLAB Parallel Server workers participating in a parallel build must use a common platform and compiler.
Set up a consistent MATLAB environment for each MATLAB worker session and the MATLAB client session. For example, use consistent shared base workspace
variables, MATLAB path settings, and so forth. One approach is to use the
PreLoadFcn
callback of the top model. If you configure
your model to load the top model with each MATLAB worker session, its preload function can be used for any
MATLAB worker session setup.
To take advantage of parallel building for a model reference hierarchy:
Set up a pool of local and/or remote MATLAB workers in your parallel computing environment.
Make sure that Parallel Computing Toolbox software is licensed and installed.
To use remote workers, make sure that MATLAB Parallel Server software is licensed and installed.
Issue MATLAB commands to set up the worker pool,
for example, parpool(4)
.
From the top model of the model reference hierarchy, open the Configuration Parameters dialog box. Go to the Model Referencing pane and select the Enable parallel model reference builds option. This selection enables the parameter MATLAB worker initialization for builds.
For MATLAB worker initialization for builds, select one of the following values:
None
– The software performs no special
worker initialization. Specify this value if the child models in the
model reference hierarchy do not rely on anything in the base workspace
beyond what they explicitly set up (for example, with a model load
function).
Copy base workspace
– The software attempts
to copy the base workspace to each worker. Specify this value if you use
a setup script to prepare the base workspace for multiple models to
use.
Load top model
– The software loads the top
model on each worker. Specify this value if the top model in the model
reference hierarchy handles all the base workspace setup (for example,
with a model load function).
Set Enable parallel model reference builds only for the top model of the model reference hierarchy to which it applies.
Optionally, turn on verbose messages for simulation builds. If you select verbose builds, the build messages report the progress of each parallel build with the name of the model.
To turn on verbose messages for simulation target builds, go to the Configuration Parameters dialog box and select Verbose accelerator builds.
The Verbose accelerator builds option controls the verbosity of build messages both in the MATLAB Command Window and in parallel build log files.
Optionally, inspect the model hierarchy to determine, based on model dependencies, which models will build in parallel. You can access the Model Dependency Viewer on the Modeling tab, in the Compare dropdown, by selecting one of the options under Dependencies.
Update your model. Messages in the MATLAB command window record when each parallel or serial build starts and finishes.
If you need more information about a parallel build, for example, if a build fails, see Locate Parallel Build Logs.
When you update a model for which referenced models are built in parallel, if verbose builds are turned on, messages in the MATLAB Command Window record when each parallel or serial build starts and finishes. For example,
### Initializing parallel workers for parallel model reference build. ### Parallel worker initialization complete. ### Starting parallel model reference SIM build for 'bot_model001' ### Starting parallel model reference SIM build for 'bot_model002' ### Starting parallel model reference SIM build for 'bot_model003' ### Starting parallel model reference SIM build for 'bot_model004' ### Finished parallel model reference SIM build for 'bot_model001' ### Finished parallel model reference SIM build for 'bot_model002' ### Finished parallel model reference SIM build for 'bot_model003' ### Finished parallel model reference SIM build for 'bot_model004'
To obtain more detailed information about a parallel build,
you can examine the parallel build log. For each referenced model
built in parallel, the build process generates a file named
,
where model
_buildlog.txt
is the name
of the referenced model. This file contains the full build log for
that model.model
If a parallel build completes, you can find the build log file
in the build subfolder corresponding to the referenced model. For
example, for a build of referenced model bot_model004
,
look for the build log file bot_model004_buildlog.txt
in
the referenced model subfolder
.build_folder
/slprj/sim/bot_model004
If a parallel builds fails, you can see output similar to the following:
### Initializing parallel workers for parallel model reference build. ### Parallel worker initialization complete. ### Starting parallel model reference SIM build for 'bot_model002' ### Starting parallel model reference SIM build for 'bot_model003' ### Finished parallel model reference SIM build for 'bot_model002' ### Finished parallel model reference SIM build for 'bot_model003' ### Starting parallel model reference SIM build for 'bot_model001' ### Starting parallel model reference SIM build for 'bot_model004' ### Finished parallel model reference SIM build for 'bot_model004' ### The following error occurred during the parallel model reference SIM build for 'bot_model001': Error(s) encountered while building model "bot_model001" ### Cleaning up parallel workers.
If a parallel build fails, you can find the build log file in
a referenced model subfolder under the build subfolder /par_mdl_ref/
.
For example, for a failed parallel build of model model
bot_model001
,
look for the build log file bot_model001_buildlog.txt
in
the subfolder
.build_folder
/par_mdl_ref/bot_model001/slprj/sim/bot_model001