Reduce Build Time for Referenced Models by Using Parallel Builds

In a parallel computing environment, you can increase the speed of code generation and compilation for models containing large model reference hierarchies. Achieve the speed by building referenced models in parallel whenever conditions allow. For example, if you have Parallel Computing Toolbox™ software, code generation and compilation for each referenced model can be distributed across the cores of a multicore host computer. If you also have MATLAB® Parallel Server™ software, you can distribute code generation and compilation for each referenced model across remote workers in your MATLAB Parallel Server configuration.

Parallel Building for Large Model Reference Hierarchies

The execution speed improvement realized by using parallel builds for referenced models depends on several factors. These factors include how many models can be built in parallel for a given model referencing hierarchy, the size of the referenced models, and parallel computing resources. The resources include the number of local and/or remote workers available and the hardware attributes of the local and remote machines. Examples of hardware attributes are the amount of RAM and number of cores.

Simulink® cache (.slxc) files are generated for the entire model reference hierarchy during a parallel build. For more information, see Simulink Cache Files for Incremental Code Generation.

For configuration requirements that could 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 Build Models in a Parallel Computing Environment.

For information on how to configure a custom embedded system target file to support parallel builds, see Support Model Referencing.

Note

In a MATLAB Parallel Server parallel computing configuration, parallel building is designed to work interactively with the software. You can initiate builds from the Simulink user interface or from the MATLAB Command Window using commands such as slbuild. You cannot initiate builds using batch or other batch mode workflows.

Parallel Building Configuration Requirements

The following requirements apply to configuring your parallel computing environment for building model reference hierarchies in parallel whenever conditions allow:

  • For local pools, the host machine must have enough RAM to support 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 pool uses the amount of memory required for MATLAB and the code generator at startup. For memory requirements, see System Requirements for MATLAB & Simulink.

  • Remote MATLAB Parallel Server workers participating in a parallel build and the client machine must use a common platform and compiler.

  • A consistent MATLAB environment must be set up in each MATLAB worker session as in the MATLAB client session — for example, 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.

  • It is possible to cause a build error by relying on callbacks to load variables when executing an incremental parallel build (referenced model hierarchy build). To avoid this issue during parallel builds, use one of these options:

    • Do not rely on callback to manage workspace variable of referenced models,

    • Between builds, run the commands spmd, bdclose all, end to close all models on the parallel build workers.

    • Between builds, restart the parallel pool.

Build Models in a Parallel Computing Environment

To take advantage of parallel building for a model reference hierarchy:

  1. Set up a pool of local and/or remote MATLAB workers in your parallel computing environment.

    1. Make sure that Parallel Computing Toolbox software is licensed and installed.

    2. To use remote workers, make sure that MATLAB Parallel Server software is licensed and installed.

    3. Issue MATLAB commands to set up the parallel pool, for example, parpool(4).

  2. From the top model of the model reference hierarchy, open the Configuration Parameters dialog box. Select the Enable parallel model reference builds (Simulink) check box. This selection enables the parameter MATLAB worker initialization for builds (Simulink).

    For MATLAB worker initialization for builds, select one of the following values:

    • None if it is preferable that the software does not perform 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. An example is a model load function.

    • Copy base workspace if it is preferable that 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 if it is preferable that the software loads the top model on each worker. Specify this value if the top model in the model reference hierarchy handles the base workspace setup. An example is a model load function.

    Note

    Only set Enable parallel model reference builds for the top model of the model reference hierarchy to which it applies.

  3. Optionally, turn on verbose messages for simulation builds, code generation builds, or both. If you select verbose builds, the build messages report the progress of each parallel build with the name of the model. To produce build messages, select these configuration parameters:

    • Verbose accelerator builds.

    • Verbose build

    You can see the build messages in the MATLAB Command Window and in parallel build log files.

  4. Optionally, inspect the model reference hierarchy to determine, based on model dependencies, which models are built in parallel. You can use the Model Dependency Viewer. On the Modeling tab, in the Evaluate & Manage section, select Dependencies > Referenced Model Instances.

  5. Build your model. Messages in the MATLAB Command Window record when each parallel or serial build starts and finishes. The order in which referenced models build is nondeterministic. They could build in a different order each time the model is built.

    If you need more information about a parallel build, for example, if a build fails, see Locate Parallel Build Logs.

Locate Parallel Build Logs

If verbose builds are turned on when you build a model for which referenced models are built in parallel, 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'
### Starting parallel model reference RTW build for 'bot_model001'
### Starting parallel model reference RTW build for 'bot_model002'
### Starting parallel model reference RTW build for 'bot_model003'
### Starting parallel model reference RTW build for 'bot_model004'
### Finished parallel model reference RTW build for 'bot_model001'
### Finished parallel model reference RTW build for 'bot_model002'
### Finished parallel model reference RTW build for 'bot_model003'
### Finished parallel model reference RTW 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 model_buildlog.txt, where model is the name of the referenced model. This file contains the full build log for that 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 a referenced model subfolder such as build_folder/slprj/grt/bot_model004, build_folder/slprj/ert/bot_model004, or build_folder/slprj/sim/bot_model004. The build log (diagnostic viewer) provides a relative path to the location of each build log file.

If a parallel builds fails, you could see output similar to the following:

### Initializing parallel workers for parallel model reference build.
### Parallel worker initialization complete.
...
### Starting parallel model reference RTW build for 'bot_model002'
### Starting parallel model reference RTW build for 'bot_model003'
### Finished parallel model reference RTW build for 'bot_model002'
### Finished parallel model reference RTW build for 'bot_model003'
### Starting parallel model reference RTW build for 'bot_model001'
### Starting parallel model reference RTW build for 'bot_model004'
### Finished parallel model reference RTW build for 'bot_model004'
### The following error occurred during the parallel model reference RTW 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/model. For example, for a failed parallel build of model bot_model001, look for the build log file bot_model001_buildlog.txt in a subfolder such as build_folder/par_mdl_ref/bot_model001/slprj/grt/bot_model001, build_folder/par_mdl_ref/bot_model001/slprj/ert/bot_model001, or build_folder/par_mdl_ref/bot_model001/slprj/sim/bot_model001.

View Build Process Status

The Build Process Status window lets you view in-progress build status or cancel in-progress parallel builds of models. After completing a model build, you can view the completion status by using the Build Process Status window. For more information, see Apply Build Process Status to Improve Parallel Builds.

Note

The Build Process Status window support parallel builds of referenced model hierarchies. Do not use the Build Process Status window for sequential (non-parallel) builds.

To open the Build Process Status window, use any of these options:

  • To open the Build Process Status window for a model, in the command window, type:

    coder.buildstatus.open('model')
  • To open the Build Process Status window for a model with the rtwbuild function, in the command window, type:

    rtwbuild('model', ...
        'OpenBuildStatusAutomatically',true)
  • To open the Build Process Status window for a model with the slbuild function, in the command window, type:

    slbuild('model','StandaloneCoderTarget', ...
        'OpenBuildStatusAutomatically',true)

To cancel an in-progress model build, the Build Process Status window provides a Cancel button. This button cancels the build after completion of the current model or referenced model build. Using cancel to stop a build ends a build process without creating out-dated build artifacts that require post-build clean up.

Apply Build Process Status to Improve Parallel Builds

The Build Process Status window lets you view in-progress build status or cancel in-progress parallel builds of models. For more information, see View Build Process Status.

This example shows how apply build process status from parallel builds. The status information can help you identify ways to improve parallel builds by modifying the referenced model hierarchy.

  1. Open a parallel pool for the build process and add the model folder to the path for all workers.

    parpool('local', 2)
    addpath(fullfile(matlabroot,'toolbox','rtw','rtwdemos','rtwdemo_parallelbuild'))
    spmd
    addpath(fullfile(matlabroot,'toolbox','rtw','rtwdemos','rtwdemo_parallelbuild'))
    end
  2. Open the top-level model in a reference model hierarchy. The rtwdemo_parabuild_a_1 model refers to a number of referenced models.

    open_system('rtwdemo_parabuild_a_1')

  3. View the model dependencies with the Model Dependency Viewer. On the Modeling tab, in the Evaluate & Manage section, select Dependencies > Referenced Model Instances.

    During the build process, the Build Process Status window displays the progress of the code generator as it works its way up the referenced model hierarchy. The code generator builds the referenced models in the order that they block building of models further up the dependency tree.

  4. Start a parallel build of the referenced model hierarchy and open the Build Process Status window.

    rtwbuild('rtwdemo_parabuild_a_1','OpenBuildStatusAutomatically',true)
  5. As the build progresses, the Build Process Status window displays the status for each referenced model.

The table describes the types of build status.

Build Process StatusDescription

Blocked

The code generator cannot schedule the model build because the build is blocked by dependencies. For example, another model build must complete before the blocked build can be scheduled.

Scheduled

For parallel build processes, the code generator schedules the model build when it is not blocked by dependencies. The model build waits at the scheduled status until a parallel core is available to process the model build.

Building

The code generator is executing the build process for the model.

Completed or Error

When the build process exits successfully, the status is Completed. When the build process is not success, the status is Error.

Up To Date

When the build process detects that it does not need to generate code (for example, generated code is current with the model), the status is Up to Date.

Canceling or Canceled

When you use the Cancel Build button, the build process changes the status of incomplete builds to Canceling. After processing the Canceling operation, the build process changes the status of these builds to Canceled.

The elapse time shows you where the build process spends time. Use the dependency tree of the model hierarchy and the elapse time of reference model builds to identify locations where the build process spends the most time and restricts the build progress. Some options for reducing the parallel build time include:

  • Restructure the referenced model hierarchy to reduce build time for individual models.

  • Provide sufficient parallel workers in the pool to match the number of referenced model dependencies being built.

See Also

| | |

Related Topics