Exposable Parameters

Definition

When code is generated for a Super Block, for example to create a new block or export an FMU, the OML variables used in the parameterization of the diagram inside the Super Block can be considered fixed, in which case their numerical values are used for the generation of the code, but they can also be considered exposable, in which case their values can be modified even after code generation.

The exposable parameters of the Super Block can be used as block parameters of the new block created by code generation, and the parameters of the exported FMU.

Selection

Designating a variable as an exposable parameter can be achieved in two ways: using the OML exposable function or Super Block masking.

Selection using the exposable function

Using the exposable function explicitly is one way to define a parameter as exposable. This is a simple way to define a parameter as exposable, anywhere in the Super Block. For example, in the following Super Block, the Gain parameter of the Gain block is defined as an exposable parameter named A with the default value 3.

The parameter can also be defined in the Context of the diagram, as follows:

A=exposable(‘A’,3)

and used to define the Gain parameter value of the block. In this case, when code is generated for the Super Block, the parameter A (the gain value) is exposed. The second argument of the exposable function defines the default value of the parameter.

The exposing of the parameter A and its default value is possible for example by using any of the code generators to create a CCustomBlock or generate the FMU of the Super Block:

The exposable parameters are defined primarily for code generation purposes but defining them explicitly using the exposable function affects the simulation of the model as well. Particularly, if a variable with the same name exists in the OML base environment, then the exposed parameter takes the value of this variable for Model Evaluation. So, in the above example, if a variable A is defined having a value of 4 in the OML base environment, then the simulation uses the value 4 for parameter A.

If A is not defined in the OML base, then the simulation runs normally as if A were not exposed (with value 3). The exposable function behaves like the GetFromBase function during the Model Evaluation phase.

This way of designating a parameter as exposable is useful in some cases, for example when a deep level parameter is to be made exposable without having to modify the model, but in most cases, it is not the most convenient way of defining exposable parameters. The natural way to select exposable parameters is to mask the Super Block (by auto-masking for example), specifying the variables used but not defined inside the Super Block, and then use these variables to select the exposable parameters.

Selection by masking

For an unmasked Super Block, no diagram parameter is considered exposable (other than any explicitly defined using the exposable function, as presented previously). This is the case even if a variable used inside the Super Block is defined outside the Super Block. But in this latter case, if the block is auto-masked, the variable becomes a mask parameter, and it can then be defined as an exposed parameter if desired.

Consider the following model where the variable A is defined in the Model Initialization script and is used inside the Super Block (to define the parameter value of the Gain block). If the Super Block is not masked, no parameter is exposed and the generated code for the Super Block uses the numerical value of A=1. It would be the same as if the value of the parameter of the Gain block was set to 1.

The variable A in this case is not defined as an exposable parameter even though it becomes a mask parameter if the Super Block is auto-masked (the auto-masking operation identifies the variables used inside and defined outside the Super Block, in this case A), as shown here:

Masking the Super Block is a way to define exposable parameters. In particular, when code is generated for a masked Super Block, all the variables used in the definition of the values of mask parameters are defined as exposable parameters. Note that if the masking is done using the auto-masking operation, the variables correspond exactly to the mask parameters. But the expressions defining the values of the mask parameters may contain any variables defined outside the Super Block.

Consider the model shown in the previous figure. The Super Block mask parameter is A, and so is its value. In code generation for this Super Block, A is considered exposable, and its default value is taken to be 1. Note that A is considered exposable because the value of the mask parameter is defined as A and not because of the name of the mask parameter, which also happens to be A and corresponds to a local variable of the Super Block. So, if the value of the mask parameter A is defined numerically, as shown next, prior to code generation:

then A is not exposed when the code is generated for the Super Block.

In the following example, on the other hand, where the parameter value of A is defined as a function of other variables (B and C in particular):

the exposed parameters are B and C (these variables must be defined outside the Super Block for the model to be correct). B and C become the parameters of the new block obtained by generating code for the Super Block:

Note that A is not exposable in this case; it is simply a local variable of the Super Block.

The two methods for defining exposable parameters (via Super Block mask parameters and the explicit use of the exposable function) can be used simultaneously for the same diagram. The resulting exposed parameters then include both the parameters exposed by masking and the use of the exposable function.

Classical Inverted Pendulum on a Cart

Consider the problem of the classical inverted pendulum on a cart.

The system state contains the position and speed of the cart, and the angle and angular velocity of the pendulum. State feedback control is used to stabilize the pendulum in the vertical upright position. The model contains a delay block for studying the effect of control delay in the performance of the controller:

The model of the Pendulum dynamics is placed inside a Super Block. Here various code generation methods are applied to this Super Block, illustrating how the methods work and differ.

The Super Block can now be used like a regular block, with the mask as the parameter GUI. This GUI can be customized by editing the mask as follows:

Code Generation

The application of code generation to this Super Block, as discussed earlier, exposes all the mask parameters because their values are defined as variables with the same names. The application of the code generators produces a C Custom block with opar parameters x0, J, M, g, l and m, as shown here in the case of the standard code generator:

The C Custom block is placed automatically in a masked Super Block with the same parameters.

Selection of Exposable Parameters to Expose

Parameters that you would want to expose are not necessarily exactly the parameters obtained by masking the Super Block. For example, in the cart-pendulum system, the more natural set of parameters to expose are m, M, l and the initial positions. The moment of inertia is a function of the pendulum mass and length (J=ml²/12) and g=9.81. The full initial state is also often not required; only the initial system positions (cart position and pendulum angles), z₀ = x₀(1) and θ₀ = x₀ (3), are considered. To use these as exposed parameters, the mask parameter values of the original system can be modified as follows:

Note that the initial velocities are set to zero.

After defining initial values for z₀ (z0) and θ₀(th0), for example in the Model Initialization script, the application of code generation, as expected, results in the following set of exposed parameters (the values of the exposed parameters here are manually replaced by numerical values):

Similarly, if the Super Block is used to export an FMU, the exported FMU will have the same parameters:

Limitations with Exposable Parameters

Exposable parameters of a Super Block can be used directly in expressions defining the values of the parameters of the blocks inside the diagram of the Super Block or be used in the Super Block Context to define other variables used as such. There are however limitations in the usage of exposable parameters.

Exposable parameters can be used in OML expressions involving basic operators (addition, subtraction, multiplication…), matrix extraction and concatenation, and basic math and trigonometric functions. These functions are overloaded to accept exposable parameters. Since the implementation uses operator overloading, expressions including calls to functions including basic operators and overloaded functions are also supported. However, exposable parameters cannot be used in non-overloaded built-in functions. For example, in the implementation of a Chebyshev filter block where the block parameters are computed using the OML built-in function cheby1, the parameters of the mask (filter parameters) cannot be exposed because cheby1 is not overloaded.

Even if an expression involving exposable parameters is valid, it cannot necessarily be used for the definition of all block parameter values. The reason is that not all block parameters in Twin Activate libraries accept expressions with exposable parameters. Structural block parameters are clearly excluded, and so are any parameters that affect the size or type of signals. Other block parameters, for the most part, accept expressions with exposable parameters. The list of block parameters that support the use of exposable parameters is provided below.

List of Block Parameters that You Can Expose

The following Twin Activate block parameters support expression with exposable parameters:

OML Operators and Functions that You Can Apply to Exposable Parameters

Exposable parameters can be used in the computation of the values of exposable block parameters. This computation can be limited to an OML expression or based on the execution of one or more scripts included in Super Block Contexts. Even though there is no explicit limit on the complexity of the resulting expression, the usage should be limited to “simple” expressions; complex expressions may not be efficient to evaluate and may even fail.

Exposable parameters, and other variables depending on exposable parameters, can be matrices of arbitrary sizes. Their usage is supported for the following operators and functions:

• Basic operators:

  +

  -

  *

  /

  \

  .*

  .\

  ./

  ^

  .^

  ==

  ~=

  >

  <

  >=

  <=

  &

  |

  ‘

  .’

  :

• Matrix row and column concatenations, and matrix extraction (with access via ‘:’ and ‘end’ supported)
• Primitive functions: sin, cos, tan, asin, acos, atan, sinh, cosh, tanh, asinh, acosh, atanh, exp, log, sqrt, min, max, transpose, floor, ceil, round, svd
• Primitive functions returning numeric values: size, length, isvector, isscalar, issquare. Since the sizes of exposable parameters are fixed and do not depend on their values, the output of these functions can be determined at compile time.
• Any OML function that uses only the above operators and functions within its definition, or other OML functions of the same type.

The last statement is valid because at compile time, it is known whether X is scalar or not based on its default value.