Browse Source

First documentation for modeller

Yentl Van Tendeloo 6 years ago
parent
commit
6198ef3045
4 changed files with 178 additions and 19 deletions
  1. 54 7
      doc/interaction.rst
  2. 6 0
      doc/modeller.rst
  3. 102 3
      doc/modelling.rst
  4. 16 9
      doc/users.rst

+ 54 - 7
doc/interaction.rst

@@ -30,18 +30,65 @@ Only developers will ever have to directly interface with the Modelverse Kernel.
 Modelverse Interface (MvI)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The Modelverse Interface (MvI) ...
+The Modelverse Interface (MvI) is the actual interface used by most users of the Modelverse.
+It provides any type of interface, whether it be graphical, textual, or any other interface.
+While this is the component that users interact with, there should be no (meta-)modelling knowledge whatsoever in this part, as it is only responsible for providing a user-friendly interface to the Modelverse.
+This component can make use of the provided wrapper, which does the binding with the Modelverse.
 
 Necessary scripts
 -----------------
 
-Explain the different scripts and how they can be used
-Briefly show the *run_tests.py* and *run_local_modelverse.py*
-Also *prompt.py*
+The Modelverse consists of a set of scripts.
+For most users, there are only three relevant scripts, none of them taking parameters:
+
+1. *run_tests.py*, which runs all tests.
+2. *run_local_modelverse.py*, which starts up a local Modelverse server, combining the MvS and MvK.
+3. *prompt.py*, which connects to the local Modelverse and provides a minimal raw interface.
 
 Wrapper
 -------
 
-We explain the simple Python wrapper
-Other wrappers can be defined quite easily due to the Modelverse architecture
-Later is a full overview of the wrapper, we now introduce it piece by piece in Python
+In addition to these scripts, we provide a simple Python-based wrapper for the Modelverse.
+As the Modelverse can run as a service, wrappers can be created in any language that supports XML/HTTPRequests.
+By default, a Python wrapper is provided, which is discussed in this documentation.
+This Python wrapper was used by a variety of MvI implementations supported today.
+Tools can include all Modelverse operations merely by including the *modelverse.py* file from the *wrappers* folder.
+
+The wrapper provides all necessary (meta-)modelling operations that can be used by the MvI.
+As the Modelverse is independent of its (visual/textual) user interface, we only discuss the Modelverse wrapper in this documentation.
+The wrapper functions are explained through the use of examples, in a tutorial-like fashion.
+A full overview of all wrapper functions is also provided at the end of the documentation.
+
+Initializing the Modelverse
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Before we start, we must connect to the Modelverse.
+This can be done by executing the operation *init*::
+
+    >>> init("http://modelverse.uantwerpen.be")
+
+This assumes that there is a Modelverse running at the specified address.
+It is also possible to work fully locally.
+For that, you must start up a Modelverse at your own system by invoking the command::
+
+    python scripts/run_local_modelverse.py
+
+Afterwards, connect to the local Modelverse through the usual *init* operation.
+Note that, for a local Modelverse, the init can be left empty::
+
+    >>> init()
+
+Logging in
+^^^^^^^^^^
+
+Now that we are connected to the Modelverse, we need to log in.
+Without logging in, the Modelverse has no clue which operations are permitted, and which models are readable, or even writable.
+To log in, use the *login* operation::
+
+    >>> login("yentl", "secret password")
+
+The operation will succeed if it terminates normally, and throw a Python exception otherwise.
+When the username does not exist yet, it is created upon invocation.
+The provided password can be used in subsequent invocations of the Modelverse to login as this user again.
+
+If this command finished successfully, the Modelverse is ready to be used.

+ 6 - 0
doc/modeller.rst

@@ -1,6 +1,11 @@
 Using the Modelverse as a Modeller
 ==================================
 
+The first category of users that we consider, is that of a modeller.
+Whatever category a user falls in, this section is useful as it introduces the basic concepts of modelling using the Modelverse.
+
+In this section, we introduce users to modelling in the Modelverse, basic modelling permissions, and process enactment.
+
 .. toctree::
    :maxdepth: 2
 
@@ -8,3 +13,4 @@ Using the Modelverse as a Modeller
    Permission system <permissions>
    Action Langugage <actionlanguage>
    Model Langugage <modeller_modellanguage>
+   Process Enactment <process_enactment>

+ 102 - 3
doc/modelling.rst

@@ -1,14 +1,113 @@
 Modelling
 =========
 
-explain use of modelling and assume that a metamodel exists
+Modelling is the core activity in the Modelverse.
+A model is based on a meta-model, or a language, which, for the sake of this tutorial, assume to exist.
+Throughout this tutorial, we will focus on how to instantiate a simple Petri Net model.
+We assume that our language has a notion of *Place*, *Transition*, *P2T* arc, and *T2P* arc.
+The *Place* has a *name* and *tokens*, the *Transition* has a *name*.
+Both the *P2T* and *T2P*"arcs have a *weight*.
+This information is stored in the metamodel, which we will define later on.
+For now, assume that the metamodel is stored in the Modelverse using the name *PetriNets*.
 
 Creating a model
 ----------------
 
-Example of creating a simple model
+Creating a new instance of PetriNets is simple, and can be done using the *model_add* operation of the wrapper::
+
+    >>> model_add("my_pn", "PetriNets")
+
+The first parameter of the operation indicates the name that we would like to give to our newly created model.
+This name is available to all users, and is therefore a unique identifier.
+The second parameter is the metamodel that we want to use to conform to.
+The value needs to be a name that is available in the Modelverse, and readable to the current user.
+
+To get a list of currently available models, users can query the Modelverse with the *model_list* operation::
+
+    >>> model_list()
+    [("PetriNets", "SimpleClassDiagrams"), ("SimpleClassDiagrams", "SimpleClassDiagrams"), ("ProcessModel", "SimpleClassDiagrams"), ...]
+
+This list contains the various models, and the metamodel of these models.
+Note that this operation does not specify anything about the permissions of the supplied models.
 
 Modifying a model
 -----------------
 
-Example of basic modelling operations on this new model
+Now that we have created our model, we can start modifying it.
+To do so, we have access to several operations offered by the Modelverse.
+We categorize them by their effects on the Modelverse: create, read, or delete.
+Create and delete operations are only allowed when the user has write permission to the model, which users have by default on their own models.
+
+Create
+^^^^^^
+
+1. *instantiate* creates a new instance in the model, for example a new PetriNet place::
+
+        >>> instantiate("my_pn", "Place")
+        __12345
+
+    The operation requires the model on which we are working, and the type of the element you want to instantiate.
+    When successful, the operation returns the identifier that can be used in future operations.
+    This identifier has no value within the model, and should only be used as a handle to that specific model element.
+
+    When instantiating an edge, the optional *edge* parameter must be passed with the identifiers to connect::
+        
+        >>> instantiate("my_pn", "Place")
+        p1
+        >>> instantiate("my_pn", "Transition")
+        t1
+        >>> instantiate("my_pn", "P2T", edge=("p1", "t1"))
+        p2t1
+
+2. *attr_assign* assigns attributes of a specific model element.
+   For example, it specifies the name and number of tokens of our PetriNet place::
+   
+        >>> instantiate("my_pn", "Place")
+        p1
+        >>> attr_assign("my_pn", "p1", "name", "place 1")
+        >>> attr_assign("my_pn", "p1", "tokens", 2)
+
+   The value of the attribute can be any simple primitive: string, integer, float, or boolean.
+   When the attribute already exists, its value is overwritten.
+   If it doesn't exist, it is created.
+
+Read
+^^^^
+
+1. *read* reads out basic information about a queried element, such as its type and the source and target (if it is an edge)::
+
+        >>> instantiate("my_pn", "Place")
+        p1
+        >>> read("my_pn", "p1")
+        ("Place, None)
+        >>> instantiate("my_pn", "Transition")
+        t1
+        >>> instantiate("my_pn", "P2T", edge=("p1", "t1"))
+        p2t1
+        >>> read("my_pn", "p2t1")
+        ("P2T", ("p1", "t1"))
+
+2. *read_attrs* reads out the attributes of a specific element, in a dictionary form.
+   This operation can be used to read out, for example, the number of tokens of a specific place::
+
+        >>> instantiate("my_pn", "Place")
+        p1
+        >>> attr_assign("my_pn", "p1", "name", "place 1")
+        >>> attr_assign("my_pn", "p1", "tokens", 2)
+        >>> read_attrs("my_pn", "p1")
+        {"name": "place 1", "tokens": 2}
+   
+types
+element_list_nice
+read_outgoing
+read_incoming
+read_association_source
+read_association_destination
+connections_between
+all_instances
+
+Delete
+^^^^^^
+
+delete_element
+attr_delete

+ 16 - 9
doc/users.rst

@@ -1,24 +1,31 @@
 Types of users
 ==============
 
-Identify three types of users
-The next one implies all previous ones due to required knowledge
-
-Add figure showing the hierarchy maybe?
+For the Modelverse, we identify three types of users.
+It is possible for users to switch between these three different types over time.
+The remainder of this documentation is split up based on these three types of users: modellers, language engineers, and developers.
+Due to the design of the Modelverse, language engineers must also know all about modelling: languages are created through modelling.
+Similarly, developers must know about all knowledge of the modeller and language engineer, as they must implement operations for them.
+Nonetheless, there is still a different focus and different requirements for their domain knowledge.
 
 Modeller
 --------
 
-Explain the job of the modeller
+The majority of the users of the Modelverse will fall in the category of modellers.
+These users make use of the languages provided by other users, by instantiating them.
+While this is likely the biggest category of users, they will mostly be abstracted from the Modelverse wrapper by their MvI.
+For modellers, the documentation is focused on instantiating existing languages and modifying models or executing processes on specific models.
 
 Language Engineer
 -----------------
 
-Explain the job of the language engineer
-Explain why this includes all knowledge of the modeller as well, though in a different domain
+Language engineers are the second category of users, who create language to be used by the modellers.
+Language engineering in the Modelverse is similar to modelling, as metamodels are models themselves.
 
 Developer
 ---------
 
-Explain the job of the developer
-Explain why this includes all knowledge of the modeller and language engineer as well, though in a different domain
+The final category of users is that of developer.
+Developers of the Modelverse will modify the internals of the Modelverse, but, as the Modelvers is explicitly modelled, this often takes the form of a modeller as well.
+Nonetheless, the various files are stored external to the Modelverse, and can be modified without the Modelverse.
+Similarly, some core languages are also included in the Modelverse, which requires developers to be familiar with language engineering.