Main Content

Variant Sink

Route amongst multiple outputs using variants

expand all in page
  • Library:

  • Simulink / Signal Routing

  • Variant Sink block

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 Sourceblock 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.

Multiple implementations to control speed of car windshield using a Variant Sink block

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.

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

expand all

Input signal to be connected to the active output port.

Data Types: single | double | half | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | Boolean | fixed point | enumerated | bus | struct

Output

expand all

Output signal from the first 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

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

expand all

The variant control that determines the active variant choice can be any of these types.

  • expression — In expression mode, Simulink chooses the active variant based on the evaluation of the variant conditions. When a condition expression evaluates to true, the corresponding variant choice becomes active. When a condition expression evaluates to false, the corresponding variant choice becomes inactive. See Switch Between Choices Using Condition Expressions in Variant Blocks.

  • label — In label mode, Simulink 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 — To automatically switch between the variants for simulation and code generation workflows without creating any workspace variable, use sim codegen switching mode. When you simulate a model, Simulink automatically chooses the sim 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, Simulink automatically chooses the codegen 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 Simulink 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 modeupdate diagramupdate diagram analyze all choicescode compilestartup
expression✓✓✓✓
label✓xxx
sim codegen switching✓✓xx

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.

You can set the Variant activation time parameter as:

  • 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 regular if conditions. The executable built from the generated code also contains both active and inactive choices.

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 Simulink 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 diagramupdate diagram analyze all choicescode compilestartup
expression✓✓✓✓
label✓xxx
sim codegen switching✓✓xx

Programmatic Use

Block Parameter: VariantActivationTime
Type: character vector
Values: update diagram | update diagram analyze all choices | code compile | startup
Default: update diagram

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.

the add a new output port button

Delete selected port: Delete the selected variant choice from the block and its entry from the table.

the delete selected port button

Create/Edit selected variant object: Create or edit a Simulink.Variant object for the selected variant choice in the global workspace and specify the variant condition using the Simulink.Variant object parameter dialog box.

Note

For a model that uses the base workspace, this operation creates the Simulink.Variant object in the base workspace, and the object is available only for the current MATLAB session. To permanently store the data, save the object in a MAT file or MATLAB script.

the Create or Edit selected variant object button

Number of the output port that is connected to one variant choice upstream of the Variant Sink block. This value is read-only.

Click the add a new output port button to add a port or the delete selected port button to delete an existing one.

A name for a choice, specified as a string.

Dependencies

To enable this parameter, set Variant control mode to label.

Specify the condition expression to determine the active choice. When a condition expression evaluates to true, Simulink activates the corresponding variant choice. When a condition expression evaluates to false, Simulink deactivates the corresponding variant choice.

The variant controls can be:

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.

Programmatic Use

Structure field: Represented by the read-only variant.Name field in the Variant parameter structure
Type: character vector
Value: variant control that is associated with the variant choice
Default: 'variant'

This read-only field displays the condition expression specified as Simulink.Variant object. To change or edit the condition expression, use the Simulink.Variant 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.Variant 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.

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, you can follow the approaches described in Set Active Choices Using Variant Control Labels to change the active choice in label mode.

Dependencies

To enable this parameter, set the Variant control mode parameter to label.

Programmatic Use

Parameter: LabelModeActivechoice
Type: character vector
Value: if no label mode active choice is specified, the value is empty. If label mode active choice is specified, the value is the name of the label mode active choice.
Default: ''

  • 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 controlsGenerated 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'

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'

Model Examples

Variant Source and Variant Sink Blocks

Variant Source and Variant Sink Blocks

Define variant choice in Variant Source and Sink blocks.

Open Model

Block Characteristics

Data Types

Boolean | bus | double | enumerated | fixed point | half | integer | single | string

Direct Feedthrough

no

Multidimensional Signals

no

Variable-Size Signals

no

Zero-Crossing Detection

no

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

| | |

Topics