Structure Parameters

About Structure Parameters

Separately defining all base workspace variables used in block parameter expressions can clutter the base workspace and result in very long lists of arguments to subsystems and referenced models. The technique provides no way to conveniently group related base workspace variables, or to configure generated code to reflect the variables' relationships.

To minimize the disadvantages of separately defining workspace variables used by block parameters, you can group numeric variables by specifying their names and values as the fields of a MATLAB® structure in the base workspace. A MATLAB structure that Simulink® uses in block parameter expressions is called a structure parameter. You can use structure parameters to:

  • Simplify and modularize the base workspace by using multiple structures to group related variables and to prevent name conflicts

  • Dereference the structure in block parameter expressions to provide values from structure fields rather than separate variables

  • Pass all the fields in a structure to a subsystem or referenced model with a single argument.

  • Improve generated code to use structures rather multiple separate variables

For information about creating and using MATLAB structures, see Structures in the MATLAB documentation. You can use all the techniques described there to manipulate structure parameters. This section assumes that you know those techniques, and provides only information that is specific to Simulink.

For information on structure parameters in the context of generated code for a model, see Structure Parameters and Generated Code. For an example of how to convert a model that uses unstructured workspace variables to a model that uses structure parameters, see sldemo_applyVarStructsldemo_applyVarStruct.

Define Structure Parameters

Defining a structure parameter is syntactically the same as defining any MATLAB structure, as described in Structures. Every field in a MATLAB structure that functions as a structure parameter must have a numeric data type, even if Simulink never uses the field. Different fields can have different numeric types.

In structure parameters, numeric types include enumerated types, by virtue of their underlying integers. The value of a structure parameter field, can be a real or complex scalar, vector, or multidimensional array. However, a structure that contains any multidimensional array cannot be tuned. See Tunable Structure Parameters.

MATLAB structures, including those used as structure parameters, can have substructures to any depth. Structures and substructures at any level behave identically, so the following instructions refer only to structures unless substructures are specifically the point.

Referencing Structure Parameters

You can use MATLAB syntax, as described in Structures, to dereference a structure parameter field anywhere in a block parameter expression that a MATLAB variable can appear. You cannot specify a structure name in a mathematical block parameter expression, because that would pass a structure rather than a number. For example, suppose you have defined the following parameter structure:

A          /* Root structure
|__x          /* Numeric field
|__y          /* Numeric field
|__z          /* Substructure
   |__ m          /* Numeric field
   |__ n          /* Numeric field
   |__ k          /* Numeric field

Given this structure, you can specify an individual field, such as A.x,  in a block parameter expression, thereby passing only x to the block. The effect is exactly the same as if x were a separate base workspace variable whose value was the same as the value of A.x. Similarly, you could reference A.z.m, A.z.n, etc. The next figure shows an example that uses a Gain block:

The Gain block's Gain parameter is the value of A.x + A.z.k, a numeric expression. You could not reference A or A.z to provide a Gain parameter value, because neither resolves to a numeric value.

Structure Parameter Arguments

You can use a parameter structure field as a masked subsystem or model reference argument by referencing the field, as described in the previous section, in Subsystem block mask, or Model block. For example, suppose you have defined the parameter structure used in the previous example:

A          /* Root structure
|__x          /* Numeric field
|__y          /* Numeric field
|__z          /* Substructure
   |__ m          /* Numeric field
   |__ n          /* Numeric field
   |__ k          /* Numeric field

You could then:

  1. Use a whole structure parameter as a masked subsystem argument or a referenced model argument by referencing the structure's name

  2. Dereference the structure as needed in the subsystem mask code, the subsystem itself, or the referenced model.

For example, you could pass A, providing access to everything in the root structure, or A.z, providing access only to that substructure. The dereferencing syntax for arguments is the same as in any other context, as described in Structures.

When you pass a structure parameter to a referenced model, the structure definitions must be identical in the parent model and the referenced model, including any unused fields. See Systems and Subsystems, Masking, and Using Model Arguments more information about passing and using arguments.

Tunable Structure Parameters

Declare a structure parameter to be tunable using one of the following techniques.

  • Clear Model Configuration Parameters > Optimization > Signals and Parameters > Inline parameters. See Inline parameters for more information.

  • Set Inline parameters, and then specify the parameter structure as tunable in the Model Parameter Configuration Dialog Box.

  • Associate a Simulink.Parameter object with a structure parameter, and specify the object's storage class as anything other than Auto.

    myStruct = Simulink.Parameter;
    myStruct.Value = struct('number',1,'units',24);
    myStruct.CoderInfo.StorageClass = 'ExportedGlobal';

A tunable structure parameter can contain a nontunable numeric field (like a multidimensional array) without affecting the tunability of the rest of the structure. You cannot define individual substructures or fields within a structure parameter to be tunable. Only the name of the root level of the structure appears in the Model Configuration Parameter dialog box, and only the root can have a Simulink.Parameter object assigned to it.

For more information about tunability, see Inline Parameters and Tunable Parameters. For simplicity, those sections mention only separately defined base workspace variables, but all of the information applies without change to tunable structure parameters.

Parameter Structure Limitations

  • You cannot define individual substructures or fields within a structure parameter as tunable.

  • Tunable structure parameters do not support context sensitivity.

  • You cannot tune structure parameters that contain one or more fields that are arrays. For example, consider the structure parameter pstruct. This structure is tunable if its fields are defined as follows:

    pstruct.gains1.k = 3
    pstruct.gains2.k = 4

    However, this structure is not tunable if one or more of its fields are arrays.

    pstruct.gains(1).k = 3
    pstruct.gains(2).k = 4

Was this topic helpful?