Organize Related Parameters in Structures and Arrays of Structures

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

To organize parameter structures that have similar characteristics, you can create a single parameter whose value is an array of structures. To use the parameter in a block dialog box, you specify an expression that references a field of one of the structures in the array.

You can also partition the parameter in a For Each subsystem. This technique helps you to organize workspace variables when a model executes an algorithm repeatedly, for example, by using identical subsystems. For an example, see Repeat an Algorithm Using a For Each Subsystem.

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

To create an array of structures, you can use the same syntax that you use to create arrays of numeric values. For example, you can define an array of structures arrayStruct by concatenating two similar structures.

arrayStruct = [struct('gain',1.5,'offset',30),...

You can also create arrayStruct by assigning values to the structure fields in the array.

arrayStruct(1).gain = 1.5;
arrayStruct(1).offset = 30;

arrayStruct(2).gain = 2.1;
arrayStruct(2).offset = 40;

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.

To specify a block parameter by using a field of an array of structures, use a single expression that selects a structure in the array and references a field of that structure. For example, suppose that you define an array of structures arrayStruct:

arrayStruct = [struct('gain',1.5,'offset',30),...

To reference the field offset of the second structure in the array, use the expression arrayStruct(2).offset. The expression returns the value of the field, 40.

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, Block Masks, and Model Arguments more information about passing and using arguments.

Parameter Structure Limitations

All of the structures in an array of structures must have the same hierarchy of fields. Each field in the hierarchy must have the same characteristics throughout the array:

  • Field name

  • Numeric data type, such as single or int32

  • Complexity

  • Dimensions

For example, suppose that you define an array of two structures.

paramStructArray = ...
[struct('sensor1',int16(7),'sensor2',single(9.23)) ...

You cannot use any of the fields of paramStructArray in a block parameter because the field sensor1 uses a different data type in each structure.

Generate Code with Structure Parameters

For information about generating code with structure parameters, see Structure Parameters and Generated Code.

Related Examples

Was this topic helpful?