Create and Use Referenced Subsystems in Models

What Is a Subsystem Reference?

In component-based modeling, you can divide a Simulink^® model into smaller components, such as subsystems, subsystem references, and model references. Each component has a well-defined scope and performs a certain functionality. For more information on different Simulink components, see High-Level Component Selection Guidelines.

A subsystem reference enables you to store a subsystem in a separate file and reference it in a model. This is particularly useful when you have to reuse a subsystem multiple times in a model. This helps in maintaining consistency and reducing redundancy in the model, as any changes you make to the original subsystem automatically propagate to all its referenced instances. These instances exhibit identical execution behavior as the original subsystem.

For example, consider the front and rear windshield wipers of a car. The front and rear wipers have the same behavior but use different rain sensor inputs to control their speeds. Instead of designing multiple subsystems that contain the same logic to control the speeds of the windshield wipers, you can save a single subsystem to control the wiper speed in a separate file and reuse this subsystem in your model by passing different inputs to it. This approach promotes component reuse, simplifies model maintenance, and enhances modularity in your design.

To use a subsystem reference, save the subsystem in a separate file, known as the subsystem file, in either .slx or .mdl format. Then, reference this subsystem file in a model using a Subsystem Reference block. When you reference a subsystem file in a model, it forms a referenced subsystem. A Subsystem Reference block has triangles in opposite corners of the block icon with the subsystem filename in the center.

Advantages of Using Subsystem Reference

Using subsystem references in component-based modeling provides several advantages:

• Modular development — You can develop and test a subsystem reference as an individual component, separate from the models that use it.

• Inclusion by reference — You can reference a subsystem file multiple times without making redundant copies.

• Automatic synchronization — When you edit and save a subsystem reference instance, the changes are saved in the subsystem file and all the referenced instances of that file are synchronized.

• Dynamic interface — Subsystem reference adapts to the context of the parent model and does not require a defined input-output interface.

• Incremental loading — Simulink loads a subsystem reference only when it is needed, which speeds up model loading.

• Reduced file conflict — Subsystem reference isolates the subsystem components in separate files and reduces conflict during parallel access.

• Instance-specific customization — You can customize and debug subsystem reference instances individually and maintain the same execution behavior as the original subsystem.

Reference a Subsystem File in a Model

This example shows you how to create and reference a subsystem file in a model. The example also demonstrates these capabilities of subsystem references:

• Instance-specific customization using a system mask.

• Behavior adaptation based on the properties of the input data.

• Instance-specific debugging.

• Automatic synchronization in multiple subsystem reference instances while editing and saving.

• Individual testing of subsystem files.

Create a Subsystem File

1. Open an empty subsystem window using any of these methods:

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

• In the Simulink toolstrip, on the Simulation tab, select New and click Blank Subsystem.

• Use the new_system command:

sub = new_system("slexTimesK","Subsystem");
open_system(sub);

2. Add content to the subsystem. Inside the subsystem, add Inport, Gain, and Outport blocks and connect them as shown.

3. Save the subsystem file as slexTimesK.

You also have the option to convert an existing Subsystem block within a model or library into a Subsystem Reference block. When you convert a Subsystem block, it creates a subsystem file for the Subsystem Reference block. For more information, see Convert Subsystem to a Referenced Subsystem.

Reference a Subsystem File in a Model

Subsystem references allow you to reference the same subsystem file multiple times in a model without creating redundant copies.

1. Create a new model called slexSubsystemReferenceContextAdapting. Alternatively, you can open a model in which you want to reference the subsystem file.

2. Add a Subsystem Reference block using the Simulink Library Browser or the Quick Block Insert menu.

3. In the Simulink toolstrip, on the Subsystem Block tab, enter the name of the subsystem file slexTimesK in the File Name field, or click Browse and navigate to the subsystem file.

Alternatively, you can double-click the Subsystem Reference block and enter the subsystem file name.

This creates a subsystem reference instance in the model that references the subsystem file slexTimesK. Name this instance SSREF1.

4. To reference the same subsystem file in another subsystem reference instance SSREF2, make a copy of the Subsystem Reference block SSREF1.

Customize Subsystem Reference Instances

You can set a different behavior for each subsystem reference instance and simultaneously use the shared characteristics and functionality of the subsystem file. To enable instance-specific customization, create a system mask for the subsystem file. When you create a system mask for the subsystem file, all its referenced instances share the same mask parameters. You can assign different values to these mask parameters using the Mask dialog box of each referenced instance.

1. Add a System Mask to the subsystem file. In the Simulink toolstrip of slexTimesK, on the Subsystem tab, click Create System Mask. The Mask Editor window opens. Add a new mask parameter and set it to k, the Gain value. Set the Prompt to Input for Gain. Save the mask.

For more information on masking a subsystem file, see Mask a Subsystem File.

2. Save the subsystem file slexTimesK.

3. Edit the mask parameter values of the subsystem reference instances in the model slexSubsystemReferenceContextAdapting. Double-click the Subsystem Reference block SSREF1 and enter the value 5 in the Input for Gain box of the mask dialog box. Similarly, set the mask parameter value of SSREF2 to 10.

Dynamic Behavior of Subsystem Reference Based on Input Data

A subsystem reference adapts its behavior according to the properties of its input data. You do not need to define the signal attributes and you can directly use input signals of different dimensions and data types for each subsystem reference instance.

1. In the model slexSubsystemReferenceContextAdapting, set different input signals for both subsystem reference instances:

• Use a Constant block with scalar value 1 as an input to SSREF1.

• Use a Constant block with vector value [1,2,3,4] as an input to SSREF2.

2. To view the output, add Display blocks to both subsystem reference instances.

3. Simulate the model.

Observe that the subsystem reference instances SSREF1 and SSREF2:

• Use mask parameter values of 5 and 10, respectively, which are set using their mask dialog boxes.

• Adapt to have one dimension and four dimensions, respectively, in the output.

Instance Specific Debugging

As each subsystem reference instance is driven by its own set of inputs in the model, you must debug and analyze each instance individually.

To debug the subsystem reference instance SSREF1:

1. In the model, select the subsystem reference SSREF1 and on the Subsystem tab, click Look Under Mask.

2. Inside SSREF1, select the output signal of the Gain block and set a breakpoint. Set the breakpoint condition to pause the simulation if the signal value is greater than 2. For more information to set breakpoints, see Debug Simulation Using Signal Breakpoints.

3. Save SSREF1.

4. Simulate SSREF1 to debug and analyze the behavior of the subsystem reference instance.

When you set a breakpoint in the subsystem reference instance SSREF1, the other subsystem reference instance SSREF2 in unaffected. This enables you to debug SSREF2 independently.

Edit and Save Subsystem Reference

In a model containing multiple instances of the same subsystem file, you can edit any instance. After you edit and save a subsystem reference instance, the changes are automatically saved in the subsystem file. These changes are also reflected in any other open windows that currently display instances of the same subsystem file. The remaining subsystem reference instances are updated when you:

• Open, simulate, or update a model containing the subsystem reference instances.

• Use the find_system , get_param , or set_param commands. For more information on using these commands, see Control Subsystem Reference Programmatically.

When you actively edit a subsystem reference instance, all the other instances may be locked and unavailable for editing. You must save the changes to unlock the other instances. For some changes to a subsystem reference instance, the changes automatically propagate to the subsystem file and other loaded subsystem reference instances without locking. For these changes, while editing an instance you can simultaneously observe the changes in other instances. Automatic synchronization is applicable when you:

• Add or delete a block.

• Modify block name, parameter, position, or size.

• Modify a signal label.

• Add or modify annotations.

Follow these steps to edit an instance of the subsystem file slexTimesK:

1. In the model, navigate inside the subsystem reference instance SSREF1 and add a Scope block.

A badge at the bottom left corner indicates whether the instance is available for editing.

2. Right-click the badge and select Go to instance to view a list of all the active instances of the same subsystem file. Select the option to open the instance SSREF2. Observe the newly added Scope block. For this modification, automatic synchronization occurs.

3. In the subsystem reference instance SSREF1 connect the Inport and Scope blocks.

4. Go to the subsystem reference instance SSREF2. For this modification, SSREF2 is dimmed and cannot be edited.

Once you have edited a subsystem reference instance, you can save or discard your changes.

To save the changes, save the subsystem file or use these options from the drop-down menu of the Save All button on the Simulation tab of the model window.

• Save All — Save all the updates in the current model.

• Save Referenced Files > Save Specific File — 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. A dialog box appears asking whether to save the subsystem file before closing. Click No. This action reverts changes in all the instances of the subsystem file.

Simulate a Subsystem File with a Test Harness

A subsystem file cannot simulate like a model or a subsystem. Instead, you must associate a test harness with the subsystem file and then simulate the subsystem file using the test harness. Using a test harness enables you to:

• Check for any errors or discrepancies while editing a subsystem file.

• Enable use of subsystem reference instances in only tested environments in a model. For information on unit testing, see Define Subsystem Reference Interfaces Using Test Harnesses and Generate Reusable Code.

You can associate more than one test harness with a subsystem file and set a default test harness from a set of available test harnesses.

Follow these steps to develop and test a subsystem file as an individual component, separate from the models that use it:

1. In the Simulink toolstrip of the subsystem file slexTimesK, on the Subsystem tab, click Add Test Harness. The Create Test Harness dialog box opens.

2. To create the test harness, specify its name and click OK. Save the test harness. For more information on test harness, see Create a Test Harness (Simulink Test).

3. Edit the subsystem file slexTimesK and introduce an error by deleting the signal line between the Gain block and the Outport block.

4. Click Run with Test Harness on the Simulink toolstrip to simulate the subsystem file using the test harness. You can also select the Open harness on run check box, to automatically open the test harness while running.

Observe the warnings displayed in the Diagnostic Viewer.

Subsystem Reference Requirements

Do not reference a parent subsystem from a subsystem file because it creates reference loop.

Subsystem Reference Compatibility with Previous Versions of Simulink

When you export a model containing subsystem reference components to a version of Simulink prior to R2019b, all the Subsystem Reference blocks are converted to independent Subsystem blocks. This conversion is done because the subsystem reference components were not available before R2019b. Also, 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 of Simulink, see Export Model to Previous Version of Simulink.