Basic Interaction
=================

As previously mentioned during the installation phase, the Modelverse is merely a collection of scripts.
We briefly present how the Modelverse is structured, and introduce the most important scripts for general use.
A more elaborate view on the architecture and the different scripts is only required for developers of the Modelverse.

Simplified Architecture
-----------------------

The Modelverse architecture consists of three core concepts, which will be referred to throughout the documentation.

Modelverse State (MvS)
^^^^^^^^^^^^^^^^^^^^^^

The Modelverse State (MvS) is the memory of the Modelverse, and contains all data pertaining to it.
This includes not only the different models created by the users, but also all metamodels, transformations, operations, but also all bootstrap files.
Furthermore, it includes all execution state of operations being executed in the Modelverse.
As such, the Modelverse State is the database of the Modelverse, which is the only component containing data.
Only developers will ever have to directly interface with the Modelverse State.

Modelverse Kernel (MvK)
^^^^^^^^^^^^^^^^^^^^^^^

The Modelverse Kernel (MvK) is the execution core of the Modelverse, and connects to the Modelverse State to fetch the instructions to execute.
All its execution information is stored in the MvS as well, and therefore it has to (theoretically) query the MvS for each and every instruction.
It merely consists of a set of model transformation rules which take the current state of the MvS, and does a transformation on it, similar to model transformations.
Only developers will ever have to directly interface with the Modelverse Kernel.

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 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 operations.
All meta-modelling related operations, such as model transformations, conformance checking, process enactment, and so on, are directly supported in the Modelverse and are available to the MvI through the use of the provided interface.
This component can make use of the provided wrapper, which does the binding with the Modelverse.

Necessary scripts
-----------------

The Modelverse consists of a set of scripts, stored in the *scripts* folder.
For most users, there are only two relevant scripts, none of them taking mandatory parameters:

1. *run_tests.py*, which runs all tests.
2. *run_local_modelverse.py*, which starts up the Modelverse server, combining the MvS and MvK at the same machine. An optional argument can be passed to run the Modelverse on a specific port (default: 8001).

While other scripts are present, they are mostly variations of the existing scripts or are only useful for Modelverse development purposes.

Wrapper
-------

Most often, the Modelverse is not used using the raw interface it provides by default.
Therefore, we additionally provide a simple Python-based wrapper for the Modelverse, which can be included in arbitrary scripts.
As the Modelverse can run as a service, wrappers can be created in any language that supports XML/HTTPRequests.
By default, a Python and SCCDXML wrapper are provided, of which the Python interface is discussed in this documentation.
The SCCDXML wrapper forms the basis for the Python wrapper and is similar in use.
These wrappers are used by a variety of MvI implementations supported today, and indeed themselves encompass an MvI if they are used directly by the user (e.g., in batch processing of models).
Tools can include all Modelverse operations merely by including the *modelverse.py* file from the *wrappers* folder (or including the SCCDXML model in *wrappers/classes/modelverse.xml*).
It is this interface that is used throughout this documentation, although other interfaces are highly similar.
Note that the Python interface is a synchronous (i.e., blocking) interface, and therefore not recommended for use in Graphical User Interfaces (GUI).
The SCCDXML wrapper is asynchronous and perfectly suited for use in GUIs.

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.
For an example use of the wrappers, we refer to the tests of the Modelverse (using all functionality of the wrapper) and the `Modelverse prototype GUI <https://msdl.uantwerpen.be/git/yentl/modelverse_GUI.git>`_.
The wrapper functions are explained further in this documentation through the use of examples, in a tutorial-like fashion.
A full overview of all Python wrapper functions is provided at the end of the documentation.

Note that the Modelverse makes use of exceptions to signal unexpected behaviour.
These are not covered in this tutorial, as their meaning is obvious from their name.
All Modelverse exceptions inherit from the *ModelverseException*, which can be used as a catch-all.

Initializing the Modelverse
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Before we start, we must connect to the Modelverse.
This can be done throught the *init* function::

    >>> init("http://modelverse.uantwerpen.be")

This assumes that there is a Modelverse running at the specified address.
It is also possible to omit this optional argument, in which case a connection is made to localhost at port 8001 (i.e., the default when running locally).
For that, you must first 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.
This call might block for some time if the Modelverse server is still starting up::

    >>> init()

Logging in
^^^^^^^^^^

Now that we are connected to the Modelverse, we need to log in before any operations can be invoked.
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.
The used operations will differ depending on the type of user you are.
