Main Content

Variant Configurations

Note

This functionality requires Variant Manager for Simulink®.

What is a Variant Configuration?

Using variant elements in Simulink, you can represent all design alternatives of a system component in a single model. Each variant of a system component is depicted as a variant choice in the model. A variant control associated with each variant choice allows you to activate or deactivate the choice in the model.

For example, consider a model for a system with a plant and a controller. The controller component has three variant choices, Linear, NonLinear, and Smart. The plant component has two choices, External and Internal. This model uses Variant Subsystem blocks to represent these components and their choices. Combinations of these variant choices represents different modes or different configurations of the system, for example, a linear controller with an internal plant with no noise or a nonlinear controller with an external low fidelity plant. The former configuration is shown in this figure.

Model with variant blocks representing a plant and controller

A variant configuration represents a combination of variant choices across the model hierarchy. It contains a set of variant control variables and their values, which you can use to activate a specific variant in the model hierarchy. It helps you to easily define and manage variation points in a model.

The number of variant configurations for a model can be high depending on the number of variant choices. Configuring the choices and switching between them manually can be complicated and can introduce errors. You can use Variant Manager to define, apply, and manage variant configurations for the model.

Variant Manager enables you to:

  • Create variant configurations and define constraints.

  • Automatically generate and validate all possible variant configurations for a model.

  • Validate and activate a configuration on the model.

  • Use Variant Reducer to generate a reduced model that contains only selected configurations.

  • Use Variant Analyzer to compare multiple variant configurations in a tabular form, verify that all variant choices have been activated at least once, and identify any inconsistencies in the configurations.

Types of Variant Configurations

  • The workspace configuration:

    The variant control variables and their values currently present in the base workspace or data dictionary of the model function as a temporary variant configuration for the model.

    Note

    This configuration is temporary because it is not saved to the variant configuration object associated with the model.

  • A named variant configuration:

    You can create multiple named variant configurations that contain a set of control variables, their values, a set of constraints, and a description. You can set one of these named configurations as a preferred configuration for the model.

You can automatically generate all possible variant configurations for a model using Variant Manager. See Generate Variant Configurations Automatically.

Constraints on Variant Configurations

A constraint is a user defined check that you can use to prevent invalid variant combinations in a model. The constraint 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.

For example, this constraint checks that a Linear controller in a system does not have an External plant.

~((Ctrl == ControllerType.Linear) && (PlantLoc == PlantLocation.External))

When a model is associated with a VariantConfigurationObject that has constraints, Simulink validates the variant configurations against these constraints during Variant Manager activation, update diagram, simulation, and code generation workflows.

Variant Configuration Data Object

You can use a variant configuration data object of type Simulink.VariantConfigurationData to manage and reuse variant configurations for a model. The object stores all the variant configurations and constraints created 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 associated with a variant configuration data object, Variant Manager helps you to setup a new variant configuration data object.

From the Manage tab in Variant Manager, you can:

  • Specify a name for the variant configuration data object for the model.

  • Apply the changes made to the variant configuration data object from Variant Manager to the base workspace or data dictionary used by the model.

  • Export the variant configuration data object to a MAT-file or MATLAB® script file.

  • Import a variant configuration data object from a MAT-file or MATLAB script file into Variant Manager.

  • Reload the object from the base workspace or data dictionary used by the model. This allows you to revert the changes that are not yet exported to the base workspace or data dictionary.

    When you export the variant control variables in a variant configuration to the base workspace or data dictionary used by the model or when you activate a variant configuration, the corresponding variant control variables are pushed to the base workspace or data dictionary. Reloading the variant configuration object from Variant Manager does not revert these changes.

  • Disassociate the variant configuration data object from the model.

For an example that shows how to perform these actions from Variant Manager, see Save and Reuse Variant Configurations Using Variant Configuration Data Object.

The Simulink.VariantConfigurationData class has methods that enable you to add or remove variant configurations, constraints, and control variables.

Get Variant Configuration Data Object for Model

To get the variant configuration data object associated with a model programmatically, execute this command from the MATLAB Command-Line window.

vcdo = Simulink.VariantManager.getConfigurationData('model');

To get only the name of the variant configuration data object associated with the model, use this command:

get_param('model','VariantConfigurationObject');

Associate or Disassociate Variant Configuration Object from Model

To associate or disassociate a variant configuration data object from a model programmatically, use the VariantConfigurationObject model parameter.

% Associate vcdo
set_param('model','VariantConfigurationObject','name_of_vcdo');
% Disassociate vcdo
set_param('model','VariantConfigurationObject','');
% Save the model
save_system('model');

Edit Variant Configuration Data Object from Workspace

You can edit a variant configuration object from the base workspace or data dictionary without launching Variant Manager. Double-click the object that is present in the base workspace or in the Configurations section of the data dictionary in the Model Explorer. This action opens the Simulink.VariantConfigurationData property dialog box. This dialog box functions as a stand-alone variant manager and allows you to modify variant configurations, control variables, and constraints in the variant configuration object.

VariantConfigurationData dialog box in Model Explorer

Activate a Variant Configuration

Activating a variant configuration using Variant Manager validates that the variant elements in the model and the variant configuration are set up correctly and applies the configuration to the model. It also validates the configuration against applicable constraints. You can then compile, simulate, or generate code from the model for this configuration.

You can activate these configurations from Variant Manager:

  • The workspace configuration:

    Activation is based on the control variables that are currently in the base workspace or data dictionary used by the model. You can also add new control variables to this configuration using the table in the Control Variables section. Activation pushes these variables to the base workspace or data dictionary.

  • A named variant configuration:

    Activation is only based on the values of control variables defined in the configuration. This operation also pushes the control variables to the base workspace or data dictionary used by the model.

For detailed steps to create and activate a variant configuration, see Create and Activate Variant Configurations. To activate a variant configuration programmatically, use the Simulink.VariantManager.activateModel method.

Tip

On successful activation, the model hierarchy reflects the active configuration.

Variant Manager model hierarchy reflects the active configuration

Differences Between Variant Manager Activation and Update Diagram Process

Activation of a variant configuration using Variant Manager or using the Simulink.VariantManager.activateModel method differs from the update diagram process that Simulink performs before simulation or when you update the diagram while editing the model (Ctrl+D).

Activation using Variant Manager analyzes variant elements such as variant blocks, variant parameters, or variant transitions in the model individually. The process validates that the variant elements and the variant configuration are set up correctly and then activates the configuration for the model. For example, for a variant block with Variant control mode set to expression, the process evaluates the variant controls on the block and checks if the control variables used by the block are present in the variant configuration. Variant Manager does not analyze activeness information based on block connectivity and variant condition propagation.

Referenced Component 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. For more information, see Compose Variant Configurations for Top Model Using Referenced Model Configurations.

Preferred Configuration

You can set any of the named configurations defined for a model as the preferred variant configuration. You can use this property to indicate the configuration that is suited for the model for common workflows.

Note

The preferred configuration does not function as the default configuration for a model. You must activate the preferred configuration explicitly on the model, if required.

To programmatically apply the PreferredConfiguration on your model before compiling or simulating the model, use the applyConfiguration method:

% Get the variant configuration data object for your model
vcd = Simulink.VariantManager.getConfigurationData(model);
% Apply the preferred configuration on the model
Simulink.VariantManager.applyConfiguration ...
(model, 'Configuration', vcd.getPreferredConfigurationName());
Alternatively, use this command:
Simulink.VariantManager.applyConfiguration ...
 (model, 'Configuration', Simulink.VariantManager.getPreferredConfigurationName(model));

Variant Manager View of Variant Configurations

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.

View the Configurations tab in Variant Manager.

Variant configurations pane in Variant Manager

  • The first entry indicates the base workspace or data dictionary used by the model, for example, topdata.sldd. The variant control variables and their values currently present in this workspace of the model act as a temporary variant configuration for the model.

  • 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 grey background color.

  • The Preferred Configuration section allows you to select a named configuration that is suitable for the model for common workflows.

Use Variant Configurations in Simulation and Testing Workflows

Since R2024a

When you run simulations for your variant model programmatically, you can specify the variant configuration to apply to the model during simulation. For simulation functions such as sim, parsim, and batchsim, you can set the VariantConfiguration property in the Simulink.SimulationInput object. For an example, see Run Simulations for Variant Models Using Variant Configurations. However, if variant configurations are not defined for your model, you must write scripts to activate the required variant configuration using the Simulink.VariantManager.activateModel method in the setPreSimFcn callback for each SimulationInput object.

When running programmatic tests, you can specify variant configurations for both test cases and test iterations to cover different variant paths implemented in the model. You can set the VariantConfiguration property in the sltest.testmanager.TestCase (Simulink Test) and sltestiteration (Simulink Test) objects. For an example, see Run Tests for Variant Models Using Variant Configurations. For models that do not have variant configurations defined, you must write scripts that use the setVariable method to set the variant control variables as input to the test iteration, or you must activate the required variant configurations using the Simulink.VariantManager.activateModel function in the PostLoadFcn model callback before running the test.

Limitations

  • For a variant block, you can define variant configurations only if the Variant control mode parameter of the block is set to expression.

See Also

|

Related Topics