Simulink.VariantManager.generateConfigurations

Class: Simulink.VariantManager
Package: Simulink

Generate variant configurations automatically

Since R2022b

Syntax

vcdataobj = Simulink.VariantManager.generateConfigurations(modelName)

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

Description

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

[vcdataobj,configsInfo] = Simulink.VariantManager.generateConfigurations(modelName,Name=Value) generates variant configurations for the given model modelName as specified by optional Name=Value arguments.

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

Input Arguments

modelName — Name of the model

string | character vector

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: vcdataobj=Simulink.VariantManager.generateConfigurations("slexVariantManagement", Precondition={'Ctrl == ControllerType.Linear', 'PlantLoc == PlantLocation.Internal'}, AddPreconditionAsConstraint=true, Validity="valid")

Precondition — Conditions that must be satisfied by generated configurations

character vector | cell array of character vectors

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

AddPreconditionAsConstraint — Option to export preconditions as constraints

false or 0 (default) | true or 1

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

Validity — Type of configurations to include in the output

"valid-unique" (default) | "valid" | "all"

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

The configurations generated by this method can include invalid configurations that might result in compilation errors or duplicate configurations that are functionally equivalent and hence 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, this option lists one of those equivalent configurations also in the result with the Validity Status value as EquivalentK. 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 repetitive 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, 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 method generates only those configurations that satisfy the specified preconditions.

Example: "valid"

ExcludeVariantConfigurationData — Configurations and constraints that do not need to be generated

character vector

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: 'vcataObjIgnore'

Output Arguments

vcdataobj — Variant configuration data object

Simulink.VariantConfigurationData

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.

configsInfo — Name and validity of configurations

structure array

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

• Name — Name of the generated configuration

• ValidityStatus — Validity of the generated configuration that indicates whether a configuration is unique, a functional equivalent, or an invalid one, 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 vcdataobj 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

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

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

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

Examples

Generate Variant Configurations Programmatically

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

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

This command returns valid variant configurations for the model slexVariantManagement that satisfy the conditions specified on the variant control variables Ctrl and PlantLoc.

model = "slexVariantManagement";
open_system(model);
[vcdataobj,configsInfo] = Simulink.VariantManager.generateConfigurations ...
 (model, Precondition = {'Ctrl == ControllerType.Linear', 'PlantLoc == PlantLocation.Internal'}, ...
 AddPreconditionAsConstraint = true, Validity = "valid");

Activating the model for the current state of the model.
An update diagram operation is required to generate variant configurations.
Performing update diagram for the model.
Evaluating 96 potential combinations to generate...
Number of generated configurations: 16
Created snapshot of the model at '/tmp/Bdoc23a_2213998_1376426/tp81ec0541/simulink_variants-ex51080552/slexVariantManagement_vmgrsnap/20230303_082353'.

The variant configuration data object vcdataobj 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.

[vcdataobj,configsInfo] = Simulink.VariantManager.generateConfigurations(model,...
  Precondition = {'Ctrl == ControllerType.Linear', 'PlantLoc == PlantLocation.Internal'}, ...
  AddPreconditionAsConstraint = true, Validity = "valid-unique");

Activating the model for the current state of the model.
An update diagram operation is required to generate variant configurations.
Performing update diagram for the model.
Evaluating 96 potential combinations to generate...
Number of generated configurations: 3
Created snapshot of the model at '/tmp/Bdoc23a_2213998_1376426/tp81ec0541/simulink_variants-ex51080552/slexVariantManagement_vmgrsnap/20230303_082359'.

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

[vcdataobj,configsInfo] = Simulink.VariantManager.generateConfigurations(model,...
  Precondition = {'Ctrl == ControllerType.Linear', 'PlantLoc == PlantLocation.Internal'}, ...
  AddPreconditionAsConstraint = true, Validity = "all");

Activating the model for the current state of the model.
An update diagram operation is required to generate variant configurations.
Performing update diagram for the model.
Evaluating 96 potential combinations to generate...
Number of generated configurations: 16
Created snapshot of the model at '/tmp/Bdoc23a_2213998_1376426/tp81ec0541/simulink_variants-ex51080552/slexVariantManagement_vmgrsnap/20230303_082402'.

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