Simulink.VariantConfigurationData

Create and store variant configurations and constraints

expand all in page

    Description

    Note

    This object requires Variant Manager for Simulink®.

    Use a Simulink.VariantConfigurationData object to store a collection of variant configurations, constraints that must be satisfied by the configurations, and the name of a preferred variant configuration for a model. You can define the variant configuration data object in the base workspace or in the Configurations section of a Simulink data dictionary.

    A variant configuration represents a specific set of variation points across the model hierarchy. It contains a group of variant control variables and their values, which you can use to activate a specific variant in the model hierarchy. A Simulink.VariantConfigurationData object enables you to:

    • Define new variant configurations.

    • Add variant control variables to a variant configuration.

    • Define constraints to check for invalid variant configurations.

    • Add or remove association between variant configurations of top-level model and referenced model.

    • Delete existing variant configurations, constraints, and control variables.

    • Set a specific configuration as the preferred variant configuration.

    Creation

    Syntax

    varconfigdata = Simulink.VariantConfigurationData
    varconfigdata = Simulink.VariantConfigurationData(PropertyName=Value)

    Description

    varconfigdata = Simulink.VariantConfigurationData creates an empty VariantConfigurationData object.

    varconfigdata = Simulink.VariantConfigurationData(PropertyName=Value) creates a VariantConfigurationData object and sets its properties using one or more property name-value arguments.

    example

    Properties

    expand all

    This property is read-only after object creation.

    Set of variant configurations in the variant configuration data object, specified as a structure or structure array with these fields:

    FieldTypeDescription
    Namecharacter vector or string scalar

    Name of the configuration. The value must be a unique and valid MATLAB® variable name.

    Descriptioncharacter vector or string scalar

    Description of the configuration.

    ControlVariables

    structure or structure array

    Variant control variable names and their values, specified as a structure or structure array with the fields:

    • Name — Name of the control variable, specified as a character vector or string scalar.

    • Value — Value of the control variable, specified as any of these data types:

      • MATLAB variable

      • Simulink.Parameter

      • AUTOSAR.Parameter

      • Simulink.VariantControl whose Value is a normal MATLAB variable

      • Simulink.VariantControl whose Value is a Simulink.Parameter

      • Simulink.VariantControl whose Value is a user-defined type that inherits from Simulink.Parameter

      • Simulink.VariantControl whose Value is a Simulink.Parameter object or an object of a class that inherits from Simulink.Parameter, with the value of the object set to a mathematical expression specified using the slexpr function.

    • Source — Data source of the control variable, specified as a character vector or string scalar.

    Example: ctrlVarStruct=struct(Name="Ctrl",Value="ControllerType.Linear",Source="plant.sldd");

    Example:ctrlVarStruct=struct(Name="Vctrl",Value="1",Source="base workspace");

    For an example that shows the use of different types of variant control variables, see Use Variant Control Variables in Variant Blocks.

    Data Types: struct

    This property is read-only after object creation.

    Constraints that must be met by all variant configurations in the variant configuration data object, specified as a structure or structure array with these fields:

    • Name — Name of the constraint, specified as a character vector or string scalar. The value must be a unique and valid MATLAB variable name.

    • Condition — Boolean expression defined using variant control variables, specified as a character vector or string scalar. The expression must evaluate to true to satisfy the constraint.

    • Description — Description of the constraint, specified as a character vector or string scalar.

    Data Types: struct

    Name of the preferred variant configuration, specified as a character vector or string scalar. Use this property to indicate the configuration that is suited for the model for common workflows. The value must be the name of a variant configuration present in the variant configuration data object.

    Data Types: char | string

    Object Functions

    addConfigurationAdd new variant configuration to variant configuration data object
    addComponentConfiguration Associate top-model variant configuration with variant configuration of referenced model
    addConstraintAdd constraint to variant configuration data object
    addControlVariablesAdd variant control variables to named variant configuration in variant configuration data object
    addCopyOfConfigurationAdd copy of existing variant configuration to variant configuration data object
    convertDefaultToPreferredConvert default variant configuration to preferred variant configuration
    getConfigurationGet specific variant configuration from variant configuration data object
    getComponentConfigurationNameGet name of variant configuration used by referenced component in model hierarchy
    getPreferredConfigurationGet name of preferred variant configuration for variant configuration data object
    isConfigActiveCheck if variant configuration is active
    setPreferredConfiguration Set name of preferred variant configuration for variant configuration data object
    removeConfigurationRemove variant configuration from variant configuration data object
    removeComponentConfigurationRemove association between variant configurations of top-level model and referenced model
    removeConstraint Remove constraint from variant configuration data object
    removeControlVariableRemove variant control variable from variant configuration

    These functions specialize standard MATLAB set operations for Simulink.VariantConfigurationData objects.

    intersect

    vcdC = intersect(vcdA,vcdB)

    Find the intersection of variant configuration data objects vcdA and vcdB. This function returns a variant configuration data object, vcdC, with the common variant configurations present in vcdA and vcdB. The function finds the intersection by matching the variant control variables and their values.

    Constraints in vcdC are formed as follows. Consider the case where vcdA and vcdB have two constraints each.

    • vcdA has constraints constraintA1 and constraintA2.

    • vcdB has constraints constraintB1 and constraintB2.

    Then, vcdC has these constraints:

    • constraintA1 && (constraintB1 && constraintB2)

    • constraintA2 && (constraintB1 && constraintB2)

    The constraint conditions formed by logical AND, OR, and NOT operations are simplified by default and symbols can be reordered.

    vcdC = intersect(vcdA,vcdB,SimplifyConditions=false) returns a variant configuration data object vcdC in which constraint conditions are not simplified.

    The remaining properties of vcdC are the same as vcdA, and the data in vcdC appears in the same order as in vcdA.

    setdiff

    vcdC = setdiff(vcdA,vcdB)

    Find the difference between variant configuration data objects vcdA and vcdB. This function returns a variant configuration data object vcdC that contains configurations that are in vcdA but not in vcdB. The function finds the difference by identifying changes in the values of variant control variables.

    Constraints in vcdC are formed as follows. Consider the case where vcdA and vcdB have two constraints each.

    • vcdA has constraints constraintA1 and constraintA2

    • vcdB has constraints constraintB1 and constraintB2

    Then, vcdC has these constraints:

    • constraintA1 && ~(constraintB1 && constraintB2)

    • constraintA2 && ~(constraintB1 && constraintB2)

    The constraint conditions formed by logical AND, OR, and NOT operations are simplified by default and symbols can be reordered.

    vcdC = setdiff(vcdA,vcdB,SimplifyConditions=false) returns a variant configuration data object vcdC in which constraint conditions are not simplified.

    The remaining properties of vcdC are the same as vcdA, and the data in vcdC appears in the same order as in vcdA.

    union

    vcdC = union(vcdA,vcdB)

    Find the union of variant configuration data objects vcdA and vcdB. This function returns a variant configuration data object vcdC that contains configurations from both vcdA and vcdB, with no duplicates. The function finds the union by matching the variant control variables and their values.

    Constraints in vcdC are formed as follows. Consider the case where vcdA and vcdB have two constraints each.

    • vcdA : constraintA1, constraintA2

    • vcdB : constraintB1, constraintB2

    Then, vcdC has these constraints:

    • constraintA1 || (constraintB1 && constraintB2)

    • constraintA2 || (constraintB1 && constraintB2)

    The constraint conditions formed by logical AND, OR, and NOT operations are simplified by default and symbols can be reordered.

    vcdC = union(vcdA,vcdB,SimplifyConditions=false) returns a variant configuration data object vcdC in which constraint conditions are not simplified.

    The remaining properties of vcdC are the same as vcdA, and the data in vcdC appears in the same order as in vcdA, then vcdB.

    unique

    uniquedVCD = unique(vcd)

    Find unique configurations in the variant configuration data object vcd.

    Duplicate configurations in vcd are removed by comparing the values of variant control variables. Duplicate constraints in vcd are removed by comparing the constraint conditions.

    Examples

    collapse all

    This example uses:

    Open Live Script

    This example shows how to create a Simulink.VariantConfigurationData object and set these object properties:

    • Configurations

    • Constraints

    • PreferredConfiguration

    Define New Variant Configuration

    Define a new variant configuration to add to the variant configuration data object.

    The Configurations property of a Simulink.VariantConfigurationData object is a structure with these fields:

    • Name

    • ControlVariables

    • Description

    Create a structure for the ControlVariables field that contains the variant control variables and values for the new configuration.

    ctrlVarStructA(1).Name = "Ctrl";
ctrlVarStructA(1).Value = "ControllerType.Linear";
ctrlVarStructA(1).Source = "topData.sldd";
ctrlVarStructA(2).Name = "Noise";
ctrlVarStructA(2).Value = "NoiseType.NoNoise";
ctrlVarStructA(2).Source = "topData.sldd";
ctrlVarStructA(3).Name = "PlantLoc";
ctrlVarStructA(3).Value = "PlantLocation.Internal";
ctrlVarStructA(3).Source = "topData.sldd";
ctrlVarStructA(4).Name = "FidType";
ctrlVarStructA(4).Value = "Fidelity.High";
ctrlVarStructA(4).Source = "plantData.sldd";

    Create a structure for the new variant configuration.

    configStruct(1).Name = "LinInterExpNoNoise";
configStruct(1).ControlVariables = ctrlVarStructA;
configStruct(1).Description = "Linear Internal Plant Controller";

    Define a second variant configuration.

    ctrlVarStructB(1).Name = "Ctrl";
ctrlVarStructB(1).Value = "ControllerType.Nonlinear";
ctrlVarStructB(1).Source = "topData.sldd";
ctrlVarStructB(2).Name = "Noise";
ctrlVarStructB(2).Value = "NoiseType.NoNoise";
ctrlVarStructB(2).Source = "topData.sldd";
ctrlVarStructB(3).Name = "PlantLoc";
ctrlVarStructB(3).Value = "PlantLocation.External";
ctrlVarStructB(3).Source = "topData.sldd";
ctrlVarStructB(4).Name = "FidType";
ctrlVarStructB(4).Value = "Fidelity.Low";
ctrlVarStructB(4).Source = "plantData.sldd";

configStruct(2).Name = "NonLinExterLowFid";
configStruct(2).ControlVariables = ctrlVarStructB;
configStruct(2).Description = "Nonlinear External Plant Controller";

    Define Constraints

    Define any constraints applicable for all the variant configurations in the variant configuration data object.

    constrStruct = struct(Name="PlantLocation", ...
  Condition="(PlantLoc==PlantLocation.Internal) || (PlantLoc==PlantLocation.External)", ...
 Description="Plant location constraint");

    Create Variant Configuration Data Object

    Create the object by adding variant configurations, constraints, and the name of the preferred configuration.

     vcdo = Simulink.VariantConfigurationData(Configurations=configStruct,Constraints=constrStruct, ...
  PreferredConfiguration="LinInterExpNoNoise")
    vcdo = 
  VariantConfigurationData with properties:

            Configurations: [1×2 struct]
               Constraints: [1×1 struct]
    PreferredConfiguration: 'LinInterExpNoNoise'

    Associate or Disassociate Variant Configuration Data Object from Model

    You can associate vcdo with a Simulink® model using the VariantConfigurationObject model parameter.

    set_param("model",VariantConfigurationObject="vcdo");

    To disassociate vcdo from the model, set the VariantConfigurationObject model parameter to an empty character vector or string.

    set_param("model",VariantConfigurationObject="");

    Save the model to save your changes.

     save_system("model");

    Tips

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

    Version History

    Introduced in R2013b

    expand all

    See Also

    Topics