This post has a closer look at the different inlining options: Inline, LateInline and InlineAfterIndexReduction as described in the Modelica Specifications in Section 8.3. The post describes how these inlining options differ and gives some extra details about how this inlining has been implemented in Dymola.
What is inlining?
“Inlining a function” is the ability for a function call in a model to be replaced by the function’s algorithm. As in Figure 1.
Why inline?
Inlining can increase performance by removing the overhead needed to call a function (for more detail please refer to ‘Inline Functions in C++‘).
An additional advantage is that during model translation, symbolic manipulation may be performed on the algorithm; if it is inlined this can further improve simulation performance.
How is inlining requested in Dymola?
Using an inlining annotation requests inlining of a function. The following inlining annotations are supported:
- Inline=true inlines the function before the code is flattened
- InlineAfterIndexReduction=true inlines the function after index reduction
- LateInline=true inlines the function after all symbolic transformations have been performed
Dymola inlines simple functions without the Inline annotation being present, to avoid this set Inline=false.
Figure 2 gives the location where these different inlining options implement inlining in the translation process:
For further information about the translation process refer to our blog post on ‘Introduction to the model translation and symbolic processing‘, and Section 8.8 of the Dymola User Manual Volume 2.
Examples
This section goes through inlining examples and gives further information about each method.
An Inline example
In Figure 3 the equalFn function is replaced with the algorithm b=a when the code is flattened. So c=equalFn(time) is replaced with c=time. When the function’s algorithm replaces the function call, this algorithm is treated as an equation. This allows Dymola to perform symbolic manipulation with this equation. The flat Modelica code is generated by selecting Generate listing of translated Modelica code in dsmodel.mof as in Section 2.3.2 of the Dymola User Manual Volume 1B.
An InlineAfterIndexReduction example
When InlineAfterIndexReduction=true then inlining occurs after index reduction and fairly early in the symbolic manipulation. This allows some symbolic manipulation to be used with this function which can improve the efficiency of the simulation. The InlineAfterIndexReduction annotation rather than Inline=true is used because when Inline=true is used the derivative defined by the function being inlined is not used and the derivative is calculated symbolically from the algorithm in the inlined function.
The example in Figure 4 shows how a derivative can be supplied to a signal and this is efficiently inlined using IndexAfterIndexReduction.
In the example above the derivative of y is set to zero by making use of the zeroDerivativePassThrough function which has a derivative function which sets the derivative to zero. This type of functionality can be useful when a model with inputs is exported as an FMI and the derivatives for these inputs are required and are zero. This is a simple example intended to show how InlineAfterIndexReduction can be used.
Care is required when using InlineAfterIndexReduction=true as this can cause the translation to fail. If it does, use LateInline=true. See the Modelica trac issues:
Use InlineAfterIndexReduction consistently in Move and Move block + MultiBody model can give issues with index reduction
A LateInline example
LateInline=true results in the function being inlined in dsmodel.c. This reduces the overhead associated with function calls.
Also, when a function that has an inverse function defined is inlined using the Inline=true or the InlineAfterIndexReduction=true annotation then this inverse function is not used and the inverse function is calculated either by symbolic manipulation or by a non-linear equation. So using LateInline=true or Inline=false will ensure that the defined inverse function is not lost. Note that if no inlining annotation is provided, Dymola may inline a function as if Inline=true was set, resulting in a defined inverse function not being used.
Figure 5. is an example of a function that has an inverse function defined.
In dsmodel.c the erfFn call has been replaced with the algorithm of this function which is Modelica.Math.Special.erf; also note that the the inverse function Modelica.Math.Special.erfInv is used in dsmodel.c. See ‘The Dymola Compilation Process in Action‘ for more information about how dsmodel.c is generated.
Why is my function not being inlined?
The inlining annotations only request that a given function is inlined, however the Dymola translation process will decide if this function can be inlined or not.
There are a number of reasons why a function is not inlined in Dymola. Basically only simple models are inlined. So functions with the following contents are not likely to be inlined:
- protected variables
- assert statements that are present in the algorithm section
- outputs that are vectors
- make use code that can only be expressed as an algorithm
- multiple outputs
Also if the calling function is in an algorithm section, the function will not be inlined.
Setting the following flag in the Dymola command line will cause Dymola to print all the functions that failed to inline to the translation log:
Advanced.Translation.Log.FailureToInline=true
When should inlining not be used?
When inlining, functions can specify a derivative, as described in ‘Applying Derivatives to Functions in Dymola‘, or inverse functions care is required. Using Inline=true will result in both these derivatives and the inverse functions not to be used. Using InlineAfterIndexReduction will cause the inverse function not to be used.
If a function is used in multiple places in a model with the same inputs, Dymola can detect this and can call the function once and replace the other function calls with the answer. This could result in a model that does not make use of inlining being more efficient.
In some cases, functions are used as a way to hide events (hiding events like this will have impact on the simulation accuracy and robustness).
Inlining can increase code size which is also a problem experienced by procedural/programming languages (Modelica is a Modelling language due to it’s acausal nature). Other disadvantages of inlining that procedural languages also have can be found in Inline Functions in C++.
The future of Inlining
The developers are continually enhancing Dymola’s capability to inline more functions.
Written by: Garron Fish – Chief Engineer
Please get in touch if you have any questions or have got a topic in mind that you would like us to write about. You can submit your questions / topics via: Tech Blog Questions / Topic Suggestion