A Dymola Primer
Krister Edstrom
Department of Electrical Engineering Linkoping University
S-581 83 Linkoping Sweden
email: edstrom@isy.liu.se 1995-05-15
Abstract: This is a beginner's guide to the simulation and modeling environment Dymola. Dymola is presented by means of a simple hybrid example system which is modeled and simulated.
Keywords: dymola, events, introduction, modeling, simulation
Contents
1 Introduction 1
2 An Introductory Example 2
3 Working with Dymola 3
3.1 The Dierent Parts : : : : : : : : : : : : : : : : : : : : : : : : 3 3.2 Object Orientation : : : : : : : : : : : : : : : : : : : : : : : : 3 3.3 Dymodraw : : : : : : : : : : : : : : : : : : : : : : : : : : : : 4 3.3.1 Window Description : : : : : : : : : : : : : : : : : : : 4 3.3.2 Before Starting Dymodraw : : : : : : : : : : : : : : : 4 3.3.3 Entering a Model : : : : : : : : : : : : : : : : : : : : : 4 3.3.4 Creating Libraries : : : : : : : : : : : : : : : : : : : : 8 3.4 Dymola : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 9 3.4.1 Before Starting Dymola : : : : : : : : : : : : : : : : : 9 3.4.2 Using Dymola: : : : : : : : : : : : : : : : : : : : : : : 9 3.4.3 Creating a Script : : : : : : : : : : : : : : : : : : : : : 11 3.5 Dymoview : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 11 3.5.1 Plotting the Output : : : : : : : : : : : : : : : : : : : 12 3.5.2 Animation: : : : : : : : : : : : : : : : : : : : : : : : : 12
4 Errors and bugs 13
4.1 Dymodraw : : : : : : : : : : : : : : : : : : : : : : : : : : : : 13 4.2 Dymola : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 13 4.3 Dymoview : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 13
A Dymola Code 15
B Dymola Script 16
C Dymola Library 16
1 Introduction
Dymola is a modeling and simulation environment based on a declarative simulation language, Dymosim. A declarative language is a language where the user speci es relations between variables, and not assigns variables. In a non-declarative language the following to statements are dierent:
u=Ri i=u=R
The rst line assigns the value of Ri to the variable u and the second line assignsu=R to the variablei. In a declarative language the statements
u=Ri i=u=R 0 =u;Ri
are the same. They are just stating the relationship between the variables.
The system deals with problems such as algebraic loops, causality prop- agation and handling of discrete events. Due to its complex user's interface the system is rather dicult to use for the beginner.
The report will show how to use the Dymola environment to create mod- els and make simulations. The Dymosim language and the more advanced use of the system will not be discussed here. The more advanced user is recommended to read 2].
2 An Introductory Example
The example we will be using in this report is a model of a bouncing ball, see gure 1. The ball will be represented by a mass m which is subject to a gravitational eld g and an air resistance, given by a force Fa which is proportional to the velocity v of the ball. The bounces are modeled as events, i.e. abrupt changes in the model. Using Newton's rst and second
Fa mg
Figure 1: Two models of a falling ball.
laws we obtain the following equations describing the motion of the falling ball:
mg+Fav=ma (1)
x_ =v (2)
v_ =a (3)
The bounce is supposed to be fully elastic so when the ball reaches the ground only the sign of the velocity changes.
3 Working with Dymola
3.1 The Dierent Parts
The Dymola environment includes four dierent parts called Dymodraw, Dymola, Dymosim and Dymoview. Note that both the environment and one of the parts are called Dymola. The rst part, Dymodraw is used for the modeling process it is here the model is entered. When the model is entered it can be prepared for simulation in the part called Dymola, e.g.
the equations of the model can be partitioned and compiled. The prepared model is simulated with Dymosim and nally the results are presented in Dymoview. A description of each one of these parts follows below.
3.2 Object Orientation
Dymola is object oriented in the sense that a model can be built from sub- models. A /sub/model can be an instance of a certain prede ned model class with certain speci ed parameters see gure 2. If e.g. the model class
model class damper model class gravity
model class inertia
submodel(gravity) G m=10
submodel(friction) F k=5
submodel(inertia) I m=10
model ball
Figure 2: Using instances of model classes.
resistor with a general resistancer is speci ed, a /sub/model R1 which is a certain model of a resistor can be speci ed as follows:
/sub/model(Resistor) R1 r=10
A nice way to work with Dymola is to create libraries which contain all the model classes needed for simulating a model. When working with electric circuits, a library can for instance consist of the following model classes:
source, resistor, capacitor and inductor. The model will then be a list of submodels, e.g. certain instances of model classes, and a description of how they are connected.
3.3 Dymodraw
This is the subprogram in which new models are created. This can be done either graphically or textually. For more information about Dymodraw see
1].
3.3.1 Window Description
When using Dymodraw, four dierent types of windows appear, see gure 3.
The Log Window, in which error messages and the most important commands are logged
The Edit Windows, which are the 'working' windows. It is here where new models and model classes are created.
The Library Windows, in which existing model classes can be viewed.
When creating a model in an Edit Window, submodels can be dragged from a Library Window and dropped in the Edit Window.
The Tool and Palette Windows are used for creating connections (cuts) between submodels and the graphics shown in a Library Window.
3.3.2 Before Starting Dymodraw
Before starting Dymodraw it is necessary to choose which le directory to use. This is done by modifying the le $dymola/insert/dymodraw.ini. The reason for doing this is that it enables the possibility to drag and drop submodels which shall be included in the model. When using libraries, problems can occur if two model classes with the same name are entered, or if the same model class is entered twice see section 4.
3.3.3 Entering a Model
Independently of how the model is created, graphically or textually, the decomposition of the model is made in the same way. The rst step is to create the model classes that will be used. Let us divide our model of the
Figure 3: The four dierent types of windows. Log window, edit window, library window and tools window.
falling ball into three submodels one describing the eect of gravity, one the air friction and the last one the acceleration and the bounce see gure 4.
The connections between the submodels are the velocity, v, and the force, F. When working with mechanical systems, gravity, air friction and accel- eration due to a force are three common phenomena. To make future use of such phenomena easier, three model classes can be constructed, namely
inertia,frictionandgravity. Consider construction of the model classgravity. Textually this model class can be constructed by writing the following Dy- mola code in a text editor:model class gravity
cut C (v/-F) parameter m=1 parameter g=10 F=m*g
This code tells us that we are creating a model class. When using an instanceend
model class Friction Air Friction
model class Inertia Inertia
Bounceand
Model Class Gravity Gravity v, F
Figure 4: Decomposition of the model into three submodels.
of this model class, the model is connected to other models by velocity, v, and force,F. The connection with other parts of the model is de ned by the cut command. In the cut command the name of the cut is de ned, and also the cut variables. There are two kinds of cut variables, those assigned to a common value, and those adding to zero. The variables before the '/'-sign are assigned to the common value and the ones after add to zero. In the model class above the name of the cut isC. The variable v is assigned to the same value as the variables in the same position in cut de nitions of the other parts of the model, and the variables in the same position as;F adds to zero. The minus sign is due do a positive reference direction upwards.
Two parameters are introduced, the mass and the gravity. The parame- ter values can be changed when running Dymola without recompiling the model. Finally the equation yielding the force is entered.
To enter the model with Dymodraw we rst have to give the model a name. This is done by choosing Edit/New Class from the menu and then typing the name here gravity. To make it an instance of a certain model class, the name of the model class has to be entered asname of super class. For example, if we are working with electrical components we can create a model class twoport in which the connection with other components is de ned. Then model classes such as resistor, inductor and capacitor can be made as instances of the model class twoport describing the physical properties of the components. Finally /sub/models can be made from these
model classes, e.g.
submodel(resistor) R1 r=10.
Here we have no super class. To make the model a model class we choose Edit/Change Attributes and at the last line we change the 'n' to a 'y'. These steps will create the rst line in the code above.
Next step is to de ne how to connect instances to other models. Drag and drop any cut from the Cuts Window to the Edit Window by clicking at cut in the Cuts Window and then in the Edit Window containing the model.
Click twice at the cut appearing in the Model Window and write v=;F in the largest square in the window appearing. Parameters are entered by Edit/Declarations, where
parameter m=1 parameter g=10
is entered. Then choose Close/Update. The equation is entered in the same way, choosing Edit/Equation. To make it easy to use the drag and drop facility for submodels, an icon for the model class can be made. Choose View/Icon Layer and create an icon by using the Tools and Palette Windows.
Go back by choosing View/Diagram Layer. Finally the model class is saved, File/Save e.g. as gravity.dym.
When looking at the created le, default $dymola/bin/gravity.dym, the same code as above will be found, with some extra comments, containing graphical information.
With one of the methods shown above, construct a model class called friction. If the model class is entered graphically, start with creating a new Edit Window, View/New Window.
model class friction cut C (v/F)
parameter k=1 F=-k*v
end
Also create the following model class called inertia:
model class inertia cut C (v/F)
parameter m=1 local a=0
der(v)=a F=-m*a end
The next step is to create a model class covering both the inertia and the bounce, calledinertiab, and the nal step is to connect inertiab,friction and
gravity.
To create a model with the name inertiab and super class inertia, chose Edit/New Class. Make it a model class by Edit/Change Attributes. Some new equations have to be added viaEdit/Equations, namely
der(x)=v when x<0 then
init(v)=-v endwhen
where the last three rows handle the bounce. When reaching the ground, the sign of the velocity is changed. A new declaration has to be done by Edit/Declarations, and
local x=2
The cut and the acceleration are taken care of by the underlying model class
inertia. Create an icon for the model class and save it.
To connect the submodels we create another model, ball, which is not a model class and does not have a super class. Insert three submodels by using the commandEdit/Insert Component three times, one of classgravity named e.g. G, one of class inertiab named IB and the third of classfriction namedF. Connect them with lines by clicking on the line below 'TEXT' in the Tools Window and then on the cuts visible in the Edit Window. Save the model.
The model of the bouncing ball is now complete and can be entered in Dymola. The complete code can be found in Appendix A.
3.3.4 Creating Libraries
To enable the drag and drop facility mentioned above, libraries have to be created. The rst thing to do is to collect all model classes that shall be in the library in the same le, e.g. ball.lib and make sure that they are read into Dymodraw. Create a new model, not a model class, e g ballgra and enter all the model classes into this model without connecting them.
Save the model as ballgra.lib. The code in this le can be found in
Appendix C. Add the following three lines to the Dymola initiation le
$dymola/insert/dymodraw.ini
open {path}/ball.lib open {path}/ballgra.lib
window l 0.0 0.0 0.5 0.5 ballgra
where the rst two lines is for reading the two les, and the last line is for opening a Library Window. The l stands for library - the window type.
The gures tell where the window will appear on the screen. The two rst gures tells where the upper left corner of the window will be placed and the two last gures is the distance to the lower right corner. The unit is the length/height of the screen, so the above example will create a Library Window in the upper left fourth of the screen. ballgra tells which model to be plotted in the window.
If those lines are not included in the initiation le, the model classes can still easily be entered into Dymodraw by choosing File/Open and opening ball.lib.
3.4 Dymola
In the Dymola part of the Dymola environment the code for simulation is created and compiled. It is also possible to manipulate the model in other ways. Dymola is also used to start Dymosim. For more information about Dymola and Dymosim see 2] and 3] respectively. The Dymola Window is shown in gure 5.
3.4.1 Before Starting Dymola
Similar to Dymodraw, the les that will be used when simulating a model have to be entered. This can be done either by entering the used model classes in Dymodraw or by putting all the model classes in the same le as the model and load it into Dymola. Another alternative is to create a Dymola script which will load the necessary model classes see section 3.4.3.
3.4.2 Using Dymola
Dymola is easily started from Dymodraw by choosing 'File/Run Dymola'.
The most straightforward way to make the simulation is to follow the steps below.
Figure 5: Dymola Window.
Enter the model into Dymola by File/Enter Model.
Set the ag 'Events' by Translation/Set. Change the last line to 'set Events on' and chooseFile/Update. This ag has to be set for Dymola to handle events. More about the ags is found in 2].
Partition the model, i.e. sort the equations and propagate into numer- ical causality by Translation/Partition.
Translate the model to the programming language Dymosim by Out- put/Model. The code will be saved in the le$dymola/bin/dsmodel.c.
Compile the model. The model is transferred to the programming language C and then compiled by Simulation/Compile
Determine some parameter values for simulation, e.g. start and stop time by Simulation/Simulation.
Generate an experiment description, to get an internal representation of the chosen parameters and coecients by Simulation/Output Exper- iment. The result is saved in $dymola/bin/dsin.txt.
Simulate by Simulation/Simulate. This command starts Dymosim.
The le $dymola/bin/dsres.texcontains the result. Dymoview will automatically start when the simulation is done. A problem often occur when Dymoview is started see section 4.
There are some other features that can be useful. All parameters and initial conditions can be changed. This is done by Variables/Parameters or Variables/Initial. Before resimulating the model, another output experiment has to be created. It is also possible to do some manipulation of the equa- tions, and get information about the variables.
Output/Variables gives information about the variable type, such as state variable, through variable or parameter. The result of this com- mand can be found in the le $dymola/bin/dsmodel.var.
Output/Equations saves the equations of the model in the le
$dymola/bin/dsmodel.equ.
Output/Sorted Equations sorts the equations and saves them in the le
$dymola/bin/dsmodel.sor.
Output/Solved Equations solves the equations and saves them in the le $dymola/bin/dsmodel.sol.
The results can be shown in the Dymola Window instead of being saved to a le by setting the ag 'AutoFileName' to 'o'.
3.4.3 Creating a Script
A convenient way of working with Dymola is to create scripts for the simula- tion. A script for simulating the bouncing ball following the steps above can be found in Appendix B. The script shall be saved to a le with the exten- sion dyc and entered into Dymola with the menu optionFile/Run Script @.
3.5 Dymoview
In Dymoview there are two dierent types of windows: the Dynamic Model Viewer and the Plot Window see gure 6. In the Dynamic Model Viewer the models are entered into Dymoview. Here animations of the models are also
Figure 6: Dymoview Dynamic Model Window and Dymoview Plot Window.
made. The Plot Window is for plotting the dierent variables as functions of time. See also 4]
3.5.1 Plotting the Output
First the result from the simulation has to be entered in Dymoview. This is done in the Dynamic Model Viewer by selectingFile/Read Dymosim. The default result le isdsres.txt. The plot is then presented in the Plot Window View/Plot Window by selecting the variables to be plotted under Variables.
3.5.2 Animation
It is possible to make 3D animation in Dymoview. To be able to make an animation some special model classes has to be used when the simulation model is constructed. These model classes can be found under the library
$dymola/library/dymoview.
4 Errors and bugs
Since Dymola is a rather new program, there are quite a few bugs. Here are the ones I have found.
4.1 Dymodraw
In Dymodraw the same model or model class can never be entered twice.
This will create a runtime error, and Dymodraw has to be restarted. It is important to know this when one chooses which libraries are going to be included when Dymodraw is started.
A rule to remember is the following: whenever an error occurs, save and restart Dymodraw.
4.2 Dymola
The same rule as for Dymodraw is to be obeyed in Dymola whenever an error occurs, the program seems to stop working properly. The best thing to do is to save and restart Dymola.
4.3 Dymoview
A problem often occurs when Dymoview is started. If the error message 'Dymoview could not nd any data in the le' appears, open the result le
$dymola/bin/dsres.tex and look at the last line before the data starts
the line beginning with ' oat data'. Typically there is a missing parenthesis in that line. If the line reads
float data 44,6)
change it to
float data( 44,6)
Then the le can be reloaded.
Another error is that when a 3D view controller is started, the program execution can not be terminated.
References
1] Dynasim AB, Research Park Ideon, S-223 70 Lund, Sweden. Dymodraw- Dynamic Model Drawing, User's Manual, 1994.
2] Dynasim AB, Research Park Ideon, S-223 70 Lund, Sweden. Dymola- Dynamic Modeling Language, User's Manual, 1994.
3] Dynasim AB, Research Park Ideon, S-223 70 Lund, Sweden. Dymosim- Dynamic Model Simulator, User's Manual, 1994.
4] Dynasim AB, Research Park Ideon, S-223 70 Lund, Sweden. Dymoview- Dynamic Model Viewer, User's Manual, 1994.
A Dymola Code
model class gravity {* (-100, -100) (100, 100) grid (2, 2)}
cut B {* CutB at (-4.84715, 42.8438) (-12.8472, 50.8438)} (v/-F) parameter m=1
parameter g=10 F=m*g
{* layer icon}
{* text "GRAVITY" (-156, -106) (154, 104) color=0 } end
model class friction {* (-100, -100) (100, 100) grid (2, 2)}
cut B {* CutB at (-12.9624, 35.1628) (-20.9624, 43.1628)} (v/F) parameter k=1
F=-k*v
{* layer icon}
{* text "FRICTION" (-156, -106) (156, 106) color=1 } end
model class inertia {* (-100, -100) (100, 100) grid (2, 2)}
cut B {* CutB at (-9.17416, 44.8545) (-17.1742, 52.8545)} (v/F) parameter m=1
local a=0 der(v)=a F=-m*a
{* layer icon}
{* text "INERTIA" (-154, -106) (156, 106) color=2 } end
model class (inertia) inertiab {* (-100, -100) (100, 100) grid (2, 2)}
local x=2 der(x)=v when x<0 then
init(v)=-v endwhen
{* layer icon}
{* text "BOUNCE" (-144, -32) (156, -106)}
end
model ball {* (-100, -100) (100, 100) grid (2, 2)}
submodel (gravity) G {* at (-130, 94) (-36, 34)}
submodel (friction) F {* at (28, 104) (124, 26)}
submodel (inertiab) IB {* at (20, 6) (104, -86)}
connect G:B at F:B {* via (-88, 50) (68, 50)}
connect F:B at IB:B {* via (68, 50) (56, -62)}
end
B Dymola Script
enter model
@{path}/ball.lib
@{path}/ball.dym set events on partition output model compile
simulation Stoptime=10 Algorithm=8 output experiment
simulate
C Dymola Library
model ballgra {* (-100, -100) (100, 100) grid (2, 2)}
submodel (gravity) G {* at (-128, 88) (-42, 50)}
submodel (friction) F {* at (30, 112) (124, 26)}
submodel (inertia) I {* at (-126, 32) (-40, -14)}
submodel (inertiab) IB {* at (32, 28) (120, -10)}
submodel (ball) B {* at (-64, -102) (72, -20)}
end
