Main Content

Subsystem Reference

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.

Note

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 Subsystem Reference block. The block has triangles in two opposite corners and the block diagram of the underlying subsystem in the center.

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.

Note

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:

  1. Open Simulink®.

  2. On the Start Page, in the Simulink product group, click Blank Subsystem.

    Menu of Simulink products with the option to launch a blank subsystem highlighted.

    Alternatively, in the Simulink toolstrip, on the Simulation tab, select New and click Blank Subsystem. A Subsystem window opens.

  3. Add content and click Save .

  4. 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 mysubsystem programmatically, use the command:

sub = new_system("mysubsystem","Subsystem")
open_system(sub)
Once you create the subsystem file programmatically, it appears in the MATLAB File Browser as: MATLAB file browser showing the current folder with the file mysubsystem.slx highlighted.

For more information on controlling subsystem files programmatically, see Control Referenced Subsystem Programmatically.

Reference a Subsystem File in a Model

  1. Open a model in which you want to reference a subsystem block diagram.

  2. 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.

  3. 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.

  4. 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.

A model with two subsystem blocks named as Controller and Plant.

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:

  1. Select the Controller Subsystem block and on the Subsystem Block tab, select Convert and click Convert to Subsystem Reference. A dialog box opens.

    Convert to Subsystem Reference dialog box

  2. 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.

    Model with the Controller subsystem block converted to a referenced subsystem.

Tip

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.

  • Use the find_system, get_param, or set_param commands. 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.

View of two Subsystem Reference instances with the open and locked for editing badges in bottom left corner. One instance is being edited and the other instance is locked and greyed out.

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:

  1. Create a new data dictionary or open an existing data dictionary.

  2. In the data dictionary, define all data objects that you will use, such as variables, bus objects, and enumeration types.

  3. Save the data dictionary.

  4. 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:

  1. Open the subsystem file to be masked.

  2. 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.

  3. Add mask parameters and click OK.

Note

  • 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_param in 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.

Code tab of System Mask Editor of the subsystem file ssref1 with the option 'Allow mask initialization code to modify the subsystem's content' selected.

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 self-modifiable.

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 ssref1 that 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.

Model using a self-modifiable masked subsystem file, ssref1, with a Gain block with Gain parameter set to 10, and two Subsystem Reference instances, SR1 and SR2, that reference the subsystem file ssref1. The mask dialog box of SR1 shows the Gain parameter set to 10. The System Mask Editor shows the contents of instance SR1 and the mask initialization code of the subsystem file.

Allow Masked Subsystems Inside a Masked Subsystem Reference to Self-Modify

Consider a self-modifiable masked subsystem file ssref2 that includes a masked subsystem Subsystem-1. Further, Subsystem-1 includes a Gain block. Subsystem reference instance SR3 and masked subsystem Subsystem-1 use 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 callback of ssref2 gets the Gain parameter value from the parent subsystem Subsystem-1 mask and then sets the value of the Gain block.

Model using a self-modifiable subsystem file ssref2 that includes a masked subsystem Subsystem-1 and has a Gain block with Gain parameter set to 60. Two Subsystem Reference instances, SR3 and SR4, reference the subsystem file ssref2. The mask dialog box of SR3 shows the Gain parameter set to 60. The masked subsystem block Subsystem-1 is shown with its mask dialog box, with Gain parameter set to 60. A Mask Editor window shows the mask initialization code of the subsystem file ssref2. Another Mask Editor window shows the mask initialization code of the subsystem Subsystem-1.

Considerations

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:

  1. Open a subsystem block diagram.

  2. In the Simulink toolstrip, on the Subsystem tab, click Add Test Harness.

    The Create Test Harness window appears.

    The Create Test Harness dialog box.

  3. Specify a name for the new test harness and click OK. This becomes the default test harness.

  4. 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.

    Simulink toolstrip with test harness options.

Set the Test harness using the Command line

You can set the default test harness of a subsystem block diagram using the command:

set_param('<subsystemfilename>','DefaultTestHarness','<testHarnessName>');

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:

new_system(subsystemfilename,'SubSystem')

Find Subsystem Reference in a Model

You can find if a model contains a referenced subsystem using the Simulink.findBlocksOfType function:

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 default, find_system lists all the child blocks inside a subsystem reference instance.

If you do not want find_system to look inside a referenced subsystem, use find_system with LookInsideSubsystemReference set to off. By default, LookInsideSubsystemReference is set to on.

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 command:

set_param(gcb, 'ReferencedSubsystem', '<subsystemfilename>')
This command changes the file being currently referenced by the Subsystem Reference block and replaces it with the new subsystem file you specify.

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:

bdIsSubsystem(bdname)
This command returns logical 1 if bdname.slx is a Subsystem block diagram type and logical 0 if it is not. When using this command, make sure that bdname.slx is loaded.

get_param(bdname,'BlockDiagramType')

This command returns Subsystem if bdname.slx is a Subsystem block diagram type. When using this command, make sure that bdname.slx is loaded.

Simulink.MDLInfo(bdname)

This command gives the entire model information where the BlockDiagramType property is shown as Subsystem if bdname.slx is a Subsystem block diagram type.

Best Practices

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.

Related Topics