Once you’ve got comfortable with creating models using components in the Diagram layer you will probably need to create your own models. This requires understanding and implementation of the Modelica language. This, like any other coding language, must be written in the correct order, with the correct punctuation. This is called the syntax which and, once understood, is quite easy to follow.
This blog post will be outlining the structure and syntax of a class created within Dymola; the differences between the classes and what must be included for the structure to be correct. A future post will go into more detail about the different elements within a class and the implementation of calculations.
The text layer is where most of the Modelica coding takes place; but this can also be relevant when modifying components in the diagram layer. Descriptions and differences between the layers are described in Dymola Basics 2: Layers of a Model within Dymola. To leave the text layer of a model the syntax must be correct; classes don’t need to check without errors, but the use of the language must.
The first thing to note is that there can be lots of different types of elements in a class, and each needs to be treated slightly differently. On the right is a simple example, Modelica.Blocks.Math.Add3 (slightly modified for demonstration purposes). While the order shown here is typical, some of it can be different; but when making your own classes this order does follow the logical route when creating a class is recommended.
The first thing in any class must be the Class Restriction, which defines what and how class will be used. This restriction is important as each class can have different restrictions and uses. The next section briefly describes the different classes.
Next is the Name of the class. This can only contain letters, numbers and the underscore symbol and the first character cannot be a number. Finally the class should, but is not required to, have a Description which is contained in double quotation marks which can contain all other characters.
classRestriction NameOfClass "Description of class"
An example of the first line is:
model Universal "Universal joint (2 degrees-of-freedom, 4 potential states)"
The final line of a class must be an end statement. This starts with end and then the Name of the class followed by a semicolon:
an example of this is:
Class Restriction Uses and Contents
Each Class Restriction has certain restrictions to what the class can contain, aiding their application. Here is a list of the common classes in Modelica with their associated structure and use:
model – general class
Can contain acausal (bi directional) connectors and other components and contain an equation section.
block – for block diagrams
Public elements must only be inputs, outputs or parameters. Used where the causality is know and the direction is maintained. Protected elements can be acausal and contain an equation section.
function – mathematical functions
Similar to block class with inputs, outputs and parameters. Contains Algorithm section, instead of an equations, which is procedural code.
In Algorithm sections variables must be on the left, expressions on the right.
record – define a data structure
Can only contain parameters, variables and constants. No equations or Algorithms.
connector – declare the structure of ports or interface points
Only contains variable declarations, no equations. There are 3 types of variables:
- non-flow (across) – quantities that are equal across a connection
- flow – quantities that sum to zero across a connection
- stream – ensure that bi-directional flow of enthalpy is reliable
package – define libraries of classes
Can only contain declarations of classes, used to organise libraries.
type – extension to the built-in types
Can only contain definitions of types with associated details, e.g. unit and display units.
As you can see when looking at the image at the top of this post, and almost all published models, there is an annotation before the end statement. An annotation contains additional code to aid the model, such as the description and icon animation definitions; it can also contain simulation preferences and library requirements. Many times, when viewing the text layer, the annotations will be collapsed, hiding all of the annotations and replacing it with a single lower case green a and semicolon:
This can be expanded to view what the annotation contains by clicking on the a or right clicking, looking at the “Expand” drop down menu to expand annotations throughout the model.
Tips To Aid Writing In The Text Layer
The easiest way of seeing examples of the use of the Modelica Language is to look at the text layers of published libraries. Published libraries are syntactically correct and most are not protected, allowing viewing of text layers.
When writing in the text layer using Ctrl + Space brings up a context menu containing all the words beginning with the letters written so far. This can also be used to aid writing out library paths as it will provide a list of packages/classes when writing a path.
If you attempt to move away from a model but are unable and greeted with an error message that looks like the image on the right, then it is most likely that you have a syntax error. If you go to the Dymola Messages box then it will give you more information as to where the problem is occurring. In the example below it is due to a missing semicolon on a parameter declaration on line 6; this is showing an error on line 8 as it doesn’t know that this is a start of a new definition, therefore it thinks that syntax in incorrect.
Modelica (line 8, column 3: Add3) Expected one of: ";" "," ")" "constrainedby" "annotation" 60 (line 9, column 56: Add3) Expected one of: identifier ERRORS have been issued.
When the Dymola Messages box highlights a line then this can really help identify the problem area. But be aware that if there is a syntax error within brackets then it will signal that the error is found in the first line of the definition. This means that you need to check the modification of the class.
To help you get around the text layer, the line that a cursor is on is displayed in the bottom right corner of the screen. You can also navigate to any line by hitting Ctrl + G and selecting the line you want to go to.
Written by: David Briant – Project 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.