Rotalumis Logo

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 specified poosl 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.