matlab subsystem reference block cover image

Raptor Power User Tip: Subsystem Reference

Chris Beecher Blog

In MATLAB R2019b, MathWorks released a new Simulink feature called Subsystem Reference. It is a modeling construct that is good for componentization and is similar to libraries and Model Reference but has a slightly different use case.

An Introduction to Subsystem Reference from Mathworks:

Subsystem reference allows you to save the contents of a subsystem in a separate SLX 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 SLX file in which the subsystem is stored and all the referenced instances of that file are synchronized.

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.

Libraries and Model Reference

This new feature sounds very similar to Libraries and Model Reference, but they are each slightly different and provide for difference use cases:

Libraries are intended for a large amount of reuse for a small amount of functionality and stable implementations. The Raptor Blockset library uses this functionality. When composing large applications where a team needs to make changes to different areas of the model, libraries can be used, but there are a few problems that can occur:

  1. It is easy to disable or parameterize a link that disconnects the local implementation from the reference implementation creating future maintenance complications.
  2. You can’t perform an update (CTRL+D) on a library so making frequent edits can be a challenge.

Model Reference is a standalone file that has very rigid architectural boundaries in both simulation and code generation. They can provide some benefits in simulation and code generation because the generated files don’t need to be rebuilt every time. However, Model Reference has some challenges:

  1. Signal properties must be specified at the boundaries and thus cannot be inherited from its connecting blocks.
  2. Code customization is difficult due to the rigid constraints and limits on flexibility (Raptor-Dev does not support Model Reference due to these constraints).

Subsystem Reference is a blend of these two. It is stored in a separate file, but it does not have rigid architectural constraints of Model Reference or the added overhead of minor changes to a model like libraries. From a modeling standpoint, the subsystem reference will open in the model browser and edits (and updates) can be performed when editing the reference from the full model.

It should be noted that unlike libraries, there is no “disable link” feature on a subsystem reference. All instances of the subsystem reference will share an implementation.

More comparisons between these different constructs can be found on the MathWorks website here:

How Subsystem Reference Works

Starting with the VeeCAN 500 template application:

>> raptor_create_project(‘SubsystemReferenceRaptorDemo’, ‘DISP-VC500-1904’)

Navigate to this subsystem:

subsystemLet’s create a Subsystem Reference for the Screens subsystem thus allowing two developers to edit the main model and the subsystem in parallel.

First, right-click on the subsystem and select the following:


You will be prompted for the name of the file to create for this subsystem. For this example, “ScreensComponent” was chosen.

Therefore, the model looks like this:

Note the triangles in the upper left and lower right. This signifies that the subsystem is a Subsystem Reference. Double-clicking on the block opens the contents of the new Subsystem Reference file. Any changes made in this view will be propagated to the full parent model.

More importantly, the file is stored separately and can be revision controlled separately from the main model.

Download the sample files created for this Raptor User Tip follow this link.

Be Sure You Know This About Subsystem Reference

  1. This is a new feature in MATLAB R2019b, so there may be some wrinkles.
  2. As noted earlier, all instances will share the same implementation so if the reference is shared between two applications then both applications will get the changes.
  3. If the Subsystem Reference file is opened, it behaves like a library (cannot update/sim/code gen). It needs the context of the full application for these features. ScreensComponent
  4. Inputs and Outputs can be inherited so adding a signal specification block to protect the Subsystem Reference from inheriting unexpected data types would be a good idea.

Learn how Raptor helps you take control of your vehicle development from prototype to production. Download the eBook