When building a model, it’s important to remember that the majority of parameters and variables we add are not just real numbers but represent physical quantities. So, to add physical meaning to the parameters and variables in our models we should make use of unit types. Doing this will enable Dymola to check if the equations balance, help the users of your models to provide appropriate inputs, and improve their understanding of the results delivered. In this blog post I will cover some of the basics of using units in Dymola models.
Unit Types
The Modelica Standard Library (MSL) contains a package of SI unit types, Modelica.SIunits. These unit types contain additional attributes for:
- The quantity which is the description of the unit.
- The unit used in the equations.
- The default display unit.
- The minimum and maximum allowed values.
Figure 1 shows the Angle type in the MSL SIunits package, and the Modelica code defining the type.
Figure 1: The MSL SIunits package
If the Modelica Standard Library SIunits package does not contain the unit type you want to use, then you can create your own. The blog post Adding additional Units? Utilising Type definitions explains how to do this.
Using Unit Types in Your Models
As you create new variable declarations in your models you should use unit types rather than the basic Real type wherever possible, as shown in Figure 2. The previous blog post, Import your way to more lean Modelica code shows you how to use import statements to alias the Modelica.SIunits package to a shorter local name in your libraries to abbreviate unit type declarations and make your code easier to read.
Figure 2: Using unit types in parameter and variable declarations
We can improve models with Real connectors, Modelica.Blocks.Interfaces.RealInput and Modelica.Blocks.Interfaces.RealOutput, by adding units to provide physical meaning to these connectors and maintain units associated with the variables in our model. The VeSyMA vehicle body angle sensor has real output connectors for the roll and pitch angles, if we look at its text layer in figure 3 we see that additional attributes of unit and display unit have been added to the connectors to give them physical meaning.
Figure 3: Applying units to Real connectors in the VeSyMA.Bodies.Sensors.Components.BodyAngles
In our model icons we can include parameter or variable values by adding a text field with %<variable name>, Figure 4 shows the icon layer for the Modelica.Mechanics.MultiBody.Parts.Body where this is used to display the value of the mass parameter m. From Dymola 2019, units are presented in the diagram layer when the component icon includes a variable value. Figure 4 shows the diagram layer for the Modelica.Mechanics.MultiBody.Examples.Elementary.Pendulum, where parameter values and units are displayed below the damper and body.
Figure 4: Displaying variables in the diagram layer with their units
Benefits of Using Units in Your Models
Unit Checking
When you apply units to the variables in your models, Dymola can perform dimensional analysis to check that the units are balanced in the model equations during translation. Figure 5 shows an example model calculating area from length and width parameters, the unit type defined for the area variable is incorrectly set to Modelica.SIunits.Length whose unit is m, but from the equation Dymola knows that the unit should be m2. So, the warning shown in the Translation Log is produced to highlight this inconsistency.
Figure 5: Incompatible units warning when checking a model
Unit Conversion
Fundamentally Dymola works in SI units, but it includes an extendable method for unit conversion in parameter dialogs and plots if you are using unit types. This is very useful if your users’ culture is to use a non-SI unit. The Dymola installation directory contains two scripts of common unit conversions in the insert folder, displayunit.mos and displayunit_us.mos. The unit conversion scripts used are controlled in the dymola.mos script, located in the same folder. By default, only the display_unit.mos is run. If there are unit conversions you need that are not in these display unit scripts then you can edit them, similarly the dymola.mos script can be modified to run additional display unit scripts when Dymola is launched. There is a more detailed description of this in this blog post, and also in the Dymola User Manual Volume 1 section on display units.
When you use unit types in your models, and there are unit conversions available, you will be able to change the display unit used when specifying a value in the parameter dialog, as illustrated for a mass parameter in Figure 6. Select the unit for the parameter and a dropdown list of display unit options will appear to select from.
Figure 6: Unit conversions in the parameter dialog box
From Dymola 2019 you can also enter a parameter value with prefixed units, even if that unit is not in the display unit dropdown list in the parameter dialog. From Figure 6 we can see that the display unit options for the mass parameter m does not include grams only kilograms, so if I wanted to enter a value in grams I could enter 1 g in the parameter dialog, note there must be a space between the value and the unit. Reopening the parameter dialog after I have entered this value, I will see that grams has been added to the display unit options as shown in figure 7. Grams will appear in the display units everywhere the mass unit is used. However prefixed display units are not saved between Dymola sessions, so it will not appear in the display unit options the next time I open Dymola.
Figure 7: Entering parameter values with prefixed units
Remember that Dymola uses SI units, so when you look at the text layer the value shown will be stored in the SI unit even if you have used a unit conversion. Figure 8 shows the text layer after I changed the mass parameter m to a value in grams in the example above. The value is stored as the equivalent value in kilograms as this is the SI unit for mass, but the display unit attribute is set to grams for when you view this parameter in the parameter dialog.
Figure 8: Parameter modifier when a display unit has been changed
You can also take advantage of unit conversions when looking at your results in the Dymola simulation window. Select the unit next to an entry in the Variable Browser and you can select from the display unit options available. In a plot, you can right click on the line and select Display Unit from the menu to choose an alternative display unit. Also, by using unit types for our variable, units are applied to axes of our plots.
Figure 9: Display units in the Simulation Window
Convinced Yet
Hopefully these benefits will persuad you of the importance of using units in your Dymola models if you do not already, as well as providing some tips on using them effectively. Users of your models will certainly thank you for considering units when building your models; clarity of knowing what is going in and coming out of a model is key to their understanding.
Written by: Hannah Hammond-Scott – Senior 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