Browse Source

Updated section on transformations

Yentl Van Tendeloo 5 years ago
parent
commit
d81b82b860
1 changed files with 20 additions and 19 deletions
  1. 20 19
      doc/transformations.rst

+ 20 - 19
doc/transformations.rst

@@ -29,7 +29,7 @@ For example, when combining two models, both of the same type, but one of them b
 In this case, the LHS can match specifically for elements of the master (e.g., *master/Place*).
 
 The output dictionary is interesting as well: multiple output models are possible, and these are based on the tags as well.
-When model elements do not match any tags, they are ignored.
+When model elements do not match any tags, an exception is raised.
 When a model element matches a tag, it is put into that specific output model.
 More information on tags can be found in the *invocation* subsection.
 
@@ -46,7 +46,7 @@ This consists of the following three phases:
 
 1. The metamodel is **Relaxed**, such that lower cardinalities are no longer applied. Similarly, constraints are removed, and abstract entities can be instantiated. This is done because in model transformations, we only use a specific part of the metamodel.
 2. The metamodel is **Augmented**, such that new attributes and concepts are added. These new attributes are *label* and *constraint* in the LHS, and *label* and *action* in the right hand side. New concepts that are added, are the LHS and RHS entity. These are the containers for all elements of the LHS and the RHS, respectively.
-3. The metamodel is **Modified**, such that existing attributes are renamed and their types are altered. All attributes have to become constraints on that specific attribute in the LHS, and actions for the new value in the RHS. For example, the *tokens* attribute of a place becomes a constraint function (returning True or False), instead of an attribute of type integer.
+3. The metamodel is **Modified**, such that existing attributes are renamed and their types are altered. All attributes have to become constraints on that specific attribute in the LHS (name prepended with *constraint_*), and actions for the new value in the RHS (name prepended with *value_*). For example, the *tokens* attribute of a place becomes a constraint function (returning True or False), instead of an attribute of type integer.
 
 RAMification happens in the background in the Modelverse.
 Users can, of course, open the RAMified metamodel just like any other metamodel.
@@ -116,8 +116,8 @@ An example specification is shown below, which will copy the highest number of t
     }
 
 Some remarks, specifically in relation to users of AToMPM:
-1. Unspecified attributes in the LHS are always fulfilled (i.e., *result = True* in AToMPM notation).
-2. Unspecified attributes in the RHS are always copied as-is (i.e., *result = get_attr()* in AToMPM notation).
+1. Unspecified constraint attributes in the LHS are always fulfilled (i.e., *result = True* in AToMPM notation).
+2. Unspecified value attributes in the RHS are always copied as-is (i.e., *result = get_attr()* in AToMPM notation).
 3. Just like in AToMPM, labels are strings and can be used as such.
 4. While *mapping* contains a mapping for the labels to their elements in the host model, all elements of the host model an technically be used, even those not occuring in the LHS.
 5. During rewriting, it is possible to access the values of all elements of the host model, including those matched before in the LHS. Newly created elements in the RHS can of course not be referenced. Elements removed in the RHS can no longer be referenced either, though this will likely be updated in future versions.
@@ -190,41 +190,42 @@ Querying
 Similarly, it is often easy to forget which transformations are supported between a source and target metamodel.
 Therefore the *transformation_between* function can be used to query for all transformations that take a certain metamodel as input, and generate another metamodel as output::
 
-    >>> transformation_between("formalisms/PetriNets", "formalisms/PetriNets")
+    >>> transformation_between({"PN": "formalisms/PetriNets"}, {"PN": "formalisms/PetriNets"})
     ["models/pn_optimize", "models/pn_simulate", "models/pn_rename", "models/pn_combine"]
 
-    >>> transformation_between("formalisms/PetriNets", "formalisms/ReachabilityGraph")
+    >>> transformation_between({"PN": "formalisms/PetriNets"}, {"Reachability": "formalisms/ReachabilityGraph"})
     ["models/pn_analyze"]
 
 Note that this operation does not take into account other input or output metamodels::
 
-    >>> transformation_between("formalisms/PetriNets", "formalisms/Boolean")
+    >>> transformation_between({"PN": "formalisms/PetriNets"}, {"result": "formalisms/Boolean"})
     ["models/analyze_query", "models/is_safe", "models/conforms"]
 
-Tracability links
------------------
+Traceability links
+------------------
 
 As the metamodels are merged together into a single metamodel, models can contain elements from both.
 It is often useful to create some kind of link between these different metamodels.
 However, a simple merge does not allow for this, as the different metamodels form their own "islands".
-To create links between them, for example for matching or tracability, we need tracability links.
+To create links between them, for example for matching or traceability, we need traceability links.
 
 Definition
 ^^^^^^^^^^
 
-Tracability links, or links between different metamodels, can be created by passing a callback function.
+Traceability links, or links between different metamodels, can be created by passing a callback function.
 As the intermediate merged metamodels are not designed to be modified by users (though they can be), the callback operation is executed on the merged metamodel.
 Only after the changes in the callback function are applied, is the metamodel RAMified.
 
-This callback function takes a series of operations, just like all previous operations.
-The only exception is that the model is to be put to *None*, as changes to other models are not allowed in this context.
-For example, to define a tracability link between a *PetriNets/Transition* and *ReachabilityGraph/Transition*, we can do the following when defining the transformation::
+This callback function takes a single parameter *model*, which is the intermediate model on which operations are to be done.
+In the function, the usual modelling operations can be done, and they should happen on the passed model.
+While technically other operations are possible as well, this use case is not supported and untested.
+For example, to define a traceability link between a *PetriNets/Transition* and *ReachabilityGraph/Transition*, we can do the following when defining the transformation::
 
-    >>> def callback():
-    ...     instantiate(None, "Association", edge=("PetriNets/Transition", "ReachabilityGraph/Transition"), ID="PN2RG_Transition")
+    >>> def callback(model):
+    ...     instantiate(model, "Association", edge=("PetriNets/Transition", "ReachabilityGraph/Transition"), ID="PN2RG_Transition")
     >>> transformation_add_MT({"PetriNets": "formalisms/PetriNets"}, {"ReachabilityGraph": "formalisms/ReachabilityGraph"}, "models/pn_analyse", open("models/pn_analyse.mvc", "r").read(), callback)
 
-As the forward slash (/) is already used to distinguish between the metamodel tag and the original entity, entities defined through a callback function should not contain this same symbol.
+As the forward slash (/) is already used to distinguish between the metamodel tag and the original entity, entities defined through a callback function should not contain this same symbol in their ID.
 
 Use
 ^^^
@@ -253,9 +254,9 @@ This new entity can be used in the rules like any other, either in the LHS, RHS,
     }
 
 This is in contrast to AToMPM, where there was a notion of *GenericLink*, which could connect all entities, but was not defined at the domain-specific level.
-In the Modelverse, these tracability links are also modelled explicitly, such that their use is also governed by the usual conformance rules.
+In the Modelverse, these traceability links are also modelled explicitly, such that their use is also governed by the usual conformance rules.
 
 When the transformation is finished, all entities in the model are split across the multiple tagged metamodels.
 Tracability links, not belonging to any of them, are stored in a separate model, typed by the *Tracability* metamodel.
-Future model merge operations can pass this tracability model, in order to restore the original model that was split.
+Future model merge operations can pass this traceability model, in order to restore the original model that was split.
 This is mostly useful to developers of the Modelverse, and is not elaborated here.