Model Reference Conversion Advisor

Convert subsystems to referenced models

Description

The Model Reference Conversion Advisor converts subsystems to referenced models. The advisor can convert a variety of subsystems, including conditional, masked, and referenced subsystems.

Converting subsystems to referenced models is beneficial for modeling large, complex systems and for team-based development. Many large models use a combination of subsystems and referenced models. To decide whether to convert a subsystem to a referenced model, see Explore Types of Model Components.

When the conversion encounters an issue, the Model Reference Conversion Advisor helps you review and fix the issue. Preparing the contents of a Subsystem block can eliminate or reduce the number of issues. Addressing these issues in the model editing environment can be more efficient than switching repeatedly between the Model Reference Conversion Advisor and the Simulink^® Editor. For more information, see Convert Subsystems to Referenced Models.

Open the Model Reference Conversion Advisor

• Simulink Editor: Select a Subsystem block. Then, in the Simulink Toolstrip, on the Subsystem Block tab, select Convert > Referenced Model.

• MATLAB^® Command Window: Use the Simulink.SubSystem.convertToModelReference function with UseConversionAdvisor set to true.

Examples

Set Subsystem Conversion Options

Specify input parameters that determine the output of the conversion and control whether the advisor automatically attempts to fix conversion errors.

When you open the advisor, in the left pane, the top node is selected. This node identifies the Subsystem block that the advisor will convert to a referenced model and provides conversion input parameters. You can use the default parameter values or change the values to customize the conversion.

For information about specific parameters, see Parameters.

Automatically Convert Subsystem to Referenced Model

The Model Reference Conversion Advisor can step through each check automatically.

1. After you configure the subsystem conversion options, click Convert.

   The Model Reference Conversion Advisor steps through each check automatically.

2. Address any issues that the advisor reports. The advisor provides a Fix button for any issues it can fix automatically.

3. After you address the reported issues, click Continue.

After the Model Reference Conversion Advisor successfully runs all checks, it completes the conversion.

Check Conversion Input Parameters

Verify that all conversion input parameters are valid.

For information about specific parameters, see Parameters.

1. In the left pane, select the Check conversion input parameters node.

2. Click the Run This Task button.

3. Address any issues that the advisor reports. The advisor provides a Fix button for any issues it can fix automatically.

4. After you address the reported issues, click Continue.

Check Model Configurations

Verify that the model configurations meet model referencing requirements. This check identifies model configuration parameter settings that are not valid for model references.

1. In the left pane, select the Check model configurations node.

2. Click the Run This Task button.

3. Address any issues that the advisor reports. The advisor provides a Fix button for any issues it can fix automatically.

4. After you address the reported issues, click Continue.

Check Subsystem Interface

Verify whether the subsystem interface meets model reference requirements.

1. In the left pane, select the Check subsystem interface node.

2. Click the Run This Task button.

   The advisor verifies that the type of subsystem is one that the advisor can convert. Then, the advisor verifies that the interfaces to specific types of subsystems, such as masked subsystems, meet conversion requirements.

3. Address any issues that the advisor reports. The advisor provides a Fix button for any issues it can fix automatically.

4. After you address the reported issues, click Continue.

Check Subsystem Content

Verify whether the subsystem content meets model reference requirements.

1. In the left pane, select the Check subsystem content node.

2. Click the Run This Task button.

   The advisor checks whether the model compiles successfully. Upon successful compilation, the advisor checks whether the blocks in the subsystem meet the requirements for conversion.

3. Address any issues that the advisor reports. The advisor provides a Fix button for any issues it can fix automatically.

4. After you address the reported issues, click Continue.

Complete Conversion

After all checks run successfully, complete the conversion.

1. In the left pane, select the Complete conversion node.

2. Click the Run This Task button.

   The Model Reference Conversion Advisor:

   • Creates a model.

   • Copies the contents of the subsystem into the new model.

   • By default, attempts to replace the Subsystem block with a Model block that references the new model.

   • Updates the root-level input and output blocks of the new model to use the compiled attributes from the original subsystem.

   • Copies the configuration set of the parent model to the new model or references the same configuration set as the parent model. The conversion can change some configuration settings for the new model to support using the new model as a referenced model.

   • Creates an HTML conversion summary report in the slprj folder. This report summarizes the results of the conversion process, including the results of the fixes that the advisor performed. This report also describes the elements that the advisor copies.

   • Optionally, checks the consistency of simulation results before and after conversion.

   When applicable, the Model Reference Conversion Advisor also:

   • Copies the model workspace contents used by the subsystem from the parent model to the new model.

   • Applies the data dictionary used by the parent model to the new model.

   • Creates the Simulink.Bus objects, Simulink.Signal objects, and tunable parameters that the new model requires.

   • Creates a system mask for the new model based on the block mask of the original Subsystem block. System masks do not support some of the functionalities of block masks, such as mask initialization code. For more information, see Introduction to System Mask.

   • Copies the requirements links created with Requirements Toolbox™ software from the original Subsystem block to the new Model block.

If you are not satisfied with the conversion results, you can restore the model to its initial state. After you successfully run the Complete conversion check, click the Click here to restore the original model link.

If you selected Check simulation results after conversion, you can view the results by clicking the Click here to view the comparison results link.

Compare Simulation Results Before and After Conversion

If you selected Check simulation results after conversion, the Model Reference Conversion Advisor provides a comparison of top-model simulation results before and after conversion.

After you successfully run the Complete conversion check, click Click here to view the comparison results. The results display in the Simulation Data Inspector. A green check mark indicates that simulation results are within tolerance between the baseline model and the model with the new referenced model.

For more information, see Compare Simulation Data.

Related Examples

• Convert Subsystem to Referenced Model

Parameters

New model name — Unique name for new model

text

The default new model name is a unique name on the MATLAB path that is based on the Subsystem block name.

For information about valid model file names, see Choose Valid Model File Names.

Conversion data file name — Unique name for conversion data file

text

The conversion data file stores variables and objects created during the conversion.

By default, the filename begins with the model name and ends with _conversion_data.mat. For example, for a subsystem in a model named myModel, the default conversion filename is myModel_conversion_data.mat.

You can save the conversion data in a MAT file (.mat) or a script (.m). When you specify a .m file extension, the file serializes the variables.

Dependencies

To enable this parameter, the parent model must not use a data dictionary.

Fix errors automatically (if possible) — Automatic fixes for conversion issues

off (default) | on

When you select this parameter, the advisor fixes some conversion issues automatically.

By default, when an advisor check finds an error that the advisor can fix, the advisor provides a Fix button. To have the advisor fix the issue, click the Fix button.

The advisor can fix conversion issues such as Goto and From blocks that cross the subsystem boundary. Based on the automatic fixes, the new model can have more ports than the original subsystem.

To reduce the number of fixes required during the conversion, see Prepare Subsystem for Conversion.

Replace the content of a subsystem with a Model block — Replacement of subsystem with referenced model

on (default) | off

By default, the advisor attempts to replace the Subsystem block with a Model block that references the new model. If automatic fixes add ports to the interface, then to preserve the parent model layout, the advisor replaces the original Subsystem block with a Subsystem block that contains the Model block.

When you clear this parameter, the advisor does not update the original model. The advisor opens the new model in a new window. The advisor also opens a window that contains a Model block that references the new model.

Tips

For masked Subsystem blocks, consider making a backup of the original Subsystem block before conversion. A backup lets you compare the new system mask against the original Subsystem block mask. The system mask of the new model can differ from the block mask of the original Subsystem block. For example, the conversion does not copy mask initialization code from the block mask to the system mask. For more information, see Introduction to System Mask.

Copy code mappings — Code mappings copied from parent model

off (default) | on

Select this parameter to copy the code mapping information from the parent model to the new model.

Code mapping information includes configurations of model data elements for code generation. This parameter does not affect simulation.

For more information, see Convert Subsystem to Referenced Model and Generate Code (Simulink Coder).

Model block simulation mode — Simulation mode for new Model block

Normal (default) | Accelerator | Software-in-the-loop (SIL)

The Model block simulation mode controls the simulation mode for the corresponding instance of the referenced model. Another Model block that references the same model can specify a different simulation mode.

• Normal — Execute the referenced model interpretively, as if the referenced model is an atomic subsystem implemented directly within the parent model.

• Accelerator — Create a MEX file for the referenced model. Then, execute the referenced model by running the S-function.

• Software-in-the-loop (SIL) — This option requires an Embedded Coder^® license. Generate production code based on the Model block Code interface parameter setting. The code is compiled for and executed on the host platform.

The corners of the Model block indicate the simulation mode of the Model block. For normal mode, the corners have empty triangles. For accelerator mode, the corner triangles are filled in. For SIL mode, the corners are filled in and the word (SIL) appears on the block icon.

The simulation mode of a parent model can override the simulation mode of a Model block. For more information, see Choose Simulation Modes for Model Hierarchies.

Check simulation results after conversion — Comparison of top-model simulation results before and after conversion

off (default) | on

Select this parameter to compare top-model simulation results before and after conversion.

To see the results after the conversion is complete, click View comparison results. The Simulation Data Inspector displays the results of the comparison. For more information, see Compare Simulation Results Before and After Conversion.

Tips

Before you perform the conversion:

• Set the Model block simulation mode option in the advisor to the same simulation mode as the original model.

• Set Stop time, Absolute tolerance, and Relative tolerance.

Dependencies

• To use this option, enable signal logging for the subsystem output signals of interest.

• To enable this option, select Replace the content of a subsystem with a Model block.

Stop time — Stop time for simulation results comparison

finite scalar

By default, the simulation results comparison uses the stop time of the parent model. The stop time must be a finite scalar that is greater than or equal to the start time of the parent model. For more information, see Start time.

Dependencies

To enable this parameter, select Check simulation results after conversion.

Absolute tolerance — Absolute tolerance for simulation results comparison

1e-06 (default) | positive scalar

The absolute tolerance is the largest acceptable solver error as the value of the measured signal approaches zero. The simulation results before conversion establish the baseline. The simulation results after conversion must be within the tolerance.

Dependencies

To enable this parameter, select Check simulation results after conversion.

Relative tolerance — Relative tolerance for simulation results comparison

0.001 (default) | positive scalar

The relative tolerance is the largest acceptable solver error relative to the size of each signal during each time step. The simulation results before conversion establish the baseline. The simulation results after conversion must be within the tolerance.

The default value (0.001) means that the compared signal is accurate to within 0.1% of the baseline signal.

Dependencies

To enable this parameter, select Check simulation results after conversion.

Show report after run — Option to open conversion report upon completion

off (default) | on

After the conversion completes, the HTML conversion summary report appears in the slprj folder. This report summarizes the conversion setup and results, including the results of the fixes that the advisor performed. This report also describes the elements that the advisor copies.

Select this parameter to open the conversion report after the conversion completes.

Programmatic Use

Simulink.SubSystem.convertToModelReference

Limitations

The Model Reference Conversion Advisor does not support conversion for some types of subsystems. For example:

• Subsystem blocks with Simscape™ Multibody™ components that cross the subsystem boundary

• Asynchronous subsystems — To convert asynchronous subsystems to referenced models that accept asynchronous function calls, see Asynchronous Support Limitations (Simulink Coder).

Tips

To convert one or more subsystems to models, use the Simulink.SubSystem.convertToModelReference function. To generate a conversion summary report, use the Model Reference Conversion Advisor.

This table provides a mapping between the Model Reference Conversion Advisor parameters and the corresponding Simulink.SubSystem.convertToModelReference function arguments.

Tool Parameter	Function Argument
New model name	To specify one or more model names, use the second input argument of the function.
Conversion data file name	DataFileName
Fix errors automatically (if possible)	AutoFix
Replace the content of a subsystem with a Model block	ReplaceSubsystem
Copy code mappings	CopyCodeMappings
Model block simulation mode	SimulationModes
Check simulation results after conversion	CheckSimulationResults
Stop time	StopTime
Absolute tolerance	AbsoluteTolerance
Relative tolerance	RelativeTolerance

Version History

Introduced in R2014a

R2025a: New models avoid implicit signal resolution

When you convert a subsystem to a model and the parent model has the Signal resolution configuration parameter set to Explicit and implicit or Explicit and warn implicit, the configuration set of the new model changes Signal resolution to Explicit only. This change avoids implicit signal resolution to Simulink.Signal objects in the new model.

For more information, see Signal resolution.

R2025a: Conversion detects unsupported Parameter Writer block configurations

When you convert a subsystem to a model, the conversion now checks for Parameter Writer blocks that write to:

• A block outside the subsystem

• A base workspace variable used outside the subsystem

• A model workspace variable

When a Parameter Writer block writes to one of these destinations, the conversion now detects the issue and fails. In previous releases, the conversion succeeds, but compiling or simulating the new model hierarchy results in an error.

For more information about Parameter Writer blocks, see Parameter Writer.

R2024b: Convert masked subsystems that have mask initialization code

The Model Reference Conversion Advisor can now convert a masked subsystem that has mask initialization code. The conversion is no longer blocked by the mask initialization code. The system mask of the new model does not use the mask initialization code because system masks of models do not support mask initialization code. For more information, see Introduction to System Mask.

R2024b: Conversion preserves mask parameter and cross-parameter constraints

When you convert a masked subsystem to a model, the conversion now copies the applicable parameter and cross-parameter constraints from the Subsystem block mask to the system mask of the new model. For a constraint to apply to the system mask, the related mask parameters must be available on the system mask. For more information about these constraints, see Validating Mask Parameters Using Constraints.

R2024b: Conversion better supports virtual buses at interface

When you convert a subsystem to a model and the subsystem interface uses virtual buses, the block diagram of the new model better mimics the block diagram of the subsystem.

To specify the bus hierarchy without creating Simulink.Bus objects or adding blocks, the new model uses In Bus Element and Out Bus Element blocks. The corresponding bus element ports specify the elements of the bus hierarchy both with and without blocks. For more information, see Specify Multiple Elements of a Port.

R2023a: Copy service interface code mappings from parent model to referenced model

Service interface code mappings were introduced in R2022b. Starting in R2023a, you can copy service interface code mappings from the parent model to the newly created referenced model. To copy the mappings, select the Copy code mappings parameter in the Model Reference Conversion Advisor. To learn more about service interface code mappings, see C Service Interfaces (Embedded Coder). To learn more about code mapping configurations, see Define Service Interfaces, Storage Classes, Memory Sections, and Function Templates for Software Architecture (Embedded Coder).

R2020b: Copy code mappings from parent model to referenced model

Starting in R2020b, you can copy code mappings from the parent model to the newly created referenced model. To copy the code mappings, select the Copy code mappings parameter in the Model Reference Conversion Advisor.