Main Content

Implement Variations in Separate Hierarchy Using Variant Subsystems

Open Model

This example shows how to configure and use a Variant Subsystem block in Simulink®. The Variant Subsystem block is a hierarchical variant block. The block allows you to encapsulate multiple implementations or variations of a system component in a separate hierarchy in the model. Each variation of the component represented within a Variant Subsystem block is referred to as a choice. Only one of the variant choices within the Variant subsystem block can be active during model execution. You can use a combination of Subsystem blocks, Model blocks, or Subsystem Reference blocks to represent the choices within the Variant Subsystem block.

For information on the block and its parameters, see Variant Subsystem, Variant Model, Variant Assembly Subsystem.

Explore the Model

  • Open the model sldemo_variant_subsystems. A variant subsystem block, Controller, encapsulates two different implementations of the controller component in the system.

  • Open the variant subsystem block, Controller. Two Subsystem blocks represent the two possible variations of the Controller component. The first choice is a Linear Controller and the second choice is a Nonlinear Controller. Note that there are no drawn connections between the blocks inside the Variant Subsystem block. Simulink automatically wires the active variant to the Inport and Outport blocks of the Variant Subsystem block during simulation and disables the inactive ports.

  • Open the Block Parameters dialog box for the Controller block. The Variant choices table lists the choices of the variant subsystem. Each variant choice in the Controller block is associated with a variant control. Here, the variant controls are the Simulink.Variant objects VSS_LINEAR_CONTROLLER and VSS_NONLINEAR_CONTROLLER. Simulink determines the active choice of the variant subsystem by evaluating the variant controls of all the choices. When a variant control evaluates to true, Simulink activates the variant choice that corresponds to that variant control and disables the inactive choices. So, while each variant choice is associated with a variant control, only one variant control must evaluate to true. This allows you to swap the active and inactive choice in the Variant Subsystem without modifying the model structure.

Configure a Variant Subsystem Block

In this model, the Controller Variant Subsystem is preconfigured with two subsystems, Linear Controller and Nonlinear Controller, as variant choices. To add more Variant Subsystem blocks to this model and configure the blocks, perform these steps:

  1. Add a Variant Subsystem block to your model using the Simulink Library Browser or the Quick Block Insert menu and name the block. This block serves as the container for the variant choices.

  2. To open the Variant Subsystem, double-click the block. The Variant Subsystem block, by default, is a template preconfigured with two Subsystem blocks to represent the variant choices.

  3. Inside the Variant Subsystem block, add Inport and Outport blocks so that they match the inputs into and outputs from the Variant Subsystem block.

  4. Name the variant choice blocks.

NOTE:

  • You can add only Inport, Outport, Subsystem, Model, and Subsystem Reference blocks inside a Variant Subsystem block. You can pass control signals through data ports.

  • When you add a Variant Subsystem block to your model, the Variant activation time parameter is set to update diagram and the Propagate conditions outside of variant subsystem parameter is set to off by default.

Types of Variant Choices in Variant Subsystem

You can add Subsystems, Simulink models, and Subsystem References as variant choices in a Variant Subsystem.

Include Subsystem Block as Variant Choice

You can add a Subsystem block as a variant choice from the Block Parameters dialog box of the Variant Subsystem or using the action bar in the Simulink Editor from inside the Variant Subsystem. Simulink creates an empty Subsystem block with the same number of input and output ports as the containing Variant Subsystem block.

a. Using Block Parameters Dialog Box

  1. Open the block parameter dialog box of the Variant Subsystem block. Right-click the badge on the Variant Subsystem block and select Block Parameters (Subsystem).

  2. The Variant choices (table of variant systems) in the block parameter dialog box shows the variant choices that you added. You can use buttons to the left of the table to add or modify elements in the table.

  3. To include a Subsystem block as a new variant choice inside the Variant Subsystem, click the Create and add a new subsystem variant choice button to the left of the Variant choices table.

  4. Open the new Subsystem block and add the model elements that represent a variant choice.

b. Using Action Bar

  1. Double-click the Variant Subsystem block.

  2. Drag a selection box around an empty area inside the Variant Subsystem block. The action bar shows subsystem insertion options that are based on the type of subsystem choices in the block.

  3. From the action bar, select the Variant Subsystem Choice option to add a subsystem block.

  4. Open the new Subsystem block and add the model elements that represent a variant choice.

NOTE:

  • When you prototype variants, you can create empty Subsystem blocks with no inputs or outputs inside the Variant Subsystem block. The empty subsystem recreates the situation in which that subsystem is inactive without the need for completely modeling the variant choice.

Include Simulink Model as Variant Choice

  1. To include a Simulink model (Model block) as a new variant choice inside the Variant Subsystem, click the Create and add a new model variant choice button to the left of the Variant choices table. Simulink creates an unresolved Model block in the Variant Subsystem block.

  2. Double-click the unresolved Model block. In the Model name box, enter the name of the model you want to use as a model variant choice and click OK.

NOTE: The referenced model must have the same number of input and output ports as the containing Variant Subsystem block. If your model has different number of input and output ports, see Represent Variant Choices That Have Different Interfaces.

Include Subsystem Reference as Variant Choice

  1. To include a Subsystem Reference as a new variant choice inside the Variant Subsystem, add a Subsystem Reference block using the Simulink Library Browser or the Quick Block Insert menu. Simulink creates an empty Subsystem Reference block in the Variant Subsystem block.

  2. Double-click the Subsystem Reference block. In the Block Parameters dialog box, specify the subsystem block diagram file and click OK.

Choose a Variant Control Mode

You must associate each variant choice in a model with a variant control that determines if the choice is active or inactive. You can choose the mode in which you want to specify the variant controls using the Variant control mode block parameter. The Variant control mode parameter for the Controller block in this example is set to expression. In this mode, you can specify the variant control for a choice as a Boolean condition expression, a Simulink.Variant object, the default variant choice, or an empty choice. For information on the different types of variant control modes, see Variant Control Modes in Variant Blocks.

Use Variant Controls to Activate and Switch Between Variant Choices

In this model, the variant control for each choice is defined using two Simulink.Variant objects, VSS_LINEAR_CONTROLLER and VSS_NONLINEAR_CONTROLLER. To see the definitions of the Simulink.Variant objects used in this model, click Model Settings > Model Properties > PreLoadFcn callback. When you open the model, the PreLoadFcn callback runs and creates the objects in the base workspace of the model.

A Simulink.Variant object allows you to encapsulate a Boolean condition expression that activates a specific variant choice when it evaluates to true. You can build the condition expression using one or more variant control variables, which are defined as MATLAB® variables or Simulink.Parameter objects in the base workspace or a data dictionary. In this example, a normal MATLAB variable, VSS_MODE, is used to build the condition expression for the Simulink.Variant objects.

To associate the Simulink.Variant objects, VSS_LINEAR_CONTROLLER and VSS_NONLINEAR_CONTROLLER, with the variant choices of the Controller block:

  • In the Block Parameters dialog box, enter the name of the object in the Variant control expression column for each choice.

  • The Condition column automatically shows the boolean condition that the Simulink.Variant object represents.

Since VSS_MODE is set to 2 , the NonLinear Controller gets activated by default. To switch the active choice to Linear Controller, set VSS_MODE = 1 in the base workspace and simulate the model.

Specify Default Variant Choice: When the variant control mode is set to expression, you can specify at most one variant choice as the default for the model. Simulink evaluates the variant controls and verifies that only one variant choice is active during simulation. If none of the variant controls evaluate to true, Simulink uses the default variant for simulation and code generation. To set a variant choice as the default, select the (default) keyword in the Variant control expression column for that choice.

Specify Empty Variant Choice: If you added an empty variant choice, you can either specify a variant activation condition for the choice or comment out the existing variant condition by placing a % symbol before the condition. If this variant choice is active during simulation, Simulink ignores the empty variant choice. However, Simulink continues to execute block callbacks inside the empty variant choices.

For information on other ways to define variant controls, see Use Variant Control Variables in Variant Blocks.

Choose a Variant Activation Time

The Variant activation time that you specify for the Variant Subsystem block determines the stage when Simulink sets the active choice for the block. This parameter also determines how the active and inactive choices participate in the simulation and code generation workflows.

For the Controller block, this parameter is set to update diagram. So, Simulink sets the active choice at the start of the model compilation stage and the inactive choices are removed. When you execute the model, only the active choice is analyzed for consistency. Generated code contains only the active choice. For information on other variant activation times, see Activate Variant During Different Stages of Simulation and Code Generation Workflow.

Represent Variant Choices That Have Different Interfaces

In this example, the two variant choices, Linear Controller and NonLinear Controller, have the same number of input and output ports as the Controller variant subsystem block. The blocks that represent the variant choices can also have input and output ports that differ in number from the input and output ports on the parent Variant Subsystem block. The Variant Subsystem block can adapt its interface based on the activeness of the underlying blocks. This allows you to model component variations that do not have a similar interface. In this case, these conditions must be satisfied by the variant choices:

  • The Allow flexible interface parameter must be set to 'on'.

  • The variant choices must have same set of inports as the Variant Subsystem container block or it must be a subset of ports on the container block.

  • The variant choices must have same set of outports as the Variant Subsystem container block or it must be a subset of ports on the container block.

  • If the Variant Subsystem container block has control ports, the type of control port blocks in all the variant choices must be same as the Variant Subsystem block. For example, you cannot use Enabled Subsystem and Function-Call Subsystem blocks as choices within a Variant Subsystem block. The control port on the Variant Subsystem block and the corresponding control ports on its variant choices must have the same name. For example, if the name of the control port on the Variant Subsystem is fcn, then the name of the corresponding control ports on all its variant choices must also be fcn.

For an example, see Adaptive Interface for Variant Subsystems.

Allow Zero Active Variant Controls for Variant Subsystem

The Allow zero active variant controls parameter on the Variant Subsystem block determines whether the block allows simulation even if none of the variant choices are active. When you select this option and if there is no active variant choice, Simulink simulates the model without any active variant choice in the Variant Subsystem. When you clear the option, Simulink generates an error when there is no active variant choice. This parameter is available only if there are no (default) variant choices in the Variant Subsystem and if you set Variant control mode to expression.

Propagate Variant Conditions Outside Variant Subsystem

During simulation, Simulink automatically propagates variant conditions from variant blocks to connecting blocks to determine which components of the model remain active. For a variant subsystem, the variant conditions defined on the choices do not propagate outside the Variant Subsystem block by default. To enable this, you can set the Propagate conditions outside of variant subsystem parameter on the Variant Subsystem block.

When you select the Propagate conditions outside of variant subsystem parameter, Simulink propagates the variant condition of the underlying blocks to the Variant Subsystem container block so that the subsystem can adapt its interface to the state of the underlying blocks. Ports that are mapped to the ports on the active choice becomes active. Ports that are mapped to the ports on the inactive choice becomes inactive. Selecting this option ensures that the components outside of the Variant Subsystem are aware of the active and inactive state of blocks within the Variant Subsystem block. For more information, see Propagate Variant Conditions to Define Variant Regions Outside Variant Subsystems.

Convert to Variant Subsystem Block

In the Simulink Editor, you can convert these blocks to a Variant Subsystem block:

  • Subsystem block

  • Model block

  • Conditionally executed subsystems

To do so, right-click the block and in the context menu click Subsystem & Model Reference > Convert to > Variant Subsystem.

You can also convert these blocks to a Variant Subsystem block programmatically using the Simulink.VariantUtils.convertToVariantSubsystem method.

See More