Main Content

Limitations for Block Parameter Tunability in Generated Code

A block parameter, MATLAB® variable, or Simulink.Parameter object is tunable if it appears in the generated code as data stored in memory, such as a global variable. For example, when you apply the storage class ExportedGlobal to a parameter object, the parameter object appears tunable in the generated code. When you set Default parameter behavior to Tunable, MATLAB variables and parameter objects appear tunable in the generated code. By definition, model arguments also appear tunable.

Under certain conditions, the code generator cannot maintain tunability of a parameter, variable, object, or expression. In this case, the code generator inlines the numeric value, preventing you from changing the value during code execution.

To detect these conditions in your model, set the model configuration parameter Detect loss of tunability (see Detect loss of tunability) to warning or error.

Tunable Expression Limitations

You can specify block parameter values as expressions that use Simulink.Parameter objects or workspace variables. For example, you can use the expression 5 * gainParam. For general information about using expressions to set block parameter values, see Use Mathematical Expressions, MATLAB Functions, and Custom Functions. For limitations with respect to expressions that you use to set the values of Simulink.Parameter objects, see Code Generation of Parameter Objects With Expression Values.

A tunable workspace variable is a Simulink.Parameter object or workspace variable that appears tunable in the generated code. For example, an object or variable is tunable if you apply a storage class other than Auto or if you set Default parameter behavior to Tunable.

An expression that contains one or more tunable workspace variables, model arguments, or tunable mask parameters is called a tunable expression. The expression is tunable because the code generator attempts to preserve the expression in the code. Because the code generator preserves the expression, you can change the values of the parameter data during code execution.

The code generator reduces certain expressions to an inlined numeric value in the generated code. The inlining renders workspace variables in the expression nontunable. To avoid loss of tunability due to unsupported expressions, observe these guidelines:

  • Expressions involving complex (i) workspace variables or parameter objects are not supported.

  • Certain operators and functions cause the code generator to reduce expressions and remove tunability. To determine whether an operator or function causes loss of tunability, use the information in this table.

    CategoryOperators or Functions

    1

    + - .* ./ < > <= >= == ~= & |

    2

    * /

    3

    abs, acos, asin, atan, atan2, boolean, ceil, cos, cosh, exp, floor, log, log10, sign, sin, sinh, sqrt, tan, tanh, single, int8, int16, int32, uint8, uint16, uint32

    4

    : .^ ^ [] {} \ .\ ' .' , ;

    • Use operators from category 1 without loss of tunability.

    • Use operators from category 2 in expressions as long as at least one operand is a scalar. For example, scalar/scalar and scalar/matrix operand combinations are supported, but matrix/matrix combinations are not supported.

    • You can use tunable workspace variables as arguments for the functions in category 3. If you use other functions, the code generator removes the tunability of the arguments.

    • The operators in category 4 are not supported.

  • The Fcn and If blocks do not support tunable expressions for code generation or in referenced models.

  • You can write mask initialization code that creates and modifies variables. If you use those variables in an expression, the expression is not tunable in the generated code. This limitation also applies to Simulink® library blocks with mask initialization code. For example, block parameters that specify bit operations for the Bitwise, Bit Set, and Bit Clear blocks are not tunable because the parameter is used in the mask initialization code for the block.

  • You can specify a data type for the Simulink.Parameter objects or workspace variables that make up expressions. As long as the data type of these variables and objects and the data type of the corresponding block parameters are the same or double, the code generator can preserve tunability.

  • Bus and structure types that have empty elements do not support tunable expressions in generated code. As a workaround, you can use an alternative convention such as using -1 to represent empty element values.

If the code generator preserves tunability of a parameter expression that includes at least one element of an integer type, simulation and execution of generated code can produce results that are numerically inconsistent. Evaluation of the expression in the generated code results in an overflow while the expression saturates during simulation. For more information, see Numerical Consistency of Model and Generated Code Simulation Results.

Linear Block Parameter Tunability

These blocks have a Realization parameter that affects the tunability of their numeric parameters:

  • Transfer Fcn

  • State-Space

  • Discrete State-Space

To set the Realization parameter, you must use the command prompt:

set_param(gcb,'Realization','auto')

For the Realization parameter, you can choose these options:

  • general: The block's numeric parameters appear tunable in the generated code.

  • sparse: The generated code represents the block’s parameters as transformed values that increase efficiency. The parameters are not tunable.

  • auto: The default. If one or more of the block’s parameters are tunable (for example, because you use a tunable parameter object to set a parameter value), then the block uses the general realization. Otherwise, the block uses the sparse realization.

    To tune the parameter values of one of these blocks during an external mode simulation, the block must use the general realization.

Parameter Structures

As described in Organize Data into Structures in Generated Code, you can create structures of parameter data in the generated code.

  • If a parameter structure is tunable, the numeric fields of the structure are tunable in the generated code. However, if a field contains a nontunable entity, such as a multidimensional array, the structure fields are not tunable.

  • You cannot declare individual substructures or fields within a parameter structure as tunable. You cannot use a Simulink.Parameter object as the value of a structure field. Instead, you must store the entire structure in the parameter object.

Related Topics