Basic information written about model operations and their use (missing examples)

doc/operations.rst

@@ -1,24 +1,94 @@
+.. TODO include examples!!
+
 Operations
 ==========
 
-Describe the different types of operations
+While model transformations are in many tools considered to be the only types of operations on models, this is not necessarily the case in the Modelverse.
+Indeed, MPM advocates to use the most appropriate formalism, and, as model transformations are models themselves, this should also apply to specifying operations.
+As such, we extend the notion of model transformations to more general model operations.
+
+Model operations come in three types, depending on how they are ideally specified: model transformations, manual operations, and action language.
+In the remainder of this section, we will show all types, and what situation they are ideally suited for.
 
 Model Transformations
 ---------------------
 
-Link back to previous section
+When model matching and rewriting is involved, model transformations are clearly the ideal solution in most cases.
+The LHS is used to match elements in the host model, and the RHS is put in its place.
+As this could also be combined with a visual concrete syntax, it could even become possible for domain experts to create a model transformation without too much programming knowledge.
 
-Manual Operations
------------------
+Nonetheless, model transformations are a completely different paradigm, based solely on matching and rewriting.
+Some operations have a long history in computer science, and have therefore efficient or simple procedural algorithms.
+For example, computing the reachability graph of a PetriNets instance can certainly be done with model transformations, but will be overly difficult.
+On the other hand, procedural algorithms are relatively easy (when implemented naively).
 
-Explain manual operations: do the merge and split automatically
+The functions on model transformations are exposed using the *transformation_add_MT* and *transformation_execute_MT* operations.
 
 Action Language
 ---------------
 
-Explain how to do things programmatically
+Doing operations in a procedural way is supported in the Modelverse through the use of action language models.
+As action language is explicitly modelled, we can create models consisting solely of action language.
+They are therefore similar to model transformations, which are also models, but only define a different operational semantics.
+Instead of having a model transformation interpreter apply the schedule and rules, we merely call the action language functions enclosed in the model.
+
+The functions on action language are exposed using the *transformation_add_AL* and *transformation_execute_AL* operations.
+Their signature is identical to that of model transformations.
+
+The action language model itself requires a single *main* function, or it will execute the topmost function in the specified code.
+This function should take a single argument, being the merged model.
+From this model, the merged metamodel can easily be accessed.
+As with model transformations, the names of model entities are prefixed with their tags.
+
+Manual Operations
+-----------------
+
+Some other operations simply cannot be automated.
+For example, translating natural language descriptions of requirements of a model to the actual model is not something that can be automated, at least for now.
+The only solution, therefore, is to do these operations manually, thereby requiring user intervention.
+
+Even though they are manual, they can still be partially automated: merging and splitting based on tags can still be done before and after the manual operation.
+
+The functions on action language are exposed using the *transformation_add_MANUAL* and *transformation_execute_MANUAL* operations.
+Their signature is identical to that of model transformations, except that now there is no model to provide with the *transformation_add_MANUAL*.
+As with model transformations, the names of model entities are prefixed with their tags.
+
+Execution callbacks
+^^^^^^^^^^^^^^^^^^^
+
+As specified before, manual operations require user intervention during execution.
+The *transformation_execute_MANUAL* operation is therefore not a simple function that is executed and returns after some time: user input must be given.
+For this, an additional argument is provided as callback function.
+This callback function can be any sequence of operations again, such that it is possible to create or alter the model.
+Certainly, if it were to be possible automatically, we could have done it that way in the Modelverse.
+Therefore, the callback function can do much more than just these calls: all expressive power of Python is available, such as the possibility for user input (*raw_input()*).
+Based on this, the callback can define whatever structure is desired, possibly even going as far as starting up a dialog box or using a graphical interface.
+As before, the first parameter of the operations (*model_name*) should be set to *None*.
+
+Manual operations are not the only operations which might require user input.
+Model transformations and action language can just as well query the users for input.
+This is done the same way: by defining a callback function.
+Note that they are slightly different, in the sense that their callback functions have no option to call any of the Modelverse operations.
+Instead, the callback is invoked when the action language, either standalone or in the actions/constraints of model transformations, executes the *input* or *output* operations.
+The return value of the callback is made available to the action language (fragment) when it executes the *input* operations, and can be a single primitive type, or a list.
+In case it is a list, the primitive types are offered to the action language individually, requiring multiple *input* calls.
 
 Process Model
 -------------
 
-Explain how process model can combine different operations and manage data flow as well as control flow
+A next logical step is the chaining of these various operations, or activities.
+For this reason, the FTG+PM was previously developed.
+The Modelverse provides both modelling and enactment support for the FTG+PM.
+
+When modelling, the FTG+PM is just a metamodel like all others, and instances can easily be created of it.
+There are notions of activities, decision nodes, forks, joins, and so on.
+Apart from control flow, an FTG+PM also specifies data flow: which models are used in this scope, and how are they interrelated.
+Indeed, we could define the sequence of activities to execute, but we still need information on what are the input models of the various activities.
+For example, the same activity might execute multiple times, but each time on different input models and generating different output models.
+
+When enacting, the FTG+PM is executed by starting at the initial node.
+The first element it points to is executed, thereby branching, deciding, or executing an activity.
+Due to the branching, it is possible for multiple activities to be scheduled concurrently.
+As for now, the Modelverse sequentializes the various activities internally.
+When executing an activity, which can either be a model transformation, action language, or manual operation, the operation is executed with the required operation.
+More information on enactment was previously given.

doc/transformations.rst

@@ -43,16 +43,9 @@ In RAMification, the original metamodel is Relaxed, Augmented, and Modified.
 As such, the new metamodel can be used to define model transformation rules.
 
 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.
+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.
 
 RAMification happens in the background in the Modelverse.
 Users can, of course, open the RAMified metamodel just like any other metamodel.
@@ -126,9 +119,7 @@ Some remarks, specifically in relation to users of AToMPM:
 2. Unspecified 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.
+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.
 
 Schedule
 ^^^^^^^^