Tutorial 1a: Modeling a Cruise Control System using OpenModelica

Learning Objectives

Understand how to model the ‘physics’ of complex systems.

1 – Model systems as differential algebraic equations in OpenModelica

2 – Model the adaptive cruise-control system’s controller, plant, and environment/context.

3 – Make the models re-usable in an object-oriented fashion.

4 – Understand the function of a PID controller, and find the appropriate control parameters by simulation.

Handout & Setup

The presentation or the tutorial on introduction to (multi-paradigm) modeling and OpenModelica can be found here.

  1. You should install OpenModelica for your platform via this link.
  2. Make sure that the Modelica Standard Library (MSL) is included and set-up as a default library (or atleast among one of the loaded libraries). The instructions for the same are included in the previous link.
    1. If the MSL does not show up automatically in the Libraries pane of OMEdit, you should download a copy of the latest release of the MSL via this link. Then go to File > Open Model/Library File(s) and selecting the download file.
  3. Download this archive. Unzip the content, which is a single .mo (Modelica) file. This is the package that you will work with during the tutorial.
  4. Load the Modelica file in OpenModelica Connection Editor (OMEdit) by going to File > Open Model/Library File(s) and selecting the unzipped .mo file.

Tools Presentation

You are going to use OpenModelica Connection Editor (OMEdit) in this tutorial.

Installing OpenModelica installs a number of applications in your system:

OMEdit

The OpenModelica Connection Editor (OMEdit) is the standard graphical user interface that is used for graphical Modelica model creation and editing. We will use OMEdit for all the tasks. Launch instructions and other features of OMEdit are available on the OMEdit website. OMEdit has 4 different views but we are only interested in the Modelling and Plotting views. We will primarily use OMEdit to design the model. Information about the other OpenModelica applications are just given for information.

OMNotebook

OMNotebook is a notebook-like tool to learn the usage of OpenModelica and construct more-readable documentation which incorporates code-windows in between text. Think of Jupyter Notebooks.

OMShell

OMShell is an interactive session handler that parses and interprets commands and Modelica expressions for evaluation, simulation, plotting, etc. The session handler also contains simple history facilities, and completion of file names and certain identifiers in commands. We will not use OMShell because we want to learn and visualize graphically the models that we are building. Hence we will only use OMEdit.

We use Python because we can then directly use the data obtained from simulation for analysis through a number of data analysis packages available in Python.

One thing to note is that a Modelica model needs to be compiled only once. Once compiled, the parameters can be changed in subsequent executions/simulation runs without having to compile the model again. This is advantageous since compilation can prove to be a significant overhead if we are optimising for a number of different parameters and ranges (read: the number of simulation runs could go into the thousands or more, as I’m doing in my research, but that is the beauty of it).

Basics

While the Modelica language and its capabilities of object-oriented acausal modeling of the multi-physics have already been described online, what follows is a ‘how-to’ to get started building your own Modelica models for the tutorial using OMEdit.

On the left of the OMEdit window, is the Libraries pane which displays all the libraries that have been loaded in the current Modelica session. Modelica models are organised in Packages which can contain other packages and Modelica classes.

Create a Modelica Package

Go to File > New > New Modelica Class. In the Create New Modelica Class dialog box, enter a valid package name for example, example_package. In Specialization, select Package. Click OK. You should now see your Modelica package in the Libraries class. You should save it before proceeding further by clicking on the corresponding icon in the menu bar or going to File > Save.

If you have already created and saved a package, you can load it in the current session by goign to File > Open Model/Library Files, and choosing the corresponding file in the browsing window.

Create your first Modelica Model

Right click on your Modelica package in the Libraries window > in the drop-down menu select New Modelica Class. In the create New Modelica Class dialog box, enter a valid class name, for example, example_model. In Specialization, select Model. Make sure that for Insert in class, the textbox specifies the Modelica package within which you want to create your Modelica model. Click OK. You have created your first Modelica model!

You can edit the model from within the package or by opening the model. Ideally you should edit the model directly, since then you can visualize it if in the form of blocks and connectors. You cannot visualise a package sinc eit just contains other modelica classes with no phsyical connections between them. The modelica classes are just organised that way since they may be related. For example, the Modelica package contains sub-packages like Electrical (for electrical components), etc. Modelica classes can extend other Modelica classes, i.e. inherit the declarations from the extended class. They may also simply re-use components defined in other Modelica classes.

Build/Edit your Modelica Model

Double click on the Modelica model you want to edit. This takes you to the Modeling view. In the top right corner of the Modeling view are 3 buttons to toggle between different editing interfaces. The 2nd button is to open the Graphical editor and the 3rd button is to open the textual editor.

The graphical editor can only be used in case the model consists of blocks with causal/acausal connections between them. For the 1st and 2nd tasks, you will not use the graphical editor, since we are just creating a model based on Ordinary Differential Equations which have no graphical concrete syntax (within OpenModelica atleast).

In the text editing pane, you can now define your modelica model in-between the model and its corresponding end declarations. Look at the Modelica By Example website for simple introductory examples of Modelica models based on simple Ordinary DIfferential Equations of physics.

If you are making a component-based model. You can add components to the model by dragging them from the Libraries pane onto the graphical editor. You will be prompted to give the component a unique name. You can draw connections between the interfaces of components by holding the left mouse button while simultaneously moving it from one iterface ot the other. This highly intuitive. You can modify parameters of the components by double-clicking on them, which will open the Element Parameters box.

Simulate your Modelica Model in OMEdit

Once you have defined a complete and correct Modelica model, you can now simulate it. To do so, you should click on the S icon in the menu bar. This opens the Simulation Setup dialog box. You can set simulation paramters in this dialog box.

Make sure that you have verified the simulation start time, stop time, step-size/number of intervals, solver method (DASSL is preferred), and tolerance (the default 1e-6 is good enough, as low as possible is preferred ideally).

You can also set the output format to output the data to a file. However, we do not need to do so, since we will later perform simulations through Python where we will handle the simulation output directly. This is just for visualization and initial validation of the model.

Click OK to begin simulation.

Note: You can also ‘check’ the model by clicking on the tick-mark icon in the menu bar. The output from this can be observed in the message browser. The message browser will tell you if something is missing in the model, or if there are inconsisencies in the model.

Visualize simulation trace

Clicking OK in the Simulation Setup ideally takes you to the Plotting view. If not, you can go to the plotting view through the corresponding tab in the bottom-right corner.

On the right you will see the variable browser. You can select any variable/s to plot them in the pane and observe their values over the simulation. The values indicated in the variables pane is the value of that variable at the end of the simulation.

Parametrizing simulation quantities in OMEdit

To define a parameter you simply have to use the ‘parameter’ keyword followed by its unit name and default value in this syntax: parameter <unit> <name>(start = <default value>). If you want to parametrize a quantity which is a parameter of a block in your model. Simply double click on the block in the graphical editor and change the parameter value to the parameter name. This value need not be a numeric quantity but it can be a reference to the name of the parameter within the model, or a function of the parameter as well. Once you hve changed the value in the block, go to the textual editor of your model, and use the same syntax as above to define a parameter. Note that the name of this parameter should correspond to the name of the parameter you have defined in the value of the block. Look at the following image for an example:


Figure 1: Parametrizing the values of the block-parameters of the blocks in your model.

Multiple simulations and analyses of your Modelica model

The example Python file contained in the zip file describes how to use Python to simulate and visualize data from an example Modelica model which will be introduced in the tutorial as well.

We will perform multiple simulations by generating the executable through OMEdit. You should make sure that the executable is generated and not deleted in the right directory by:

  1. go to Tools > Options > General > Adjust the value of Working DIrectory as you like. The executable will be stored in selected_working_directory/model_name/ . So, in the example, if I select example as the working directory, the executable will be example/NewtonCooling/NewtonCooling
  2. go to Tools > Options > General > disable ‘Delete entire simulation directory of the model when OMEdit is closed’

To generate these files, once the settings mentioned above are correctly configured, you should simulate the model in OMEdit at least once.

To re-simulate your model, but not from OMEdit you can simply use the terminal command to execute the executable which is in the directory as described above ‘./the_model_name’. For the example, it will be ‘./NewtonCooling’. Note that you should change the current directory of the terminal session to the example/NewtonCooling/ directory before doing so. This cannot be done from within the example/ directory.

The simulation results will be stored in the same directory as the executable. By default it is a MAT-file, and you should try to use the same because it is the most efficient (compared to CSV, etc.). At the end of each simulation you should read the MAT-file, and record the variables that you are interested in before performing the next simulation, because this file will be overwritten during re-simulation. You can read the MAT-files generated by OpenModelica using the readMat function in the example code!

To re-simulate the model, but with different parameters, you can use command line as well. You simply have to structure your command using the -override flag, as the following ‘./model_name -override parameter1=value, parameter2=value ..’. This is also described and demonstrated in the example code.

To implement a loop over the parameter values, you will have to write a Python script. You can execute shell commands using the os package as demonstrated in the example. Take special note that os.changedir function is used to change the working directory of the virtual shell to the results directory.

Presenters

Rakshit Mittal, University of Antwerp, Belgium (rakshit.mittal@uantwerpen.be)

Hans Vangheluwe, University of Antwerp, Belgium (hans.vangheluwe@uantwerpen.be)