Choose and Configure a Workspace for Variant Control Variables of Variant Blocks

R2026b

Variant blocks allow you to represent multiple design alternatives in a single Simulink^® model. Each variant block contains several variant choices. A variant control determines which variant choice is active during simulation and code generation.

You can configure variant blocks to use one of three control modes: expression, label, or sim codegen switching. In expression mode, Simulink determines the active variant choice by evaluating variant control variables defined in a workspace. In label and sim codegen switching modes, workspace variables are not required. These modes use only the update diagram variant activation time and generate code only for the active variant choice.

In expression mode, you can define variant control variables in the base workspace, a data dictionary, the model workspace, or a mask workspace. The mask workspace includes mask parameters and mask initialization code. You can also override variant control variable values for individual simulation runs by using a Simulink.SimulationInput object without modifying the persistent workspace values.

The workspace you choose affects the scope of the variable, the activation time at which the active variant choice is resolved, and whether each instance in the model hierarchy can independently control which variant choice is active.

Choose the right workspace based on scope or variant activation time:

If you have identified whether your variant control variables must be accessible globally, scoped to a specific model, or confined to a subsystem instance, see Choose a Workspace Based on Scoping Requirement.
If you have identified the variant activation time for your simulation and code generation workflow, see Choose a Workspace Based on Variant Activation Time.

After you choose a workspace, see Verify Variable Type Compatibility with Workspace and Variant Activation Time to verify that your variable type supports the chosen workspace and variant activation time.

Choose a Workspace Based on Scoping Requirement

Each workspace provides a different level of visibility for variant control variables. The base workspace and data dictionaries make variables accessible globally across all models in the session. The model workspace scopes variables to a single model or to individual instances of a referenced model through model arguments. The mask workspace confines variables to a masked subsystem, allowing each subsystem instance to activate a different variant choice independently. For more information on the capabilities and advantages of each workspace, see Determine Where to Store Variables and Objects for Simulink Models.

Use this decision flow chart to determine the appropriate workspace. Start by determining whether your variant controls require workspace variables, then follow the branch that matches your scoping requirement.

This table lists each workspace, the scope it provides, the use cases it is best suited for, and examples to help you configure variant control variables.

Scoping Need	Workspace	Description	Use Cases	Examples
Global	Base workspace	All models in the MATLAB^® session can access the variable. All variant activation times are supported, including `code compile`.	Rapid prototyping, single-user workflows, or workflows that require `code compile` activation time without additional setup	Use Base Workspace to Define Globally Accessible Variant Control Variables for Variant Blocks
Global	Data dictionary	Same capabilities as the base workspace, plus version control, team sharing, and traceability.	Production workflows, team collaboration, and maintaining consistent definitions across multiple models	Use Data Dictionary to Define Shared Variant Control Variables for Variant Blocks
Model	Model workspace	The variable is scoped to a single model and instances of that model resolve to the same variant control variable value. The variable is stored within the model file and does not require external scripts to restore the variable when the model loads.	Referenced models where the same variant choice is active across instances	Use Model Workspace to Define Variant Control Variables Scoped to the Model for Variant Blocks
Model instance	Model workspace with model arguments	A model argument allows the parent model to set a different variant control variable value for each instance of the referenced model.	Referenced models where each instance must activate a different variant choice	Use Model Arguments with Fast Restart to Switch Variant Choices Per Instance Without Recompiling for Variant Blocks
Subsystem	Mask parameter	The variable is scoped to the masked subsystem. Each instance of the masked subsystem can set a different variant control variable value from the mask dialog box.	Masked subsystems where each instance must activate a different variant choice	Use Mask Parameters for Per-Instance Variant Control in Variant Blocks Use Mask Parameters with Enumeration Classes for Per-Instance Variant Control of a Variant Block in a Locked Library Use Mask Parameter Object to Control Variant Choices in Masked Variant Assembly Subsystem Block Use Mask Initialization Code for Per-Instance Variant Control in Variant Blocks

Choose a Workspace Based on Variant Activation Time

The variant activation time determines when Simulink resolves the active variant choice and how that choice affects simulation and code generation. For example, the code compile activation time requires variant control variables to be in the base workspace or a data dictionary, while the startup and runtime activation times support all workspaces. For more information on variant activation times, see Activate Variant During Different Stages of Simulation and Code Generation Workflow.

Use this table to determine how workspace placement affects simulation and code generation behavior for your chosen variant activation time.

Activation Time	Workspace Usage	Examples
`update diagram`	Define variant control variables in any supported workspace. Simulink compiles only the active variant choice and ignores inactive choices, minimizing compilation overhead. The code generator produces code only for the active variant choice. If each subsystem instance or referenced model must activate a different variant choice, define the variable in the mask or model workspace.	Use Base Workspace to Define Globally Accessible Variant Control Variables for Variant Blocks Use Data Dictionary to Define Shared Variant Control Variables for Variant Blocks
`update diagram analyze all choices`	Define variant control variables in any supported workspace. Simulink checks signal attributes across variant choices to detect mismatches early, then compiles only the active variant choice. The code generator produces code only for the active variant choice. If each subsystem instance or referenced model must activate a different variant choice, define the variable in the mask or model workspace.
`code compile`	Define variant control variables in the base workspace or a data dictionary. The code generator produces code for variant choices enclosed within `#if` and `#elif` preprocessor conditionals. Specify the active variant choice before compiling the code to build an executable for only that choice without regenerating code.	Compile Code Conditionally for Variations of Component Represented Using Variant Block (Embedded Coder)
`startup`	Define variant control variables in any supported workspace. Simulink compiles variant choices into a single compiled model so that you can use fast restart to switch between variant choices before each simulation run without recompilation. The code generator produces code for variant choices enclosed within `if` and `else if` conditions. Variant choices are included in the executable, so you can switch the active variant choice at application startup without recompiling code. If each subsystem instance or referenced model must activate a different variant choice, define the variable in the mask or model workspace.	Use Model Arguments with Fast Restart to Switch Variant Choices Per Instance Without Recompiling for Variant Blocks Use Mask Parameters with Fast Restart to Switch Variant Choices Without Recompiling for Variant Blocks
`runtime`	Define variant control variables in any supported workspace. Simulink compiles variant choices into a single compiled model so that you can switch between variant choices during simulation without stopping or recompiling. The code generator produces code for variant choices enclosed within `if` and `else if` conditions. Variant choices are included in the executable, so you can switch the active variant choice during execution without recompiling code. If each subsystem instance or referenced model must activate a different variant choice, define the variable in the mask or model workspace.	Control Active Choice of Variant Subsystem During Simulation or Execution of Generated Code

Verify Variable Type Compatibility with Workspace and Variant Activation Time

The type of variant control variable you use determines which workspace and variant activation times are available. For example, a Simulink.VariantControl object supports all workspaces and variant activation times, while a Simulink.Parameter object with a custom storage class does not support the mask workspace. Scalar variables support all workspaces but do not support the code compile variant activation time when defined in the mask workspace.

After you choose a workspace and variant activation time, use this table to verify that your variable type supports that combination.

Type of Variant Control Variable	Workspaces Supported	`update diagram`	`update diagram analyze all choices`	`code compile`	`startup`	`runtime`
`Simulink.VariantControl` — Associate the variant control variable with the variant activation time to centralize and synchronize variant activation logic across variant blocks and parameters. This approach prevents incorrect variant selections during frequent variant switching. See Use Simulink.VariantControl Variables for Coherent Switching of Choices in Variant Blocks.	base workspace data dictionary	✓	✓	✓	✓	✓
	model workspace	✓	✓		✓	✓
	mask initialization code	✓	✓
`Simulink.Parameter` — Set the `Simulink.VariantControl` object to an object of a user-defined data class derived from `Simulink.Parameter`. You can extend the standard parameter behavior by incorporating additional properties, methods, or validation within the parameter by using the custom storage classes defined in your package. The package containing your custom data class must be available on the MATLAB search path. See Use Custom Data Class Objects as Values of Simulink.VariantControl Objects.	base workspace data dictionary	✓	✓	✓	✓	✓
	model workspace	✓	✓		✓	✓
`Simulink.Parameter` — Set the `Simulink.VariantControl` object to a `Simulink.Parameter` object (or an object inheriting from it) with its value defined as a mathematical expression using the `slexpr` function. This approach allows you to specify the value as a relationship between known physical constants instead of using an arbitrary literal number. Additionally, it enables you to explicitly model algebraic dependencies between parameter data, so when you modify the values of independent parameters, the dependent parameters update automatically. See Use Mathematical Expressions as Values of Simulink.VariantControl Objects and Simulink.VariantVariable Choices.	base workspace data dictionary	✓	✓	✓	✓	✓
	model workspace	✓	✓		✓	✓
`Simulink.Parameter` — Control the scope, placement, accessibility, and visibility of the variable in the generated code by defining its storage class. See Simulink.Parameter Type of Variant Control Variables for Code Generation in Variant Blocks.	base workspace data dictionary	✓	✓	✓	✓	✓
	model workspace	✓	✓		✓	✓
Scalar variable — Rapid prototyping and simulation for quick variant switching. See Scalar Variant Control Variables for Rapid Prototyping in Variant Blocks.	base workspace data dictionary	✓	✓	✓	✓	✓
	model workspace mask parameter	✓	✓		✓	✓
	mask initialization code	✓	✓

Variant Control Variable Resolution Order

When you define variant control variables in multiple workspaces, Simulink resolves the variable by searching from the narrowest scope to the broadest scope. The resolution order is mask workspace, model workspace, then base workspace or data dictionary.

For example, if a variable named VSS_MODE exists in both the model workspace and the base workspace, Simulink uses the model workspace value. The base workspace value is ignored. To avoid unexpected behavior, verify that you do not have variables with the same name in multiple workspaces that could shadow each other.

Override Variant Control Variables per Simulation Run

After you define variant control variables in a workspace, you can override their values for individual simulation runs by using a Simulink.SimulationInput object. This approach is useful for parameter sweeps and parallel simulations where each run must activate a different variant choice without modifying persistent workspace values. For more information, see Override Variant Control Variables of Variant Blocks in Simulation Runs.

Workspace Constraints for Variant Control Variables

The workspace in which you define variant control variables determines the available variant activation times, scoping behavior, and code generation capabilities. Consider these constraints when choosing a workspace for your variant control variables.

Propagate Variant Conditions Across Workspaces

All variant control variables in a variant block must originate from the same workspace.
Variant conditions created using variant control variables defined in a mask workspace or model workspace cannot propagate outside the scope of the workspace. The scope boundary is the subsystem boundary for mask workspace variables and the model block boundary for model workspace variables.
A block cannot receive propagated variant conditions originating from multiple workspaces. All variant conditions that propagate to a block must come from the same workspace.
For Variant Subsystem blocks that use variant control variables defined in a mask or model workspace, the Propagate conditions outside of variant subsystem parameter is not supported. For more information on condition propagation, see Propagate Variant Conditions to Define Variant Regions with Variant Blocks.

Define Variant Controls in Mask Workspace

The name of a variant control variable originating from a mask or model workspace must not exceed 40 characters.
The name of a variant control variable originating from a mask workspace must not start with SLMASK.
Enumeration types used as variant control values are defined globally on the MATLAB path. Each mask instance can set a different enumeration member as the variant control value, but all instances share the same enumeration type definition.

Define Variant Controls in Model Workspace

The name of a variant control variable originating from a mask or model workspace must not exceed 40 characters.
MATLAB structures defined in the model workspace are not supported as variant control variables when the variant activation time is set to startup or runtime.
Simulink.VariantControl objects defined in the model workspace cannot be overridden as model arguments from the parent model. For more information on model arguments, see Use Model Arguments with Fast Restart to Switch Variant Choices Per Instance Without Recompiling for Variant Blocks.
When a variant control variable in the referenced model is defined as a model argument, the highlighting of the active and inactive variant choices in the block diagram reflects the value of the model argument in the model workspace, not instance-specific values set from the parent model. During simulation, Simulink correctly uses instance-specific values. To confirm per-instance behavior, compare simulation outputs rather than block diagram highlighting.

Choose Variable Types for Workspaces

Define variant control variables in the base workspace or a data dictionary to use the code compile variant activation time. This variant activation time produces preprocessor conditionals #if and #endif in the generated code. For more information, see Activate Variant During Different Stages of Simulation and Code Generation Workflow.
Define a Simulink.VariantExpression object that contains condition expressions for variant control variables in the base workspace or a data dictionary.

Define Variant Controls for Simulink Function Blocks in Mask or Model Workspace

When the variant control variable of a Simulink Function block originates from the mask or model workspace:
- Only the update diagram variant activation time is supported.
- The Function Visibility parameter must be set to Scoped.
- Define variant conditions directly on the block. Inheriting variant conditions from other blocks is not supported.
- Using a Function Caller block in an export-function model is not supported when the variant control variable of the Simulink Function block originates from the mask or model workspace.

Run Simulations with Workspace Variant Controls

Use a Simulink.SimulationInput object to temporarily set values of variant control variables for each simulation run. The object is useful with startup variants in applications such as testing, iterative simulation, and rapid prototyping, because you do not need to change workspace variables. For more information, see Override Variant Control Variables of Variant Blocks in Simulation Runs.
In accelerator and rapid accelerator simulation modes, changing variant control values that originate from mask parameters, model workspace variables, or model arguments causes checksum changes and triggers model rebuilds during incremental builds. For more information on acceleration modes, see How Acceleration Modes Work.