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:

Download standalone Rotalumis binaries:

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 --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.
  • --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.2.0:

v4.2.0

The v4.2.0 release main goal was changing the way models can interact with the world (co-simulation). In the past there was no official way, a work-around existed via DataClasses (most notably the Socket class). This solution did not fit with the language and had undesired side effects. In this release we resolve this by adding support for external ports that live on the edge of the system. These external system ports can be configured, separate from the model, to communicate using sockets, files or the console.

Besides this major addition, several long requested features were implemented:

  • Parametrisable models: Environment variables can be included as literals in the model. On model loading these will be resolved and substituted.
  • IEEE 754-2008 double precision Floating point data class: Float.
  • Better debug output: The console debug output of the executation engine has been extended. This should help debugging issues.

To improve the overall stability of Rotalumis, the (unit)testing framework has been improved. This provided a significant improvement of the coverage of the regression tests. Beside this, many small bug-fixes and extensions have been added.

Other fixes and added features

  • Remove writing out of ‘archive.cps’.
  • Limit length of printString in StackTrace.
  • Improve type checking error messages on arguments.
  • Improve error message on a model that failed to load.
  • Improve error message on model consistency check.
  • Improve message on model termination.
  • Improve error message on class instantiation.
  • Do not allow aliassing of variables between inheritance.
  • Add commandline –validate option.
  • Remove platform specific implementations.
  • Allow and ignore systems in included files.
  • Fix mixing of data-types (32bit/64bit) in argument handling.
  • Extend unittest @error checking with regex support.
  • Support annotations for all classes and methods.
  • Socket data class, auto-reconnect when connecting to remote server.
  • Fix handling comments at the end of a Poosl file.

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.

Standard Library (WiP)

Some of the more commonly used data storage classes are being integrated as native data classes in rotalumis. This is still Work in Progress, but will be part of the next release. More information about this can be found here

License

Rotalumis license can be found here.