modelverse

Installation

Installing the Modelverse is unnecessary, as it is mere Python code and doesn't use installation scripts. All scripts which are generally useful are found in the 'scripts' directory, and are written in OS-independent Python code.

You will, however, need to install a dependency: the SCCD compiler and runtime.

Starting up the Modelverse

Starting up the Modelverse is easy: simply execute the scripts/run_local_modelverse.py script, with as parameter the port you want to use. This will compile the Modelverse statechart and execute it afterwards. You can now directly communicate with the Modelverse user initialisation layer. It is not recommended that you do this manually, so we will now introduce the action language.

Compiling Action Language

For a more user-friendly experience, an Action Language compiler was introduced that can automatically generate Modelverse instructions. During compilation, a live Modelverse is required, as the bytecodes are immediately uploaded after compilation. The Modelverse uses a traditional compilation phase and linking phase, though this is all hidden to the user through the scripts/make_all.py script. The script takes as parameter the address of the Modelverse, the username in whose name to execute the code, and a list of source files. For realistic applications, we recommend to always link to the bootstrap code, by including the file bootstrap/\*.alc. Even on systems that don't support globbing (e.g., Windows), this will automatically be expanded by the compiler.

For example, to compile the simple textual interface, you must compile the interface's action language, together with all bootstrapping code (the libraries):

python scripts/make_all.py http://127.0.0.1:8001 test_user bootstrap/*.alc integration/code/pn_interface.alc

Compilation is (relatively) smart, as it will not compile code again that is already present in the Modelverse. As such, except for the first user, the bootstrap code no longer needs to be compiled, only linked. In the future, this is expected to become more user friendly for users, such that they no longer need to have the bootstrapping code available locally.

After this part, your action language in integration/code/pn_interface.alc is compiled and running on the Modelverse. The Modelverse will, during loading, execute the main function it finds in any of these files.

Communicating with the Modelverse

Now that your code is running on the Modelverse, you will want to communicate with it! To do this, you can use whatever tool you want, as long as it can send and receive XML/HTTPRequests. For example, a mere internet browser can already communicate with the Modelverse, though not in the most user-friendly way.

A nicer way is through the Python prompt script scripts/prompt.py. It will ask you the location of the Modelverse, and the user to connect to. After that, it will print out all the output of the Modelverse, and send in all your queries directly to the Modelverse.

Performance

Performance of the Modelverse is currently rather low, especially in the make_all script, as this uses an explicitly modelled bytecode upload system. To drastically increase performance, this can be switched to a native implementation and a different compiler. Additionally, all compilations of source files can happen in parallel, using as many cores as are available. Even further, you can skip symbol resolution in the linking phase if you know that all symbols are defined. To do all of this, use the scripts/make_parallel.py script. It is identical to the scripts/make_all.py script, but uses multiple cores and uses native code.

Additional documentation

Some additional documentation can be found online in the Modelverse techreport, describing the internal workings of the Modelverse, as well as a brief introduction on how to use it. There is also in-depth documentation describing how to use the Modelverse and its various languages.

Tests

Running the tests is easy: simply execute scripts/run_tests.py in the main modelverse folder. This will invoke the necessary build commands (to create bootstrapping code etc.) and call the tests for each individual aspect of the Modelverse. Note that testing is done using py.test, which is the only dependency of the Modelverse (and only for tests, of course).

Regarding performance of tests, the tests will try to execute the compilation in parallel, though they test both the explicitly modelled upload system and the native code. As such, test performance for the "co_*" tests is known to be slow.

Using PyPy

Since all scripts chain the invocation with the same interpreter as originally invoking the script, you will need to install py.test for PyPy. Assuming that you already have PyPy installed, you can simply install py.test using these commands:

wget https://bootstrap.pypa.io/get-pip.py
pypy get-pip.py --user
pypy -m pip install pytest --user

From then on, you can simply invoke all tests in PyPy using:

pypy scripts/run_tests.py