High-speed Simulation of POOSL Models with Rotalumis
Rotalumis is a high-speed execution engine for POOSL models. This execution engine simulates POOSL models conform the formal semantics. If you wonder what Rotalumis actually stands for, try reading it backwards.
Rotalumis can be used as a standalone simulator for POOSL. There is also an Integrated Development Environment for POOSL that uses Rotalumis in the back-end. It is developed by ESI (TNO). It supports graphical modelling, interactive simulaton and debugging. It can be freely used and is available from the following location: PooslIDE.
Installation
Rotalumis is best used with the Eclipse based PooslIDE frontend. The IDE will automatically enable the Rotalumis repository and install Rotalumis.
To manually install the latest version, we provide two Eclipse repositories:
- Release,
http://www.es.ele.tue.nl/rotalumis/repository/release/
- Integration (development)
http://www.es.ele.tue.nl/rotalumis/repository/integration/
Download standalone Rotalumis binaries:
- Release, stable
- Integration
If you are unsure which version of Rotalumis to use, you are probably looking for the Release version.
Using Rotalumis from the commandline
The Rotalumis binary can be used directly from the commandline without using the
PooslIDE frontend. To see all available options, check the output of
$ rotalumis --help
.
Running a POOSL model
The most basic usage is to run a POOSL model. This can be done by passing the
toplevel file of the model using the --poosl
flag.
$ rotalumis --stdlib --poosl model.poosl
This will start executing the model. The execution of the model can be aborted
at any point in time by hitting the q
key + Enter
.
NOTE: Depending on the model, it might take some time to quit the engine.
During execution Rotalumis will periodically print a dot on the commandline to indicate it is still processing and print the elapsed simulation time:
[INFO ] Real Time: 41.783 Steps: 2.88358e+06 Simulated Time: 193.235
Once the execution is done it will print more detailed information about the execution:
[INFO ] Real time: 102.072
[INFO ] Steps: 7542760
[INFO ] Simulated time: 500
[INFO ]
[INFO ] Fix requests granted: 0
[INFO ] Action transitions: 5667040
[INFO ] Communication transitions: 1343328
[INFO ] Communication requests tested: 0
[INFO ] Delay transitions: 532392
[INFO ]
[INFO ] Delay requests granted: 532392
[INFO ]
[INFO ] Garbage collection cleanup cycles: 1190154
[INFO ] Number of reclaimed objects: 89195710
[INFO ]
[INFO ] Virtual machine cycles: 1328403416
[INFO ]
NOTE: The output can be disabled using the --quiet
flag.
Running unittests
If the model has data classes that have unittest specified, these test can be ran using:
$ rotalumis --unittest model.poosl
This will run all tests and output the results.
$ rotalumis --unittest run.poosl
[INFO ] ======================================
[INFO ] Testsuite summary
[INFO ] ======================================
[INFO ] # TOTAL: 394
[INFO ] # PASS: 392
[INFO ] # FAIL: 0
[INFO ] # SKIP: 2
[INFO ] ======================================
Debugging a fault in Rotalumis or model
More debug output can be generated by passing the --debug
flag. With this
option Rotalumis will report more information about the internal state of the
execution engine. This will include a stack-trace when the model executions hits an exceptions:
$ rotalumis --poosl broken.poosl
[DEBUG ] Parsing SYSTEM in file: broken.poosl
[DEBUG ] Done parsing: broken.poosl
[DEBUG ] CPS File close. Set ready for read: 32768(21134) bytes buffered.
[DEBUG ] CPS File read. Cleaning up.
[INFO ] Press 'q <Enter>' to quit the simulation.
[DEBUG ] ---------------- Poosl Model Error ----------------
[DEBUG ] Error: 'Expecting right-hand-side to be an Integer instead of a String in data class Integer on
method +(i: Integer).'
[DEBUG ] Stmt Handle: '13' (broken.poosl:12:3-broken.poosl:12:14)
[DEBUG ] Process path: '/system/someInstance'
[DEBUG ] Process name: 'someInstance
[DEBUG ] Process function: 'expression'
[DEBUG ] Stackframes: '2'
[DEBUG ] Stackframe(1):
[DEBUG ] Method: 'Integer::+(operand) <native>'
[DEBUG ] Global variables: 0
[DEBUG ] Local variables: 2
[DEBUG ] 1 <unnamed>(Integer) = 1
[DEBUG ] 2 <unnamed>(String) = "ap"
[DEBUG ] Stackframe(2):
[DEBUG ] Method: 'someInstance::<process method>'
[DEBUG ] Stmt handle: '11' (broken.poosl:12:8-broken.poosl:12:14)
[DEBUG ] Global variables: 0
[DEBUG ] Local variables: 3
[DEBUG ] 1 z(Nil) = nil
[DEBUG ] 2 x(Nil) = nil
[DEBUG ] 3 y(Nil) = nil
[DEBUG ] --------------------------------------------------
[ERROR ] An exception occurred during run.
[ERROR ] Expecting right-hand-side to be an Integer instead of a String in data class Integer on method +(i: Integer
).
Other options
Other commandline options that Rotalumis supports:
--validate
: Instantiate and load the model without executing it.--stdlib
: Enable the standard libraries. See here--basic-classes
: Override the internal basic classes definition file.--stime
: Set a maximum on the simulated time.--rtime
: Set a maximum on the simulation time.--seed
: Set the random seed used by the scheduler. Use this to make runs repeatable.--ep-desc
: Pass an external port description file.--stack-limit
: Set the maximum stack size (in bytes) for each virtual machine.--includedir
: Add an include directory, used to resolve imports. This option can be passed multiple times.--version
: Print the version.
Character Encoding
Rotalumis internally does not support multi-byte characters. A character is seen as an 8 bit byte and strings are handled as an array of bytes. String indexes and size are in number of bytes.
The JSon parser in rotalumis works internally with UTF-8. It is adviced to limit the use in JSON to ASCII (subset of UTF-8).
Rotalumis and its communication with the IDE (PooslIDE) is in ISO-8859-1 encoding. When using rotalumis together with the IDE, string encoding should be in ASCII or ISO-8859-1.
Changelog
The latest version is 4.3.0
:
v4.3.0
The v4.3.0 release main change is the integration of a standard library of often used data types:
- Bag, BagIterator
- Map, MapIterator
- Set, SetIterator
- Sequence, SequenceIterator
- Stack
- Queue
With the addition of these data types, we now also made the serialization and de-serialization of json a built-in feature.
Fixes and added Features
- Change to meson build system. Simplifies building on Linux and Mac Os.
- Cleanup of old unused/partially implemented legacy code.
- Update XSD schemas.
- Add 64bit Microsoft Windows build.
- Update boost to 1.7.6.
- Split large source files.
- Introduction of native JSon serialization and de-serialization.
- Evaluation of guards is now side-effect free.
The changelog for previous versions can be found here.
Advanced usage
Rotalumis can be ran in backend mode. In backend mode, Rotalumis opens a TCP/ip socket and listens for incoming commands. Using this interface models can be loaded, compiled, ran, inspected, debugged and more. This interface is used by the PooslIDE frontend.
The API between Rotalumis and the frontend is build around a request and
response system. For example, if the frontend wants to inspect a process
class, it sends an inspect_request
message, on this request Rotalumis will
return an inspect_response
message.
The messages are formatted using XML and the XSD schema of these can be found
here. Tools like xsdcxx can be used to generate
data classes from the XSD schema for the communication.
To launch Rotalumis in backend mode run:
$ rotalumis -p 1882
Rotalumis will now be listening on port 1882 for commands.
To stop Rotalumis, hit enter.
Packet format
Each communication packet between Rotalumis and the client is the xml message, preceded by a 12 byte header with the size of the packet:
ROT 00000000
A prefix “ROT “ followed by a 32 bit unsigned hexadecimal representation of the size of the packet. There is limit of 256mbyte on packet size.
The xml messages are encoded using ISO-8859-1 character set.
Loading a model
To load a model the following steps have to be followed:
Compile Request
: This will parse the specifiedpoosl
file and its imports. If there was an error parsing the model, the Compile Response will contain an error status. On success it contains a handle that can be used to instantiate the model.Instantiate request
: This will instantiate the model and setup external ports.
If the instantiation request was successful, the model can be ran using using
a Command request
with the command run
.
The state of the execution engine can be requested using the Execution State
Request
. The frontend can tell Rotalumis to push execution state updates using
the eengine event setup
request. Flow control is available to synchronize
Rotalumis with the frontend.
To get a look at the traffic between the PooslIDE and Rotalumis, the PooslIDE
has an option to log this information in html format. This can be enabled under: Window -> preferences-> POOSL -> SIMULATOR
This will generate a Logging.html
file containing all communication.
Frequently Asked Questions
Data transfer between process classes
Each process class runs in it own isolated context, objects in a class cannot be moved between process classes. When an object is received a (internal) deepcopy of the object is made.
What do the statistics at the end of a simulation mean
At the end of a simulation the execution engine prints some statistics:
[INFO ] Real time: 1.004
[INFO ] Steps: 34
[INFO ] Simulated time: 0
[INFO ]
[INFO ] Action transitions: 34
[INFO ] Communication transitions: 0
[INFO ] Delay transitions: 0
The first field, Real time, is the wall time that elapsed between the start and stop of the simulation (in seconds). The second field indicates how many successful steps (transitions) the scheduler has made. The next three fields indicate how many steps of each type are made.
By passing the --debug
flag you can get more detailed information about the
internals of the execution engine.
Backtrace Missing
Some parts of the language run ‘side-effect free’, this means that the execution does not affect the state of the model. Example of ‘side-effect free’ execution is printString being evaluated from the debugger, or the method evaluating a conditional receipt. A ‘side-effect free’ execution is implemented by making a deepCopy of the current state, execution the requested code and then removing the copy. This introduces one problem for debugging; if an error occurs during this execution you cannot inspect the state (as it has been removed). For now, until a better solution is implemented, rotalumis prints a backtrace of the error in the Console.
Standard Library
Some of the more commonly used data storage classes are being integrated as native data classes in rotalumis. More information about this can be found here
License
Rotalumis license can be found here.