The Modelica Association released the Modelica Language Specification version 3.4 on 15 May 2017. This blog entry summarises the major changes to the language specification with the aim of helping users to be aware of the changes.
These changes have been supported in Dymola since Dymola 2018.
Main Changes
The main changes are:
- Modifications to version handling and conversion rules are now defined
- Flattening is specified
- Indexing of Enumerations is now supported
- The ability to extract values of a component and store these in a Record
- Initialisation of Clocked Continuous States is simplified
- The Ellipse Annotation is extended to include an option to draw only an arc
- Records in functions with Real and non-Real elements can now be differentiated
Many minor improvements were also made, the release notes that cover these changes can be found in the Modelica 3.4 Specifications here. Dymola has supported these changes since Dymola 2018 (refer to the Dymola 2018 release notes).
1. Version handling and conversion rules
A comparison of the Version Handling in Modelica 3.3 Revision 1 versus Modelica 3.4 shows the modifications in the version handling.
Figure 1. A comparison of the Version Handling section in Modelica 3.3 Revision 1 versus Modelica 3.4. The left side is Modelica 3.3 Revision 1 and the right side is Modelica 3.4. The red text has been replaced with the green text in Modelica 3.4. Comparison done using https://draftable.com/compare.
For those not familiar with version handling; the annotation of a library can contain the conversion keyword that states how the user’s model or library that uses an old version of this library should be modified to support the latest version of the library (we will refer to the “user’s model or library” as the user’s classes).
An annotation using Modelica 3.3 Revision 1 conversion keyword is in Figure 2.
Figure 2. Modelica 3.3 Revision 1 implementation of the conversion script. This annotation can be used in the top level package of a library. The script files specify the conversion rules from the from version
The from version keyword, in Figure 2, has been modified so that from version can now specify a range of versions supplied as a string array (as in Figure 3 for version={“2017.2″,”2017.2.1”}).
The script keyword is a .mos file that contains the conversion rules to convert the user’s classes using the from version of this library to the target version of the library (i.e. “2018.2” in Figure 2). The to keyword has been added so that the target version of the conversion script can be specified. Supplying the target version of the conversion script allows for the user’s classes to be converted in a multi-step process from an old version of the library to a later version, repeatedly, up until the version of this library. This multi-step conversion reduces the developers work as now only a conversion script between the previous version and the current version is needed. An example of using to keyword is in Figure 3.
Figure 3. Modelica 3.4 implementation of the conversion script. Note that from version now supports multiple versions. And the to keyword specifies the library version that the associated conversion script will update to.
The change keyword can now be used, as well as the script keyword, to provide the conversion method between library versions. When using change={conversionRule(),…} an array of conversion rules can be supplied. A conversion rule is one of the following functions:
- convertClass(“OldClass”,”NewClass”)
- convertClassIf(“OldClass”, “oldElement”, “whenValue”, “NewClass”)
- convertElement(“OldClass”,”OldName”,”NewName”)
- convertModifiers(“OldClass”,{“OldModifier1=default1″,”OldModifier2=default2”,…},{“NewModifier1=…%OldModifier1%”} [, simplify=true]
- convertMessage(“OldClass”, “Failed Message”);
Most of the conversion rules above have been present in Dymola for many releases and are now being brought into the Modelica Specificatoin. The convertMessage rule was introduced in Dymola 2018.
For further details about these functions refer to https://modelica.org/documents/ModelicaSpec34.pdf#page=250.
2. Flattening is specified
When translating a Modelica model, the Modelica code of the model and its dependent classes are extracted into a flat model, this process is called flattening (see the Introduction to the model translation and Symbolic Processing blog post for more details about flattening and symbolic processing).
In the versions of the Modelica Language Specification before Modelica 3.4 the flattening method is not described in detail. This resulted in ambiguities that could cause problems.
In Modelica 3.4 the process for flattening the code is described in more detail, the proposed Specification modifications can be found here.
3. Indexing of Enumeration values
When Enumeration types are indexed with the Integer the corresponding element of the Enumeration type is returned.
An example of using this is in Figure 4:
Figure 4. An example of Enumeration type indexing.
In Figure 4 the selectedColor will be GREEN.
For further details refer to https://modelica.org/documents/ModelicaSpec34.pdf#page=55.
4. Extracting values from a component to a record
The variable and parameter values of a component in a model can be extracted and stored in a record using this functionality.
This feature is useful in analysing the behaviour of large models. In the example in https://svn.modelica.org/projects/MCP/public/MCP-0023_ModelToRecord/MCP-0023_ModelToRecord.pdf this feature is used to extract the variables of the pump components in a fluid network, to analyse the pumps’ behaviour. This feature could also be used to calculate the overall characteristics of a model such as the centre of mass of a multibody network.
A limiting factor to this feature is that there is currently no convenient way to automatically determine the components of a given class in a model and then extract the values of these components into records. There is a workaround using the Clatyex library; maybe this will be a future blog post.
Set the following flag in the Dymola command-line to use this functionality:
Advanced.RecordModelConstructor=true
Please refer to https://modelica.org/documents/ModelicaSpec34.pdf#page=158 for further details.
5. Initialisation of Clocked Continuous States
A new function called firstTick() is introduced that returns true when called at the first clock tick of a clocked partition. This simplifies the process of initialising a clocked section with specific values for the first clock tick. This is explained in the Modelica Change Proposal MCP-0024 which can be found here https://svn.modelica.org/projects/MCP/public/MCP-0024_InitializationClockedStates/MCP-0024_InitializationClockedStates.pdf. An example of using firstTick() is in Figure 5.
Figure 5. Example of using firstTick() for initialisation. This example is taken from https://svn.modelica.org/projects/MCP/public/MCP-0024_InitializationClockedStates/MCP-0024_InitializationClockedStates.pdf#page=2.
In addition to this, the interval() and previous() functions can now be used in clocked discretized continuous-time partitions. Please refer to the document above for further details.
6. Using the Ellipse Annotation to draw an arc
The Specification for Ellipse is in Figure 6.
Figure 6. The Ellipse specification
Arcs can now be constructed by using the startAngle and endAngle attributes to draw an arc. However in Dymola there is an arc GUI tool that draws ellipses; please refer to Dymola User Manual Volume 1 Section 4.2.5 paragraph Ellipses.
7. Differentiation of Records with non-Real elements in functions
Previously, records that were used as inputs to functions that contained Integers, Booleans, Strings or Enumerations elements could not be differentiated. This limited the ability to supply derivatives to functions that had records with non-Real elements as inputs using the derivative annotation or for Dymola to calculate the derivatives of these functions automatically during model translation.
When the input record is differentiated, a derivative version of the record is required that contains only the derivative of the Real values in the record. Dymola will create this derivative record when differentiating a function automatically. When using the derivative annotation this derivative record will have to be created. For further details please refer to https://modelica.org/documents/ModelicaSpec34.pdf#page=161.
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