1

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.

2

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

3

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

4

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.

5

- 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.

6

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).

7

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)

UML Packages xUML Classes x x

UML DataTypes x x

can have nested

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

Modelica package xModelica model / block x x

Modelica connector / record / type x x

can have nested

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.

8

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.

9

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

10

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)

11

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

12

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

13

- 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.

14

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

15

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)

16

Figure 15: Un-apply the Standard profile

2.9.1 Apply the ModelicaML Profile

17

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

18

Figure 18: Create a Package

o Create new Class inside the Package

Figure 19: Create a Class

- Apply a stereotype to the Class

19

Figure 20: Apply a stereotype to the Class

- The result should be like in the screenshot below

20

Figure 21: Applied stereotype

2.9.2 Import ModelicaML Primitive Types You need to import the primitive types defined in ModelicaML.

21

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

22

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

23

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

24

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

25

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.

26

Figure 33: Generated Modelica code

27

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