Simulink.VariantBank Class

Namespace: Simulink

Group all variant parameter values in structure array in generated code

Since R2023a

Description

A variant parameter is defined as a Simulink.VariantVariable object. Use the Simulink.VariantBank class to group variant parameters with the same variant conditions into a structure in generated code, called a variant parameter bank. To add a variant parameter to a variant parameter bank, set the Bank property of the Simulink.VariantVariable object to the name of the Simulink.VariantBank object. You can use the same variant parameter bank to group variant parameters used by models across the hierarchy. To specify code generation properties for a variant parameter bank, use the Simulink.VariantBankCoderInfo class.

When you generate code using Embedded Coder^®, Simulink.VariantVariable objects that are part of the same variant parameter bank appear in a structure. This structure is named according to the Name property of the parameter bank object. The code contains an array of this structure type and groups the choice values from the variant parameters based on the variant conditions specified for the parameter bank. Each set of values becomes an element of the structure array. The code uses a pointer variable to access the active set of values from the structure array. The code initializes this pointer based on variant conditions in the model_initialize function.

Variant parameter bank switching using a pointer variable avoids copying the parameter values into the main program memory and improves the efficiency and readability of the generated code. Additionally, you can set code generation properties for the variant parameter bank. You can specify separate memory sections, header, and definition files to place the structure array and pointer in the generated code. You can also specify a type qualifier that is applied to the declaration and definition of the array and pointer variables in the code. See Simulink.VariantBankCoderInfo.

For information on code generation with variant parameter banks, see Extended Capabilities.

Note

You can use variant parameter banks only with variant parameters that have the variant activation time set to startup.

You must have Embedded Coder to switch variant parameter banks in generated code.

You must define a variant parameter bank in the same data source (base workspace or data dictionary) as the variant parameters grouped by it. You can add Simulink.VariantBank or Simulink.VariantBankCoderInfo objects to the base workspace or the Design Data section of a data dictionary either programmatically or from the Add menu in the Model Explorer.

When using both Specification and Bank properties for a Simulink.VariantVariable object, the specification object must have storage class set to Auto and it must not use symbolic dimensions. For a variant parameter bank, use a Simulink.VariantBankCoderInfo object to specify code generation attributes.

Creation

Description

varparambank = Simulink.VariantBank returns a Simulink.VariantBank object with default property values.

varparambank = Simulink.VariantBank(PropertyName=Value) returns a Simulink.VariantBank object and sets properties using one or more name-value arguments.

Properties

Name — Name of variant parameter bank

'' (default) | string | character vector

Name of the variant parameter bank, specified as a string or character vector.

In the code generated using Embedded Coder, this property is the name of the structure that represents the variant parameter bank.

Example: "EngineParams"

Attributes:

GetAccess	public
SetAccess	public

Data Types: string | char

Description — Description of variant parameter bank

'' (default) | string | character vector

Description of the variant parameter bank, specified as a string or character vector.

In the code generated using Embedded Coder, this description appears as a comment for the variant parameter bank structure type.

Example: "Engine parameters"

Attributes:

GetAccess	public
SetAccess	public

Data Types: string | char

VariantConditions — List of variant conditions for variant parameter bank

[] (default) | cell array

List of variant conditions for the variant parameter bank, specified as a cell array of strings. These conditions must match the variant conditions of the Simulink.VariantVariable objects in this parameter bank, except any default variant choice specified using the (default) keyword.

When you use Embedded Coder, the generated code groups the choice values from the variant parameters in the parameter bank based on these variant conditions. Each set of these grouped values becomes an element of a structure array. During model initialization, Simulink^® selects the active set of parameter values from the structure array based on the variant condition that evaluates to true.

Note

Variant parameter banks do not support the (default) variant condition in the VariantConditions property.

Example: {'V == 1', 'V == 2'}

Attributes:

GetAccess	public
SetAccess	public

Data Types: cell

AllChoicesCoderInfo — Name of Simulink.VariantBankCoderInfo object to apply to structure array

'' (default) | string | character vector

Name of a Simulink.VariantBankCoderInfo object to apply to the structure array that groups the variant parameter values, specified as a string or character vector. Use this object to specify code generation attributes to apply to the structure array that groups the parameter values, including filenames for code placement and memory section to place parameter values.

Attributes:

GetAccess	public
SetAccess	public

Data Types: string | char

ActiveChoiceCoderInfo — Name of Simulink.VariantBankCoderInfo object to apply to pointer variable

' ' (default) | string | character vector

Name of a Simulink.VariantBankCoderInfo object to apply to the pointer variable, specified as a string or character vector. Use this object to specify code generation attributes to apply to the pointer variable that selects the active set of values from the structure array, including filenames for code placement and memory section to place the variable.

The table shows the combinations of type qualifiers that are not supported when you use the AllChoicesCoderInfo and ActiveChoiceCoderInfo properties.

AllChoicesCoderInfo	ActiveChoiceCoderInfo
Const	None
Const	Volatile
ConstVolatile	None
ConstVolatile	Volatile

Attributes:

GetAccess	public
SetAccess	public

Data Types: string | char

Examples

Group Variant Parameter Values in Code Using Variant Parameter Bank

This example shows you how to group variant parameters in the generated code by adding them to the same variant parameter bank (Simulink.VariantBank).

Create a variant parameter bank.

EngineParams = Simulink.VariantBank(Name='EngineParams',Description='Engine parameters',...
                                     VariantConditions={'V == EngType.Small','V == EngType.Big'});

Create a variant control variable V using the Simulink.VariantControl class. The Value property of this object allows you to select an active value for a variant parameter and the ActivationTime property allows you to specify a variant activation time. To use variant parameter banks, the activation time must be set up to startup. Use this variable to specify the variant condition expression for the choice values of a variant parameter.

Create two variant parameter objects K1 and K2 and associate them with the variant parameter bank EngineParams.

Use the name of the variant parameter bank to set the Bank property of a Simulink.VariantVariable object. The generated code groups the Simulink.VariantVariable objects that share the same Bank property in the same structure.

V = Simulink.VariantControl(Value=EngType.Small,ActivationTime='startup');
K1 = Simulink.VariantVariable(Choices={'V == EngType.Small',3,'V == EngType.Big',6},Bank='EngineParams');
K2 = Simulink.VariantVariable(Choices={'V == EngType.Small',[3, 6, 9],'V == EngType.Big',[5, 10, 15]},Bank='EngineParams');

To additionally specify code generation properties for a variant parameter bank, use the Simulink.VariantBankCoderInfo class.

Specify Code Generation Properties for Variant Parameter Banks

Create a variant parameter bank.

EngineParams = Simulink.VariantBank(Name="EngineParams", ...
  Description="Engine parameters", ...
  VariantConditions={'V == EngType.Small','V == EngType.Big'});

Create a Simulink.VariantBankCoderInfo object to specify code generation properties for the variant parameter bank structure array that will represent EngineParams in the generated code. Use the name of the object to set the AllChoicesCoderInfo property of the EngineParams bank object.

EngineParamsAllChoicesCoderInfo = Simulink.VariantBankCoderInfo(HeaderFile="vparams.h", ...
  DefinitionFile="vparams.c", ...
  PreStatement='#pragma data_seg(.vparamdata)',PostStatement="#pragma end", ...
  Qualifier="Const");
EngineParams.AllChoicesCoderInfo = "EngineParamsAllChoicesCoderInfo";

Create a second Simulink.VariantBankCoderInfo object to specify code generation properties for the pointer variable used by the parameter bank. Use the name of the object to set the ActiveChoicesCoderInfo property of the EngineParams bank object.To apply the same code generation properties for both the structure array and the pointer variable, set the AllChoicesCoderInfo and ActiveChoiceCoderInfo properties to the same Simulink.VariantBankCoderInfo object.

EngineParamsActiveChoicesCoderInfo = Simulink.VariantBankCoderInfo(HeaderFile="vparams_ptr.h", ...
  DefinitionFile="vparams_ptr.c", ...
  PreStatement="#pragma data_seg(.pointerdata)",PostStatement="#pragma end", ...
  Qualifier="Const");
EngineParams.ActiveChoiceCoderInfo = "EngineParamsActiveChoicesCoderInfo";

Create a variant control variable V using the Simulink.VariantControl class. The Value property of this object allows you to select an active value for a variant parameter and the ActivationTime property allows you to specify a variant activation time. Use this variable to specify the variant condition expression for the choice values of a variant parameter.

Create two variant parameter objects K1 and K2 with variant activation time startup and associate them with the variant parameter bank EngineParams.

V = Simulink.VariantControl(Value=EngType.Small, ...
   ActivationTime="startup");
K1 = Simulink.VariantVariable(Choices={"V == EngType.Small",3,"V == EngType.Big",6}, ...
    Bank="EngineParams");
K2 = Simulink.VariantVariable(Choices={"V == EngType.Small", [3, 6, 9],"V == EngType.Big",[5, 10, 15]}, ...
    Bank="EngineParams");

Use the variant parameters K1 and K2 in your model and generate code from the model using Embedded Coder®. For information on how to generate code, see Generate Code Using Embedded Coder (Embedded Coder).

Because K1 and K2 have variant activation time set to startup, the code contains a structure EngineParams. The name of this structure is the same as the Name property of the parameter bank object. The structure definition is in the header file vparams.h and the structure array is in the definition file vparams.c.

/* vparams.h */ 
/* Variant parameter bank: EngineParams, for system '<Root>' */
/* Engine parameters */
typedef struct {
  real_T K2[3];   
  real_T K1;   
} EngineParams;

/* Variant parameter bank: EngineParams */
/* Variant parameter bank section */
#pragma data_seg(.vparamdata)
extern const EngineParams EngineParams_ptr_impl[2];
#pragma end

A structure array EngineParams_ptr_impl of type EngineParams contains choice values of K1 and K2. The number of elements in the array depends on the number of variant conditions that you specify in the VariantConditions property of the parameter bank object.

/* vparams.c */ 
#pragma data_seg(.vparamdata)
const EngineParams EngineParams_ptr_impl[2] = {
  {
    /* Variable: K2
     * Referenced by: '<Root>/Gain1'
     */
    { 5.0, 10.0, 15.0 },

    /* Variable: K1
     * Referenced by: '<Root>/Gain'
     */
    6.0
  }, {
    /* Variable: K2
     * Referenced by: '<Root>/Gain1'
     */
    { 3.0, 6.0, 9.0 },

    /* Variable: K1
     * Referenced by: '<Root>/Gain'
     */
    3.0
  }
};
#pragma end    

Similarly, the header and definition files, vparams_ptr.h and vparams_ptr.c, contain the declaration and definition for the pointer variable.

/* vparams_ptr.h */
/* Variant parameter bank section */
#pragma data_seg(.pointerdata)
extern const EngineParams *EngineParams_ptr;
#pragma end

/* vparams_ptr.c */
#pragma data_seg(.pointerdata)
const EngineParams *EngineParams_ptr = &EngineParams_ptr_impl[1];
#pragma end

The var_param_bank_initialize function initializes the structure pointer variable EngineParams_ptr. The code uses the pointer variable to access the active value set from the array based on variant conditions.

/* model.c */

/* Model step function */
void var_param_bank_step(void)
{
 /* Outport: '<Root>/Out2' incorporates:
  *  Gain: '<Root>/Gain1'
  *  Inport: '<Root>/Input1' 
  */
  var_param_bank_Y.Out2[0] = EngineParams_ptr->K2[0] * var_param_bank_U.Input1;
  var_param_bank_Y.Out2[1] = EngineParams_ptr->K2[1] * var_param_bank_U.Input1;
  var_param_bank_Y.Out2[2] = EngineParams_ptr->K2[2] * var_param_bank_U.Input1;

 /* Outport: '<Root>/Out1' incorporates:
  *  Gain: '<Root>/Gain'
  *  Inport: '<Root>/Input'
  */
var_param_bank_Y.Out1 = EngineParams_ptr->K1 * var_param_bank_U.Input;
}

/* Model initialize function */
void var_param_bank_initialize(void)
{
 /* Variant Parameters startup activation time */
if (V == EngType_Big) {
    EngineParams_ptr = &EngineParams_ptr_impl[0U];
  } else if (V == EngType_Small) {
    EngineParams_ptr = &EngineParams_ptr_impl[1U];
  }
 var_param_startupVariantChecker();
}

Limitations

• Variant parameter banks do not support code generation for external mode operation over tcpip or serial protocols. These model configuration parameter settings in the Code Generation > Interface category correspond to this mode — External mode (Simulink Coder) parameter set to On and Transport layer (Simulink Coder) parameter set to tcpip or serial.

• Variant parameters that are part of a variant parameter bank do not support AUTOSAR code generation.

• Software-in-the-loop (SIL) and processor-in-the-loop (PIL) simulations are not supported for models that use variant parameter banks.

Tips

To modify a Simulink.VariantBank object, double-click the object to open the Simulink.VariantBank dialog box.

You can also create variant parameter banks from Variant Manager. See Create Variant Banks for Variant Parameters from Variant Manager.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

For variant parameters that are part of a variant parameter bank and have startup activation time:

• Simulink Coder™:

  The generated code contains inlined values of the variant parameters in the model_initialize function.

• Embedded Coder:

  The generated code contains the choice values grouped into a structure array based on the variant conditions. The code uses a pointer variable to access values from the structure array.

  • Code generation with C++ class interface:

    When you use Embedded Coder to generate C++ code with the Code interface packaging (component) (Simulink Coder) model configuration parameter set to C++ class, the Include model types in model class (Embedded Coder) parameter has no effect on the generated code. Regardless of the setting of this parameter, the code generator places the type definitions of variant parameter banks in a separate header file.

  • Code generation when variant parameter contains default variant condition:

    A Simulink.VariantVariable object that is part of a variant bank allows the (default) variant condition for its choice conditions. However, a variant parameter bank does not support (default) in its VariantConditions property.

    Consider this example with two variant parameters K1 and K2 that are part of the same variant bank. K1 defines a value for the condition V == EngType.Small and a value for the (default) condition. Similarly, K2 defines values for the variant conditions V == EngType.Big and (default).

    % Define variant parameter bank
    EngineParams = Simulink.VariantBank('Name','EngineParams',...
     'Description','Engine parameters',...
     'VariantConditions', {'V == EngType.Small', 'V == EngType.Big'});
    
    % Define Bank CoderInfo
    EngineParamsCoderInfo = Simulink.VariantBankCoderInfo...
    ('HeaderFile','vparams.h','DefinitionFile','vparams.cpp',...
     'PreStatement', '#pragma data_seg(.mydata)');
    EngineParams.BankCoderInfo = 'EngineParamsCoderInfo';
    
    % Define variant parameters
    V = Simulink.VariantControl('Value', EngType.Small,... 
     'ActivationTime', 'startup');
    K1 = Simulink.VariantVariable...
    ('Choices', {'V == EngType.Small', 3 , '(default)', 6},...
     'Bank', 'EngineParams');
    K2 = Simulink.VariantVariable...
    ("Choices", {'(default)', [3,6,9], 'V == EngType.Big', [5,10,15]},...
     'Bank', 'EngineParams');

    When you generate code using Embedded Coder, the structure array contains the default value if a value corresponding to a parameter bank variant condition is not found in the variant parameter.

    //vparams.cpp
    EngineParams EngineParams_ptr_impl[2] = {
      {
        // Variable: K2
        //  Referenced by: '<Root>/Gain1'
    
        { 5.0, 10.0, 15.0 },
    
        // Variable: K1
        //  Referenced by: '<Root>/Gain'
    
        6.0
      }, {
        // Variable: K2
        //  Referenced by: '<Root>/Gain1'
    
        { 3.0, 6.0, 9.0 },
    
        // Variable: K1
        //  Referenced by: '<Root>/Gain'
    
        3.0
      }
    };
    

  • When you use a variant parameter bank to group variant parameters used across the model reference hierarchy, the code generator places the header files that contain the type definition and declaration for the variant parameter bank structure array and pointer variable in a shared utilities folder. For an example, see Generate Code for Variant Parameter Banks in Model Reference Hierarchy (Embedded Coder).

Version History

Introduced in R2023a

R2025a: BankCoderInfo property replaced with AllChoicesCoderInfo and ActiveChoiceCoderInfo

The BankCoderInfo property will be removed. Use the AllChoicesCoderInfo and ActiveChoiceCoderInfo properties instead to specify code generation attributes for the parameter data array and the pointer variable corresponding to a variant parameter bank. If your existing code sets the BankCoderInfo property, Simulink uses this value to automatically set the value for the AllChoicesCoderInfo and ActiveChoiceCoderInfo properties.

Support for model reference hierarchy

You can simulate and generate code for a model reference hierarchy that uses the same variant parameter bank to group variant parameters used by models across the hierarchy. For an example, see Generate Code for Variant Parameter Banks in Model Reference Hierarchy (Embedded Coder).