Create and Activate Variant Configurations

Note

This functionality requires Variant Manager for Simulink^®.

A model might contain several variant blocks or variant parameters, each with many variant choices. A variant configuration is used to represent a combination of such variant choices across the model hierarchy. For example, in a system with a plant and a controller, a linear controller with an internal plant with no noise and a nonlinear controller with an external low fidelity plant represent two different configurations of the system.

You can use Variant Manager to create and manage variant configurations for a model. Variant Manager defines a variant configuration as a set of variant control variables and their values that can activate a specific variation in the model hierarchy. For more information on variant configurations, see Variant Configurations. For an overview of Variant Manager, see Variant Manager for Simulink.

Steps to Create Variant Configurations

You can create multiple named variant configurations for a model or you can create variant control variables in the data sources used by the model to use as a temporary variant configuration for the model.

This image shows the high-level workflow to create and save a new named variant configuration for a model.

Workflow to create a named variant configuration

Open Variant Manager

Open the model for which you want to create new variant configurations. Here, open the slexVariantManagement model using the following command.

openExample('simulink_variants/VariantConfigurationObjectForAModelRefPageExample');
open_system('slexVariantManagement');

On the Modeling tab, open the Design section and click Variant Manager.

Configurations Tab in Variant Manager

View the Configurations tab in Variant Manager.

Variant configurations pane in Variant Manager

The first entry indicates the data source used by the model, for example, topdata.sldd.
The table lists the named variant configurations created for the model. These configurations are stored in the variant configuration data object (of type Simulink.VariantConfigurationData) associated with the model.
The table in the Control Variables section shows the variant control variables and their values defined in a selected configuration. All control variables are listed in the table, either when the variant configuration object for the model is loaded, or when you import them from the workspace.
In the Control Variables table of a top-level variant configuration, the control variables that are populated using a referenced component configuration are read-only and appear with a gray background color.
The Preferred Configuration section allows you to select a named configuration that is suitable for the model for common workflows.

Add New Variant Configuration

To create a temporary variant configuration, click the entry corresponding to the storage location used by the model in the Configurations tab, for example, topdata.sldd.
To add a new named variant configuration, click the Add variant configuration button . A new row is added to the table of named configurations. Type a name for this configuration in the box.

Variant configurations pane in Variant Manager with a new configuration named Configuration

Add, Import, or Export Control Variables in Variant Configuration

In the Configurations tab, scroll down to see the Control Variables section. The section shows the name of the currently selected variant configuration.
In this section, click the Import control variables across model hierarchy button to import any existing control variables used by the model to the variant configuration.
To import variant control variables of type Simulink.VariantControl defined in the base workspace or a data dictionary linked to the model even if the variant control is not yet used by the model, click the down arrow on the Import control variables across model hierarchy button and select Import control variables from model data source.
To add a new control variable to the variant configuration, click the Add control variable button . By default, this operation adds a new control variable of type Simulink.VariantControl with a normal MATLAB^® variable as its value to the control variables table. To add other types of control variables, click the down arrow on the button. You can update the values in this table. For a list of actions that you can perform from the control variables table, see Edit Control Variables in Variant Configuration.
To export the control variables to the data sources where they are stored, click the Export control variables to workspace(s) button .
You can use the Description section to provide an optional description for the configuration.

Control variables section in Configurations tab

Edit Control Variables in Variant Configuration

You can perform these operations from the Control Variables section.

Operation	Action
Add new control variables to a configuration	Click the Add control variable button . The default type of a new control variable is `Simulink.VariantControl`, with a normal MATLAB variable as its value. You can also add these types of variables. To see all the options, click the down arrow on the button. Normal MATLAB variable `Simulink.Parameter` `AUTOSAR.Parameter` User-defined data class that derives from `Simulink.Parameter`
Import variant control variables used by the model hierarchy	Click the Import control variables across model hierarchy button . Note Control variables from blocks in `Label` mode are not imported as they are not variant control variables.
Import variant control variables of type Simulink.VariantControl from the base workspace or a data dictionary linked to the model even if the variant control is not yet used by the model	Click the down arrow on the Import control variables across model hierarchy button. Select `Import control variables from model data source`.
Export control variables to the data sources where they are stored.	Click the Export control variables to workspace(s) button .
Sort the rows based on each column	Click the column names, such as Name, Value, VAT, or Source, in the header row to sort the table based on the values in that column.
Show or hide the usage of control variables in a configuration	To find the usage of a particular variant control variable in a variant configuration, select the variable in the control variables table and click the Show usage of selected control variables button . The rows that contain the variable appear highlighted in the model hierarchy table. For variant parameters in the model hierarchy, the control variable usage is shown in the Variant Parameters tab with View set to `Choice per row`. (since R2024a) To hide the usage of a variant control variable, click the Hide usage of selected control variables button . Alternatively, right-click the variable in the control variables table and select Show usage or Hide usage. Tip You can navigate the model hierarchy to understand the usage of control variables in a configuration. After you activate a variant configuration, enable Show usage for the required variant control variables. Now select `variable usage` from the Navigate list in the model hierarchy table. Use the arrow key to step through the model hierarchy rows that use those variables.
Change the data type of control variables in a configuration	Click the down arrow in the Convert to `Simulink.VariantControl` button to see the options for conversion. You can convert the control variables to any of these types: `Simulink.VariantControl` with a `Simulink.Parameter` object as its value `Simulink.VariantControl` with a normal MATLAB variable as its value `Simulink.VariantControl` with a user-defined type that inherits from `Simulink.Parameter` as its value `Simulink.Parameter` `AUTOSAR.Parameter` Normal MATLAB variable For an example that shows the use of different types of variant control variables and their purpose, see Use Variant Control Variables in Variant Blocks.
Edit `Simulink.Parameter` or `AUTOSAR.Parameter` control variables	Use the Edit `Simulink.Parameter` or `AUTOSAR.Parameter` control variable button . To specify `Simulink.Parameter` control variable as an expression, set the Value property of the parameter object by using an equal sign (=) followed by a mathematical expression. For example, enter `= A + B`.
Filter the table based on type of control variables	Use the Filter based on variable types button .
Filter content in the table	Enter the search term in the Filter text box. Press Esc to clear the text box.

Set Up Variant Configurations for Referenced Components

Your model may consist of referenced models that have predefined variant configurations. The variant configurations for a top-level model must also define the variant control variables used by any referenced components in the model hierarchy, such as referenced models. This approach helps to maintain a single consistent definition for a variant control across the hierarchy.

If the referenced component has existing named variant configurations of its own, you can use them to set up the corresponding variant control variables in the top-level model configuration. You can use the Component Configurations view in Variant Manager to select the referenced component configurations to be used for the initialization. For steps to use the Component Configurations view, see Compose Variant Configurations for Top Model Using Referenced Model Configurations.

Define Constraints for Variant Configurations

A constraint is a user defined check that you can use to prevent invalid variant combinations in a model. You can define model-wide constraints that must be satisfied by all variant configurations created for the model. It is represented as a condition expression created using variant control variables. The expression must evaluate to true to satisfy the constraint. When you activate a variant configuration, Variant Manager validates the configuration against the applicable constraints.

Note

Variant Manager constraints are also validated when you compile the model for an active configuration. However, these constraints are not validated post compilation, for example, at startup variant activation time.

Click the Constraints tab in the Variant Manager window. The Constraints table lists any existing constraints created for the model.
To add a new constraint, click the Add constraint button . A new row gets added.
Enter a name for the constraint in the box.
In the Constraint Definition section, in the Condition box, enter the boolean condition expression defined in terms of variant control variables. The condition must evaluate to true to satisfy the constraint.
In the Description box, enter an optional description for the constraint.

Constraints tab in Variant Manager

Tip

You can change the layout of the Variant Manager window to keep the Configurations and Constraints panes next to each other. This layout allows you to refer the Control Variables section when defining constraints. To move a pane, click at the top of the pane and drag.

Save Variant Configurations

You can use a variant configuration object of type Simulink.VariantConfigurationData to store all named variant configurations and constraints for a model. You can define the object in the base workspace or in the Configurations section of a data dictionary. If the model is not yet associated with a variant configuration object, Variant Manager helps you to setup a new variant configuration data object.

Type a name for the variant configuration data object in the Simulink.VariantConfigurationData text box in the Variant Manager toolstrip.
To export the variant configuration data object to the base workspace or Simulink data dictionary used by the model, click Apply changes. This action also associates the object with the model.
To reload the object from the base workspace or data dictionary used by the model, click Reload object. This allows you to revert the changes that are not yet exported to the data sources used by the model.
When you export the variant control variables in a variant configuration or when you activate a variant configuration, the control variables are pushed to the data sources where the variables are stored. Reloading the variant configuration object from Variant Manager does not revert these changes.
To disassociate the variant configuration data object from the model, set the Simulink.VariantConfigurationData box to empty and click Apply changes.
To export the variant configuration data object to a MAT-file or MATLAB script, click Export to file.
If the variant configuration data object is defined in the base workspace, this step allows you to save the object and reuse it later by importing it into Variant Manager. However, if the object is defined in a data dictionary, you need not export the object to a MAT-file or MATLAB script. Instead, you must save changes to the data dictionary.
To load the variant configuration data object saved in a file into Variant Manager, click Import from file.

Note

After you click Apply changes, save the model to save the changes made from Variant Manager.

Validate and Activate Variant Configuration

To activate either a named variant configuration or the temporary workspace configuration, select the corresponding entry from the Configurations tab and click Activate Configuration.
The operation validates the configuration and applies the selected configuration to the model. Activation also pushes control variables in the configuration to the data sources where they are stored.
Any errors related to the process are reported in the Diagnostics pane.
On successful activation, the model hierarchy table reflects the changes. You can:
- Explore the active variant choices in the Blocks or System tab of the model hierarchy. You can also navigate the hierarchy using the Navigate filter to understand control variable usage, active choices, and invalid choices.
- Compile or simulate the model for the active configuration.

To activate a model programmatically, see Simulink.VariantManager.activateModel.

For information on how the activation process differs from model compilation (update diagram), see Differences Between Variant Manager Activation and Update Diagram Process.

Use Model Compilation Information in Variant Manager

Since R2024b

You can obtain model compilation information in Variant Manager to produce more accurate results for user workflows such as importing control variables to a configuration, activation, and identifying variant parameters used by the model hierarchy. Click Update Model in the Variant Manager toolstrip or use the Simulink.VariantManager.updateModel function. For more information, see Obtain and Use Model Compilation Information in Variant Manager.

Apply Variant Configuration on Model

Once you have saved the validated variant configuration to a file, you might want to simulate your model for the configuration at a later time.

Open Variant Manager for the model.
If the variant configuration data object is not loaded into Variant Manager, click Import from file to import the object from a file.
In the Configurations tab, click the required configuration.
The Control Variables section lists the control variables in the selected configuration. Click the Export control variables to workspace(s) button .
The operation exports the variant configuration data object to workspace and applies the selected variant configuration to the model and any referenced components in the model hierarchy. This allows you to quickly switch the configuration without validating it. You can now simulate the model for this configuration.

To programmatically apply a configuration on your model before compiling or simulating the model, use the Simulink.VariantManager.applyConfiguration method.