GuideTutorialMarkedGraph

Tutorial: Make Marked Graph models executable with the GEMOC Studio

What is expected at the end of this tutorial

This tutorial aims at demonstrating the power of the GEMOC studio to define an executable semantics and provide graphical animation for a DSML. It relies of the marked graph language.

The following animation shows the expecting results of this tutorial: according to the fired transitions, tokens move from place to place.

Figure 1. Expected animation for Marked Graph models

Install the projects defining the Marked Graph AS and CS

The domain model is implemented with several EMF projects that you need to import into your workspace. A graphical editor defined with Sirius is also available to visualize and edit Marked Graph models.

Import the Marked Graph AS and CS

Download the provided archive containing the projects and unzip it. Then, with the GEMOC Studio, select import…​ / General / Existing Projects into Workspace and import all the projects from the archive file.

Abstract Syntax

Marked Graph is a kind of Petri net in which every place has exactly one incoming arc and exactly one outgoing arc. As a consequence, it a concurrent language (several transitions may be fired) and has no conflict.

The Domain Model, also called Abstract Syntax or Metamodel, defines :

• A marked graph as a set of places and transitions.

• Each Place has exactly one input transition and one output transition and a token count.

• A transition has several input places and several output places.

Figure 2. Abstract Syntax (Metamodel) of MarkedGraph

Concrete Syntax and Sample Model

The graphical concrete syntax draws places as circles and transitions as squares. Inputs and outputs of places and transitions are designated by arrows. The following picture shows the graphical representation of the Marked Graph model of wikipedia.

Here the graphical syntax of the wikipedia example using the view defined with Sirius.

Figure 3. Example of a Marked Graph model (from wikipedia)

Set up an xDSML project

In this section, we first create an xDSML project for MarkedGraph and initialize it with the provided Abstract Syntax (AS) and Concrete Syntax (CS).

Create an xDSML Project

Select an xDSML project (New > Project > GEMOC Project / new xDSML Project).

Figure 4. Create an xDSML Project

The first dialog of the wizard asks for the name of the project. Define it as org.gemoc.sample.markedgraph.xdsml.

Figure 5. Define the name of the project

Click on Next and define the name of the language (markedgraph).

Figure 6. Define the name of the language

Open xDSML View

A file project.xml has been created in the org.gemoc.sample.markedgraph.xdsml project.

Figure 7. Content of the xDSML Project

When opened, it provides the xDSML view which summarizes all the important resources used in an xDSML project (which are part of and managed by other projects). This view is a kind of control center to have quick access to the main resources of the project.

Figure 8. The xDSML Editor

Select the AS

In the "Domain Model" section, click on the "Browse" button to select the project defining the AS: org.gemoc.sample.markedgraph.model.

Figure 9. Browse to select the AS project

Then, select the "Genmodel URI".

Figure 10. Browse to select the genmodel resource

Finally, select the "Root container model element" thanks to the "Select" buttons.

Figure 11. Browse to select the root container

Select the Graphical Editor

The Graphical Editor defines a graphical concrete syntax which is user-friendly to view and edit a model.

In the "Concrete syntax definition / Graphical editor" of the project.xdsml editor, click on "Browse" to select the "org.gemoc.markedgraph.design" project.

Figure 12. Select Sirius graphical editor

Define the Execution Semantics

A transition can be fired if there is at least one token in every of each input place. When fired, one token is removed from each of its input places and one token is added to each of its output places. Several transitions can be fired as the same time.

Defining the execution semantics consists in implementing the previous behavior. In the GEMOC approach, it is split in different concerns:

• The definition of Execution Data (ED) like the runtime count of tokens in a place and Execution Functions (EF) like fire a transition. ED and EF constitute the DSA.

• The definition of the model of concurrency as a set of events and constraints on these events. It is the MoCC concern that is defined in a DSE project (using ECL, Event Constraint Language) possibly completed with MoCCML projects to define libraries of constraints.

• The mapping between the DSA and the MoCC.

In the current version of the GEMOC studio, the MoCC and the mapping are tightly coupled and described in ECL (Event Constraint Language).

Define DSA

During execution of a MarkedGraph, the number of tokens of a place has to be recorded and changed according to the fired transitions. Thus, we have to manage an execution data (ED) called runtimeTokenCount and an execution function (EF) on Transition called fire(). Furthermore, the runtimeTokenCount of each place must be initialized at the start of the execution. It is the purpose of the EF called initialize() on the MarkedGraph element.

The DSA of Marked Graph is composed of :

• one ED called runtimeTokenCount defined on Place . It represents the number of token in a place when the model is executed.

• one EF called initialize() defined on MarkedGraph. It initializes the runtime token count of each place with the initial token count.

• one ED called fire() on Transition. It to remove one token from each of its input places and add one token to all its output places.

Extend the AS with ED and EF

At the moment, we need to complete the AS (markedgraph.ecore) with the ED and EF. In the next release of the GEMOC Studio this steps will disappear and extended the AS will be done automatically thanks to Melange

Add the 'runtimeTokenCount' ED on Place, 'fire()' on Transition and 'initialize()' on MarkedGraph.

Figure 13. Abstract Syntax of MarkedGraph extended with Execution Data (ED) and Execution Functions (EF)

Create the DSA Project

Click on K3 project in the project.xdml editor (Behavioral definition / DSA definition). The wizard to create of new Kermeta 3 project is launched with the name of the project initialized (k3dsa is the last name). Click "Finish". The project has been created.

Figure 14. Create a K3 Project

Implement the DSA

Click again on K3 project to open markedgraph.xtend. It has been initialized with a template that can be discarded and replaced with the following text.

link:MarkedGraph/markedgraph.xtend[role=include]

Figure 15. Definition of the DSA (ED and EF)

Define DSE

The purpose of the DSE project is to define events (called DSE) on AS elements that will trigger EF calls when they occurs. Furthermore, constraints can be defined on these events to ensure they occur in the right order.

Create the DSE Project

To create the DSE Project, click on the "ECL Project" in the project.xdsml editor ("Behavior definition / DSE definition"). Check that the name is org.gemoc.sample.markedgraph.dse.

Figure 16. Create a DSE Project

Click "finish" and the project is created.

Click on "ECL Project" to edit the "markedgraph.ecl" file and replace its content with the following:

Figure 17. Template of the ECL file

Define DSE

This step has three main purposes:

• First, it specifies DSE in the context of metaclasses of the AS.

• Then, it links them to EF form DSA --- when a DSE will occurs the associated EF will be executed.

• Finally, it defines constraints on the DSE to rule the possible scheduling. Constraints generally rely on relations which are defined in the MoCC.

Note	Please notice that, as often, DSE are defined at the language level, but at runtime they are instantiated as MSE on each object instance of the metaclasse they are defined on. In the same way, constraints apply to the MSE.

Replace the content of the ECL file with the following code:

The file markedgraph.ecl

link:MarkedGraph/markedgraph.ecl[role=include]

Figure 18. Definition of the DSE (events and constraints)

TODO: Give some rationals on the relation and their instancitions. In particular the delay.

What should be explained?

• The main principles (we can fire as much transition has the initial token count of a place, thus a delayed is introduce)

• We want to ensure that one init is done before any fire (and only once)

Define Animation Viewpoint

During the execution of a Marked Graph model, we want to visualize :

• the number of tokens in any place: the runtime token count will be printed in the circle of one place.

• the firable transitions: they will be drawn in green.

As the animation view is close to the graphical concrete syntax, we extend the existing diagram description.

First, we will define a graphical representation based on the graphical Marked Graph syntax to the wizard called "Create GEMOC debug representation", then we will add a layer to describe the graphical animation of a Marked Graph model.

Create a debug representation (as an extension of the graphical editor viewpoint)

Run the wizard

Do New > Other / Create GEMOC debug representation to run the wizard.

Figure 19. Create GEMOC debug representation wizard

On the first screen of the wizad, select "Extends an existing diagram description".

Figure 20. Select "Extends an existing diagram description"

Select the viewpoint to extend "MarkedGraph diagram".

Figure 21. Select the viewpoint to extend

Finally, we can fill in the Project Name in which the newly creating viewpoint file will take place (org.gemoc.sample.markedgraph.animation), the name of the viewpoint file (markedgraph-animation.odesign), the viewpoint name (MarkedGraphViewpoint) and the diagram name (MarkedGraph).

Figure 22. Information of the animation viewpoint

The last screen allows to choose the name of the layer to be created. Debug is a good name.

Once the Finish button is pressed, the project is created.

Open the markedgraph-animation.odesign

Open the markedgraph-animation.odesign file and develop its content.

TODO: explain its contents.

Load markedgraph.odesign as a resource.

To be able to complete the definition of the odesign file, we first need to load the existing markedgraph.odesign as a resource :

• Right click in the markedgraph.odesign editor.

• select Load Resource…​.

• Select Browse workspace…​

• Select markedgraph.odesign in the org.gemoc.sample.markedgraph.design project

• Click OK

• Click OK

Add markedgraph.ecore to the metamodels

• Select "Diagram Extension MarkedGraph" element.

• In the properties view, select metamodels.

• Click on "Add from workspace".

• Select "markedgraph.ecore" (unfold the project structure)

• Click OK

Complete the debug representation

On the "Mapping Based Decoration Enabled breakpoint" and "Mapping Based Decoration Disabled breakpoint", select the "Place" and "Transition" element.

The debug view will show a symbol on the Place and Transition to show whether the corresponding breakpoint is enabled or disabled.

Complete the dependencies of the project

• Open the plugin.xml file of the project.

• Select the dependencies tab.

• Click "Add…​" in the "Required Plug-ins" area.

• Select "org.gemoc.gemoc_language_workbench.extensions.sirius"

• Click OK

• Save the plugin.xml resource.

Set the animation viewpoint in project.xml

In the xDSML editor, we can select the animation viewpoint by selecting the newly created project (org.gemoc.sample.markedgraph.animation)

Create an animation representation

After the debug presentation has been defined, we can complete it to add an animation layer.

TODO: Explain…​

XXX: In Which eclipse?

TODO: The aird has to be provided!

Add a link to a tutorial for Sirius Animator.

Animate a Model

The executable MarkedGraph Language is now defined. We can use the GEMOC Modeling Workbench to execute MarkedGraph models.

Launch the Modelling WorkBench

Launch the Modeling Workbench by running a new Eclipse: right click, select "run as / Eclipse Application". The new eclipse is the Modeling Workbench.

Import the project with a sample model

Import the modeling project markedgraph.sample in the Modeling Workbench (Import / General / Existing project into Workspace).

Create a Launch Configuration

Create a Run Configuration: right click on the model and select "Run As…​ > Run Configurations". Create a new "Gemoc eXecutable Model" configuration. We can call it "gemoc" and fill in the fields: Model to execute: "first.automata", xDSML: "markedgraph".

Change the "Decider" to "Step by step user decider" (the user will decide which is the next step to execute).

Start the model

We can now run the "gemoc" configuration. The graphical representation is opened, the VCD is created, etc.

TODO: Give some explanations.

Select a logical step

From the timeline view, select the step to execute.

TODO: To complete…​