Purpose
The editor for user-defined language specifications (UDLS) can be a very powerful tool. It is used to define new specifications of how to generate code for arbitrary (existing and non-existing) programming languages. The user can do this through a graphical user interface and without modifying the MOSAICmodeling source code. The user specifies how variables are to be interpreted, what the standard mathematical operations look like in the desired programming language and from which different nested code blocks the final overall code should be composed of. Additionally, calls for external functions, code generation properties, and solver options can be defined.
In the following, all panels of the editor will be introduced. If you are interested in the workflow, please refer to the Example section of this website.
Explanation of the editor
The UDLS editor has several tabs. Above these tabs, there are four elements:
- File: filename of your UDLS once you have saved or loaded it
- Description: description of your UDLS, e.g., its purpose. A description is always necessary
- Keywords: optional keywords for your UDLS
- Usages: model elements, i.e., equations or functions, in which the UDLS is used
Global Language Settings
Creating a new language specification starts with this panel in which you mainly set the type of equation systems you want to support with your UDLS. The editor window is shown in Figure 1. All options are explained in Table 1.
| Element | Explanation |
|---|---|
| Direct Functions Supported | Direct function calls are enabled. If this option is unchecked, the code element blocks “DirectFunctionsImpl” and “DirectFunctionsCall” will be ignored. |
| Use Analytic Derivatives | Analytic derivatives are expected. This is not tested and it is not known how to actually apply analytic derivatives in the language specification |
| Case Sensitive | Case-sensitive language specification is enabled (recommended). If this option is unchecked, you should specify a “Unique Naming Index Separator” |
| Prefix | Specify a prefix for all numbers in the generated code. The number will be appended to the prefix, e.g., the number 3.5, combined with the prefix “pre”, will lead to the expression “pre3.5” |
| Suffix | Specify a suffix for all numbers in the generated code. The suffix will be appended to all numbers, e.g., the number 3.5, combined with the suffix “D”, will lead to the expression “3.5D” |
| Result | Shows the result for an example with the given prefix and suffix |
| Force Floating Point | Check this option if you want to use floating point number representation even for integer values |
| Integer Type | Specifies an additional type definition for languages, such as C++ |
| Real Type | Specifies an additional type definition for languages, such as C++ |
| Equation System Type | Choose from three options: NLE, ODE, DAE. NLE is used for algebraic equation systems. This selection enables the “NLE specific option” section of this panel containing the checkbox “’Cape Open Unit Operation’ Supported”. Select ODE for a UDLS for ordinary differential equation systems and DAE for a differential-algebraic equation systems |
| Opt or Nopt | Select whether the UDLS shall be used for simulation or optimization. If optimization is selected, you can specify this further |
| NLE specific option | At the moment, this only includes the option to support CAPE OPEN unit operations. You will have to specify special function call names and names for basic Cape Open entities, such as temperature, pressure, flow, enthalpy, and fractions |
Operations
In the Operations tab, you define how your UDLS shall generate the mathematical operations and parentheses. For each of the binary – e.g., multiplication – and unary – e.g. sine – operators, you can set prefix and suffix if necessary. Binary operators may also need an infix or have to swap the operands. All operators have to be defined (i.e., they must be non-empty) before you can use your UDLS for productive code generation. In the Specifications text field, you can see all operator definitions already set. The editor window is shown in Figure 2. All options are explained in Table 2.
| Element | Explanation | Implementation |
|---|---|---|
| Prefix | Character to be put in front of the first operand | |
| Infix | Character to be put between the first and the second operand | |
| Suffix | Character to be put behind the second operand | |
| Swap LR | Check this if you to swap the first and the second operand. This may be interesting for the radix root operator | |
| “–>” | Press this button to set the prefix, infix, suffix, and swap information of the currently active operator | |
| Result | Displays the result for the current entries | |
| Operators | This includes. “Add”, mathematical addition operation, e.g., 4+5 “Cosine”, mathematical cosine operation, e.g., cos(4) “Divide”, mathematical division operation, e.g., 4/5 “Exponential”, mathematical exponential operation, e.g., exp(4) “Multiply”, mathematical multiplication operation, e.g., 4*5 “NaturalLogarithm”, mathematical natural logarithm operation, e.g., ln(4) “Parentheses”, symbols, such as “(” and “)”, are used to group the mathematical terms and numbers to different expressions, e.g., 4+(5*6) vs. (4+5)*6 “Power”, mathematical n-th root operation, e.g., 4^5 “RadixRoot”, mathematical addition operation, e.g., sqrt(4) “Sine”, mathematical sine operation, e.g., sin(4) “Subtract”, mathematical subtract operation, e.g., 4-5 | Interpretation of code in MOSAICmodeling: LEFT+RIGHT cos(MID) LEFT/RIGHT exp(MID) LEFT*RIGHT ln(MID) () pow(LEFT,RIGHT) \sqrt[LEFT]{RIGHT} sin(MID) LEFT-RIGHT |
| Specifications | Contains your specifications for the operators from above |
Variable Namings
In the Variable Namings tab, you define how your UDLS shall interpret and display the variables of the equation system in the generated code. There are two available alternatives: an approach based on the global index of the variable and an approach using the meaning of the variable (i.e. namespace, base name, superscripts, subscript, and indexes). At least one separator has to be non-empty to be able to use the UDLS for code generation. The editor window is shown in Figure 3. All options are explained in Table 3.
| Element | Explanation |
|---|---|
| Prefix | Choose the character to be put in front of an expression. Only available for option “Use Global Index” |
| Infix | Choose the character to be put in between two expressions |
| Suffix | Choose the character to be put behind an expression. Only available for option “Use Global Index” |
| “–>” | Press this button to apply the current settings |
| Result | Shows the current specification for the variable naming |
| Strategy | Choose from “Use Global Index” and “Use Variable Naming”. The first option shall be employed if you do not want your language specification to use meaningful variable names. All variables will be identified by their global index inside the overall equation system. Prefix and Suffix should be set, e.g. prefix “X(“, and suffix “)” to get “X(23)” (variable with global index 23). The second option uses meaningful variable names. Affixes and separators for the different parts of the variable naming have to be defined |
| Separators | Specify the separators between namespace and base name, before the first superscript, before the first subscript, before the first index between index name and index value |
| Sample Variable | Contains an example for a global variable index and a namespace |
| Specifications | Contains your specifications for the naming options from above |
External Functions
In the External Functions tab, MOSAICmodeling interfaces can be added in order for the UDLS to support them. This way, code for MOSAICmodeling functions that are part of a model and that use a MOSAICmodeling interface can be generated. In this tab, the code to call the function and the code to implement the function is specified. It has to be remarked that code is actually only generated for these functions if the “Direct Functions Supported” option in the Global Language Settings tab is activated. The editor window is shown in Figure 4. All options are explained in Table 4.
Some useful code handles (placeholders) have been set up and are available for the implementation code and call code, i.e.,
- Function name: This is the full name of the function. The name is fixed by the MOSAIC function that has been included in the model the code is generated for. The handle (placeholder) is fixed to “_FUN_NAME_”
- Function name (short): This is the short name of the function. The name is fixed by the id of the MOSAICmodeling function that has been included in the model the code is generated for. The short name is particularly useful for programming languages with a limited length of function names like Scilab. The handle (placeholder) is fixed to “_FUN_NAMESHORT_”
- Function output variable: This is the actual function output variable. The output variable is different for each application (“function call”) of the function. The handle (placeholder) is fixed to “_FUN_OUT_VAR_”
- More handles are available
| Element | Explanation |
|---|---|
| Supported Function Interfaces | Name or location of a function interface that has been added as a supported function interface |
| “+ Interface” | Add a function interface to the list of supported interfaces |
| “Search” | Search the database for an interface ID |
| “Import” | Import the loaded interfaces from another UDLS |
| “Delete” | Delete the selected interface within the list of supported interfaces |
| Interface Fields | Lists all fields that have been specified in the respective MOSAICmodeling interface. The handle is not specified by the interface and has to be set by the creator of the UDLS. The following fields are available: Direction: This is the direction of the field. For function interfaces, the possible values are “In” and “Out”, with exactly one field of direction “Out” and an arbitrary number of fields with direction “In”. The direction cannot be changed here Dim: This is the dimension of the field. Possible values are “Scalar” and “Vector”. The dimension cannot be changed here Variable: This is the name of the field variable as it will be used in generated code. The variable name cannot be changed here Name: This is the meaning of the field as it has been stored in the MOSAICmodeling interface. For CAPE OPEN function interfaces, the names are predefined starting with “CO”. The field name cannot be changed here Handle: This is the name of the placeholder as it has to be used in the implementation code and in the call code definition. The handle is not a property of a MOSAICmodeling interface and therefore has to be set here |
| VectorSepSymbol | Symbol that is used to separate the different elements of a vector in the generated code. The handle (placeholder) for the separation symbol is fixed to “SEP_SYMBOL” |
| Calculation expression | Expression that actually calculates the return value of the function. The handle (placeholder) for this expression is fixed to “VALUE” |
| Implementation code | This is the full code that is used to define and implement the function in the generated code. It is recommended to use the above “calculation expression” here, but it is not necessary |
| Vector index counter start | Specifies the index at which the counter starts |
| Vector input creation code | Specifies the code to create a vector for external functions |
| Call code | Full code that is used to call the function in the generated code. The function call is used to calculate the value of a variable by calling the function with specific input values. It is usually necessary to use the handle for the function output variable (“FUN_OUT_VAR”) here to correctly assign the calculation/ function call to the variable to be calculated |
| Vector output assignment code | Specifies how the returned vector is translated into the original non-vector variables |
Code Generation Properties
In the Code Generation Properties tab, options for code generation can be specified. The options entered here will be visible to users when the UDLS is loaded in the “Simulation” or “Optimization” section where you specify the language specification for code generation. Typical properties are number of iterations, tolerances, etc. Properties, on the other hand, are used if the creator of the UDLS wishes the user to only be able to select the preferred options from a list. The editor window is shown in Figure 5. All options are explained in Table 5.
| Element | Explanation |
|---|---|
| Available Properties | Name of the property as it will later be displayed to users selecting this UDLS for code generation |
| “+ Property” | Lets you add a property. You can then specify the following parameters. Handle: Identifier of this property as it can be used in the code elements tab. It is the placeholder for the value of the property to be inserted Type: Data type of the property. Possible options are Integer, Float (Floating point number), String, and Boolean (Two-Option-String) Default: Default value of the property that will be inserted in the generated code if the user does not specify another value |
| “Edit Property” | Lets you edit a property |
| “Delete Property” | Lets you delete a property |
| Predefined Options | Each entry in this table will be one entry in the combobox in the code generation section in which the code generator and solver properties are set |
| “+ Option” | Lets you add an option |
| “Delete Option” | Lets you delete an option |
| Code Export File | Users can export the generated code of a simulation to hard disk. Here, it can be specified which filename and which extension will be used when this UDLS selected for code generation |
Code Elements
The Code Elements tab is the central part of the UDLS editor. In this tab, the elements of the structure of the code to be generated are defined. The code has by definition a tree structure with a node called “FullCode” as the root node. Each node is a code block. Code blocks are of different types and can have sub blocks. Blocks without sub blocks are leaves of the tree structure. Global and local code properties exist and can be accessed in the code blocks. An example for a global code property is the number of equations in an algebraic equation system (“_DIM_EQUAS_”). The separator symbol (“_SEP_SYMBOL_”) is an example for a local code property.
The user specifies each code block separately by plain text, thereby using the unique names (“Handles”) of the properties and of the sub blocks. When the language specification is applied to a simulation or optimization, all handles will be recursively replaced by the respective property value or code block specification. The editor window is shown in Figure 6. All options are explained in Table 6.
| Element | Explanation |
|---|---|
| Elements Tree | Visualization of the code structure. Code blocks and properties can be selected. Information on the selected elements will be displayed in the other parts of this tab |
| “+ Node” | Create a new sub block as a child of the currently selected code block. Some predefined code blocks cannot have children (e.g., “DirectFunctionsCall”) |
| “Delete Node” | Lets you delete a node. All sub-blocks will be removed, too! |
| “Up” | Move the selected node up in the tree structure. The node’s level in the tree is not changed. The node changes the position with its preceding sibling |
| “Down” | Move the selected node down in the tree structure. The node’s level in the tree is not changed. The node changes the position with its subsequent sibling |
| Input Specification | Lets you specify the content of the selected block. You can also see a description of the meaning of the selected system/code property (e.g. “VarsDimension”) |
| Show Invisible Characters | Check this option to display the invisible characters (whitespaces, tabs, and newlines) |
| CtrStart | Lets you enter the start value of the counter in loop blocks |
| Handle | Unique name of the selected code block. It can be changed and usually starts and ends with an underscore (“_”) |
| Available Subhandles | List showing all subhandles available for the selected code block. The list contains global handles, such as “DIM_VARS”, specific local handles, such as “SEP_SYMBOL”, and the handles of existing (maybe user-defined) subblocks), e.g., “MySubBlock”. |
| Code Generation Preview | This text field displays the generated code for a selected code block if code has been generated. Press the “Show Code” button to generate code according to the selected code block, based on the simulation that is loaded in the “Overall Results” tab |
Overall Results
In the “Overall Results” tab, you load a simulation to test the code generation of your language specification. You need to load a simulation in this panel to activate the “Generate Full Code” button and to be able to generate code for the different code blocks in the “Code Elements” tab.
| Element | Explanation |
|---|---|
| Evaluation | Load the simulation you want to test your UDLS with. As in any other MOSAICmodeling editor, you can use Unload, Reload, Search and Select to set (or unset) a model element. |
| Status Information | Displays status information about the simulation. It is the same as in the “Evaluate” tab within the “Simulation” section of MOSAICmodeling |
| Code | Displays the generated code if code has been generated |
| Generate Full Code | Press this button to generate code according to your UDLS and based on the loaded simulation |