Subsystem reference allows you to save the contents of a subsystem in a separate file and reference it using a Subsystem Reference block. You can create multiple instances referencing the same subsystem file. When you edit any instance of a referenced subsystem, the changes are saved in the separate file in which the subsystem is stored and all the referenced instances of that file are synchronized.
Subsystem reference is compatible with SLX and MDL file formats.
When you save a subsystem to a separate file you can reuse it multiple times by using Subsystem Reference blocks referencing the same subsystem file.
You can identify a Subsystem Reference block by the triangles in the opposite corners of the block icon.
A referenced subsystem supports all the semantics of a regular subsystem. A referenced subsystem adapts itself to the context of the parent model and has identical execution behavior when compared to a nonreferenced subsystem.
Create a Subsystem Block Diagram
A subsystem file stores the content of a subsystem block diagram in a file.
A subsystem file:
Cannot be simulated.
Does not have a full configuration set.
Does not have a model workspace.
Does not have code generation capability.
To know more about the model configuration set, see Model Configuration Parameters: Simulation Target and Model Configuration Parameters: Code Generation Custom Code (Simulink Coder).
To create a subsystem block diagram:
On the Start Page, in the Simulink product group, click Blank Subsystem.
Alternatively, in the Simulink toolstrip, on the Simulation tab, select New and click Blank Subsystem. A Subsystem window opens.
Add content and click Save .
Specify a file name in the Save As dialog box. The file name must be a valid MATLAB name.
This creates a new subsystem file at the location specified.
To create a subsystem file programmatically, use the command:
For more information on controlling subsystem files programmatically, see Control Referenced Subsystem Programmatically.
Reference a Subsystem File in a Model
Open a model in which you want to reference a subsystem block diagram.
Add a Subsystem Reference block using the Simulink Library Browser or the Quick Block Insert menu. An empty Subsystem Reference block is added to the Simulink canvas.
In the Simulink toolstrip, on the Referenced Subsystem tab, specify the name of the subsystem block diagram file in the File Name field, or click Browse to navigate to it.
Alternatively, you can double-click the Subsystem Reference block to specify the subsystem block diagram file.
Click OK to save the changes.
Convert an Existing Subsystem to a Referenced Subsystem
You can convert an existing Subsystem block to a Subsystem Reference block.
Consider a model with two Subsystem blocks as shown.
In this model, you have two Subsystem blocks – a Controller subsystem and a Plant subsystem. To convert the Controller Subsystem block to a referenced subsystem:
Select the Controller Subsystem block and on the Subsystem Block tab, select Convert and click Convert to Subsystem Reference. A dialog box opens.
Specify a name for the subsystem component in the Subsystem file name field. The name must be a valid MATLAB name. The conversion creates a subsystem file in the current directory. To create the file in a specific location, click Browse and navigate to the save location. Next, transfer existing test harnesses to the subsystem block diagram. To transfer the test harnesses, select the Transfer test harnesses check box then, click Convert.
The Subsystem block changes into a Subsystem Reference block with the name of the subsystem file displayed at the top of the block icon.
When you convert a linked block to a referenced subsystem, do so in the parent library block of that linked block. Once you convert a parent library block to a referenced subsystem, all its linked block instances are also converted to referenced subsystems.
You cannot convert a subsystem to a referenced subsystem when the subsystem:
Has no read/write permissions.
Has a mask that is trying to modify its contents.
Edit and Save Referenced Subsystem
In a model containing multiple instances of a referenced subsystem, you can edit any instance. When you actively edit an instance of a referenced subsystem, all the other instances are locked and unavailable for editing. After you edit and save a subsystem reference instance, the changes are automatically saved to the subsystem file. These changes also reflect in any other open windows that currently display the instances of the same subsystem reference. The remaining subsystem reference instances are updated when you:
Open, simulate, or update the model containing the subsystem reference instance.
set_paramcommands. For more information on using the commands, see Control Referenced Subsystem Programmatically.
A badge is shown at the bottom left corner of an open subsystem file to denote the availability of the file for edit. The badge shows two states:
indicates that the subsystem file is available for edit. Right-click the badge to see all the active instances of that subsystem and to navigate to each of them.
indicates that the subsystem file is unavailable for edit, as another instance is being actively edited. Right-click the badge to open the instance being edited.
Once you have edited an instance in a model, you can save or discard your changes.
To save the changes, select Save on the Simulation tab of the model window. The Save All drop-down lists two options to save your changes:
Save All – To save all the updates in the current model.
Save Specific Referenced File – To save a specific subsystem file when you have made changes to multiple subsystem files.
To discard the changes in a specific subsystem file made while editing its instance, close your subsystem file. You will get a dialog box asking whether to save the subsystem file before closing. Click No. This action reverts changes in all the instances of the subsystem file.
Attach Data Dictionary to Subsystem Reference
You can attach a data dictionary to a subsystem reference to store variables, objects, and interfaces. The scope of data you define in an attached data dictionary is the subsystem reference boundary. Using a data dictionary allows you to define all types of data and interfaces and reuse them in child blocks and instances of your subsystem reference.
To attach a data dictionary with a subsystem reference:
Create a new data dictionary or open an existing data dictionary.
In the data dictionary, define all data objects that you will use, such as variables, bus objects, and enumeration types.
Save the data dictionary.
Attach the data dictionary as an external data source to your subsystem file by using the External Data tab in the Subsystem Properties dialog box, or by using
set_param. The Model Explorer displays the attached data dictionary and its contents as an external data source for the subsystem file.
You can use the variables, objects, and data types defined in the data dictionary within the subsystem reference boundary. See Attach Data Dictionary to Subsystem Reference for more information.
Add a System Mask for Subsystem Reference
You can mask a subsystem file using a system mask. When you create a system mask for a subsystem file, all the referenced instances share the same system mask.
To mask a subsystem file:
Open the subsystem file to be masked.
In the Simulink toolstrip, on the Subsystem tab, click Create System Mask. Alternatively, right-click anywhere on the canvas and select Mask and click Create System Mask. The Mask Editor dialog opens.
Add mask parameters and click OK.
You cannot directly mask a Subsystem Reference block. To mask a Subsystem Reference block, select the block. On the Referenced Subsystem tab, click Create System Mask. This action opens the subsystem file being referenced and creates a mask on it.
You cannot set parameters using
set_paramin a call back code of a masked subsystem. However if the subsystem is self-modifiable or referenced from a library you can do so.
For more information on creating and editing System masks, see Introduction to System Mask.
Create Self-Modifiable Subsystem Reference Using System Mask
You can make instance-specific changes in the contents of a masked subsystem file using the system mask. To allow dynamic changes, set the masked subsystem file as self-modifiable. In a self-modifiable subsystem file, you can use the initialization callback of the system mask to add or delete blocks and set the parameters of the blocks within the file.
To set a masked subsystem file as self-modifiable, in the subsystem file, go to the Code tab of the System Mask Editor and select Allow mask initialization code to modify the subsystem's content.
You can also set the masked subsystem file
ssref1 as self-modifiable
programmatically. First, get the subsystem file mask as a mask object. Then set the masked
subsystem file as
maskObj = Simulink.Mask.get('ssref1'); maskObj.SelfModifiable = 'on';
In a self-modifiable masked subsystem file, you can modify the blocks of a masked subsystem reference instance or allow the masked subsystems inside a masked subsystem reference instance to self-modify.
Modify Blocks of a Masked Subsystem Reference
Consider a self-modifiable masked subsystem file
includes a Gain block. The system mask of the subsystem reference instance
SR1 uses Gain as the mask parameter to set the
value of the Gain block. To dynamically set the block's value from the
system mask, the mask initialization callback of
ssref1 first gets the
Gain parameter value from the system mask and then sets the value
of the Gain block inside the subsystem reference instance.
Allow Masked Subsystems Inside a Masked Subsystem Reference to Self-Modify
Consider a self-modifiable masked subsystem file
includes a masked subsystem
Subsystem-1 includes a Gain block. Subsystem reference
SR3 and masked subsystem
Gain as the mask parameter to set the value of the
Gain block. To dynamically set the block's value from the system mask,
the mask initialization callback of
Subsystem-1 gets the
Gain parameter value from the system mask. The mask initialization
ssref2 gets the Gain parameter value
from the parent subsystem
Subsystem-1 mask and then sets the value of
the Gain block.
There are certain cases where you cannot use a callback to modify the contents of a subsystem reference instance even with a self-modifiable mask.
If you want to modify a block located inside a Subsystem Reference, you cannot use callback of a top model or block that is higher in the model hierarchy than the Subsystem Reference.
If the block you want to modify is inside a masked subsystem of a Subsystem Reference, you must use the mask callback of the parent masked subsystem. Using the callback of any other block to modify a block within a masked subsystem of a Subsystem Reference is not feasible.
Simulate a Subsystem Block Diagram with a Test Harness
A subsystem block diagram cannot be simulated like a model or subsystem. However, you can create test harnesses on a subsystem block diagram and simulate the test harness. This action helps you to check for any errors or discrepancies while editing a subsystem block diagram. You can associate more than one test harness to a subsystem file and set a default test harness for the subsystem from a set of available test harnesses.
To simulate with a test harness:
Open a subsystem block diagram.
In the Simulink toolstrip, on the Subsystem tab, click Add Test Harness.
The Create Test Harness window appears.
Specify a name for the new test harness and click OK. This becomes the default test harness.
Click Run with Test Harness on the toolstrip to run the test harness on the subsystem without opening the test harness. Click the Open Harness on Run check box, to automatically open the test harness while running it on the subsystem.
Set the Test harness using the Command line
You can set the default test harness of a subsystem block diagram using the command:
Subsystem Reference Compatibility with Previous Versions
When you export a model containing referenced subsystems to a version prior to R2019b, all the Subsystem Reference blocks are converted to independent Subsystem blocks.
Subsystem files created in R2019b cannot be exported to a prior version. For information on how to export a Simulink model to a previous version, see Export Model to Previous Version of Simulink.
Control Referenced Subsystem Programmatically
You can create a referenced subsystem, find available referenced subsystems in a model, change the referenced subsystem file in a block, and check the block diagram type of the file using a command-line interface.
Create a Referenced Subsystem
You can create a referenced subsystem using the new_system command:
Find Subsystem Reference in a Model
You can find if a model contains a referenced subsystem using the
Simulink.findBlocksOfType(bdroot, 'SubSystem',... 'ReferencedSubsystem','.',Simulink.FindOptions('RegExp',1))
You can also use the find_system command:
find_system(bdroot, 'RegExp','on','BlockType','SubSystem','ReferencedSubsystem', '.')
Both return the number of Subsystem Reference blocks in the model. By
find_system lists all the child blocks inside a subsystem
If you do not want
find_system to look inside a referenced
LookInsideSubsystemReference set to
LookInsideSubsystemReference is set to
Change the Referenced File for a Subsystem
You can change the subsystem file being referenced in a Subsystem
Reference block through command-line interface using the
set_param(gcb, 'ReferencedSubsystem', '<subsystemfilename>')
Check if the SLX or MDL File is a Subsystem Block Diagram Type
You can check if an SLX or MDL file is a subsystem block diagram type that can be placed in a Subsystem Reference block using any of these commands:
bdname.slxis a Subsystem block diagram type and
logical 0if it is not. When using this command, make sure that
This command returns
a Subsystem block diagram type. When using this command, make sure that
bdname.slx is loaded.
This command gives the entire model information where the
BlockDiagramType property is shown as
bdname.slx is a Subsystem block diagram type.
While using a referenced subsystem in a model:
To mask a referenced subsystem, use a System mask.
Do not reference a parent subsystem because it creates a reference loop.
Only the subsystem file type can be referenced by a Subsystem Reference block.
For a list of models that show Subsystem Reference capabilities, see Subsystem Reference Demos.