Main Content

Simulink.SubSystem.convertToModelReference

Convert subsystem to model reference

collapse all in page

Syntax

Simulink.SubSystem.convertToModelReference(gcb,'UseConversionAdvisor',true)
[tf,h] = Simulink.SubSystem.convertToModelReference(subsys,model)
[tf,h] = Simulink.SubSystem.convertToModelReference(subsys,model,Name,Value)

Description

example

Simulink.SubSystem.convertToModelReference(gcb,'UseConversionAdvisor',true) opens the Model Reference Conversion Advisor for the selected Subsystem block.

[tf,h] = Simulink.SubSystem.convertToModelReference(subsys,model) converts the specified subsystems to referenced models.

For each subsystem that the function converts, it:

  • Creates a model.

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

  • Updates any root-level input and output blocks and the configuration parameters of the model to match the compiled attributes of the original subsystem.

  • Copies the contents of the model workspace of the original model to the new model.

Before you use this function, load the model containing the subsystem.

example

[tf,h] = Simulink.SubSystem.convertToModelReference(subsys,model,Name,Value) specifies options using one or more name-value arguments.

Examples

collapse all

Open Live Script

Open and simulate the model named sldemo_mdlref_conversion.

model = "sldemo_mdlref_conversion";
open_system(model);
sim(model);

The model simulates without warnings or errors.

Click the Subsystem block named Bus Counter. Then, open the Model Reference Conversion Advisor for the Subsystem block by using the Simulink.SubSystem.convertToModelReference function.

Simulink.SubSystem.convertToModelReference(gcb,...
    'UseConversionAdvisor',true);
Updating Model Advisor cache...
Model Advisor cache updated. For new customizations, to update the cache, use the Advisor.Manager.refresh_customizations method.

The Model Reference Conversion Advisor opens.

Open Live Script

Open and simulate the example model named sldemo_mdlref_conversion.

model = "sldemo_mdlref_conversion";
open_system(model);
sim(model);

The model simulates without warnings or errors.

Convert the contents of the Subsystem block named Bus Counter to a referenced model named bus_counter_ref_model, specifying these options:

  • Automatically fix problems when possible.

  • Replace the Subsystem block with a Model block that references the new model.

  • Check the simulation results before and after conversion.

Simulink.SubSystem.convertToModelReference(...
   'sldemo_mdlref_conversion/Bus Counter', ...
   'bus_counter_ref_model', ...
   'AutoFix',true,...
   'ReplaceSubsystem',true,...
   'CheckSimulationResults',true);
### Successfully converted Subsystem block to Model block.

The Subsystem block is replaced by a Model block named Bus Counter that references the model named bus_counter_ref_model.

Open Live Script

One call to the Simulink.SubSystem.convertToModelReference function can convert multiple subsystems to referenced models.

Open and simulate the model named f14.

model = "f14";
open_system(model);
sim(model);

The model simulates without warnings or errors.

Prepare the model for conversion to eliminate or reduce the number of issues identified during conversion.

To be able to check that the simulation results are equivalent before and after conversion, log the output of the model using Dataset format.

set_param(gcs,...
    'SaveOutput','on',...
    'SaveFormat','Dataset');

The new referenced model will inherit its configuration parameter settings from the parent model. Update the f14 model to use the recommended setting for signal resolution. This setting supports only explicitly specified signal resolution for Simulink.Signal objects.

set_param(gcs,'SignalResolutionControl','UseLocalSettings');

Convert the contents of the Subsystem blocks named Controller and Aircraft Dynamics Model to referenced models, specifying these options:

  • Automatically fix problems.

  • Replace the Subsystem blocks with Model blocks that reference the new models.

  • Check simulation results before and after conversion.

Simulink.SubSystem.convertToModelReference(...
    {'f14/Controller','f14/Aircraft Dynamics Model'},...
    {'controller_ref_model','aircraft_dynamics_ref_model'},...
    'AutoFix',true,...
    'ReplaceSubsystem',true,...
    'CheckSimulationResults',true)
### Successfully converted Subsystem block to Model block.

The Subsystem blocks named Controller and Aircraft Dynamics Model are replaced by Model blocks that reference the models named controller_ref_model and aircraft_dyanmics_ref_model, respectively.

Input Arguments

collapse all

Subsystem names or handles, specified as a numeric array, character vector, cell array of character vectors, or string array.

For information on which subsystems you can convert, see Conditionally Execute Referenced Models.

Data Types: double | char | string

Referenced model names, specified as a character vector, cell array of character vectors, or string array. Each model name must be 59 characters or less.

If you specify multiple subsystems to convert, specify the same number of referenced model names. Each model name corresponds to the specified subsystem, in the same order.

Data Types: char | string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: Simulink.SubSystem.convertToModelReference...(engineSubsys,engineModelRef,'ReplaceSubsystem',true)

Conversion

collapse all

Option to fix all conversion issues that can be fixed automatically, specified as true or false.

If you set AutoFix to true, the function fixes all conversion issues that it can fix. For issues that the function cannot fix, the conversion process generates error messages that you address by modifying the model.

Note

If you set Force to true, then the function does not automatically fix conversion issues.

Data Types: logical

Option to complete conversion even with errors, specified as true or false.

If true, the function returns conversion errors as warnings and continues with the conversion without fixing the errors, even if you set AutoFix to true. The Force option allows you to use the function to do the initial steps of the conversion and then complete the conversion process yourself.

Data Types: logical

Name of file for storing conversion data, specified as a character vector. You can specify an absolute or relative path.

You can save the conversion data in a MAT file (default) or a MATLAB® file. If you use a .m file extension, the function serializes all variables to a MATLAB file.

By default, the function uses a file name consisting of the model name plus _conversion_data.mat.

Data Types: char

Model Interface

collapse all

Option to insert wrapper subsystem to preserve model layout, specified as true or false.

When you convert a subsystem to a referenced model, you can have the conversion process insert a wrapper subsystem to preserve the layout of the parent model. The subsystem wrapper contains the Model block from the conversion.

The conversion creates a wrapper subsystem automatically if the conversion modifies the Model block interface by adding ports.

Data Types: logical

Option to create bus objects for interface definition, specified as true or false.

Models require a defined interface, unlike subsystems. To define an interface that contains virtual buses, the new model must use either of these options:

  • In Bus Element and Out Bus Element blocks

  • Inport and Outport blocks that specify Simulink.Bus objects

By default, the conversion does not create Bus objects. Instead, the conversion uses In Bus Element and Out Bus Element blocks to support virtual buses at the model interface, and the new model contains the original subsystem.

When you set this parameter to true, the conversion creates Bus objects for all virtual buses connected to Inport and Outport blocks that do not specify Bus objects. The conversion keeps the Inport and Outport blocks at the model interface, and they specify the new Bus objects.

Data Types: logical

Option to copy code mappings from parent model to the new model, specified as true or false.

If true, the function copies the existing code mapping configurations from the parent model to the new referenced model.

If false, the function does not copy the existing code mapping configurations from the parent model to the new model.

Data Types: logical

Model Implementation

collapse all

Option to replace Subsystem blocks with Model blocks, specified as true or false.

If you set the value to true, consider making a backup of the original model before you convert the subsystems. If you want to undo the conversion, having a backup makes it easier to restore the model.

If you set ReplaceSubsystem to true, the conversion action depends on whether you use the automatic fix options.

  • If you use the automatic fixes, then the conversion replaces the Subsystem block with a Model block unless the automatic fixes change the input or output ports. If the ports change, then the conversion includes the contents of the subsystem in a Model block that is inserted in the Subsystem block.

  • If you do not use the automatic fixes, then the conversion replaces the Subsystem block with a Model block.

Data Types: logical

Simulation mode for Model blocks, specified as 'Normal' or 'Accelerator'. The simulation mode setting applies to the Model blocks that reference the models that the conversion creates.

Data Types: char | string

Model reference targets to generate, specified as 'Sim' or 'Coder'.

  • 'Sim' — Model reference simulation target

  • 'Coder' — Code generation target

Data Types: char

Simulation Results Comparison

collapse all

Option to check simulation results before and after conversion, specified as true or false.

Before performing the conversion:

If the difference between simulation results exceeds the tolerance level, the function displays a message.

Data Types: logical

Absolute signal tolerance for comparison, specified as a numeric scalar.

Use this option only if you set CheckSimulationResults to true.

Data Types: double

Relative signal tolerance for comparison, specified as a numeric scalar.

Use this option only if you set CheckSimulationResults to true.

Data Types: double

Output Arguments

collapse all

True or false result, returned as 1 or 0 of data type logical.

A value of 1 indicates a successful conversion.

If you set Force to true, the function returns a value of 1 if the conversion completes. However, the simulation results can differ from the simulation results for the model before conversion.

Handles of the created Model blocks, returned as a numeric array.

Data Types: double

Tips

  • You cannot convert a parent subsystem and a child of that subsystem at the same time.

  • Specifying multiple subsystems to convert with one command can save time compared to converting each subsystem separately. The multiple subsystem conversion process compiles the model once.

  • If you specify multiple subsystems to convert, the conversion process attempts to convert each subsystem. Successfully converted subsystems produce referenced models, even if the conversions of other subsystems fail.

  • If you specify multiple subsystems, consider:

    • In the input arguments, setting 'Autofix', 'ReplaceSubsystem', and 'CheckSimulationResults' to true.

    • In the model, setting a short simulation time.

  • A data dictionary saves bus objects that it creates as part of the conversion process when both of these conditions exist:

    • The top model uses a data dictionary.

    • All changes to the top model are saved.

  • To maintain the behavior of a masked subsystem, perform these additional tasks:

    • For masked callbacks, icons, ports, and documentation, create a backup copy of the masked subsystem before converting it to a referenced model. After conversion, copy the content from the Mask Editor of the backup masked subsystem to the Mask Editor of the new Model block.

    • Replace mask parameters with model arguments (see Parameterize Instances of a Reusable Referenced Model).

    Note

    Referenced models do not support the functionality that you can achieve with mask initialization code to create masked parameters.

Version History

Introduced in R2006a

expand all

See Also

| |

Topics