Chapter 12 Functions

The relative ordering between input formal parameter declarations is significant since that determines the matching between actual arguments and formal parameters at function calls with positional parameter passing. Likewise, the relative ordering between the declarations of the outputs is significant since that determines the matching with receiving variables at function calls of functions with multiple results. However, the declarations of the inputs and outputs can be intermixed as long as these internal orderings are preserved.

[Mixing declarations in this way is not recommended, however, since it makes the code hard to read.]

[Example:

]

The return-statement terminates the current function call, see section 12.4. It can only be used in an algorithm section of a function. It has the following form:

[Example: (Note that this could alternatively use break:)

]

It is allowed for a function to inherit and/or modify another function following the usual rules for inheritance of classes (chapter 7).

[For example, it is possible to modify and extend a function class to add default values for input variables.]

A special case is defining a function as a short-class definition with modifiers for inputs inside a model. These default values, unless overridden in the function call, will then be considered for variability similarly as if they were given in the function call, see section 3.8.1.

[Example: Demonstrating the variability implications. Note that functions cannot directly use non-constants in enclosing scopes, so we cannot write input Real x1 = x; directly in foo.

]

A function call has optional positional arguments followed by zero, one or more named arguments, such as

The formal syntax of a function call (simplified by removing reduction expression, section 10.3.4.1):

The interpretation of a function call is as follows: First, a list of unfilled slots is created for all formal input parameters. If there are $N$ positional arguments, they are placed in the first $N$ slots, where the order of the parameters is given by the order of the component declarations in the function definition. Next, for each named argument identifier = expression, the identifier is used to determine the corresponding slot. The value of the argument is placed in the slot, filling it (it is an error if this slot is already filled). When all arguments have been processed, the slots that are still unfilled are filled with the corresponding default value of the function definition. The default values may depend on other inputs (these dependencies must be acyclical in the function) – the values for those other inputs will then be substituted into the default values (this process may be repeated if the default value for that input depend on another input). The default values for inputs shall not depend on non-input variables in the function. The list of filled slots is used as the argument list for the call (it is an error if any unfilled slots still remain).

Special purpose operators with function syntax defined in the specification shall not be called with named arguments, unless otherwise noted.

The type of each argument must agree with the type of the corresponding parameter, except where the standard type coercion, section 10.6.13, can be used to make the types agree. (See also section 12.4.6 on applying scalar functions to arrays.)

[Example: Assume a function RealToString is defined as follows to convert a Real number to a String:

Then the following applications are equivalent:

]

A functional input argument to a function is an argument of function type. The declared type of such an input formal parameter in a function can be the type-specifier of a partial function that has no replaceable elements. It cannot be the type-specifier of a record or enumeration (i.e., record constructor functions and enumeration type conversions are not allowed in this context). Such an input formal parameter of function type can also have an optional functional default value.

[Example:

]

A functional argument can be provided in one of the following forms to be passed to a scalar formal parameter of function type in a function call:

1. 1.

   as a function type-specifier (Parabola example below),

2. 2.

   as a function partial application (section 12.4.2.1 below),

3. 3.

   as a function that is a component (i.e., a formal parameter of function type of the enclosing function),

4. 4.

   as a function partial application of a function that is a component (example in section 12.4.2.1 below).

In all cases the provided function must be function-compatible (definition 6.8) with the corresponding formal parameter of function type.

[Example: A function as a positional input argument according to case 1:

The quadrature2 example below uses a function integrand that is a component as input argument according to case 3:

]

A function may have more than one output component, corresponding to multiple return values. The only way to use more than the first return value of such a function is to make the function call the right hand side of an equation or assignment. In this case, the left hand side of the equation or assignment shall contain a list of component references within parentheses:

(out1, out2, out3) = f($\mathrm{\dots }$);

The component references are associated with the output components according to their position in the list. Thus output component $i$ is set equal to, or assigned to, component reference $i$ in the list, where the order of the output components is given by the order of the component declarations in the function definition. The type of each component reference in the list must agree with the type of the corresponding output component.

A function application may be used as expression whose value and type is given by the value and type of the first output component, if at least one return result is provided.

It is possible to omit left hand side component references and/or truncate the left hand side list in order to discard outputs from a function call.

[Optimizations to avoid computation of unused output results can be automatically deduced by an optimizing compiler.]

[Example: Function eigen to compute eigenvalues and optionally eigenvectors may be called in the following ways:

The function may be defined as:

]

The only permissible use of an expression in the form of a list of expressions in parentheses, is when it is used as the left hand side of an equation or assignment where the right hand side is an application of a function.

[Example: The following are illegal:

]

Components in a function can be divided into three groups:

• •

  Public components which are input formal parameters.

• •

  Public components which are output formal parameters.

• •

  Protected components which are local variables, parameters, or constants.

When a function is called, components of the function do not have start-attributes. However, a binding equation (= expression) with an expression may be present for a component.

A binding equation for a non-input component initializes the component to this expression at the start of every function invocation (before executing the algorithm section or calling the external function). These bindings must be executed in an order where a variable is not used before its binding equations has been executed; it is an error if no such order exists (i.e., the binding must be acyclic).

Binding equations can only be used for components of a function. If no binding equation is given for a non-input component the variable is uninitialized (except for record components where modifiers may also initialize that component). It is an error to use (or return) an uninitialized variable in a function. Binding equations for input formal parameters are interpreted as default arguments, as described in section 12.4.1.

[It is recommended to check for use of uninitialized variables statically – if this is not possible a warning is recommended combined with a run-time check.]

[The properties of components in functions described in this section are also briefly described in section 12.2.]

[Flexible setting of array dimension sizes of arrays in functions is also briefly described in section 12.2.]

A dimension size not specified with colon (:) for a non-input array component of a function must be given by the inputs or be constant.

[Example:

]

A non-input array component declared in a function with a dimension size specified by colon (:) and no binding equation, can change size according to these special rules:

• •

  Prior to execution of the function algorithm the dimension size is zero.

• •

  The entire array (without any subscripts) may be assigned with a corresponding array with arbitrary dimension size (the array variable is re-sized).

These rules also apply if the array component is an element of a record component in a function.

[Example: A function to collect the positive elements in a vector:

]

Functions with one scalar return value can be applied to arrays element-wise, e.g., if A is a vector of reals, then sin(A) is a vector where each element is the result of applying the function sin to the corresponding element in A. Only function classes that are transitively non-replaceable (section 6.3.1 and section 7.1.4) may be called vectorized.

Consider the expression f(arg1, $\mathrm{\dots }$, argn), an application of the function f to the arguments arg1, …, argn. Potential vectorization of this call is defined as follows. For each passed argument, the type of the argument is checked against the type of the corresponding formal parameter of the function:

1. 1.

   If the types match, nothing is done.

2. 2.

   If the types do not match, and a type conversion can be applied, it is applied. Continue with step 1.

3. 3.

   If the types do not match, and no type conversion is applicable, the passed argument type is checked to see if it is an $n$-dimensional array of the formal parameter type. If it is not, the function call is invalid. If it is, we call this a foreach argument.

4. 4.

   For all foreach arguments, the number and sizes of dimensions must match. If they do not match, the function call is invalid.

5. 5.

   If no foreach argument exists, the function is applied in the normal fashion, and the result has the type specified by the function definition.

6. 6.

   The result of the function call expression is an $n$-dimensional array e with the same dimension sizes as the foreach arguments. Each element e[$i$, $\mathrm{\dots }$, $j$] is the result of applying f to arguments constructed from the original arguments in the following way:

   • •

     If the argument is not a foreach argument, it is used as-is.

   • •

     If the argument is a foreach argument, the element at index [$i$, $\mathrm{\dots }$, $j$] is used.

If more than one argument is an array, all of them have to be the same size, and they are traversed in parallel.

[Example:

This works even if the function is declared to take an array as one of its arguments. If pval is defined as a function that takes one argument that is a Real vector and returns a Real, then it can be used with an actual argument which is a two-dimensional array (a vector of vectors). The result type in this case will be a vector of Real.

add(1, [1,2,3]) adds one to each of the elements of the second argument giving the result [2,3,4]. For built-in operators one can do this with 1 .+ [1,2,3] but not with 1 + [1,2,3], because the rules for the built-in operators are more restrictive.]

An empty function call is a call that does not return any results.

[An empty call is of limited use in Modelica since a function call without results does not contribute to the simulation, but it is useful to check assertions and in certain cases for desired side-effects, see section 12.3.]

An empty call can occur either as a kind of “null equation” or “null statement”.

[Example: The empty calls to eigen() are examples of a “null equation” and a “null statement”:

]

A constructor of a record R can be used to cast an instance m of a model, block, connector class M to a value of type R, provided that for each component defined in R (that do not have a default value) there is also a public component defined in M with identical name and type. A nested record component of R is handled as follows, if the corresponding component of M is a model/block/connector a nested record constructor is called – otherwise the component is used directly; and the resulting call/component is used as argument to the record constructor R. If the corresponding component of R in M is a conditional component, it is an error. The instance m is given as single (un-named) argument to the record constructor of R. The interpretation is that R(m) is replaced by a record constructor of type R where all public components of M that are present in R are assigned to the corresponding components of R. The record cast can be used in vectorized form according to section 12.4.6.

[The problem if R would be a conditional component is that the corresponding binding would be illegal since it is not a connect-equation.]

[The record cast operation is uniquely distinguished from a record constructor call, because an argument of the record constructor cannot be a model, block or connector instance.]

[Example:

]

The given derivative-function must be a valid derivative if the derivative annotation restrictions are satisfied, and can thus be used to compute the derivative in those cases. There may be multiple restrictions on the derivative, in which case they must all be satisfied. The restrictions also imply that some derivatives of some inputs are excluded from the call of the derivative (since they are not necessary). When a function supplies multiple derivative-functions subject to different restrictions, the first one that can be used (i.e., satisfying the restrictions) will be used for each call.

[This means that the most restrictive derivatives should be written first.]

[Example: The following model illustrates the requirement that a provided derivative must be valid. That fder is a valid derivative of f means that it can be used safely to compute x2 by numeric integration: the function value, x1, will up to numerical precision be matched by the integral of the derivative, x2.

Note that tools are not required to use the provided derivative, and might solve the equations completely without numeric integration.]

[Example: Use of order to specify a second order derivative:

]

The inputs and outputs of the derivative function of order 1 are constructed as follows:

• •

  First are all inputs to the original function, and after all them we will in order append one derivative for each input containing reals. These common inputs must have the same name, type, and declaration order for the function and its derivative.

• •

  The outputs are constructed by starting with an empty list and then in order appending one derivative for each output containing reals. The outputs must have the same type and declaration order for the function and its derivative.

If the Modelica function call is a $n$th derivative ($n\ge 1$), i.e., this function call has been derived from an $(n-1)$th derivative by differentiation inside the tool, an annotation(derivative(order=$n\mathrm{+}\mathrm{1}$) = $\mathrm{\dots }$), specifies the $(n+1)$th derivative, and the $(n+1)$th derivative call is constructed as follows:

• •

  The input arguments are appended with the $(n+1)$th derivative, which are constructed in order from the $n$th order derivatives.

• •

  The output arguments are similar to the output argument for the $n$th derivative, but each output is one higher in derivative order. The outputs must have the same type and declaration order for the function and its derivative.

[The restriction that only the result of differentiation can use higher-order derivatives ensures that the derivatives x, der_x, … are in fact derivatives of each other. Without that restriction we would have both der(x) and x_der as inputs (or perform advanced tests to verify that they are the same).]

[Example: Given the declarations

the equation

]

An input or output to the function may be any simple type (Real, Boolean, Integer, String and enumeration types) or a record. For a record containing Real values, the corresponding derivative uses a derivative record that only contains the real-predefined types and sub-records containing reals (handled recursively) from the original record. When using smoothOrder, then the derivative record is automatically constructed. The function must have at least one input containing reals. The output list of the derivative function shall not be empty.

[Example: Here is one example use case with records mixing Real and non-Real as inputs and outputs:

]

• •

  "zeroDerivative" "=" ${\mathrm{𝑖𝑛𝑝𝑢𝑡𝑉𝑎𝑟}}_{\mathrm{1}}$ { "," "zeroDerivative" "=" ${\mathrm{𝑖𝑛𝑝𝑢𝑡𝑉𝑎𝑟}}_{\mathrm{2}}$ }

The derivative function is only valid if ${\mathrm{𝑖𝑛𝑝𝑢𝑡𝑉𝑎𝑟}}_1$ (and ${\mathrm{𝑖𝑛𝑝𝑢𝑡𝑉𝑎𝑟}}_2$ etc.) are independent of the variables the function call is differentiated with respect to (i.e., that the derivative of ${\mathrm{𝑖𝑛𝑝𝑢𝑡𝑉𝑎𝑟}}_1$ is zero). The derivative of ${\mathrm{𝑖𝑛𝑝𝑢𝑡𝑉𝑎𝑟}}_1$ (and ${\mathrm{𝑖𝑛𝑝𝑢𝑡𝑉𝑎𝑟}}_2$ etc.) are excluded from the argument list of the derivative-function. If the derivative-function also specifies a derivative the common variables should have consistent zeroDerivative.

[Assume that function f takes a matrix and a scalar. Since the matrix argument is usually a parameter expression it is then useful to define the function as follows (the additional derivative = fGeneralDer is optional and can be used when the derivative of the matrix or offset is non-zero). Note that the derivative annotation of fDer must specify zeroDerivative for both y and offset as below, but the derivative annotation of fGeneralDer shall not have zeroDerivative for either of them (it may specify zeroDerivative for x_der, y_der, or offset_der).

In the example above zeroDerivative=y and zeroDerivative=offset imply that

]

• •

  "noDerivative" "=" ${\mathrm{𝑖𝑛𝑝𝑢𝑡𝑉𝑎𝑟}}_{\mathrm{1}}$

The derivative of ${\mathrm{𝑖𝑛𝑝𝑢𝑡𝑉𝑎𝑟}}_1$ is excluded from the argument list of the derivative-function. This relies on assumptions on the arguments to the function; and the function should document these assumptions (it is not always straightforward to verify them). In many cases even the undifferentiated function will only behave correctly under these assumptions.

The inputs excluded using zeroDerivative or noDerivative may be of any type (including types not containing reals).

[Assume that function fg is defined as a composition f(x, g(x)). When differentiating f it is useful to give the derivative under the assumption that the second argument is defined in this way:

This is useful if g represents the major computational effort of fg.

Therefore h indirectly includes the derivative with respect to y as follows:

]

A class defined as:

is the partial derivative of a function, and may only be used as declarations of functions.

The semantics is that a function (and only a function) can be specified in this form, defining that it is the partial derivative of the function to the right of the equal sign (looked up in the same way as a short class definition, and the looked up name must be a function), and partially differentiated with respect to each IDENT in order (starting from the first one). Each IDENT must be a scalar Real input to the function.

The comment allows a user to comment the function (in the info-layer and as one-line description, and as icon).

[Example: The specific enthalpy can be computed from a Gibbs-function as follows:

]

If a function $f_1$ with one output formal parameter $y$ can be restricted to an informally defined domain and codomain, such that the mapping of the input formal parameter $u_k$ to $y$ is bijective for any fixed assignment to the other input formal parameters in the domain (see examples below), then it can be given an inverse annotation to provide an explicit inverse $f_2$ to this mapping, provided that the function is only applied on this domain:

The inverse annotation takes the following form in a function declaration: