GuideTutorialMarkedGraph
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.
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.
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.
Here is the archive containing all the projects that will be created during this tutorial.
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.
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 (using a graphical syntax defined using Sirius).
In this section, we first create an xDSML project for MarkedGraph and initialize it with the provided Abstract Syntax (AS) and Concrete Syntax (CS).
Select an xDSML project (New > Project > GEMOC Project / new GEMOC Concurrent xDSML Project).
The first dialog of the wizard asks for the name of the project. Define it as org.gemoc.sample.markedgraph.xdsml.
Click on Next and define the name of the language (markedgraph).
A file project.xml has been created in the org.gemoc.sample.markedgraph.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.
In the "Domain Model" section, click on the "Browse" button to select the project defining the AS: org.gemoc.sample.markedgraph.model.
Then, select the "Genmodel URI".
Finally, select the "Root container model element" thanks to the "Select" buttons.
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.
A transition can be fired if there is at least one token in every of each input place. When a transition is 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).
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.
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 step replaced by the use of Melange to automatically extend the AS with ED and EF.
The ED and and EF are already defined on the provided metamodel. Thus, there is no need to add the 'runtimeTokenCount' ED on Place, 'fire()' on Transition and 'initialize()' on MarkedGraph.
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.
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]
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 define when they may occur.
-
Click on the "ECL Project" in the project.xdsml editor ("Behavior definition / DSE definition").
-
Check that the name is org.gemoc.sample.markedgraph.dse.
-
Click "Next". All fields have been correctly initialized.
-
Click "finish" and the project is created.
-
Click on "ECL Project" to view the "markedgraph.ecl".
Replace the content of the ECL file with the following code (explanations on this code are given bellow):
link:MarkedGraph/markedgraph.ecl[role=include]
This step has three main purposes:
-
First, it specifies DSE in the context of metaclasses of the AS. For Marked Graph xDSML, we identify 2 DSE:
-
fireIt: defined in the context of a Transition
-
initIt: defined in the context of a MarkedGraph
-
-
Then, it links them to EF from DSA --- when a DSE will occur the associated EF will be executed.
-
fireIt is linked to the EF 'fire' of Transition
-
initIt is linked to the EF 'initialize' of MarkedGraph
-
-
Finally, it defines constraints on the DSE to rule the possible scheduling. Constraints generally rely on relations which are defined in MoCC libraries. Here constraints are expressed in CCSL and only relies on relations and expression from the CCSL core library.
-
A first constraint applies on the fireIt events. It is depends on the number of token in a place. Indeed, if there is no tokens, then the fireIt of the output transition can only occur after the fireIt event of the input transition has occured. It is expressed by the first invariant defined in the context of a Place. If there is some tokens in a place, then the fireIt event of the output transition may occur as many times as there is tokens in this place. After, it will only occur when the fireIt on the input transition of the place has occured. It is expressed using the DelayFor expression in the second envariant of Place.
-
Two other constraints are defined in the context of the MarkedGraph element. The first one expresses that the first initIt event must occur before any fireIt event. The second one expresses that the initIt event can occur only one time.
-
|
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. For example, there will be one fireIt MSE for each Transition element of MarkedGraph model. For the wikipedia example, there will a fireIt event for transitions t1, t2, t3 and t4. In the same way, constraints apply to the MSE. |
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.
Tun the wizard with New > Other / Create GEMOC debug representation.
On the first screen of the wizad, select "Extends an existing diagram description".
Select the viewpoint to extend "MarkedGraph diagram".
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).
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 file and develop its content.
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 to select Load Resource….
-
Select Browse workspace…
-
Select markedgraph.odesign in the org.gemoc.sample.markedgraph.design project
-
Click OK
-
Click OK
-
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
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.
-
Open the plugin.xml file of the project.
-
Select the dependencies tab.
-
Click "Add…" in the "Required Plug-ins" area.
-
Select "org.gemoc.executionframework.extensions.sirius"
-
Click OK
-
Save the plugin.xml resource.
After the debug presentation has been defined, we can complete it to add an animation layer.
-
Right click on "Diagram extension MarkedGraph" to select New Diagram Element / Additional Layer.
-
Set its "id" to "Animation".
-
Right click on "Animation" to select "New Customization / Style Customizations".
-
Right click on "Style Customizations" to select "New Customization / Style Customization".
-
On "Style Customization", set the "Predicate Expression" to:
[self.eGet('inputs')->forAll(p | p.eGet('runtimeTokenCount').toString().toInteger() > 0) /] -
Right click on "Style Customization" to select "New Customization / Property Customization (by selection)"
-
For "Applied On" property, select "Square white".
-
For "Property Name", set "color" (completion is available with CTRL-SPACE)
-
For "Value Selction", set "light_green"
Perform the same action as above to set the background color of places to yellow.
-
Right click on "Style Customization" to select "New Customization / Property Customization (by expression)"
-
For "Applied On" property, select "Ellipse white".
-
For "Property Name", set "labelExpression" (completion is available with CTRL-SPACE)
-
For "Value Selction", set "feature:runtimeTokenCount"
-
Right click on "MarkedGraphViewpoint" to select "New Extension / Java Extension".
-
Set "Qualified Class Name" to "org.gemoc.sample.markedgraph.animation.services.MarkedgraphAnimationServices".
In the project, org.gemoc.sample.markedgraph.animation project, in src/org.gemoc.sample.markedgraph.animation.services, copy the MarkedgraphDebugServices.java file to MarkedgraphAnimationServices.java. Then, change AbstractGemocDebuggerServices to AbstractGemocAnimatorServices in its source code (two times: import and extends). Finally, change "Debug" to "Animation".
The executable MarkedGraph Language is now defined. We can use the GEMOC Modeling Workbench to execute MarkedGraph models.
First, we will create a run configuration. Select "run / run Configurations" Double click on "Eclipse Application" and change the name "New Configuration" into "Marked Graph Modeling Workbench". We can now click "Run" to start the new runtime Eclipse which indeed corresponds to the Modeling Workbench for Marked Graph.
Import the modeling project org.gemoc.sample.markedgraph.sample in the Modeling Workbench (Import / General / Existing project into Workspace). It contains the wikipedia.markedgraph file which corresponds to the Wikipedia example.
-
Select "Window / Open Perspective / Others…"
-
Select "Modeling" in the list.
-
Select Debug / Debug Configurations
-
Double click on "Gemoc Concurrent eXecutable Model"
-
Change the name of the new configuration to "run wikipedia example"
-
Browse to select the model to run (wikipedia.markedgraph)
-
Select its language (xDSML field): markedgraph
-
Browse to select the animator
-
Check that the "Decider" is set to "Step by step user decider" (the user will decide which well be the next step to execute).
-
Click on "Debug"
We can now run the "gemoc" configuration. It opens the different views related to the execution on an xDSML model:
-
Logical Steps (top left): the list of the logical steps that may be selected at this execution step.
-
Gemoc Engine Status (middle left): the list on the running GEMOC engines. The red button stops the selected engine.
-
Stimuli Manager (bottom left): the list of MSE.
-
VCD (top right): a graphical visualisation of the events manages by the MoCC (first ones correspond to the MSE).
-
Graphical visualization (middle right) of the model (with animation information)
-
Time Line (bottom middle): the logical steps available at each steps and the selected one.
-
Console: several consoles are available. The dispolayed one is the "Default MessaginSystem Console". There is one console the the main component of the Modeling Workbench.
The Logical Steps view, presents the possible steps, and for each step, the MSE that will occur if it is selected.
Double-click on a Logical Step to choose it. The corresponding MSE occur, they are visible on the VCD, and they trigger the associated execution functions which make the state of the model evolve.
Then, we can select a new logical step (here we selected the the logical step which fires the t2 transition).
To improve readability of the ECL file and also to favor capitalization and reuse of MoCC elements, it is possible (and encouraged) to define libraries. Those libraries looks like the predefined ones that we have already used like kernel.lib and CCSL.lib.
Using the GEMOC Studio, we start by defining a MoCCML project. In the xDSML view, we select Behavioral definition / MoCC definition library to create this new project.
We can then define in this project the following markedgraph.ccslLib file. TODO: To be corrected.
link:MarkedGraph/markedgraph.ccslLib[role=include]Sometimes, it may be easier to define the MoCC using automata. For example, we can see a place as something on which we can read a token (ont output transition reads one token) or we can write a token (one input transition writes one token). A token can only be read if there is at least one in the place. Initially, there is as much token in the place as in the initial token count of the place.
For explanations on how to use the MoCCML editor, please refer to the GEMOC manual.
We first define the declaration of a relation (placeReadWrite). Here after is its graphical representation. This relation is parameterized by the r clock (some one how wants to read a token), the w clock (someone how wants to write a token, and n the initial count of token in the place).
Then we can define this relation. Here after is the resulting automaton. The local variable count represent the number of tokens in this place. s0 is the initial state. The action on the transition from s0 to s initialize count with n (the parameter). The two reflexive transitions on s explain what happens when w or r occurs. The write transition is fired when w occurs and a token is assed in the place (count is incremented). The read transition is fired when r occurs. It removes a token and thus decrements count. A guard prevents the read transition to be fired if there is not at liste one token in the place (count >= one).
Here is the textual representation of this constraint automata.
link:MarkedGraph/markedgraph.moccml[role=include]