Generate Variant Configurations Automatically

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.

Generate Variant Configurations Using Variant Manager

Creating all possible variant configurations for a model manually can be time consuming. You must activate them individually to check if they are valid and if they satisfy necessary constraints. You can automatically generate variant configurations for a model using Variant Manager, which allows you to:

Consider all possible combinations of variant control variables while creating configurations.
Specify the value range that must be considered for each control variable. This specification allows you to control the process and generate only the required subset of configurations.
Create configurations that satisfy some preconditions.
Automatically validate generated configurations to identify invalid cases.
Generate valid configurations for which model compiles successfully or all configurations including invalid ones.
Export selected configurations to the variant configuration data object associated with the model.
Export the preconditions as global constraints in the variant configuration data object.

To generate variant configurations programmatically, use the Simulink.VariantManager.generateConfigurations method.

Example for Generated Configurations for a Simple Variant Model

Steps to Generate Configurations

This image shows the steps to generate variant configurations from Variant Manager.

high-level workflow for generating configurations

Open the model for which you want to generate variant configurations.
Open Variant Manager.
On the Modeling tab, open the Design section and click Variant Manager. Alternatively, right-click the variant badge on any variant block in the model and select Open in Variant Manager.
Open the Generate Configurations tab.
In the Variant Manager toolstrip, in the Setup section, click Generate Configurations.
This image shows the Generate Configurations window for the slexVariantManagement model. To open the model, run the below command from the MATLAB^® Command-Line.
```
openExample('simulink_variants/AutomaticallyGenerateVariantConfigurationsRefPageExample');
open_system('slexVariantManagement');
```
Configure variant control variables for the operation.
The Configure Control Variables tab lists the variant control variables used by the model.
To change the order of control variables in the table, use and . This change affects only the order in which control variable combinations are considered for the generation process and has no impact on the effective configurations generated.
The Values column is filled with the possible values for the control variables, as specified in the model. You can edit the values as needed. You can also specify only a required subset of values, which allows you to restrict the configurations that gets generated. For example, provide the value Linear for the variable Ctrl to generate configurations for the linear controller alone.
Specify optional preconditions.
In the Precondition to Apply text box, specify conditions to limit the configurations to generate. The value must be a character vector or cell array of character vectors containing valid boolean expressions defined on the variant control variables. For example, the condition {'Ctrl == ControllerType.Linear', 'PlantLoc == PlantLocation.Internal'} generates only configurations corresponding to the specified values for Ctrl and PlantLoc variables.
Specify the type of configurations to generate, based on validity.
In the Generate Based on Validity list, select one of these values:
- valid — Include only valid configurations. These include duplicate configurations that are functionally equivalent.
- valid-unique — Include only valid configurations without duplicates that are functionally equivalent (default).
  If a configuration has functional equivalents, this option lists one of those equivalent configurations in the result.
- all — Include valid, invalid, and duplicate configurations.
Note
Two variant configurations are functionally equivalent if they result in the same set of active blocks in the model. You can identify a group of functionally equivalent configurations in the generated results by the Validity Status value EquivalentK, where K is an annotation used to group equivalent configurations, for example, Equivalent1.
An invalid variant configuration violates variant semantics and causes an error during the update diagram process. For example, you have a configuration that deactivates all choices in an inline variant block. However, this block has the Allow zero variant control set to off, which contradicts the deactivation and causes an error.
For any validity option, the process generates only those configurations that satisfy the specified preconditions.
Optionally exclude specific configurations from the result.
In the Exclude Configuration Data Object text box, you can specify the name of a Simulink.VariantConfigurationData object that contains the variant configurations that must not be generated. By default, the name of the current variant configuration data object associated with the model is populated in this box, and configurations present in this object are ignored.
Click Generate Configurations.
The Generated Configurations pane shows the result in a tabular form. Valid configurations appear highlighted in green and invalid ones in red.
The Validity Status column in the result indicates whether a configuration is unique, a functional equivalent, or an invalid one. The field has one of these values:
- Unique — Configuration is valid and unique without any functional equivalents.
- EquivalentK — Configuration is valid and is a functional equivalent of another configuration. K is an annotation to identify a group of equivalent configurations, for example, Equivalent1.
  If you had set the Generate Based on Validity option to valid-unique and a generated configuration has functional equivalents, the result shows one of those configurations with Validity Status set to EquivalentK.
- Invalid — Configuration is not valid.
You can edit the configuration names in the Name column. You can use and buttons to toggle the selection of the table rows.
Export the generated configurations to the variant configuration data object associated with the model. Perform this step if you would like to save the generated configurations.
- Select the configurations that you want to export from the table in the Generated Configurations pane.
- To export the specified precondition as constraint in the variant configuration data object, select Add Precondition as Constraint.
- Click Add Selected Configurations. This operation adds the selected configurations to the list of named configurations in the Configurations tab. If you selected Add Precondition as Constraint, the operation also adds the preconditions as constraints to the Constraints tab.
- Click Close Generate Configurations to return to the Manage tab of Variant Manager.
Save or revert the changes to the variant configuration data object. After exporting the generated configurations, you can use any of these options in the Manage tab to save or revert your changes:
- To apply the changes to the base workspace or data dictionary used by the model, click Apply changes.
- To reload the variant configuration 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.
- To permanently save the new configurations and constraints in the variant configuration data object to a file, click Export to file.

Snapshot of Generation Process

When you generate variant configurations automatically using Variant Manager or using the Simulink.VariantManager.generateConfigurations method, Simulink captures a snapshot of the auto-generation process. A sub-folder named based on the timestamp of the operation is created each time you generate configurations and is saved inside the <modelname>_vmgrsnap folder within the model folder. Using the snapshot, you can get an overview of the input and output of the auto-generation process and manually compare the results between snapshots to understand the impact of model edits on the generated configurations. The snapshot contains different files that stores the following information. These contents are subject to change across future releases.

Blocks considered
Variant control variables used
Command used for generating the configurations
Generated configurations

Limitations

The auto-generation process supports only ==, ~=, &&, ||, and ~ operators in the variant control expressions of variant blocks and in the preconditions. If the variant control expressions use other operators such as arithmetic or relational operators, the configurations that can activate those variant choices might not get generated.
The process does not support generating variant configurations for these modeling elements:
- Models that contain variant blocks that use variant control variables defined in the mask or model workspace.
- Variant blocks with a Variant control expression that contains noninteger double values, structure fields, or Simulink.Parameter objects with value set to an expression of type slexpr
- Variant parameter objects of type Simulink.VariantVariable
- Model that represents a library or subsystem
For variant blocks with the Variant control mode parameter set to label, the variant control labels are strings, not variables. Hence they are not present in the generated configurations.

Variant Subsystem Blocks

For Variant Subsystem blocks, these conditions also apply:

If the Variant control mode parameter is set to label, only the variations present in the active label path are considered when you generate configurations.
Consider this model hierarchy for a model with a Variant Subsystem block in label mode. The active choice for the variant subsystem is the Subsystem block, which has its variant control set to a label, SUB1. The variant control variable A is used by the active choice and is considered when you generate configurations. The process does not consider the control variable B because it is in the inactive choice of the variant subsystem.
Here is the list of all generated configurations.
If the Variant control mode parameter is set to sim codegen switching, only the variations present in the sim choice are considered when you generate configurations. For the variant controls present in the codegen hierarchy, only the default values are included in the generated configurations.
Consider this model hierarchy for a model with a Variant Subsystem block in sim codegen switching mode. The sim choice for the variant subsystem is the Subsystem block. The variant control variable B present in this choice is considered when you generate configurations. The process only considers the default value for the control variable C because it is in the codegen choice of the variant subsystem.
Here is the list of all generated configurations.
If the Variant activation time is set to update diagram, only the variations in the active choice are considered for generating configurations.