ModelicaML: Getting Started

Issue 1.0, August 2009

Wladimir Schamai
EADS Innovation Works (Hamburg, Germany)
Linkoping University (Linkoping, Sweden)

Abstract: This document provides a short introduction to ModelicaML, points out existing
constraints and limitations, and describes how to set up a ModelicaML modeling environment.

1
Table of Contents

1 ModelicaML: Short Introduction...............................................................................................4

1.1 ModelicaML Notation Overview ........................................................................................4
1.2 Validation of ModelicaML Models and Code Generation ..................................................5
1.3 Generating Code From Multiple ModelicaML Models.......................................................5
1.4 Subset Of The UML Used In ModelicaML.........................................................................6
1.4.1 Constraints for UML State Machines used in ModelicaML ......................................6
1.4.2 Constraints for UML Activities used in ModelicaML ...............................................6
1.5 Limitations With Regard To Modelica................................................................................7
1.5.1 Limitation for Nested Classes ....................................................................................7
1.5.2 Limitation for Inheritance ..........................................................................................7
1.5.3 Decomposition of Ports (Instances of Connector Classes).........................................7
1.5.4 Short-Class-Definition................................................................................................7
1.5.5 Import Clause .............................................................................................................8
1.5.6 Import of Existing Modelica Code .............................................................................8
2 Installation .................................................................................................................................9
2.1 Download Eclipse................................................................................................................9
2.2 Install Papyrus UML (Used for Modeling with ModelicaML) .........................................10
2.3 Install Acceleo (Used for Generating Modelica Code) .....................................................10
2.4 Install Modelica Development Tooling.............................................................................11
2.5 Install ModelicaML Profile and Code Generator ..............................................................12
2.6 In Papyrus: Add Modelica as an OpaqueLanguage...........................................................12
2.7 In Papyrus: Add Modelica Standard Library.....................................................................12
2.8 Alternative: Import an Example ModelicaML Project......................................................12
2.8.1 Simulate the Example Model ...................................................................................14
2.9 Alternative: Create New ModelicaML Project..................................................................15
2.9.1 Apply the ModelicaML Profile ................................................................................16
2.9.2 Import ModelicaML Primitive Types ......................................................................20
2.9.3 Setup the ModelicaML Code Generator...................................................................22
2.9.4 Test ModelicaML Code Generation: Launch the Code Generation .........................24
References.......................................................................................................................................27

2
Table of Figures

Figure 1: ModelicaML concept.........................................................................................................4

Figure 2: ModelicaML notation ........................................................................................................5
Figure 3: Eclipse website ..................................................................................................................9
Figure 4: Eclipse Network Connections..........................................................................................10
Figure 5: Add the Papyrus update-site ............................................................................................10
Figure 6: Add the Acceleo update-site............................................................................................11
Figure 7: Add the MDT update-site ................................................................................................11
Figure 8: Add Modelica as an opaque language ............................................................................12
Figure 9: Using Opaque Languages................................................................................................12
Figure 10: Import ModelicaML example project...........................................................................13
Figure 11: Result of importing the example project........................................................................14
Figure 12: ModelicaML example model loaded in MathModelica System Designer ...................14
Figure 13: Simulation of the ModelicaML example model in MathModelica System Designer ...15
Figure 14: Create new Papyrus UML project .................................................................................15
Figure 15: Un-apply the Standard profile .......................................................................................16
Figure 16: Apply ModelicaML profile ...........................................................................................17
Figure 17: Applied profile...............................................................................................................17
Figure 18: Create a Package............................................................................................................18
Figure 19: Create a Class ................................................................................................................18
Figure 20: Apply a stereotype to the Class .....................................................................................19
Figure 21: Applied stereotype.........................................................................................................20
Figure 22: Import ModelicaML primitive types .............................................................................21
Figure 23: Example of the usage of ModelicaML primitive types .................................................21
Figure 24: Create a ModelicaML Code Generator Module Lancher ..............................................22
Figure 25: Select the ModelicaML Code Generator .......................................................................22
Figure 26: Define the name for the ModelicaML Code Generator Module Launcher....................23
Figure 27: Define the locations for the model, the target folder and the log file ............................23
Figure 28: Open Acceleo Log View ...............................................................................................24
Figure 29: Launch the ModelicaML Code Generator .....................................................................24
Figure 30: Example of error or warning notification ......................................................................25
Figure 31: Errors or warnings in the Acceleo Log View ................................................................25
Figure 32: Buttons for clearing or deleting of log entries ..............................................................25
Figure 33: Generated Modelica code .............................................................................................26

3
1 ModelicaML: Short Introduction
Modelica Modeling Language (ModelicaML) is a graphical modeling language for hybrid (time-
continuous and time-discrete/event-based) systems description. ModelicaML is defined as a
concrete graphical syntax (diagrams) and enables different views (composition, inheritance,
behavior) on system definition. It is based on a subset of the OMG Unified Modeling Language
(UML) [2] and reuses concepts from the OMG Systems Modeling Language (SysML) [3].
ModelicaML is defined towards generation of executable Modelica code from UML-based
graphical models.

Figure 1: ModelicaML concept

UML/SysML provide the modeler with powerful descriptive constructs at the expense of loosely
defined semantics that are marked as “semantic variation points” in the UML/SysML
specifications. The intention of the ModelicaML is to provide the modeler with powerful
executable constructs and precise execution semantics that are based on the Modelica language.
Therefore, ModelicaML uses a limited set of the UML, extends the UML meta-model (using the
UML profiling mechanism) with new constructs in order to introduce missing Modelica concepts
and reuses concepts from the SysML. However, as the UML and SysML, ModelicaML is only a
graphical notation. ModelicaML models are eventually translated into Modelica code. Hence, the
execution semantics are defined by the Modelica language and ultimately by a Modelica compiler,
that translates the generated Modelica code into an executable form.

Since the ModelicaML profile is an extension of the UML meta-model it can be used for both:
Modeling with the standard UML and with the SysML1. See [6] for more detailed description of
the ModelicaML profile and an application example.

The following sections point out constraints and limitations that exist in ModelicaML.

1.1 ModelicaML Notation Overview

Following UML diagrams can be used in ModelicaML for representations of model data
graphically:
- Class Diagram: for representing inheritance and class decomposition.

1
SysML itself is also a UML Profile. All stereotypes that extend UML meta-classes are applicable to the SysML as well.

4
 - Composite Structure Diagram: for representing class components and their
interconnection. This diagram is similar to the Modelica Connection Diagram.
- Activity Diagram: for modeling of conditional equations or algorithm statements.
- State Machine Diagram: for modeling of state-based behavior.

Figure 2: ModelicaML notation

Textual requirements are represented using classes with additional attributes such as id and text. It
is possible to link requirements to other classes in order to establish traceability. Furthermore, it is
possible to formalize requirements, bind them to design models in order to evaluate requirements
during system simulations. See ModelicaML documentation for more information.

1.2 Validation of ModelicaML Models and Code Generation

ModelicaML code generator generates textual Modelica code (folders, representing packages, and
containing .mo files per class). De output folder is called “code” (it will create it automatically if it
does not exist yet) inside the defined project. When regenerating code from model contents
(except the use-code areas) of the .mo files that exist in this folder are overridden.

The code generator may modify the names of model elements as following:
- It replaces all special characters and white spaces (if there are any)
- If a name starts with a number the code generator adds “_” in front of the number

In parallel to the code generation the ModelicaML model is checked for consistencies. Violations
or warnings are displayed in error view and advise the modeler to correct the model. Note,
however, it does not check if there is a name clashing between classes (e.g. two classes in a
package that have the same name).

1.3 Generating Code From Multiple ModelicaML Models

It is possible to divide your ModelicaML models into multiple files and to include (import) them
mutually if needed. For each of the models you should create a code generator launcher (as
described in the next chapter). In order to generate Modelica code from multiple models (files)
- You can launch the code generators for each model individually on demand or
- Create an additional Acceleo chain that will running the individual code generator
launchers one after another.

5
Note, however, this features have not been tested yet.

1.4 Subset Of The UML Used In ModelicaML

As already mentioned, ModelicaML uses only a subset of the UML as basis meta-model. The
following UML meta-classes (their interrelations are implicit and are not listed here) from [2] are
used in ModelicaML models and are eventually translated into Modelica code. Most of them are
extended by the ModelicaML Profile in order to facilitate the capturing of required Modelica
constructs. Some are not extended and are used as defined by the UML (e.g. InitialNode,
ControlFlow, Enumeration, Comment etc.). The numbers in the title-rows correspond to the
chapter-numbers in [2].

7 Classes 11 Actions 13 Common Behaviors

Class CallBehaviorAction FunctionBehavior
Comment OpaqueAction OpaqueBehavior
Constraint
DataType 12 Activities 15 State Machines
Enumeration Activity Pseudostate (choise)
Generalization ControlFlow Region (parallel states)
Package DecisionNode State
Parameter MergeNode StateMachine
InitialNode Transition
9 Composite Structures
Class
Connector
Parameter
Port
Property

1.4.1 Constraints for UML State Machines used in ModelicaML

State machines are marked with a specific stereotype in ModelicaML. This stereotype implies the
following constraints:
- A transition from initial pseudo-state must lead to a state and cannot have guards
- No compound transitions are allowed (transition which cross state hierarchy levels)
- Explicit events (SignalEvents, TimeEvents etc.) are not used. The modeler can use use
guards of transitions instead and react on change of attributes values. For example, a
Boolean variable eventA can be set and unset using “eventA := not eventA;”. If a
transition should react on it the build-in function “change(eventA)” can be used as guard.
- No transition effect are allowed. Entry/Exit behavior of states should be used instead.
- No History, Fork/Joins, Entry/ExitPoints and ConnectionPointReference are supported.

1.4.2 Constraints for UML Activities used in ModelicaML

A subset of the UML Activity is used in ModelicaML for modeling conditional equations or
algorithm statements. The only constructs inside an Activity (with respective stereotype applied
which indicates wether it is an equations or algorithm section) that are supported by this time are:
- InitialNode (exactly one),
- ControlFlows,
- OpaqueActions (for capturing the assignments or equations),
- CallBehaviorAction (for hierarchical modeling),
- MergeNode,
- DecisionNode (with if/when stereotypes).

6
1.5 Limitations With Regard To Modelica
Since ModelicaML is based on the UML meta-model some limitations exist with regard to the
Modelica code to be generated or imported. These limitations are particularly important to be
aware of when importing existing Modelica code (e.g. Modelica Standard Library) into UML-
based (e.g. ModelicaML) models. Modelica code that makes use of the features mentioned will
most likely have to be rearranged.

1.5.1 Limitation for Nested Classes

In Modelica it is possible to nest any restricted classes (package, model, block, connector, record,
type, function) in any other restricted classes. ModelicaML represents Modelica packages using
UML packages and other Modelica classes using UML Class (for model or block) and DataType
(for connector, record or type). The following limitations exist in UML and are thus inherited by
the ModelicaML:

The UML meta-model does not allow Packages to be nested in Classes or DataTypes as
explained in the following table.
UML Package UML Class UML DataType
(represents Modelica package) (represents Modelica model or block) (represents Modelica connector or record, type)
can have nested
UML Packages x
UML Classes x x
UML DataTypes x x

The resulting implication on the Modelica code to be generated from a ModelicaML model or to
be imported into a ModelicaML model is as following.
Modelica package Modelica model / block Modelica connector / record / type
can have nested
Modelica package x
Modelica model / block x x
Modelica connector / record / type x x

In other words, in ModelicaML, it is not possible nest packages in classes or classes in records,
connectors etc.

1.5.2 Limitation for Inheritance

Furthermore, in UML, Packages cannot be extended, i.e. inherited by another Packages or
Classes. In Modelica inheritance is allowed between restricted classes as depicted in the following
figure from [1], p.62.

1.5.3 Decomposition of Ports (Instances of Connector Classes)

In UML it is not possible to represent Ports decomposition (in ModelicaML these represent
instances of connector classes) graphically.

1.5.4 Short-Class-Definition
Modelica short-class-definition is not possible in ModelicaML. The modeler should use
inheritance constructs instead.

7
1.5.5 Import Clause
When modeling with ModelicaML it is not necessary to import packages or classes explicitly. The
modeler can simply use any classes from other packages. The ModelicaML code generator will
generate Modelica code with qualified names so that no import clauses are required.

1.5.6 Import of Existing Modelica Code

Due to the limitations of the UML meta-model described above it is not yet possible to import
existing Modelica code (e.g. Modelica Standard Library) without modifying it. It is our intention
to solve this problem in the near future.

8
2 Installation
Presently, ModelicaML modeling and code generation environment is implemented using the
Eclipse technology and including the following plug-ins:
- Papyrus 1.12 [5] as UML-based modeling tool (ModelicaML modeling)
- Acceleo 2.6 [4] for model to text transformation (Modelica code generation)

Both2, Papyrus and Acceleo became Eclipse Projects and will deliver new versions in the next few
moth. We plan to migrate the current environment to the new versions.

Features of the new Papyrus version

The new version of the Papyrus (that will be compatible with Eclipse 3.5) tool will provide
features to adapt the modeling GUI based on a profile. This will allow us to reflect Modelica
wording so that the modeler will not have to learn UML and the list of meta-classes that can be
used in ModelicaML. The GUI will be restricted to only what is allowed in ModelicaML. This
will also improve consistency of models and reduce model validation effort.

Features of the new Acceleo version

The new version of the Acceleo is based on the OMG model to text specification. We also plan to
convert the current code generation scripts into the new syntax defined by this standard.

2.1 Download Eclipse

Description: Eclipse is the basis-technology used for modeling and code generation.
Provider Site: http://www.eclipse.org

Procedure:
- Download, extract and start Eclipse 3.5 Modeling Tools

Figure 3: Eclipse website

- Update the network connection properties (if required) so you can install other plug-ins.

2
http://www.eclipse.org/modeling/mdt/?project=papyrus
http://www.eclipse.org/modeling/m2t/?project=acceleo

9
 Figure 4: Eclipse Network Connections

2.2 Install Papyrus UML (Used for Modeling with ModelicaML)

Description: Papyrus UML Modeler is used for creating ModelicaML models.
Provide Site: http://www.papyrusuml.org/
Eclipse Update Site: http://www.papyrusuml.org/home/liblocal/docs/updates/papyrus

Procedure:
- In Eclipse go to Help -> Install New Software
- Add the Update-Site (see screenshot below)

Figure 5: Add the Papyrus update-site

- Select Papyrus UML Modeler.

- Install the Papyrus UML Modeler

2.3 Install Acceleo (Used for Generating Modelica Code)

Description: Acceleo technology is used for generating Modelica code from ModelicaML models.
Provide Site: http://www.acceleo.org/pages/home/en
Eclipse Update Site: http://www.acceleo.org/update/

Procedure:
- In Eclipse go to Help -> Install New Software
- Add the Update-Site
- Install Acceleo (see screenshot)

10
 Figure 6: Add the Acceleo update-site

2.4 Install Modelica Development Tooling

Description: MDT is used for viewing and editing of Modelica code within the Eclipse
environment.
Provider Site: http://www.ida.liu.se/~pelab/modelica/OpenModelica/MDT/
Eclipse Update Site: http://www.ida.liu.se/~pelab/modelica/OpenModelica/MDT/

Procedure:
- In Eclipse go to Help -> Install New Software
- Add the Update-Site
- Install MDT (see screenshot)

Figure 7: Add the MDT update-site

11
2.5 Install ModelicaML Profile and Code Generator
Download the ModelicaML Eclipse plug-ins
- ModelicaML Profile and
- ModelicaML Code Generator.

Procedure:
- Unzip this files
- Copy the .jar files into your Eclipse “plug-in” directory.
- Restart Eclipse

2.6 In Papyrus: Add Modelica as an OpaqueLanguage

- Go to Window -> Preferences -> Papyrus
- Add Modelica as a new opaque language

Figure 8: Add Modelica as an opaque language

It is used when defining the body of opaque constructs.

Figure 9: Using Opaque Languages

2.7 In Papyrus: Add Modelica Standard Library

This feature is not supported yet.

2.8 Alternative: Import an Example ModelicaML Project

- Download the example project
- Go to File -> Import- Existing Project into Workspace

12
- Select the example project
- Select the option “copy projects into workspace”

Figure 10: Import ModelicaML example project

- The result should be as illustrated in the figure below.

13
 Figure 11: Result of importing the example project

2.8.1 Simulate the Example Model

The example project contains the ModelicaML model and the generated code. You can load the
model “TwoTanksSystemExample/package.mo” and simulate it (startTime=0, stopTime=400).

Figure 12: ModelicaML example model loaded in MathModelica System Designer

14
 Figure 13: Simulation of the ModelicaML example model in MathModelica System Designer

2.9 Alternative: Create New ModelicaML Project

Procedure:
- Create new Papyrus Project

Figure 14: Create new Papyrus UML project

- Delete the Standard Profile (it is required for ModelicaML modeling)

15
 Figure 15: Un-apply the Standard profile

2.9.1 Apply the ModelicaML Profile

16
 Figure 16: Apply ModelicaML profile

- Select all except the “ProfileDecumentationStereotypes”. This sub-profile is used only for
internal ModelicaML Profile documentation only. It is not used for modeling.
- The result should be like in the screenshot below.

Figure 17: Applied profile

- Test the profile application:

o Create new Package

17
 Figure 18: Create a Package

o Create new Class inside the Package

Figure 19: Create a Class

- Apply a stereotype to the Class

18
 Figure 20: Apply a stereotype to the Class

- The result should be like in the screenshot below

19
 Figure 21: Applied stereotype

2.9.2 Import ModelicaML Primitive Types

You need to import the primitive types defined in ModelicaML.

20
 Figure 22: Import ModelicaML primitive types

- In particular this import is required for the selection of types for function variables (see
screenshot below)

Figure 23: Example of the usage of ModelicaML primitive types

21
2.9.3 Setup the ModelicaML Code Generator
Procedure:
- In your project create a new Acceleo “Module Launcher”

Figure 24: Create a ModelicaML Code Generator Module Lancher

- select the ModelicaML code generator module

Figure 25: Select the ModelicaML Code Generator

- Define the name for the code generator

22
 Figure 26: Define the name for the ModelicaML Code Generator Module Launcher

- Select the ModelicaML model, the folder and location for the error.log file

Figure 27: Define the locations for the model, the target folder and the log file

- Open the Acceleo log view. The ModelicaML code generator will display any warning or
errors in this view

23
 Figure 28: Open Acceleo Log View

2.9.4 Test ModelicaML Code Generation: Launch the Code Generation

Figure 29: Launch the ModelicaML Code Generator

- If there are any errors the code generator will inform you as illustrated below

24
 Figure 30: Example of error or warning notification

Figure 31: Errors or warnings in the Acceleo Log View

- You can clear or delete the logs using these buttons (see screenshot below).

Figure 32: Buttons for clearing or deleting of log entries

- By default the Modelica code is generated into the “code” directory of your project.
- You can open the Modelica file using the Modelica Development Tooling as shown
below.

25
Figure 33: Generated Modelica code

26
References
[1] Modelica Association. Modelica: A Unified Object-Oriented Language for Physical
Systems Modeling: Language Specification Version 3.0, Sept 2007. www.modelica.org
[2] OMG. OMG Unified Modeling Language TM (OMG UML). Superstructure Version 2.2,
February 2009.
[3] OMG. OMG Systems Modeling Language (OMG SysML™), Version 1.1, November 2008.
[4] Acceleo, Eclipse Plug-In. www.acceleo.org/pages/home/en
[5] Papyrus UML, www.papyrusuml.org
[6] W.Schamai. ModelicaML: a UML Profile for Modelica, Technical Report
http://urn.kb.se/resolve?urn=urn:nbn:se:liu:diva-20553

27