Variant Sink
Route amongst multiple outputs using variants
Libraries:
Simulink /
Signal Routing
Description
The Variant Sink block enables you to include multiple implementations of a component on the destination (sink) of a signal in a single layer.
For example, suppose you want to simulate this model to control the speed of the car windshield wiper by using different rain sensors. The Variant Source block switches between different rain sensors. The control logic uses this information to output the result to the Variant Sink block. The Variant Sink then switches between the wiper motor model during simulation and the command to the sensor during code generation. The variant blocks switch between choices based on the Types of Variant Control Modes in Variant Blocks you select. For more information, see Introduction to Variant Controls.
Note
At most, one variant choice connected to output port of the Variant Sink block is active during simulation.
The Variant Sink block has only one input port and one or more output ports. You can connect the varying choices to the output port of the block so that, at most, one choice is active during model execution.
The Variant Sink block is associated with a Variant control mode and a Variant activation time. The variant control mode determines how to specify the variant control. The variant activation time determines a time to activate the choices and to decide whether to include only the active choice or both active and inactive choices in the generated code. During simulation, Simulink® connects the active choice directly to the input port of the Variant Sink block and ignores the inactive choices.
Using a Variant Sink block allows you to:
Propagate variant conditions throughout the model.
Visualize all possible implementations of variant choices in a single layer of your model, which improves model readability.
Simulink eliminates inactive blocks throughout the model, which improves runtime performance. If all the variant choices are inactive, Simulink removes the variant region completely from your model.
Variant sources and sinks provide variant component interfaces that you can use to quickly model variant choices.
The color and icon of the variant badge on the block icon changes depending on the values of the Variant activation time, Variant control mode, and Allow zero active variant controls parameters set on the block. For more information, see Variant Badges.
Examples
Variant Source and Variant Sink Blocks
Consider the slexVariantSourceAndSink
model containing two Variant Source blocks Variant Source1
and Variant Source2
, and a Variant Sink block. The variant conditions at the inports and the outports of the Variant Source and the Variant Sink blocks determine the activation and deactivation of the blocks connected to them. V
and W
are the variant control variables and are defined in the PostLoadFcn callback of the model.
Limitations
The Variant Sink block works with time-based, function-call, and action signals. You cannot use SimEvents®, Simscape™ Multibody™, or other non-time-based signals with these blocks.
Ports
Input
Port_1 — Input signal
scalar | vector | matrix
Input signal to be connected to the active output port.
You can auto insert inport on the Variant Sink block by hovering the mouse over the block side or by dragging the signal near the block boundary. You can delete the port by either clicking delete on the keyboard or with a mouse click.
Data Types: single
| double
| half
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| Boolean
| fixed point
| enumerated
| bus
| struct
Output
Port_1 — Output from first variant
scalar | vector | matrix
Output signal from the first variant. The variant control that evaluates to
true
determines which output port is
active.
You can auto insert outport on the Variant Sink block by hovering the mouse over the block side or by dragging the signal near the block boundary. You can delete the port by either clicking delete on the keyboard or with a mouse click.
Data Types: single
| double
| half
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| Boolean
| fixed point
| enumerated
| bus
Port_N — Output from Nth variant
scalar | vector | matrix
Output signal from the Nth variant. The variant
control that evaluates to true
determines which
output port is active.
Data Types: single
| double
| half
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| Boolean
| fixed point
| enumerated
| bus
Parameters
Variant control mode — Variant control mode
expression
(default) | label
| sim codegen switching
The variant control that determines the active variant choice can be any of these types.
expression
— The software chooses the active variant based on the evaluation of the variant conditions. When a condition expression evaluates totrue
, the corresponding variant choice becomes active. When a condition expression evaluates tofalse
, the corresponding variant choice becomes inactive. See Switch Between Choices Using Condition Expressions in Variant Blocks.label
— The software chooses the active variant based on the name of the variant. The variant control is a string and does not require you to create any variable in any workspaces. See Switch Between Choices Using Labels in Variant Blocks.sim codegen switching
— Automatically switch between the variants for simulation and code generation workflows without creating any workspace variable. When you simulate a model, the software automatically chooses thesim
branch as the active choice. Similarly, when you do a software-in-the-loop (SIL) or processor-In-Loop (PIL) simulation, generate code, or use external mode, the software automatically chooses thecodegen
branch. See Switch Between Choices for Simulation and Code Generation Workflows Without Using Control Variables in Variant Blocks.
For more information on variant control modes, see Introduction to Variant Controls. For a comparison between different types of variant control modes, see Compare Different Types of Variant Control Modes in Variant Blocks.
Dependencies
The availability of different variant activation times depends on the type of the Variant control mode that you specify. The Variant activation time parameter determines the time when the software sets the active choice. The parameter also determines which variability to include in the generated code. This table explains the variant activation time supported by each variant control mode.
Variant activation time | |||||
---|---|---|---|---|---|
Variant control mode | update diagram | update diagram analyze all
choices | code compile | startup | runtime |
expression | ✓ | ✓ | ✓ | ✓ | ✓ |
label | ✓ | x | x | x | x |
sim codegen switching | ✓ | ✓ | x | x | x |
Programmatic Use
Block Parameter:
VariantControlMode
|
Type: character vector |
Values:
'expression' | 'label' | 'sim
codegen switching' |
Default:
'expression'
|
Variant activation time — Time when software chooses active variant choice
update diagram
(default) | update diagram analyze all choices
| code compile
| startup
| runtime
| inherit from Simulink.VariantControl
This parameter determines which variability to include in the simulation and code generation workflows. For more information, see Activate Variant During Different Stages of Simulation and Code Generation Workflow.
update diagram
— When you execute the model, only the active choice is included in the simulation and the code generation workflow. Generated code contains only the active choice.update diagram analyze all choices
— When you execute the model, both active and inactive choices are analyzed for consistency across the model. However, only the active choice is included in the simulation and the code generation workflow. Generated code contains only the active choice.code compile
— When you execute the model, both active and inactive choices are analyzed for consistency across the model, and all choices are included in the simulation and the code generation workflow. Generated code contains both the active and inactive choices enclosed in the preprocessor conditionals#if
and#elif
. However, the executable built from the generated code contains only active choice.startup
— When you execute the model, both active and inactive choices are analyzed for consistency across the model, and all choices are included in the simulation and the code generation workflow. With this option, you can improve the speed of iterative simulations using fast restart. For more information, see Run Iterative Simulations Without Recompiling Model for Variant Systems Using Fast Restart. Code generated from the model contains both the active and inactive choices that are enclosed in regularif
conditions. The executable built from the generated code also contains both active and inactive choices.runtime
— When you execute the model, the active variant can switch during simulation or execution of the generated code by using the Parameter Writer block. Place a Parameter Writer block inside a conditionally executed subsystem or in an Initialize Function block, a Reinitialize Function block, a Reset Function block. For more information on the blocks, see Event Functions. You can use the Parameter Writer block to write to block parameters, model workspace variables, and base workspace variables. All modeling patterns supported by the Parameter Writer block are valid for run-time activation. For more information, see Common Uses of Parameter Writer Block.inherit from Simulink.VariantControl
— When you execute the model, the block inherits the activation time from its variant control variables of typeSimulink.VariantControl
. If a variant block has multiple variant control variables of typeSimulink.VariantControl
, then all those variables must have the same activation time.
The table compares the different variant activation times based on conditional code, variant switching, handling of states, and fast restart support.
update diagram or update diagram
analyze all choices | code compile | startup | runtime | |
---|---|---|---|---|
Generated conditional code | Inactive conditional code is not available. | Conditional code is present inside preprocessor macros. The inactive choice code is eliminated when generated code is compiled. | Conditional code is generated as part of an
if-elseif-else statement. The variant control
variable value cannot be modified during execution. | Conditional code is generated as part of an
if-elseif-else statement. The variant control
variable value can be modified during execution. |
Variant switching during simulation or code execution | Not supported. | Not supported. | Supported at startup (before simulation start at t = 0). | Supported. The active variants are switched by changing the variant control variable using the Parameter Writer block. |
Explicit setting of held or reset option for states | Not supported. States are reset for inactive blocks. | Not supported. States are reset for inactive blocks | States cannot be changed during simulation. In the generated code, if you attempt to change the variant, states are in held state. | States are held by default. Reset states explicitly through State Writer blocks. Read blocks with states by using the State Reader block and transfer to another choice by using the State Writer block. |
Executable size | Smaller size. Code is not generated for the inactive variant. | Smaller size. The inactive variant code is removed during compilation. | Comparatively larger size. Both active and inactive variant code is available for startup switching. | Comparatively larger size. Both active and inactive variant code is available for run-time switching. |
Fast restart support | Not supported. | Not supported. | Supported. | Supported. |
Dependencies
The availability of different variant activation times depends on the type of the variant control mode that you specify. The Variant activation time parameter determines when the software sets the active choice. The parameter also determines which variability to include in the generated code. This table explains the variant activation time supported by each variant control mode.
Variant activation time Variant control mode update diagram
update diagram analyze all choices
code compile
startup
runtime
expression
✓ ✓ ✓ ✓ ✓ label
✓ x x x x sim codegen switching
✓ ✓ x x x To enable switching of active variant choice of the Variant Subsystem block using the
runtime
activation time, you must use the Parameter Writer block. Set the Destination parameter of the Parameter Writer block based on the location of your variant control variable and select Validate parameter :Block parameter
— Control variable is a mask parameter in a subsystem.Model workspace variable
— Control variable is located in the model workspace.Base workspace variable
— Control variable is located in the base workspace or a data dictionary.
For example, you can create a mask parameter
V
in a subsystem and use it in a variant condition expression for a variant control. The Parameter Writer block writes to the value ofV
in the variant control condition.
Programmatic Use
Block Parameter:
VariantActivationTime
|
Type: character vector |
Values:
'update diagram' | 'update diagram analyze all
choices' | 'code compile' |
'startup' | 'runtime' |
Default:
'update diagram'
|
Port and associated conditions — Table of variant choices, variant controls, and conditions
empty table (default)
The table has a row for each variant choice connected to the output port of the Variant Sink block. If there are no variant choices, the table is empty.
You can use buttons to the left of the Port and associated conditions table to modify the elements in the table.
To... | Click... |
---|---|
Add a new output port: Create a new output port as a variant choice and add an entry for the new choice in the table. | |
Delete selected port: Delete the selected variant choice from the block and its entry from the table. | |
Create/Edit selected variant object: Create or edit a
Note For a model that uses the base workspace, this
operation creates the
|
Port — Number of connected output port
no default
Number of the output port that is connected to one variant choice upstream of the Variant Sink block. This value is read-only.
Click to add a port or to delete an existing one.
Variant control label — Name of choice in label
mode
true
or
false
(default) | string
A name for a choice, specified as a string.
Dependencies
To enable this parameter, set Variant control
mode to label
.
Programmatic Use
To set the block parameter value programmatically, use
the set_param
function.
To get the block parameter value
programmatically, use the get_param
function.
Parameter: | VariantControls |
Values: | variant controls that are associated with variant choices |
Data Types: | char |
Example: set_param(gcb, 'VariantControls', {'A == 1','A ==
2'})
, where gcb
is the
Variant Sink or Variant Source
block.
Example: get_param(gcb, 'VariantControls')
,
where gcb
is the Variant Sink or
Variant Source block.
Variant control switch — Variant choices for simulation and code generation workflows
(sim)
| (codegen)
Specify (sim)
to activate the corresponding variant
choice during simulation. Specify (codegen)
to activate
the corresponding variant choice while performing code generation workflows
such as SIL, PIL, external mode, and so on.
Dependencies
To enable this parameter, set Variant control
mode to sim codegen
switching
.
Programmatic Use
To set the block parameter value programmatically, use
the set_param
function.
To get the block parameter value
programmatically, use the get_param
function.
Parameter: | VariantControls |
Values: | variant controls that are associated with variant choices |
Data Types: | char |
Example: set_param(gcb, 'VariantControls',
{'(sim)','(codegen)'})
, where gcb
is the Variant Sink or Variant Source
block.
Example: get_param(gcb, 'VariantControls')
,
where gcb
is the Variant Sink or
Variant Source block.
Variant control expression — Condition expression that determines the active choice
true
or false
(default) | boolean condition expression | a Simulink.VariantExpression
object representing a boolean condition
expression | (default)
Specify the condition expression to determine the active choice. When a condition
expression evaluates to true
, the software activates the
corresponding variant choice. When a condition expression evaluates to
false
, the software deactivates the corresponding variant
choice.
The variant controls can be:
Boolean condition expression for rapid prototyping. For example,
A == 1
,A ~= B
,A && B == 1
, and so on.A
Simulink.VariantExpression
object that contains a condition expression for condition reuse. See Simulink.VariantExpression Objects for Variant Condition Reuse of Variant Blocks.Default Variant Choice if none of the choices evaluates to
true
.
Here, A
and B
are operands called
as variant control variables. ==
,
~=
, and &&
are operators in the
condition expression. The condition expression can contain one or more such variant
control variables and operators. For information on supported types and storage location
of variant control variables, see Types of Variant Control Variables (Operands) in Variant Blocks and Storage Locations for Variant Control Variables (Operands) in Variant Blocks. For information
on operators, see Types of Operators in Variant Blocks for Different Activation Times.
For more information, see Switch Between Choices Using Condition Expressions in Variant Blocks.
In Variant Assembly Subsystem block, this parameter is a list of
auto-generated boolean expressions with Variant control variable on
the left-hand side and the members of the Variant enumeration
choice are on the right-hand side of the expressions. Both the sides of
the expressions are connected with ==
. This parameter is
read-only.
Programmatic Use
To set the block parameter value programmatically, use
the set_param
function.
To get the block parameter value
programmatically, use the get_param
function.
Variant Subsystem block:
Parameter: | VariantControl |
Values: | variant control that is associated with the variant choice |
Data Types: | char |
Example: set_param(gcb, 'VariantControl', 'V == 3')
, where
gcb
is the variant choice of the Variant
Subsystem block.
Example: get_param(gcb, 'VariantControl')
, where
gcb
is the variant choice of the Variant
Subsystem block.
Variant Source and Variant Sink blocks:
Parameter: | VariantControls |
Values: | variant controls that are associated with variant choices |
Data Types: | char |
Example: set_param(gcb, 'VariantControls', {'A == 1','A ==
2'})
, where gcb
is the Variant
Sink or Variant Source block.
Example: get_param(gcb, 'VariantControls')
, where
gcb
is the Variant Sink or Variant
Source block.
Condition (read-only) — Condition expression in Simulink.VariantExpression
object
N/A
(default)
This parameter is read-only.
This parameter displays the condition expression specified as
Simulink.VariantExpression
object. To change or edit the condition
expression, use the Simulink.VariantExpression
parameter dialog box
that appears when you double-click the object in the workspace.
Note
The operands that you specify in a condition expression of type
Simulink.VariantExpression
must be defined in the base
workspace or a data dictionary. Specifying operands that are defined in the mask
or model workspace is not supported.
Label mode active choice — Name of active choice in label
mode
true (Subsystem)
(default) | false (Subsystem1)
This list contains the labels of all the variant choices. To set an active choice, select a label from the list. The corresponding choice becomes active. Alternatively, to change the active choice in label mode, you can follow the approaches described in Set Active Choices Using Variant Control Labels.
Dependencies
To enable this parameter, set Variant control mode to
label
.
Programmatic Use
Parameter:
LabelModeActiveChoice
|
Type: character vector |
Value: If no label mode active choice is specified, the value is empty. If a label mode active choice is specified, the value is the variant control label for the active choice. |
Default: '' |
Allow zero active variant controls — Simulate model without active variant choice
off
(default) | on
off
— Simulink generates an error when there is no active variant choice.on
— When you select this parameter and if there is no active variant choice, Simulink simulates the model without any active variant choice connected to the Variant Sink block. Simulink disconnects all the blocks connected to the input and output stream of Variant Sink block, thus removing the variant regions completely from the model execution.
Consider the car windshield wiper example in the Description section. Suppose you do not want
to pass the wiper speed to either of the variant choices, wiper
motor and D/A. When you simulate the model with
Allow zero active variant controls set to
on
and if there is no active variant choice in the
Variant Sink controlled by mode
block, Simulink disconnects the Variant Sink controlled by
mode
block and all its connected blocks, which removes the
variant region completely from the model.
This table shows the code that you generate with and without the Allow zero
active variant controls parameter for the code
compile
activation time. In the code that you generate
with Allow zero active variant controls set to
off
, only the variant choices wiper
motor
and D/A
are conditional, whereas the
Gain block is unconditional. The Gain
block is unconditional, and so it executes for either of the choices. This
code support only scenarios where either of the choices evaluate to
true
. If none of the choices evaluate to
true
, both the choices are removed from compilation.
The output of the Gain remains unused and this results in an
error. In the code that you generate with Allow zero active
variant controls set to on
, the variant
choices wiper motor
, D/A
, and the
connected Gain blocks are conditional. So, if none of the
choices evaluate to true
, the Gain block
is also removed, thus enabling you to completely remove the variant region
from code compilation.
Generated code without Allow zero active variant controls | Generated code with Allow zero active variant controls |
---|---|
/* If none of the conditions Mode == 1 or Mode == 2 evaluate to true, the output of Gain remains unused which resuls in an error.*/ /* logic for Gain; */ # if Mode == 1 /* logic for wiper motor; */ # elif Mode == 2 /* logic for digital to analog conversion; */ # endif |
# if Mode == 1 /* logic for wiper motor; */ # elif Mode == 2 /* logic digital to analog conversion; */ # endif /* The logic for Gain is executed only if either of the conditions evaluate to true. Gain is removed from code compilation if none of the condition evaluates to true. */ # if (Mode == 1) ∥ (Mode == 2) /* logic for Gain; */ # endif |
Dependencies
This parameter is available only if you set Variant control
mode to expression
.
Programmatic Use
Block Parameter:
AllowZeroVariantControls
|
Type: character vector |
Values:
'off' | 'on'
|
Default:
'off'
|
Show variant condition on block — Annotate block ports
off
(default) | on
When you select this option, Simulink annotates the variant condition expression on each port of the Variant Sink block.
Programmatic Use
Block Parameter:
ShowConditionOnBlock
|
Type: character vector |
Values:
'off' | 'on'
|
Default:
'off'
|
Block Characteristics
Data Types |
|
Direct Feedthrough |
|
Multidimensional Signals |
|
Variable-Size Signals |
|
Zero-Crossing Detection |
|
Extended Capabilities
C/C++ Code Generation
Generate C and C++ code using Simulink® Coder™.
Fixed-Point Conversion
Design and simulate fixed-point systems using Fixed-Point Designer™.
Version History
Introduced in R2016a
See Also
Variant Source | Manual Variant Source | Manual Variant Sink | Variant Subsystem
Topics
- Generate Code for Variant Source and Variant Sink Blocks (Simulink Coder)
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)