Wiki
Simflowny / UserGuide_TransformationRules
Creating new transformation rules
Transformation rules are reusable functions that can be imported and used in different discretization schemas. They are equivalent to functions in a programming language, but in Simflowny they are defined in an abstract and parametrizable way.
To create a new transformation rule, select "Transformation Rule" from the Add button menu in the document manager.
Head
Head information is commonly used in several documents in Simflowny. See more detail in Head.
Function Parameters (optional)
The first mandatory element is the function parameters. They are the parameters that the schema must fill to call this transformation rule. There are six type of parameters:
- Field. References to a field variable, and also auxiliary fields and variables. When passing a field parameter, the whole field is provided to the function, and can be indexed in order to obtain the value at a specific index.
- Real. The parameter is a real value.
- Int. The parameter is a integer value.
- Boolean. The parameter is a boolean value.
- Function. The parameter is another Simflowny function. This type requires additional parameters functionParameters with a list of parameters for the given function.
- Coordinates. This is an special parameter. When using a Coordinates type, a name for the parameter must not be set. The reason is that this parameter generates as many parameters as spatial coordinates has the problem being discretized. This parameter must be used always when the transformation rule uses indexing for fields (when using Current Cell Simml instructions or similar).
For every parameter, except Coordinates, a Name must be added to identify the parameter in the transformation rule algorithm.
The following picture shows an example of function parameter usage taken from a RK3 substep:
In the picture above there is a real variable, sources . There are also two field parameters, Q1 and Q2, which are accessed in the algorithm using the Current Cell Simml infix ($cc). To allow this field access, there is a Coordinate type, with no name associated. It can be stated that when using a field parameter, there always have to be a coordinates parameter.
External Variables (only for presteps)
Presteps are special transformation rules that need this tag. In External Variables a series of input and output variables must be defined. Those variables are mapped from the discretization schema prestep configuration to be replaced directly in the final code.
In the image above there can be seen the output variables Fluxp$i$f and Fluxn$i$f correspondinf to the two last instructions in the algorithm.
Rule
The second mandatory element is the Rule, which is no more than the algorithm to execute. Notice the Simml elements inside it, which means that the Simml language is used to define the algorithm. The document SimML: language reference details the use of the Simml tags.
Performance tip
When possible, the user must set one-line algorithms. When Simflowny detects one-line algorithms it creates a macro function [1], which usually performs much better than a regular function call.
The rest of functions are generated as inlined functions, which supposedly should be treated similarly to macro functions in terms of speed. However, the inlining strongly depends on the compiler, so there is no guarantee that all the transformation rules are inlined.
| [1] | Macros are managed by the preprocessor at compilation time, further information at https://en.wikipedia.org/wiki/Macro_(computer_science). |
Updated