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.


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 create a subsystem block diagram:

  1. Open Simulink®.

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

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

Once you create the subsystem file programmatically, it appears in the MATLAB File Browser as:

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.

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.

  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.


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 and upon saving the changes the updates propagate to all the referenced instances. When you actively edit an instance of a referenced subsystem, all the other referenced instances are locked and are unavailable for edit.

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 the changes from the Save option available in the Simulation tab of the model window. The Save All drop-down gives you 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.

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.


  • 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 referenced from a library you can do so.

For more information on creating and editing System masks, see Introduction to System Mask.

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.

    test harness window

  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.

    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:


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 Simulink Version.

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

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.


This command returns Subsystem if bdname.slx is 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 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.

Related Topics