Implement Variations in Separate Hierarchy Using Variant Subsystems
This example shows the use of a Variant Subsystem, Variant Model, Variant Assembly 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 present within the 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.
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
Controllercomponent. The first choice is a
Linear Controllerand 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
Controllerblock. The Variant choices table lists the choices of the variant subsystem. Each variant choice in the
Controllerblock is associated with a variant control. 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:
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.
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.
Inside the Variant Subsystem block, add Inport and Outport blocks so that they match the inputs into and outputs from the Variant Subsystem block.
Name the variant choice blocks.
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 diagramand the Propagate conditions outside of variant subsystem parameter is set to
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
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).
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.
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. Simulink creates an empty Subsystem block inside the Variant Subsystem block. The new block has the same number of input and output ports as the containing Variant Subsystem block.
Open the Subsystem block and add the model elements that represent a variant choice.
You can use conditionally executed subsystems such as Enabled, Triggered, Reset, and the Function-Call subsystems as variant choices within the Variant Subsystem block. For more information, see Use Variant Subsystem Blocks with Conditionally Executed Subsystems.
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
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.
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.
Include Subsystem Reference as Variant Choice
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.
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
The Variant control mode parameter for the
Controller block 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
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.
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 global workspace. In this example, a normal MATLAB variable,
VSS_MODE, is used to build the condition expression for the
To associate the
VSS_NONLINEAR_CONTROLLER, with the variant choices of the
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
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.
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. You can also have different number of inports and outports for variant choices inside a 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. These conditions must be satisfied by the variant choices:
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.
The variant choices must have same set of control port as the Variant Subsystem container block.
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
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 Outside Variant Subsystems.