Simulink.SubSystem.convertToModelReference
Convert subsystems to models
Syntax
Description
Simulink.SubSystem.convertToModelReference(
opens the Model Reference Conversion Advisor for the
subsystem specified by blk
,UseConversionAdvisor=true)blk
.
Before you use this function, load the model that contains the subsystem.
[
converts one or more subsystems specified by tf
,h
]
= Simulink.SubSystem.convertToModelReference(blks
,mdls
)blks
to models with
names specified by mdls
.
For each subsystem that the function converts, the function:
Creates a model.
Copies the contents of the subsystem into 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.
When applicable, the function 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.
Examples
Open Model Reference Conversion Advisor
Open and compile the model named sldemo_mdlref_conversion
. For the conversion to succeed, the model that contains the subsystem must compile successfully.
mdl = "sldemo_mdlref_conversion"; open_system(mdl); set_param(mdl,SimulationCommand="Update")
The model compiles without warnings or errors.
Open the Model Reference Conversion Advisor for the Subsystem block named Bus Counter
.
blk = "sldemo_mdlref_conversion/Bus Counter"; Simulink.SubSystem.convertToModelReference(blk,... 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.
Convert Subsystem to Referenced Model Using Default Options
Open and compile the model named sldemo_mdlref_conversion
. For the conversion to succeed, the model that contains the subsystem must compile successfully.
mdl = "sldemo_mdlref_conversion"; open_system(mdl); set_param(mdl,SimulationCommand="Update")
The model compiles without warnings or errors.
Open the Model Reference Conversion Advisor for the Subsystem block named Bus Counter
.
blk = "sldemo_mdlref_conversion/Bus Counter"; newmdl = "BusCounter"; Simulink.SubSystem.convertToModelReference(blk,newmdl);
### Successfully converted Subsystem block to Model block.
By default, the function does not replace the Subsystem block with a Model block. Instead, the function opens a new window that contains a Model block that references the new model.
Convert Subsystem to Referenced Model Using Specified Options
Open and compile the example model named sldemo_mdlref_conversion
. For the conversion to succeed, the model that contains the subsystem must compile successfully.
mdl = "sldemo_mdlref_conversion"; open_system(mdl) set_param(mdl,SimulationCommand="Update")
The model compiles without warnings or errors.
Convert the contents of the Subsystem block named Bus Counter
to a referenced model named BusCounter
, 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.
subsys = "sldemo_mdlref_conversion/Bus Counter"; newmdl = "BusCounter"; Simulink.SubSystem.convertToModelReference(subsys,newmdl,... AutoFix=true,ReplaceSubsystem=true,CheckSimulationResults=true);
### Successfully converted Subsystem block to Model block.
The Subsystem block is replaced by a Model block that references the model named BusCounter
.
Convert Multiple Subsystems to Referenced Models
One call to the Simulink.SubSystem.convertToModelReference
function can convert multiple subsystems to referenced models.
Open and compile the model named f14
. For the conversion to succeed, the model that contains the subsystem must compile successfully.
mdl = "f14"; open_system(mdl) set_param(mdl,SimulationCommand="Update")
The model compiles 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(mdl,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(mdl,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.
ss1 = "f14/Controller"; ss2 = "f14/Aircraft Dynamics Model"; mdl1 = "Controller"; mdl2 = "AircraftDynamics"; Simulink.SubSystem.convertToModelReference([ss1 ss2],[mdl1 mdl2],... 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
and AircraftDynamics
, respectively.
Input Arguments
blk
— Subsystem block path or handle
numeric scalar | character vector | string scalar
Subsystem block path or handle, specified as a numeric scalar, character vector, or string scalar.
For information on which subsystems you can convert, see Conditionally Execute Referenced Models.
Data Types: double
| char
| string
blks
— Subsystem block paths or handles
numeric array | character vector | cell array of character vectors | string array
Subsystem block paths 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.
When 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.
You cannot convert a parent subsystem and a child of that subsystem at the same time.
Tips
Specifying multiple subsystems to convert with one command can save time compared to converting each subsystem separately. The conversion process for multiple subsystems compiles the model only once.
When you specify multiple subsystems:
In the model, consider setting a short simulation time.
In the function, consider setting
AutoFix
,ReplaceSubsystem
, andCheckSimulationResults
totrue
.
Data Types: double
| char
| string
| cell
mdls
— Unique names for new models
character vector | cell array of character vectors | string array
Unique names for new models, specified as a character vector, cell array of character vectors, or string array.
Each model name must be 59 characters or fewer. For more information, see Choose Valid Model File Names.
When you specify multiple subsystems to convert, specify the same number of model names. Each model name corresponds to a specified subsystem, in the same order.
Data Types: char
| string
| cell
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(blk,mdl,AutoFix=true,ReplaceSubsystem=true)
AutoFix
— Automatic fixes for conversion issues
false
(default) | true
Automatic fixes for conversion issues, specified as false
or
true
.
When you set AutoFix
to true
, the advisor
fixes some conversion issues automatically. For issues that the advisor cannot fix,
you must address the issues manually.
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.
Dependencies
The software ignores this option when you set Force
to
true
.
Data Types: logical
Force
— Forced conversion that downgrades errors
false
(default) | true
Forced conversion that downgrades errors, specified as false
or
true
.
When you set Force
to true
, the conversion
process returns errors as warnings and does not fix the errors, even if you set
AutoFix
to true
.
Setting Force
to true
lets you use the
function to do the initial steps of the conversion. Then, you complete the conversion
process yourself.
Data Types: logical
DataFileName
— Unique name for conversion data file
character vector | string scalar
Unique name for conversion data file, specified as a character vector or string scalar.
The conversion data file stores variables and objects created during the conversion.
By default, the filename begins with the parent 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.
To control the destination of the file, specify the filename with an absolute or relative path.
Dependencies
To use this argument, the parent model must not use a data dictionary.
Data Types: char
| string
CreateWrapperSubsystem
— Wrapper subsystem to preserve parent model layout
false
(default) | true
Wrapper subsystem to preserve parent model layout, specified as
false
or true
.
When you convert a subsystem to a referenced model, the conversion process can create a wrapper subsystem. The wrapper subsystem contains the Model block from the conversion.
The conversion creates a wrapper subsystem automatically if the conversion adds ports to the interface. For example, when Goto and From blocks cross the subsystem boundary, the Model block can have more ports than the original Subsystem block. The conversion creates a wrapper subsystem with the same number of ports as the original subsystem. The wrapper subsystem contains the Model block that references the new model.
Data Types: logical
CreateBusObjectsForAllBuses
— New bus objects for interface definition
false
(default) | true
New bus objects for interface definition, specified as false
or
true
.
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.
When you set CreateBusObjectsForAllBuses
to
true
, the conversion creates bus objects for virtual buses
connected to the subsystem input and output
ports.
When the parent model uses a data dictionary, the new bus objects go in that data
dictionary. To save the bus objects, save the parent model or data dictionary. When
the parent model does not use a data dictionary, the bus objects are saved in the file
specified by
DataFileName
.
Data Types: logical
CopyCodeMappings
— Code mappings copied from parent model
false
(default) | true
Code mappings copied from parent model, specified as false
or
true
.
When you set CopyCodeMappings
to true
, the
function copies the existing code mapping configurations from the parent model to the
new model.
Code mapping information includes configurations of model data elements for code generation. This argument does not affect simulation.
For more information, see Convert Subsystem to Referenced Model and Generate Code (Simulink Coder).
Data Types: logical
ReplaceSubsystem
— Replacement of subsystems with referenced models
false
(default) | true
Replacement of subsystems with referenced models, specified as
false
or true
.
By default, the conversion does not update the original model. When the original model is open, the conversion opens a new window that contains a Model block that references the new model.
When you set ReplaceSubsystem
to true
, the
conversion attempts to replace each Subsystem block you specify with a
Model block that references the corresponding 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 new Model
block.
Tips
Consider making a backup of the original model before you convert the subsystems. If you want to undo the conversion, having a backup can help you restore the original model. A backup also lets you compare the new system masks against the original Subsystem block masks. The system masks of the new models can differ from the block masks of the original Subsystem blocks. For example, the conversion does not copy mask initialization code from block masks to system masks. For more information, see Introduction to System Mask.
Data Types: logical
SimulationModes
— Simulation modes for new Model blocks
"Normal"
(default) | "Accelerator"
| "Software-in-the-loop (SIL)"
| cell array of character vectors | string array
Simulation modes for new Model blocks, specified as
"Normal"
, "Accelerator"
,
"Software-in-the-loop (SIL)"
, a cell array of character vectors,
or a string array.
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.
When you specify one subsystem to convert, specify the simulation mode of the new
Model block as "Normal"
,
"Accelerator"
, or "Software-in-the-loop
(SIL)"
.
Example: Simulink.SubSystem.convertToModelReference(blk,mdl,ReplaceSubsystem=true,SimulationModes="Accelerator")
Before R2024b: Specify the
SimulationModes
value in a cell array or string
array.
When you specify multiple subsystems to convert, specify the simulation mode of each new Model block in a string array or a cell array of character vectors. Use the same order to specify the Model block simulation modes as you used to specify the subsystems and names of the new models.
Example: Simulink.SubSystem.convertToModelReference([blk1 blk2],[mdl1
mdl2],ReplaceSubsystem=true,SimulationModes=["Normal"
"Accelerator"])
Dependencies
To use this argument, set ReplaceSubsystem
to
true
.
Data Types: char
| string
| cell
BuildTarget
— Model reference targets to generate
"Sim"
| "Coder"
Model reference targets to generate, specified as "Sim"
or
"Coder"
.
"Sim"
— Generate model reference simulation targets."Coder"
— Generate model reference code generation targets.
CheckSimulationResults
— Comparison of top-model simulation results before and after conversion
false
(default) | true
Comparison of top-model simulation results before and after conversion, specified
as false
or true
.
If the difference between simulation results exceeds the tolerance level, the function displays an error message.
Tips
Before you perform the conversion:
Set
SimulationModes
to the simulation mode used by the original model. Specify this simulation mode for each Model block you create.Set
StopTime
,AbsoluteTolerance
, andRelativeTolerance
.
Dependencies
To use this argument:
Enable signal logging for the subsystem output signals of interest.
Set
ReplaceSubsystem
totrue
.
Data Types: logical
StopTime
— Stop time for simulation results comparison
10
(default) | numeric scalar
Stop time for simulation results comparison, specified as a numeric scalar.
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 use this argument, set CheckSimulationResults
to
true
.
Data Types: double
AbsoluteTolerance
— Absolute tolerance for simulation results comparison
1e-06
(default) | numeric scalar
Absolute signal tolerance for comparison, specified as a numeric 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 use this argument, set CheckSimulationResults
to
true
.
Data Types: double
RelativeTolerance
— Relative tolerance for simulation results comparison
0.001
(default) | numeric scalar
Relative signal tolerance for comparison, specified as a numeric 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 use this argument, set CheckSimulationResults
to
true
.
Data Types: double
Output Arguments
tf
— True or false result
1
| 0
| logical array
True or false result, returned as a 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.
h
— Handles of created Model blocks
numeric array
Handles of the created Model blocks, returned as a numeric array.
Data Types: double
Version History
Introduced in R2006aR2024b: Convert masked subsystems that have mask initialization code
To convert a masked subsystem that has mask initialization code, you no longer need to
set Force
to true
. 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, use the
Simulink.SubSystem.convertToModelReference
function with CopyCodeMappings
argument specified as true
.
To learn more about service interface 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
You can copy code mappings from the parent model to the newly created referenced model.
To copy the code mappings, use the
Simulink.SubSystem.convertToModelReference
function with the
CopyCodeMappings
argument specified as true
.
R2019a: BuildTarget
value 'RTW'
is not recommended
To build model reference code generation targets, set BuildTarget
to 'Coder'
instead of 'RTW'
. The new name has a
clearer meaning.
There are no plans to remove support for 'RTW'
.
Comando de MATLAB
Ha hecho clic en un enlace que corresponde a este comando de MATLAB:
Ejecute el comando introduciéndolo en la ventana de comandos de MATLAB. Los navegadores web no admiten comandos de MATLAB.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)