Information on model transformations

doc/transformations.rst

@@ -1,12 +1,39 @@
 Model transformations
 =====================
 
-Explain model transformations
+A next step in the Modelverse is the use of model transformations.
+Model transformations are implemented using RAMification, and are therefore also modelled explicitly.
+As such, all previous modelling concepts are again useful.
 
 Specification
 -------------
 
-Explain how to specify a model transformation, with a drawn out example.
+To create a model transformation, users must specify a set of source metamodels and target metamodels.
+The model transformation will afterwards get a signature of these models.
+To create a simple Petri Net simulation transformation, we use the operation *transformation_add_MT* as follows::
+
+    >>> transformation_add_MT({"PN": "PetriNets"}, {"PN": "PetriNets"}, "pn_simulate", open("pn_simulate.mvc", "r").read())
+
+The first dictionary we pass, is the input dictionary: it specifies the name the model elements will get in the LHS, and the expected type of them.
+Similarly, the output dictionary specifies the name of output elements and their types.
+The actual metamodel in which the model transformation executes is defined as the merger of the keys in both the input and output dictionary.
+
+Note that in the transformation, all types are renamed by prepending the tag of their signature.
+For example, all types in the previous model transformation will be renamed by prepending *"PN/"* (e.g., *PN/Place*, *PN/P2T*).
+
+All types are renamed, in order to make multiple inputs with the same type possible.
+For example, when combining two models, both of the same type, but one of them being the *master*, it is possible to do the following::
+
+    >>> transformation_add_MT({"master": "PetriNets", "slave": "PetriNets"}, {"result": "PetriNets"}, "pn_merge", open("pn_merge.mvc", "r").read())
+
+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 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.
+
+We will now continue on how to specify a model transformation through modelling.
 
 RAMification
 ^^^^^^^^^^^^
@@ -14,6 +41,34 @@ RAMification
 Explain how RAMification works and what it does.
 Specifically, which attributes does it add etc.
 
+Rule specification
+^^^^^^^^^^^^^^^^^^
+
+How to specify a rule
+
+Schedule
+^^^^^^^^
+
+Scheduling constructs
+
+Invocation
+----------
+
+The actual binding is only done later on, upon invocation, and goes as follows::
+
+    >>> transformation_execute_MT("pn_simulate", {"PN": "my_pn"}, {"PN": "my_pn"})
+
+In this case, the model transformation takes the model *my_pn* as input for the *pn_simulate* model transformation, and writes out the result in *my_pn*.
+As the output model matches the input model, the model transformation is effectively in-place.
+For out-place transformations, it is possible to specify a different output model, in which case the model is implicitly copied as well::
+
+    >>> transformation_execute_MT("pn_simulate", {"PN": "my_pn"}, {"PN": "my_simulated_pn"})
+
+Model transformation invocation has no effect on the original model in this case.
+Also, model transformations always happen on a copy of the original model.
+As such, it is also possible to restore the model to before the transformation.
+When a model transformation fails (i.e., the schedule ends in a *Failure*), no output models are written and the models are left untouched.
+
 Tracability links
 -----------------