simpylogo SimPy Manual

Author: Tony Vignaux <Vignaux@users.sourceforge.net>
Author: Klaus Muller <Muller@users.sourceforge.net>
SimPy version:1.6.1
Date: 2005-November-1 gav
Web-site:http://simpy.sourceforge.net/
Python-Version:2.2, 2.3, 2.4

Contents

SimPy is an efficient, process-based, open-source simulation language using Python as a base. The facilities it offers are Processes, Resources, and Monitors.

This document describes version 1.6.1 of SimPy.

Changes from version 1.6

The SimPy API provided by version 1.6.1 is unchanged and programs written to it work as before.

SimPy 1.6.1 adds a new variety of monitor, the Tally class. This saves memory by calculating appropriate sums and sums of squares as each value is observed. It does not retain the whole history of the values observed as the Monitor class. Changes to the Resource class follow (see Monitoring a resource). The default monitor type used in a reqource remains the Monitor though a Tally can be chosen if desired.

Introduction

SimPy is a Python-based discrete-event simulation system. It uses parallel processes to model active components such as messages, customers, trucks, planes. It provides a number of facilities for the simulation programmer including Processes, Resources, and ways of recording results in Monitors.

Processes are the basic component of a SimPy simulation script. A Process models an active component (for example, a Truck, a Customer, or a Message) which may have to queue for scarce Resources, to work for fixed or random times, and to interact with other processes and components.

A SimPy script consists of the declaration of one or more Process classes and the instantiation (that is, creation) of process objects from them. Each such object is activated and executes its Process Execution Method (referred to later as a PEM) that describes its activity. This runs in parallel with the operation of other objects.

Resources model congestion points where process objects may have to wait for service. For example, a Message may have to wait for one of a limited number of communication links. These will be modelled as a number of units of a communication Resource. The Resource automatically queues process objects until a unit is available. A process object retains their unit of resource until it has finished with it and then releases it for possible use by another.

Monitors are used by to record the values of variables such as waiting times and queue lengths as a function of time. A Monitor may later be accessed to provide statistics for these outputs. These statistics may be simple averages and variances, time-weighted averages, or histograms.

Before attempting to use SimPy, you should be able to write Python code. In particular, you should be able to use and define classes of objects. Python is free and available on most machine types. We do not introduce it here. You can find out more about it and download it from the Python web-site, http://www.Python.org

SimPy requires Python 2.2 or later [1].

[1]If Python 2.2 is used, the command: from __future__ import generators must be placed at the top of all SimPy scripts. The following examples do not include this line.

Simulation with SimPy

All discrete-event simulation programs automatically maintain the current simulation time in a software clock. In SimPy this can be accessed using the now() function. This is used in controlling the simulation and in producing printed traces of its operation. The software clock is set to 0.0 at the start of the simulation. The user cannot change the software clock directly.

While a simulation program runs, time steps forward from one event to the next. An event occurs whenever the state of the simulated system changes. For example, an arrival of a customer is an event. So is a departure.

To use the event scheduling mechanism of SimPy we must import the Simulation module:

from SimPy.Simulation import *

Before any SimPy simulation statements, such as those defining processes or resources, are issued, the following statement must appear in the script:

initialize()

Then there will be some SimPy statements, creating and activating objects. Execution of the timing mechanism itself starts when the following statement appears in the script:

simulate(until=endtime)

The simulation then starts, the timer routine seeking the first scheduled event. Having executed that event, the timer routine seeks the next event. The simulation will run until one of the following states:

  • there are no more events to execute (now() == the time of the last event)
  • the simulation time reaches endtime (now() == endtime)
  • the stopSimulation() command is executed (now() == the simulation time when stopSimulation() was called).

Typically a simulation is terminated using the until argument of the simulate statement but it can be stopped at any time using the command:

stopSimulation()

which immediately stops simulation.

Further statements can still be executed after exit from simulate and this is useful for reporting results such as average delays or lengths of queues.

The following fragment shows only the main block in a simulation program. Arrival is a Process class (previously defined) and p is defined as an object of that class. Activating p has the effect of scheduling at least one event by starting its Process Execution Method (here called execute). The simulate(until=1000.0) statement starts the simulation itself and it immediately jumps to that first scheduled event. It will continue until it runs out of events to execute or the simulation time reaches 1000.0. When the simulation stops the (previously written) Report function is used to display the results:

initialize()
p = Arrival()
activate(p,p.execute(),at=0.0)
simulate(until=1000.0)

Report()  #  report results when the simulation finishes

Processes

The active objects for discrete-event simulation in SimPy are classes that inherit from class Process.

For example, if we are simulating a messaging system we might model a message as a Process. A message arrives in a computing network; it makes transitions between nodes, waits for service at each one, and eventually leaves the system. The Message class describes these actions in an Process Execution Method. Individual messages are created as the program runs and they go through their modelled lifetimes.

Defining a process

A process is a class that that inherits from the class Process. For example here is the header of the definition of a new Message process class:

  • class Message(Process):

The user must define one (and only one) Process Execution Method (PEM) for a Process. Other methods may also be defined, perhaps including an __init__ method.

  • __init__(self,...), where ... indicates method arguments. This function initialises the Process object, setting values for any attributes. The first line of this method must be a call to the Class __init__() in the form: Process.__init__(self,name='a_process')

    Then other commands can be used to initialize attributes of the object. The __init__() method is called automatically when a new message is created.

    In this example of an __init__() method for a Message class we give each new message an integer identification number, i, and message length, len as instance variables:

    def __init__(self,i,len):
        Process.__init__(self,name='Message'+str(i))
        self.i = i
        self.len = len
    

    If you do not wish to set any attributes (other than a name, the __init__ method may be dispensed with.

  • A process execution method (PEM) This describes the actions of the process object and must contain at least one of the yield statements, described later, to make it a Python generator function. This means it has resumable execution: it can be restarted again after the yield statement. A PEM can have arguments. Typically this can be called execute() or run() but any name may be chosen.

    The execution method starts running when the process is activated and the simulate(until=...) statement has been called.

    In this example of the process execution method (go())for the same Message class, the message prints out the current time, its identification number and the word 'Starting'. After a simulated delay (in the yield hold,.. statement) it announces that it has 'Arrived':

    def go(self):
        print now(), self.i, 'Starting'
        yield hold,self,100.0
        print now(), self.i, 'Arrived'
    

Starting a process

A Process object must be activated in order to start it operating (see Starting and stopping SimPy Processes)

Elapsing time in a Process

A PEM can cause time to elapse for a process using the yield hold command:

  • yield hold,self,t causes the object to wait for a delay of t time units (unless it is interrupted). It then continues its operation with the next statement. During the hold the object is suspended.
  • yield passivate,self suspends the process's operations indefinitely.

This example of script with a Customer class demonstrates that the PEM method (buy) can have arguments which can be used in the activation. All processes can have a name attribute which can be set, as here, when an object is created. Here the yield hold is executed 4 times with delays of 5.0:

from SimPy.Simulation import *

class Customer(Process):
   def buy(self,budget=0):
      print 'Here I am at the shops ',self.name
      t = 5.0
      for i in range(4):
          yield hold,self,t
          print 'I just bought something ',self.name
          budget -= 10.00
      print   'All I have left is ', budget,\
              ' I am going home ',self.name,

initialize()
C = Customer(name='Evelyn')
activate(C,C.buy(budget=100),at=10.0)
simulate(until=100.0)

Starting and stopping SimPy Processes

Once a Process object has been created, it is 'passive', i.e., it has no event scheduled. It must be activated to start the process execution method:

  • activate(p,p.PEM(args)[,at=t][,delay=period][,prior=false]) will activate the execution method p.PEM() of Process instance, p with arguments args.

    The default action is to activate at the current time, otherwise one of the optional timing clauses, at=t, or delay=period, operate.

    prior is normally False. If it is True, the process will be activated before any others at the specified time in the event list.

The process can be suspended and reactivated:

  • yield passivate,self suspends the process itself. It becomes 'passive'.
  • reactivate(p,at=t,delay=period,prior=boolean) will reactivate a passive process, p. It becomes 'active'. The optional timing clauses work as for activate. A process cannot reactivate itself. If that is required, use yield hold,self,t instead.
  • self.cancel(p) deletes all scheduled future events for process p. Only 'active' processes can be cancelled. A process cannot cancel itself. If that is required, use yield passivate,self instead. Note: This new format replaces the p.cancel() form of earlier SimPy versions.

When all statements in a process execution method have been completed, a process becomes 'terminated'. If the instance is still referenced, it becomes just a data container. Otherwise, it is automatically destroyed.

Even activated processes will not start until the simulate(until=T) statement has been executed. This starts the simulation going and it will continue until time T (unless it runs out of events to execute or the command stopSimulation() is executed)

A complete SimPy script

Before introducing the more complicated process capabilities let us look at a complete runnable SimPy script. This simulates a firework with a time fuse. I have put in a few extra yield hold commands for added suspense:

from SimPy.Simulation import *

class Firework(Process):

   def execute(self):
       print now(), ' firework activated'
       yield hold,self, 10.0
       for i in range(10):
           yield hold,self,1.0
           print now(),  ' tick'
       yield hold,self,10.0
       print now(), ' Boom!!'

initialize()
f = Firework()
activate(f,f.execute(),at=0.0)
simulate(until=100)

The output from Example . No formatting of the output was attempted so it looks a bit ragged:

0.0  firework activated
11.0  tick
12.0  tick
13.0  tick
14.0  tick
15.0  tick
16.0  tick
17.0  tick
18.0  tick
19.0  tick
20.0  tick
30.0  Boom!!

A source fragment

One useful program pattern is the source. This is an process with an execution method that generates events or activates other processes as a sequence -- it is a source of other processes. Random arrivals can be modelled using random (exponential) intervals between activations.

The following example is of a source which activates a series of customers to arrive at regular intervals of 10.0 units of time. The sequence continues until the simulation time exceeds the specified finishTime. (Of course, to achieve random'' arrivals of *customer*s the *yield hold method should use an exponential random variate instead of, as here, a constant 10.0 value) The example assumes that the Customer class has been defined with a PEM called run:

class Source(Process):

   def execute(self, finish):
      while now() < finish:
         c = Customer()          ## new customer
         activate(c,c.run())     ## activate it now
         print now(), ' customer'
         yield hold,self,10.0

initialize()
g = Source()
activate(g,g.execute(33.0),at=0.0)   ## start the source
simulate(until=100)

Asynchronous interruptions

An active process can be interrupted by another but cannot interrupt itself. The interrupter process will use the following statement to interrupt the victim process.

  • self.interrupt(victim)

The interrupt is just a signal. After this statement, the interrupter continues its current method.

The victim must be active - that is one that has an event scheduled for it (that is, it is 'executing' a yield hold,self,t). If the victim is not active (that is it is either passive or terminated) the interrupt has no effect on it. processes queuing for resources cannot be interrupted as they are passive. Processes which have acquired a resource are active and can be interrupted.

If interrupted, the victim returns from its yield hold prematurely. It should then check if it has been interrupted by calling

  • self.interrupted() which returns True if it has been interrupted. It can then either continue in the current activity or switch to an alternative, making sure it tidies up the current state, such as releasing any resources it owns. When self.interrupted()== True:
    • self.interruptCause is a reference to the interrupter instance.
    • self.interruptLeft gives the time remaining in the interrupted yield hold,

The interruption is reset at the victim's next call to a yield hold,. It can also be reset by calling

  • self.interruptReset()

Here is an example of a simulation with interrupts. A bus is subject to breakdowns which are modelled as interruptions. Notice that in the first yield hold, interrupts may occur, so a reaction to the interrupt (= repair) has been programmed by testing self.interrupted(). The Bus Process here does not require an __init__ method:

from SimPy.Simulation import *

class Bus(Process):

  def operate(self,repairduration,triplength):  # process execution method (PEM)
     tripleft = triplength
     while tripleft > 0:
        yield hold,self,tripleft                # try to get through trip
        if self.interrupted():
              print self.interruptCause.name, "at %s" %now() # breakdown
              tripleft=self.interruptLeft  # yes; time to drive 
              self.interruptReset()             # end interrupt state
              reactivate(br,delay=repairduration) # delay any breakdowns 
              yield hold,self,repairduration
              print "Bus repaired at %s" %now()
        else:
              break                             # no breakdown, bus arrived
        print "Bus has arrived at %s" %now()

class Breakdown(Process):
   def __init__(self,myBus):
       Process.__init__(self,name="Breakdown "+myBus.name)
       self.bus=myBus

   def breakBus(self,interval):                 # process execution method 
       while True:
          yield hold,self,interval
          if self.bus.terminated(): break
          self.interrupt(self.bus)

initialize()
b=Bus("Bus")
activate(b,b.operate(repairduration=20,triplength=1000))
br=Breakdown(b)                                 # breakdown to bus b
activate(br,br.breakBus(300))
print simulate(until=4000)

The ouput from this example:

Breakdown Bus at 300
Bus repaired at 320
Breakdown Bus at 620
Bus repaired at 640
Breakdown Bus at 940
Bus repaired at 960
Bus has arrived at 1060
SimPy: No more events at time 1260

Where interrupts can occur, the process which may be the victim of interrupts must test for interrupt occurrence after every yield hold and react to it. If a process holds a resource when it gets interrupted, it continues holding the resource.

Advanced synchronisation/scheduling capabilities

(SimPy 1.5 and beyond) All scheduling constructs discussed so far are either time-based, i.e., they make processes wait until a certain time has passed, or use direct reactivation of processes. For a wide range of models, these constructs are totally satisfactory and sufficient.

In some modelling situations, the SimPy scheduling constructs are too rich or too generic and could be replaced by simpler, safer constructs. SimPy 1.5 has introduced synchronisation by events and signals as one such possible construct.

On the other side, there are models which require synchronisation/scheduling by other than time-related wait conditions. SimPy has introduced a general "wait until" to support clean implementation of such models.

Signalling between processes

Event signalling is particularly useful in situations where processes must wait for completion of activities of unknown duration. This situation is often encountered, e.g. when modelling real time systems or operating systems.

Events in SimPy are implemented by class SimEvent. This name was chosen because the term 'event' is already being used in Python for e.g. tkinter events or in Python's standard library module signal -- Set handlers for asynchronous events.

An instance of a SimEvent is generated by something like myEvent=SimEvent("MyEvent"). Associated with a SimEvent are

  • a boolean occurred to show whether an event has happened (has been signalled)
  • a list waits, implementing a set of processes waiting for the event
  • a list queues, implementing a FIFO queue of processes queueing for the event
  • an attribute signalparam to receive an (optional) payload from the signal method

Processes can wait for events by issuing:

yield waitevent,self,<events part>

<events part> can be:

  • an event variable, e.g. myEvent
  • a tuple of events, e.g. (myEvent,myOtherEvent,TimeOut), or
  • a list of events, e.g. [myEvent,myOtherEvent,TimeOut]

If one of the events in <events part> has already happened, the process contines. The occurred flag of the event(s) is toggled to False.

If none of the events in the <events part> has happened, the process is passivated after joining the set of processes waiting for all the events.

Processes can queue for events by issuing:

yield queueevent,self,<events part> (with <events part> as defined above)

If one of the events in <event>s part> has already happened, the process continues. The occurred flag of the event(s) is toggled to False.

If none of the events in the <events part> has happened, the process is passivated after joining the FIFO queue of processes queuing for all the events.

The occurrence of an event is signalled by:

<event>.signal(<payload parameter>)

The <payload parameter> is optional. It can be of any Python type. It can be read by the process(es) triggered by the signal as the SimEvent attribute signalparam, like message = MySignal.signalparam.

When issued, signal causes the occurred flag of the event to be toggled to True, if waiting set and and queue are empty. Otherwise, all processes in the event's waits list are reactivated at the current time, as well as the first process in its queues FIFO queue.

Here is a small, complete SimPy script illustrating the new constructs:

from SimPy.Simulation import *

class Waiter(Process):
    def waiting(self,myEvent):
        yield waitevent,self,myEvent
        print "%s: after waiting, event %s has happened"%(now(),myEvent.name)
        
class Queuer(Process):
    def queueing(self,myEvent):
        yield queueevent,self,myEvent
        print "%s: after queueing, event %s has happened"%(now(),myEvent.name)
        print "   just checking: event(s) %s fired"%([x.name for x in self.eventsFired])
        
class Signaller(Process):
    def sendSignals(self):
        yield hold,self,1
        event1.signal()
        yield hold,self,1
        event2.signal()
        yield hold,self,1
        event1.signal()
        event2.signal()

initialize()
event1=SimEvent("event1"); event2=SimEvent("event2")
s=Signaller(); activate(s,s.sendSignals())
w0=Waiter(); activate(w0,w0.waiting(event1))
w1=Waiter(); activate(w1,w1.waiting(event1))
w2=Waiter(); activate(w2,w2.waiting(event2))
q1=Queuer(); activate(q1,q1.queueing(event1))
q2=Queuer(); activate(q2,q2.queueing(event1))
simulate(until=10)

When run, this produces:

1: after waiting, event event1 has happened
1: after waiting, event event1 has happened
1: after queueing, event event1 has happened
   just checking: event(s) ['event1'] fired
2: after waiting, event event2 has happened
3: after queueing, event event1 has happened
   just checking: event(s) ['event1'] fired

When event1 fired at time 1, two processes (w0 and w1)were waiting for it and both got reactivated. Two proceses were queueing for it(q1 and q2), but only one got reactivated. The second queueing process got reactivated when event1 fired again. The 'just checking' line reflects the content of the process' self.eventsFired attribute.

"wait until" synchronisation -- waiting for any condition

Simulation models where progress of a process depends on a general condition involving non-time-related state-variables (such as "goodWeather OR (nrCustomers>50 AND price<22.50") are difficult to implement with SimPy constructs prior to version 1.5. They require interrogative scheduling, while all other SimPy synchronisation constructs are imperative: after every SimPy event, the condition must be tested until it becomes True. Effectively, a new (hidden, system) process has to interrogate the value of the condition. Clearly, this is less runtime-efficient than the event-list scheduling used for the other SimPy constructs. The SimPy 1.5.1 implementation therefore only activates that interrogation process when there is a process waiting for a condition. When this is not the case, the runtime overhead is minimal (about 1 percent extra runtime).

The new construct takes the form:

yield waituntil, self, <cond>

<cond> is a reference to a function without parameters which returns the state of condition to be waited for as a boolean value.

Here is a simple program using the yield waituntil construct:

from SimPy.Simulation import *
import random
class Player(Process):
    def __init__(self,lives=1):
        Process.__init__(self)
        self.lives=lives
        self.damage=0
    def life(self):
        self.message="I survived alien attack!"
        def killed():
            return self.damage>5
        while True:
            yield waituntil,self,killed
            self.lives-=1; self.damage=0
            if self.lives==0:
                self.message= "I was wiped out by alien at time %s!"%now()
                stopSimulation()             
class Alien(Process):
    def fight(self):
        while True:
            if random.randint(0,10)<2: #simulate firing
                target.damage+=1       #hit target
            yield hold,self,1

initialize()
gameOver=100
target=Player(lives=3); activate(target,target.life())
shooter=Alien(); activate(shooter,shooter.fight())
simulate(until=gameOver)
print target.message 

In summary, the "wait until" construct is the most powerful synchronisation construct. It effectively generalises all other SimPy synchronisation constructs, i.e., it could replace all of them (but at a runtime cost).

Resources

A resource models a congestion point where there may be queueing. For example, in a manufacturing plant, a Task (modelled as a process) needs work done at a Machine (modelled as a resource). If a Machine unit is not available, the Task will have to wait until one becomes free. The Task will then have the use of it for however long it needs. It is not available for other Tasks until released. These actions are all automatically taken care of by the SimPy resource.

A resource can have a number of identical units. So there may be a number of identical Machine units. A process gets service by requesting a unit of the resource and, when it is finished, releasing it. A resource maintains a queue of waiting processes and another list of processes using it. These are defined and updated automatically.

Defining a Resource

A Resource is established by the following statement:

  • r=Resource(capacity=<integer>, name=<string>, unitName=<string>, qType=[FIFO|PriorityQ], preemptable=<boolean>, monitored=<boolean>, monitorType=[Monitor|Tally])
    • capacity is the number of identical units of the resource available (default=1).
    • name is the name by which the resource is known (eg gasStation). (default='a_resource')
    • unitName is the name of a unit of the resource (eg pump). (default='units')
    • qType describes the queue discipline of the waiting queue of processes; typically, this is FIFO (First-in, First-out). and this is the presumed value. An alternative is PriorityQ. (default=FIFO)
    • preemptable, if it is non-zero, indicates that a process being put into the PriorityQ may also pre-empt a lower-priority process already using a unit of the resource. This only has an effect when qType == PriorityQ. (default=False)
    • monitored indicates if the size of the waitQ and activeQ queues (see below) are to be monitored. (see Monitors, below) (default=False)
    • monitorType is the variety of monitor to be used. This can take one of the values [Monitor, Tally]. (see Monitors, below) (default=Monitor)

A Resource, r, has the following attributes:

  • r.n The number of units that are currently free.
  • r.waitQ A waiting queue (list) of processes (FIFO by default). len(r.waitQ) is the number of Processes held in the waiting queue at any time.
  • r.activeQ A queue (list) of processes holding units. len(r.activeQ) is the number of Processes held in the active queue at any time.
  • r.waitMon A Monitor automatically recording the activity in r.waitQ if monitored==True
  • r.actMon A Monitor automatically recording the activity in r.activeQ if monitored==True

A simple request for a unit of Resource

A process can request and later release a unit of resource, r, in a Process Execution Method using the following yield commands:

  • yield request, self, r requests one unit of resource, r. The process may be temporarily queued and suspended until one is available.

    If, or when, a unit is free, the requesting process will take one and continue its execution. The resource will record that the process is using a unit (that is, the process will be listed in r.activeQ)

    If one is not free , the the process will be automatically placed in the resource's waiting queue, r.waitQ, and suspended. When a unit eventually becomes available, the first process in the waiting queue, taking account of the priority order, will be allowed to take it. That process is then reactivated.

    If the resource has been defined as being a priorityQ with preemption == 1 then the requesting process can pre-empt a lower-priority process already using a unit. (see Requesting a resource with preemptive priority, below)

  • yield release,self,r releases the unit of r. This may have the side-effect of allocating the released unit to the next process in the Resource's waiting queue.

    In this example, the current Process requests and, if necessary waits for, a unit of a Resource, r. On acquisition it holds it while it pauses for a random time (exponentially distributed, mean 20.0) and then releases it again:

    yield request,self,r
    yield hold,self,expovariate(1.0/20.0)
    yield release,self,r
    

Requesting resources with priority

If a Resource, r is defined with priority queueing (that is qType==PriorityQ) a request can be made for a unit by:

  • yield request,self,r,priority requests a unit with priority. priority is real or integer. Larger values of priority represent higher priorities and these will go to the head of the r.waitQ if there not enough units immediately.

Here is an example of a complete script where priorities are used. Four clients with different priorities request a resource unit from a server at the same time. They get the resource in the order set by their relative priorities:

from SimPy.Simulation import *
class Client(Process):
    inClients=[]
    outClients=[]

    def __init__(self,name):
       Process.__init__(self,name)

    def getserved(self,servtime,priority,myServer):
        Client.inClients.append(self.name)
        print self.name, 'requests 1 unit at t=',now()
        yield request, self, myServer, priority
        yield hold, self, servtime
        yield release, self,myServer
        print self.name,'done at t=',now()
        Client.outClients.append(self.name)

initialize()
server=Resource(capacity=1,qType=PriorityQ)
c1=Client(name='c1') ; c2=Client(name='c2')
c3=Client(name='c3') ; c4=Client(name='c4')
activate(c1,c1.getserved(servtime=100,priority=1,myServer=server))
activate(c2,c2.getserved(servtime=100,priority=2,myServer=server))
activate(c3,c3.getserved(servtime=100,priority=3,myServer=server))
activate(c4,c4.getserved(servtime=100,priority=4,myServer=server))
simulate(until=500)
print 'Request order: ',Client.inClients
print 'Service order: ',Client.outClients

This program results in the following output:

c1 requests 1 unit at t= 0
c2 requests 1 unit at t= 0
c3 requests 1 unit at t= 0
c4 requests 1 unit at t= 0
c1 done at t= 100
c4 done at t= 200
c3 done at t= 300
c2 done at t= 400
Request order:  ['c1', 'c2', 'c3', 'c4']
Service order:  ['c1', 'c4', 'c3', 'c2']

Although c1 has the lowest priority, it requests and gets the resource unit first. When it completes, c4 has the highest priority of all waiting processes and gets the resource next, etc. Note that there is no preemption of processes being served.

Requesting a resource with preemptive priority

In some models, higher priority processes can preempt lower priority processes when all resource units have been allocated. A resource with preemption can be created by setting arguments qType==PriorityQ and preemptable non-zero.

When a process requests a unit of resource and all units are in use it can preempt a lower priority process holding a resource unit. If there are several processes already active (that is, in the activeQ), the one with the lowest priority is suspended, put at the front of the waitQ and the preempting process gets its resource unit and is put into the activeQ. The preempted process is the next one to get a resource unit (unless another preemption occurs). The time for which the preempted process had the resource unit is taken into account when the process gets into the activeQ again. Thus, the total hold time is always the same, regardless of whether or not a process gets preempted.

An example of a complete script. Two clients of different priority compete for the same resource unit:

from SimPy.Simulation import *
class Client(Process):
    def __init__(self,name):
       Process.__init__(self,name)

    def getserved(self,servtime,priority,myServer):
        print self.name, 'requests 1 unit at t=',now()
        yield request, self, myServer, priority
        yield hold, self, servtime
        yield release, self,myServer
        print self.name,'done at t=',now()

initialize()
server=Resource(capacity=1,qType=PriorityQ,preemptable=1)
c1=Client(name='c1')
c2=Client(name='c2')
activate(c1,c1.getserved(servtime=100,priority=1,myServer=server),at=0)
activate(c2,c2.getserved(servtime=100,priority=9,myServer=server),at=50)
simulate(until=500)

The output from this program is:

c1 requests 1 unit at t= 0
c2 requests 1 unit at t= 50
c2 done at t= 150
c1 done at t= 200

Here, c2 preempted c1 at t=50. At that time, c1 had held the resource for 50 of the total of 100 time units. c1 got the resource back when c2 completed at t=150.

Reneging -- leaving a queue before acquiring a resource

In most real world situations, processes do not wait for a requested resource forever, but leave the queue (renege) after a certain time or when some other condition has arisen.

SimPy provides an extended (compound) yield request statement form to model reneging.

yield (request,self,resource[,priority]),(<reneging clause>).

The structure of a SimPy model with reneging is:

yield (request,self,resource),(<reneging clause>)
if self.acquired(resource):
   ## process got resource and did not renege
   . . . . 
   yield release,self,resource
else:
   ## process reneged before acquiring resource
   . . . . . 

A method acquired(resource) has been added to class Process. A call to this method (self.acquired(resource)) is mandatory after a compound yield request statement. It is not only a predicate which indicates whether or not the process has acquired the resource, but it also removes the reneging process from the resource's waitQ.

There are two reneging clauses, one for reneging after a certain time and one for reneging when an event has happened.

Reneging after a time limit

To make a process renege after a certain time, the reneging clause used is identical to the parameters of a yield hold statement, namely hold,self,waittime:

  • yield (request,self,res,[,priority]),(hold,self,waittime) process self requests one unit of resource res with relative priority if it is set. This blocks the process from continuing execution if the resource unit is not available. If the resource unit has not been acquired by the process after a time period waittime, the process leaves the queue and its execution continues.

An example code snippet:

## Queuing for a parking space in a parking lot
. . . .
parking_lot=Resource(capacity=10)
patience=5   # time units
park_time=60 # time units
. . . .
# wait no longer than 'patience' time units for a parking space 
yield (request,self,parking_lot),(hold,self,patience)
if self.acquired(parking_lot):
   # park the car
   yield hold,self,park_time
   yield release,self,parking_lot
else:
   # give up
   print "I have had enough, I am going home"

Reneging when an event has happened

To make a process renege at the occurrence of an event, the reneging clause used is identical to the parameters of a "yield waitevent" statement, namely waitevent,self,events:

  • yield (request,self,res[,priority]),(waitevent,self,events) process self requests one unit of resource res priority if priority is set. (events can either be one event or a list (or tuple) of several SimEvents.) This blocks the process from continuing execution if the resource unit is not available. If the resource unit has not been acquired by the process when one of the events in events has been signalled, the process leaves the queue and its execution continues.

An example code snippet:

## Queuing for movie tickets
. . . .
tickets=Resource(capacity=100)
sold_out=SimEvent() # signals 'out of tickets'
too_late=SimEvent() # signals 'too late for this show'
. . . .
# Leave the ticket counter queue when movie sold out or its too late for show
yield (request,self,tickets),(waitevent,self,[sold_out,too_late])
if self.acquired(tickets):
   # watch the movie
   yield hold,self,120
   yield release,self,tickets
else:
   # did not get a ticket
   print "Who needs to see this silly movie anyhow?"

Monitoring a resource

The section Monitors describes the use of Monitors in general.

If the argument monitored is set True for a resource, r, the length of the waiting queue, len(r.waitQ), and the active queue, len(r.activeQ), are both monitored automatically (see Monitors, below). This solves a problem, particularly for the waiting queue which cannot be monitored externally to the resource. The monitors are called r.waitMon and r.actMon, respectively.

The argument monitorType indicates which variety of monitor is to be used, either Monitor or Tally. The default is Monitor. If this is chosen, a complete time series for both queue lengths are maintained so that a graph of the queue length can be plotted and statistics, such as the time average can be found at any time. If Tally is chosen, statistics are accumulated continuously and time averages can be reported but, to save memory, no complete time series is kept. Histograms can be generated, though.

In this example, the resource, server is monitored, using the Tally variety of Monitor. The time-average of the length of each queue is calculated:

from SimPy.Simulation import *
class Client(Process):
     inClients=[]
     outClients=[]

     def __init__(self,name):
        Process.__init__(self,name)

     def getserved(self,servtime,myServer):
         print self.name, 'requests 1 unit at t=',now()
         yield request, self, myServer
         yield hold, self, servtime
         yield release, self,myServer
         print self.name,'done at t=',now()

initialize()
server=Resource(capacity=1,monitored=True,monitorType=Tally)
c1=Client(name='c1') ; c2=Client(name='c2')
c3=Client(name='c3') ; c4=Client(name='c4')
activate(c1,c1.getserved(servtime=100,myServer=server))
activate(c2,c2.getserved(servtime=100,myServer=server))
activate(c3,c3.getserved(servtime=100,myServer=server))
activate(c4,c4.getserved(servtime=100,myServer=server))
simulate(until=500)

print 'Average waiting',server.waitMon.timeAverage()
print 'Average in service',server.actMon.timeAverage()

The output from this program is:

c1 requests 1 unit at t= 0
c2 requests 1 unit at t= 0
c3 requests 1 unit at t= 0
c4 requests 1 unit at t= 0
c1 done at t= 100
c2 done at t= 200
c3 done at t= 300
c4 done at t= 400
Average waiting 1.5
Average in service 1.0

Random Number Generation

Simulation usually needs pseudo-random numbers. SimPy uses the standard Python random module. Its documentation should be consulted for details.

This can be used in two ways: you can import the methods directly or you can import the Random class and make your own random objects. This gives us multiple random streams, as in Simscript and ModSim. Each object gives a different pseudo-random sequence.

Here the first, simpler, method is described. A single pseudo-random sequence is used for all calls.

One imports the methods you need from the random module. For example:

A good range of distributions is available. For example:

This example uses exponential and normal random variables. The random object, g is initialised with its initial seed set to 333555. X and Y are pseudo-random variates from the two distributions using the object g:

from random import expovariate, normalvariate

X = expovariate(10.0)
Y = normalvariate(100.0, 5.0)

Monitors

Monitors are used to observe variables of interest and to return a simple data summary at any time during simulation run. Each monitoring object observes one variable. For example we might use one monitor to record the waiting times for a sequence of customers and another to record the total number of customers in the shop. In a discrete-event system the number of customers changes only at events and it is at these events that data is observed. Monitors are not intended as a complete substitute for real statistical analysis but they have proved useful in many simulations.

There are two varieties of monitoring objects, Tally and Monitor.

The simpler class, Tally, records enough information (sums and sums of squares) to return simple data summaries at any time. It has the advantage of speed and low memory use. It can collect data to produce a histogram.

The more complicated class, Monitor, keeps a complete series of observed data values, y, and associated times, t. It calculates the data summaries using these series only when they are needed. It is slower and uses more memory than Tally. In long simulations the memory demand may be a disadvantage.

Both varieties of monitor use the same observe method to record data on the variable.

Defining a Monitor

To define a new Tally object:

  • m=Tally(name=<string>, ylab=<string>, tlab=<string>)
    • name: is the name of the tally object. (default='a_Tally')
    • ylab and tlab are provided as labels for plotting graphs from the data held in the monitor using facilities in the SimPlot package (defaults= 'y' and 't', respectively). (If a histogram is required the method setHistogram must be called before observing starts)

To define a new Monitor object:

  • m=Monitor(name=<string>, ylab=<string>, tlab=<string>)
    • name: is the name of the Monitor object (default='a_monitor').
    • ylab and tlab are provided as labels for plotting graphs from the data held in the monitor using facilities in the SimPlot package (default='y' and 't', respectively). (If a histogram is required this can be requested at any time).

Observing data

Data is observed by the both varieties of monitor using the observe method. Here m is either a Tally or a Monitor object:

  • m.observe(y [,t]) records the current value of the variable, y and time t (the current time, now(), if t is missing). A Monitor retains the two values as a sublist [t,y]. The Tally uses them to update the accumulated statisics.

    To calculate time averages correctly observe should be called immediately after a change in the variable. For example, if we are monitoring the number of jobs in a system, N, using monitor m, the correct sequence of commands on an arrival is:

    N = N+1      # increment the number of jobs
    m.observe(N) # observe the new value of N using m
    

The recording of data can be reset to start at any time in the simulation:

  • m.reset([t]) resets the observations. The recorded data is re-initialised, and the starting time set to t or, if it is missing in the call, to the current simulation time, now().

Data Summaries

For both varieties of monitor, simple data summaries can be obtained:

  • m.count() the current number of observations. (In the case of a Monitor, M, this is the same as len(M)).

  • m.total() the sum of the y values

  • m.mean() the simple average of the observed y values, ignoring the times at which they were made. This is m.total()/m.count().

    If there are no observations, the message: 'SimPy: No observations for mean' is printed.

Standard mean value
  • m.var() the sample variance of the observations, ignoring the times at which they were made. This should be multiplied by n/(n-1), where n=m.count() to get an estimate of the population variance. The standard deviation is, of course, the square-root of this.

    If there are no observations, the message: 'SimPy: No observations for sample variance' is printed.

  • m.timeAverage([t]) the average of the time-weighted y graph, calculated from time 0 (or the last time m.reset([t]) was called) to time t (the current simulation time, now(), if t is missing). This is determined from the area under the graph shown in the figure, divided by the total time of observation. y is assumed to be continuous in time but changes in steps when observe(y) is called.

    If there are no observations, the message 'SimPy: No observations for timeAverage'. If no time has elapsed, the message 'SimPy: No elapsed time for timeAverage' is printed.

Time Average
  • m.__str__() is a string that briefly describes the current state of the monitor. This can be used in a print statement.

Special Monitor methods:

The Monitor variety is a sub-class of List and has a few extra methods:

  • m[i] holds the i th observation as a list, [ti, yi]
  • m.yseries() a list of the recorded data values, yi
  • m.tseries() a list of the recorded times, ti

Histograms

A histogram is an object that counts observations into a number of bins.

Histogram
  • h = histogram(low=<float>,high=<float>,nbins=<integer>) is a histogram object (a derived class of list) which contains the number of y values in each of its bins. It is calculated from the monitored y values. A histogram can be graphed using the plotHistogram method in the SimPlot package.
    • low is the lowest value of the histogram (default=0.0)
    • high is the highest value of the histogram (default=100.0)
    • nbins is the number of bins beween low and high into which the histogram is to be divided (default=10). The number of y values in each of the divisions is counted into the appropriate bin. Another 2 bins are constructed, counting the number of y values under the low value and the number over the high value. There are nbins+2 counts altogether.

Both varieties of monitor can return a histogram of the data but they handle histograms in different ways. The Tally object accumulates values for the histogram as each value is observed. The histogram must therefore be set up before any values are observed using the setHistogram method.

The Monitor object accumulates its values from the stored data series when needed. The histogram need not be set up until it is needed and this can be done after the data has been gathered.

Setting up a Histogram for the Tally class

To establish a Histogram for a Tally object, m, we call the setHistogram method with appropriate arguments before we observe any data, e.g.

  • m.setHistogram(name = '',low=0.0,high=100.0,nbins=10)

Then, after observing the data we need:

  • h = m.getHistogram() returns a completed histogram using the

    histogram parameters as set up.

In the following example we establish a Tally monitor to observe values of an exponential random variate. A histogram with 30 bins (plus an under and an over count) is required:

from SimPy.Simulation import *
from random import expovariate

m = Tally('Tally')
m.setHistogram(low=0.0,high=20.0,nbins=30)  # before  observations

for i in range(1000):
   y = expovariate(0.1)
   m.observe(y)

h = m.getHistogram()

Setting up a Histogram for the Monitor class

For Monitor objects, a histogram can be both set up and constructed in a single call, e.g.

  • h = m.histogram(low=0.0,high=100.0,nbins=10)

This call is equivalent to the following pair:

  • m.setHistogram(name = '',low=0.0,high=100.0,nbins=10)
  • h = m.getHistogram() returns the completed histogram.

In the following example we establish a Monitor to observe values of an exponential random variate. A histogram with 30 bins (plus an under and an over count) is required.

from SimPy.Simulation import *
from random import expovariate

M = Monitor()

for i in range(1000):
   y = expovariate(0.1)
   M.observe(y)

h = M.histogram(low=0.0, high=20, nbins=30)

Other Links

Several SimPy models are included with the SimPy code distribution.

Klaus Muller and Tony Vignaux, SimPy: Simulating Systems in Python, O'Reilly ONLamp.com, 2003-Feb-27, http://www.onlamp.com/pub/a/python/2003/02/27/simpy.html

Norman Matloff, Introduction to the SimPy Discrete-Event Simulation Package, U Cal: Davis, 2003, http://heather.cs.ucdavis.edu/~matloff/simpy.html

David Mertz, Charming Python: SimPy simplifies complex models, IBM Developer Works, Dec 2002, http://www-106.ibm.com/developerworks/linux/library/l-simpy.html

Acknowledgments

We will be grateful for any corrections or suggestions for improvements to the document.

Appendices

A1. SimPy Error Messages

Advisory messages

These messages are returned by simulate(), as in message=simulate(until=123).

Upon a normal end of a simulation, simulate() returns the message:

  • SimPy: Normal exit. This means that no errors have occurred and the simulation has run to the time specified by the until parameter.

The following messages, returned by simulate(), are produced at a premature termination of the simulation but allow continuation of the program.

  • SimPy: No more events at time x. All processes were completed prior to the endtime given in simulate(until=endtime).
  • SimPy: No activities scheduled. No activities were scheduled when simulate() was called.

Fatal error messages

These messages are generated when SimPy-related fatal exceptions occur. They end the SimPy program. Fatal SimPy error messages are output to sysout.

  • Fatal SimPy error: activating function which is not a generator (contains no 'yield'). A process tried to (re)activate a function which is not a SimPy process (=Python generator). SimPy processes must contain at least one yield . . . statement.
  • Fatal SimPy error: Simulation not initialized. The SimPy program called simulate() before calling initialize().

Monitor error messages

  • SimPy: No observations for mean. No observations were made by the monitor before attempting to calculate the mean.

  • SimPy: No observations for sample variance. No observations were made by the monitor before attempting to calculate the sample variance.

  • SimPy: No observations for timeAverage, No observations

    were made by the monitor before attempting to calculate the time-average.

  • SimPy: No elapsed time for timeAverage. No simulation time has elapsed before attempting to calculate the time-average.

A2. SimPy Process States

From the point of the model builder, at any time, a SimPy process, p, can be in one of the following states:

  • Active: Waiting for a scheduled event. This state simulates an activity in the model. Simulated time passes in this state. The process state p.active() returns True.
  • Passive: Not active or terminated. Awaiting (re-)activation by another process. This state simulates a real world process which has not finished and is waiting for some trigger to continue. Does not change simulation time. p.passive() returns True.
  • Terminated: The process has executed all its action statements and continues as a data instance, if referenced. p.terminated() returns True

Initially (upon creation of the Process instance), a process returns passive.

In addition, a SimPy process, p, can be in the following (sub)states:

  • Interrupted: Active process has been interrupted by another

    process. It can immediately respond to the interrupt. This simulates an interruption of a simulated activity before its scheduled completion time. p.interrupted() returns True.

  • Queuing: Active process has requested a busy resource and is waiting (passive) to be reactivated upon resource availability. p.queuing(a_resource) returns True.

A3. SimPlot, The Simpy plotting utility

SimPlot provides an easy way to graph the results of simulation runs.

A4. SimGUI, The Simpy Graphical User Interface

SimGUI provides a way for users to interact with a SimPy program, changing its parameters and examining the output.

A5. SimulationTrace, the SimPy tracing utility

SimulationTrace has been developed to give users insight into the dynamics of the execution of SimPy simulation programs. It can help developers with testing and users with explaining SimPy models to themselves and others (e.g. for documentation or teaching purposes).

A6. SimulationStep, the SimPy event stepping utility

SimulationStep can assist with debugging models, interacting with them on an event-by-event basis, getting event-by-event output from a model (e.g. for plotting purposes), etc.

It caters for:

  • running a simulation model, with calling a user-defined procedure after every event,
  • running a simulation model one event at a time by repeated calls,
  • starting and stopping the event stepping mode under program control.

A7. SimulationRT, a real-time synchronizing utility

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

Created:2003-April-6
SourceForge Logo