Browse Source

First draft of internal model representation in documentation

Yentl Van Tendeloo 3 years ago
parent
commit
b051d3d902
1 changed files with 30 additions and 1 deletions
  1. 30 1
      doc/model.rst

+ 30 - 1
doc/model.rst

@@ -1,4 +1,33 @@
 Model representation
 ====================
 
-Documents the internal model representation and provides remarks.
+The internal structure of models is normally not exposed to modellers and language engineers, although this is necessary to operate on models.
+For example in the context of activities, there might be a need to operate on the model structure directly, although this should rarely be necessary.
+In essence, a model is stored as a dictionary containing at least three entries: *model*, *type_mapping*, and *metamodel*.
+We describe each next.
+
+Model
+-----
+
+The model entry is again a dictionary, but this time for the elements of the model.
+The identifier of each element is used as the key in the dictionary, with the value being the physical node or edge in the graph representing the data.
+As such, to resolve the actual node (e.g., to read out the value), the model dictionary must be read as a dictionary.
+Note that all parts of the model must have such a dictionary link, as otherwise the model is only partially stored, which could result in errors.
+
+Type Mapping
+------------
+
+The type mapping is again a model, although this one stores the type mapping.
+The model has an element with ID *root*, which can be accessed as if it were a dictionary.
+This dictionary has keys equal to the elements of the model, and the value for each key represents the ID in the metamodel.
+Note that modifications to the type mapping should never be done directly, as the dictionary is itself completely contained in a model.
+For that reason, specific typing related operations are provided.
+The type mapping model can also be opened as if it were a normal model, conforming to the *formalisms/TypeMapping* metamodel.
+In this context, however, only the dictionary part is required and thus no metamodel is loaded for performance reasons.
+
+Metamodel
+---------
+
+The metamodel in the dictionary merely links to another model, which is itself again a dictionary containing at least the *model*, *type_mapping*, and *metamodel* keys.
+This keeps going on, until eventually the *metamodel* link is actually a reference to the exact same dictionary.
+This thereby enables the meta-circular level.