Updated README specifically to live modelling

README.md

@@ -6,87 +6,50 @@ All scripts which are generally useful are found in the 'scripts' directory, and
 
 You will, however, need to install a dependency: the [SCCD compiler and runtime](https://msdl.uantwerpen.be/git/simon/SCCD).
 
-Starting up the Modelverse
-==========================
+Next we specifically focus on using the Modelverse for live modelling.
+Note that these GUIs are mostly a proof of concept and therefore not very intuitive or user friendly.
+Nonetheless, they support live modelling of systems in their respective formalism.
 
-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):
+Live Modelling of CBDs
+======================
 
+To start live modelling of CBDs, start up the Modelverse with the following command.
 ```sh
-python scripts/make_all.py http://127.0.0.1:8001 test_user bootstrap/*.alc integration/code/pn_interface.alc
+python scripts/run_local_modelverse.sh 8001
 ```
 
-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](http://msdl.cs.mcgill.ca/people/yentl/files/Modelverse.pdf), describing the internal workings of the Modelverse, as well as a brief introduction on how to use it.
-There is also [in-depth documentation](https://msdl.uantwerpen.be/documentation/modelverse) describing how to use the Modelverse and its various languages.
-
-Tests
-=====
+When this has started, compile all CBD related files and its execution semantics with the following command.
+```sh
+python scripts/execute_model.sh http://localhost:8001 test bootstrap/*.alc integration/code/cbd_*.mvc integration/code/cbd_*.alc
+```
 
-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).
+After the previous command has finished, start up the GUI with the following command.
+Any other GUI, or even textual, is also possible.
+Only this GUI and a very minimal textual prompt are provided out-of-the-box.
+```sh
+cd interface/CBD
+python main.py
+```
 
-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.
+In the GUI, you select the desired block in the top bar, and then create it by left-clicking in the canvas.
+Links can be created by selecting "Link" in the top bar, and dragging between two blocks while holding the right mouse button.
+Blocks can be deleted by middle clicking.
+To modify attributes of a block, such as the value of the constant block, left click it again.
 
-Using PyPy
-----------
+Modifications can be done even during simulation, and will immediately be taken into account.
+If the background colours red, the model is not conforming and something is wrong (*e.g.*, a constant block doesn't have a value).
+The background will turn grey again when the problem was resolved.
 
-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:
-```sh
-wget https://bootstrap.pypa.io/get-pip.py
-pypy get-pip.py --user
-pypy -m pip install pytest --user
-```
+Live Modelling of FSAs
+======================
 
-From then on, you can simply invoke all tests in PyPy using:
+Live modelling of FSAs is identical to the live modelling of CBDs.
+Instead of loading CBD files, now load FSA files with the command shown below.
 ```sh
-pypy scripts/run_tests.py
+python scripts/execute_model.sh http://localhost:8001 test bootstrap/*.alc integration/code/fsa_*.mvc integration/code/fsa_*.alc
 ```
 
+The GUI can be started similarly with the files in the folder *interface/FSA*.
+Commands are very similar, but there is no need to select the required kind of state and transition in the top bar, as there are only two options.
+To turn a state into the initial state, control-left-click the new initial state.
+Events can be injected by typing in the name of the event in the top right entry box, and clicking the *event* button.