Main Content

Simulink.VariantManager.generateConfigurations

Generate variant configurations automatically

Since R2022b

collapse all in page

Syntax

vcdo = Simulink.VariantManager.generateConfigurations(modelName)
[vcdo,configsInfo] = Simulink.VariantManager.generateConfigurations(modelName,Name=Value)

Description

vcdo = Simulink.VariantManager.generateConfigurations(modelName) generates variant configurations for the given model modelName. The function returns a variant configuration data object vcdo that contains the generated configurations.

example

[vcdo,configsInfo] = Simulink.VariantManager.generateConfigurations(modelName,Name=Value) generates variant configurations for the given model modelName as specified by one or more optional name-value arguments.

If Precondition argument is specified and the AddPreconditionAsConstraint argument is set to true, the corresponding condition is defined as a global constraint in the output object vcdo. The optional configsInfo output contains information on the validity of the generated configurations.

Note

To use this function, you must install the Variant Manager for Simulink® support package.

example

Examples

collapse all

This example uses:

Open Live Script

This example shows how to generate variant configurations for a model programmatically.

To generate variant configurations from Variant Manager, see Generate Variant Configurations Automatically.

These commands return valid variant configurations for the model slexVariantManagement that satisfy the conditions specified on the variant control variables Ctrl and PlantLoc.

modelName = "slexVariantManagement";
open_system(modelName);
[vcdo,configsInfo] = Simulink.VariantManager.generateConfigurations...
 (modelName,Precondition={'Ctrl==ControllerType.Linear','PlantLoc==PlantLocation.Internal'},...
 AddPreconditionAsConstraint=true,Validity="valid");
Activating the model for the current state of the model.

Warning: The model has Simulink.VariantVariable(s) 'Kc, LUTBPs' which are not supported for generating configurations. Generated configurations will not have variations for variant parameters.

Only the active variant choice is considered for the following blocks with 'Variant activation time' set to 'update diagram'.
 slexVariantManagement/Plant
 slexVariantManagement/Plant/Internal
An update diagram operation is required to generate variant configurations.
Performing update diagram for the model.
Evaluating 12 potential combinations to generate...
Number of generated configurations: 4
Created snapshot of the model at 'C:\Users\dskolnic\OneDrive - MathWorks\Documents\MATLAB\ExampleManager\dskolnic.Bdoc.j2631799\simulink_variants-ex51080552\slexVariantManagement_vmgrsnap\20240606_141640'.

The variant configuration data object vcdo stores all the valid configurations. The structure array configsInfo provides information on the validity status of generated configurations.

To return only valid and functionally unique configurations, set Validity to "valid-unique".

[vcdo,configsInfo] = Simulink.VariantManager.generateConfigurations(modelName,...
  Precondition={'Ctrl==ControllerType.Linear','PlantLoc==PlantLocation.Internal'},...
  AddPreconditionAsConstraint=true,Validity="valid-unique");
Activating the model for the current state of the model.

Warning: The model has Simulink.VariantVariable(s) 'Kc, LUTBPs' which are not supported for generating configurations. Generated configurations will not have variations for variant parameters.

Only the active variant choice is considered for the following blocks with 'Variant activation time' set to 'update diagram'.
 slexVariantManagement/Plant
 slexVariantManagement/Plant/Internal
An update diagram operation is required to generate variant configurations.
Performing update diagram for the model.
Evaluating 12 potential combinations to generate...
Number of generated configurations: 2
Created snapshot of the model at 'C:\Users\dskolnic\OneDrive - MathWorks\Documents\MATLAB\ExampleManager\dskolnic.Bdoc.j2631799\simulink_variants-ex51080552\slexVariantManagement_vmgrsnap\20240606_141644'.

To return all generated configurations, including invalid configurations, set Validity to "all".

[vcdo,configsInfo] = Simulink.VariantManager.generateConfigurations(modelName,...
  Precondition={'Ctrl==ControllerType.Linear','PlantLoc==PlantLocation.Internal'},...
  AddPreconditionAsConstraint=true,Validity="all");
Activating the model for the current state of the model.

Warning: The model has Simulink.VariantVariable(s) 'Kc, LUTBPs' which are not supported for generating configurations. Generated configurations will not have variations for variant parameters.

Only the active variant choice is considered for the following blocks with 'Variant activation time' set to 'update diagram'.
 slexVariantManagement/Plant
 slexVariantManagement/Plant/Internal
An update diagram operation is required to generate variant configurations.
Performing update diagram for the model.
Evaluating 12 potential combinations to generate...
Number of generated configurations: 4
Created snapshot of the model at 'C:\Users\dskolnic\OneDrive - MathWorks\Documents\MATLAB\ExampleManager\dskolnic.Bdoc.j2631799\simulink_variants-ex51080552\slexVariantManagement_vmgrsnap\20240606_141649'.

Input Arguments

collapse all

Name of the model, specified as a character vector or string.

Example: "slexVariantManagement"

Data Types: char | string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: vcdo = Simulink.VariantManager.generateConfigurations("slexVariantManagement", Precondition={'Ctrl == ControllerType.Linear','PlantLoc == PlantLocation.Internal'}, AddPreconditionAsConstraint=true,Validity="valid")

Conditions that must be satisfied by the generated configurations, specified as a character vector or cell array of character vectors containing valid Boolean expressions. You can use preconditions to limit the combinations of control variables to consider at a time or to apply constraints based on requirements.

Example: {'Ctrl == ControllerType.Linear', 'PlantLoc == PlantLocation.Internal'}

Data Types: char | cell

Option to export preconditions as constraints in the output variant configuration data object vcdo specified as a numeric or logical 1 (true) or 0 (false). If false, the predicate conditions are not added to vcdo. If true, the conditions are added as constraints that must be satisfied by all configurations in vcdo.

Type of configurations to include in the output, specified as "valid-unique", "valid", or "all".

The configurations generated by this function can include invalid configurations that might result in compilation errors or duplicate configurations that are functionally equivalent and produce similar results. Use this argument to specify which of these configurations to retain in the output.

  • "valid-unique" — Include only valid configurations without any duplicates that are functionally equivalent. Two variant configurations are functionally equivalent if they result in same set of active blocks in the model. This option generates a minimal set of configurations with maximum coverage.

    If a configuration has functional equivalents, using this option also lists one of those equivalent configurations in the output with the Validity Status value set to EquivalentK. In this value, K is an annotation to identify a group of equivalent configurations, for example, Equivalent1.

  • "valid" — Include only valid configurations.

    These configurations might include duplicate configurations that are functionally equivalent. Functional duplicates might occur due to the structure of a model resulting in the same variant paths being active for different variant control values. This option generates the full set of configurations with redundant coverage.

  • "all" — Include valid, invalid, and duplicate configurations.

    An invalid configuration violates variant semantics and causes an error during the update diagram process, for example, if you have a configuration that deactivates all choices in an inline variant block. However, this block has the Allow zero variant control parameter set to off, which contradicts the deactivation and causes an error.

For any Validity option, the function generates only those configurations that satisfy the specified preconditions.

Example: "valid"

Name of a variant configuration data object of type Simulink.VariantConfigurationData that contains the configurations that do not need to be generated, specified as a character vector. This also excludes any constraints present in the variant configuration data object. Use this option to augment existing configurations for a model or to generate configurations incrementally.

Example: "vcDataObjIgnore"

Output Arguments

collapse all

Variant configuration data object that contains the generated variant configurations for the given model, returned as an object of type Simulink.VariantConfigurationData. If Precondition is provided and AddPreconditionAsConstraint is set to true, the corresponding conditions are defined as model-wide constraints in this object.

Name and validity of generated configurations, returned as a structure array with these fields:

  • Name — Name of the generated configuration

  • ValidityStatus — Validity of the generated configuration that indicates whether a configuration is unique, a functional equivalent, or invalid, specified as one of these values:

    • Unique — Configuration is valid and unique without any functional duplicates.

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

    • Invalid — Configuration is not valid.

For example, consider a variant configuration object vcdo with six generated configurations. The generated configurations have validity as follows:

  • VConfig1 is valid and has no functional duplicates.

  • VConfig3 is invalid.

  • VConfig2 and VConfig5 are valid and equivalent.

  • VConfig4 and VConfig6 are valid and equivalent.

Then, configsInfo is a 1-by-6 structure array: 

'VConfig1'	'Unique'
'VConfig2'	'Equivalent1'
'VConfig3'	'Invalid'
'VConfig4'	'Equivalent2'
'VConfig5'	'Equivalent1'
'VConfig6'	'Equivalent2'

Data Types: struct

Limitations

  • Automatic configuration generation supports only logical operators ==, ~=, &&, ||, and ~ 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 be generated.

  • Automatic configuration generation 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

    • Models that represent libraries or subsystems

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

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

      Model with a Variant Subsystem block in label mode

      Here is the list of all generated configurations.

      Variant Manager with generated configurations that use only variable A

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

      Model with a Variant Subsystem block in simcodegen mode

      Here is the list of all generated configurations.

      Variant Manager with generated configurations for sim choice

    • If the Variant activation time is set to update diagram, only the variations in the active choice are considered for generating configurations.

Tips

You can use the intersect, setdiff, union, and unique methods in the Simulink.VariantConfigurationData class to perform set operations on variant configuration data objects. See Specialized Operators and Functions.

Version History

Introduced in R2022b

See Also

| | |

Topics