# SimulationRTManual

Authors: | Klaus Muller <Muller@users.sourceforge.net> Tony Vignaux <Vignaux@users.sourceforge.net>
Version: | 1.1
Date: | 2004-December-1
SimPy version: | 1.7.1
Web-site: | http://simpy.sourceforge.net/
Python-Version: | 2.2, 2.3, 2.4
Created: | 2003-December-18

## A Manual for SimulationRT

This manual describes SimulationRT, a SimPy module which supports synchronizing the execution of simulation models with real (wallclock) time.

### Acknowledgement

SimulationRT is based on an idea by Geoff Jarrad of CSIRO (Australia). He contributed a lot to its development and testing on Windows and Unix.

### Introduction

SimulationRT allows synchronizing simulation time and real (wallclock) time. This capability can be used to implement e.g. interactive game applications or to demonstrate a model's execution in real time.

Over and above the capabilities provided by Simulation, SimulationStep caters for executing SimPy models at user-controlled speed. This is done by setting a parameter in the call to simulateSimulationStep is a derivative of the Simulation module. It is identical to Simulation, except for the *simulate function which takes an additional parameter controlling execution speed.

Here is an example:

    ## RealTimeFireworks.py
    from __future__ import generators
    from SimPy.SimulationRT  import *
    from random import *
    import time
    class Launcher(Process):
        def launch(self):
            while True:
                print "Launch at %.1f; wallclock: %s"%(now(),time.clock()-startTime)
                yield hold,self,uniform(1,maxFlightTime)
                print "Boom!!! Aaaah!! at %.1f; wallclock: %s"%(now(),time.clock()-startTime)
    def model():
        initialize()
        for i in range(nrLaunchers):
            lau=Launcher()
            activate(lau,lau.launch())
        simulate(real_time=True,rel_speed=1,until=20) ##unit sim time = 1 sec clock
    nrLaunchers=2
    maxFlightTime=5.0
    startTime=time.clock()
    model()

rels_speed=1 sets the synchronization so that 1 simulation time unit is executed approximately in 1 second wallclock time. Run under Python 2.2.2 on a Windows XP-box (1.7 GHz), this output resulted over about 18 seconds of wallclock time:

    Launch at 0.0; wallclock: 0.000195555580376
    Launch at 0.0; wallclock: 0.00190107960634
    Boom!!! Aaaah!! at 1.8; wallclock: 1.78082661344
    Launch at 1.8; wallclock: 1.78274501368
    Boom!!! Aaaah!! at 2.8; wallclock: 2.84245930698
    Launch at 2.8; wallclock: 2.84435982785
    Boom!!! Aaaah!! at 4.1; wallclock: 4.08443978215
    Launch at 4.1; wallclock: 4.09004328762
    Boom!!! Aaaah!! at 5.2; wallclock: 5.14561822801
    Launch at 5.2; wallclock: 5.14878203794
    Boom!!! Aaaah!! at 7.0; wallclock: 6.99845622838
    Launch at 7.0; wallclock: 7.00175357483
    Boom!!! Aaaah!! at 7.4; wallclock: 7.39919794276
    Launch at 7.4; wallclock: 7.40245282571
    Boom!!! Aaaah!! at 9.7; wallclock: 9.69250728794
    Launch at 9.7; wallclock: 9.69912935862
    Boom!!! Aaaah!! at 10.6; wallclock: 10.5938587167
    Launch at 10.6; wallclock: 10.6006140445
    Boom!!! Aaaah!! at 13.8; wallclock: 13.8082362423
    Launch at 13.8; wallclock: 13.8134877477
    Boom!!! Aaaah!! at 14.1; wallclock: 14.1385670525
    Launch at 14.1; wallclock: 14.1438146468
    Boom!!! Aaaah!! at 16.4; wallclock: 16.411963811
    Launch at 16.4; wallclock: 16.4172373863
    Boom!!! Aaaah!! at 17.1; wallclock: 17.1429980626
    Launch at 17.1; wallclock: 17.1482308506
    Boom!!! Aaaah!! at 18.1; wallclock: 18.0742063586
    Launch at 18.1; wallclock: 18.0794469688

Clearly, the wallclock time does not deviate significantly from the simulation time.

### Limitations

This module works much better under Windows than under Unix or Linux, i.e., it gives much closer synchronization. Unfortunately, the handling of time in Python is not platform-independent at all. Here is a quote from the documentation of the time module:

    "clock()
    On Unix, return the current processor time as a floating point number expressed in seconds.
    The precision, and in fact the very definition of the meaning of ``processor time'' , depends
    on that of the C function of the same name, but in any case, this is the function to use for
    benchmarking Python or timing algorithms.

    On Windows, this function returns wall-clock seconds elapsed since the first call to this
    function, as a floating point number, based on the Win32 function QueryPerformanceCounter().
    The resolution is typically better than one microsecond.
    "

### The SimulationRT API

#### Structure

Basically, SimulationStep has the same API as Simulation, but with a change in the definition of simulate.

#### simulate

Executes the simulation model.

Call:

> simulate(<optional parameters>)

Mandatory parameters:
  None.
Optional parameters:
  - until=0 : the maximum simulation (end) time (positive floating point number; default: 0)
  - real_time=False : flag to switch real time synchronization on or off (boolean; default: False, meaning no synchronization)
  - rel_speed=1 : ratio simulation time over wallclock time; example: rel_speed=200 executes 200 units of simulation time in about one second (positive floating point number; default: 1, i.e. 1 sec of simulation time is executed in about 1 sec of wallclock time)
Return value:
  Simulation status at exit.

$Revision: 1.1.1.10 $ $Date: 2006/06/14 10:58:32 $ kgm