SimPy Manual

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 two particular methods and may define any others.

• __init__(self,...), where ... indicates method arguments. This function initializes 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
  

• A process execution method It 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. It can have arguments. Typically this can be called execute() or run() but, naturally, any name may be chosen.

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

  In this example of the process execution method for the same Message class, the message prints out the current time, its identification number and the word 'Starting'. After a simulated delay it tehn announces it has 'Arrived':

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

This is a complete, runnable, SimPy script. We declare a Message class and define __init__() and go() methods for it. Two messages, p1 and p2 are created. We do not actually use the len attribute in this example. p1 and p2 are activated to start at simulation times 0.0 and 6.0, respectively. Nothing happens until the simulate(until=200) statement. When they have both finished (at time 6.0+100.0=106.0) there will be no more events so the simulation will stop at that time:

from __future__ import generators
from SimPy.Simulation import *

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

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

initialize()
p1  = Message(1,203)
activate(p1,p1.go())
p2  = Message(2,33)
activate(p1,p1.go())
simulate(until=200)
print now() # will print 106.0

Elapsing time in a Process

An execution method 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 an execution method (buy) for a Customer class demonstrates that the method can have arguments which can be used in the activation. The Customer also has an identification attribute id. The yield hold is executed 4 times:

  def buy(self,budget=0):
     print 'Here I am at the shops ',self.id
     t = 5.0
     for i in range(4):
         yield hold,self,t
         print 'I just bought something ',self.id
         budget -= 10.00
     print   'All I have left is ', budget,\
             ' I am going home ',self.id,
  
  initialize()
  C = Customer(1)
  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.execute(args),at=t,delay=period,prior=boolean) will activate the execution method p.execute() of Process instance, p with arguments args. The default action is to activate at the current time, otherwise one of the optional timing clauses operate. If prior 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, . . . 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 prrocess becomes 'terminated'. If the instance is still referenced, it becomes just a data container. Otherwise, it is automatically destroyed.

And, finally,

• stopSimulation() stops all simulation activity, even if some processes still have events scheduled.

Asynchronous interruptions

A process (interruptor) can interrupt a second, active process (the victim). A process cannot interrupt itself.

• self.interrupt(victim)

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

The victim must be active. An active process 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. As processes queuing for resources are passive, they cannot be interrupted. Active processes which have acquired a resource can be interrupted.

If interrupted, the victim returns from its yield hold prematurely. It can sense 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 this is True:
  • self.interruptCause is a reference to the interruptor 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 a complete example of a simulation with interrupts. Notice that in the first yield hold, interrupts may occur, so a reaction to the interrupt (= repair) has been programmed:

  class Bus(Process):
    def __init__(self,name):
       Process.__init__(self,name)
  
    def operate(self,repairduration,triplength):  # process execution method
       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)
  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.

Starting the simulation

Even activated processes will not start until the following statement has been executed:

• simulate(until=T) 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

This complete runnable script simulates a firework with a time fuse. I have put in a few extra yield hold commands for added suspense:

from __future__ import generators
from SimPy.Simulation import *

class Firework(Process):
   def __init__(self):
       Process.__init__(self)

   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. An example is shown in Example ). This is an object 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 a source with random (exponential) intervals between activations.

A source object 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. 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 examples assumes that the Customer class has been defined with an execute method called run:

class Source(Process):
   def __init__(self,finish):
       Process.__init__(self)
       self.finishTime = finish

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

initialize()
g = Source(33.0)
activate(g,g.schedule(),at=0.0)
simulate(until=100)

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

where 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.

A complete script. Four clients of 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 __future__ import generators
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

The output from Example:

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, the one with the lowest priority is suspended, put at the front of the waitQ and the higher priority 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.

A complete script. Two clients of different priority compete for the same resource unit:

from __future__ import generators
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)

Defining a monitor

To define a new Monitor object:

• m=Monitor(name='')

Where name is the name of the monitor object.

Methods of the Monitor class include:

• m.tally(x) adds the value x to the current totals in the Monitor. This is used for observing the mean and variance of a series of individual observations of x.
• m.accum(x) adds the accumulated integral of time and x to the current totals. In fact it used the value of the previous value of x observed last time accumulate was used multiplied by the time difference. It is used to approximate the time integral of x.
• m.reset(t) resets all the current totals. Sets the starting time to t or, if it is missing, to the current simulation time.

Simple statistics can be obtained from such a Monitor object.

• m.count() returns the current number of observations.
• m.mean() returns the simple average of the observations. If there are no observations, the message: "zero observations for mean()" is printed.
• m.var() returns the variance of the observations. If there are no observations, the message: "zero observations for variance" is printed.
• m.timeAverage(t) returns the time-average of accumulated values, measured at time t (the current simulation time if t is missing). If no time has elapsed, the message "zero time elapsed in timeAverage" is printed.
• m.__str__() is a string that briefly describes the current state of the monitor. This can be used in a print statement.

Reminder: We tally variables that are individual observations, such as waiting times; we accumulate variables that are continuous in time s0 as to get a time averge. For example, the length of a queue does change discretely but it has some value at any time in contrast to a waiting time which is a mesurement taken at one time.

Here we establish a monitor to estimate the mean and variance of ten observations of an exponential random variate:

from SimPy.Monitor import Monitor
from random import Random

M = Monitor()
g = Random()

for i in range(10):
   x = g.expovariate(0.1)
   M.tally(x)

print 'mean= ',M.mean(), 'var= ',M.var()

Here the queue waiting for the Resource r is to be monitored to estimate the average of the number of processes waiting or using it. (This example is only fragmentary):

from __future__ import generators
from SimPy.Monitor import Monitor
from SimPy.Simulation import *

r = Resource(u)
M = Monitor()

   ...   # during  the simulation
   Qlength = len(r.waitQ)
   M.accum(Qlength) 
   ...

print 'mean= ',M.timeAverage()

trace.tchange(): Changing the tracing

trace is an instance to the Trace class defined in SimulationTrace.py. This gets imported.

The tracing can be changed at runtime by calling trace.tchange() with one or more of the following named parameters:

start:

changes the tracing start time. Default is 0. Example: trace.tchange(start=222.2) to start tracing at simulation time 222.2.

end :

changes the tracing end time. Default is a very large number (hopefully past any simulation endtime you will ever use. Example: trace.tchange(end=33) to stop tracing at time 33.

toTrace:

changes the commands to be traced. Default is ["hold","activate","cancel", "reactivate","passivate","request","release","interrupt","terminated"]. Value must be a list containing one or more of those values in the default. Note: "terminated" causes tracing of all process terminations. Example: trace.tchange(toTrace=["hold","activate"]) traces only the yield hold and activate() statements.

outfile:

redirects the trace out put to a file (default is sys.stdout). Value must be a file object open for writing. Example: trace.tchange(outfile=open(r"c:python22bank02trace.txt","w"))

All these parameters can be combined. Example: trace.tchange(start=45.0,toTrace=["terminated"]) will trace all process terminations from time 45.0 till the end of the simulation.

The changes become effective at the time trace.tchange() is called. This implies for example that, if the call trace.tchange(start=50) is made at time 100, it has no effect before now()==100.

treset(): Resetting the trace to default values

The trace parameters can be reset to their default values by calling trace.treset().

trace.tstart(), trace.tend(): Enabling/disabling the trace

Calling trace.tstart() enables the tracing, and trace.tstop() disables it. Neither call changes any tracing parameters.

trace.ttext(): Annotating the trace

The event-by-event trace output is already very useful in showing the sequence in which SimPy's quasi-parallel processes are executed.

For documentation, publishing or teaching purposes, it is even more useful if the trace output can be intermingled with output which not only shows the command executed, but also contextual information such as the values of state variables. If one outputs the reason why a specific scheduling command is executed, the trace can give a natural language description of the simulation scenario.

For such in-line annotation, the trace.ttext(<string>) method is available. It provides a string which is output together with the trace of the next scheduling statement. This string is valid only for the scheduling statement following it.

Example:

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

     def operate(self,repairduration=0):
         tripleft = 1000
         while tripleft > 0:
             trace.ttext("Try to go for %s"%tripleft)
             yield hold,self,tripleft
             if self.interrupted():
                 tripleft=self.interruptLeft
                 self.interruptReset()
                 trace.ttext("Start repair taking %s time units"%repairduration)
                 yield hold,self,repairduration
             else:
                 break # no breakdown, ergo bus arrived
         trace.ttext("<%s> has arrived"%self.name)

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

     def breakBus(self,interval):

         while True:
             trace.ttext("Breakdown process waiting for %s"%interval)
             yield hold,self,interval
             if self.bus.terminated(): break
             trace.ttext("Breakdown of %s"%self.bus.name)
             self.interrupt(self.bus)
             
 print"\n\n+++test_interrupt"
 initialize()
 b=Bus("Bus 1")
 trace.ttext("Start %s"%b.name)
 activate(b,b.operate(repairduration=20))
 br=Breakdown(b)
 trace.ttext("Start the Breakdown process for %s"%b.name)
 activate(br,br.breakBus(200))
 trace.start=100
 print simulate(until=4000)

 This produces:

 0 activate <Bus 1> at time: 0 prior: 0
 ---- Start Bus 1
 0 activate <Breakdown Bus 1> at time: 0 prior: 0
 ---- Start the Breakdown process for Bus 1
 200 reactivate <Bus 1> time: 200 prior: 0
 200 interrupt by: <Breakdown Bus 1> of: <Bus 1>
 ---- Breakdown of Bus 1
 200 hold <Breakdown Bus 1> delay: 200
 ---- Breakdown process waiting for 200
 200 hold <Bus 1> delay: 20
 ---- Start repair taking 20 time units
 220 hold <Bus 1> delay: 800
 ---- Try to go for 800
 400 reactivate <Bus 1> time: 400 prior: 0
 400 interrupt by: <Breakdown Bus 1> of: <Bus 1>
 ---- Breakdown of Bus 1
 400 hold <Breakdown Bus 1> delay: 200
 ---- Breakdown process waiting for 200
 400 hold <Bus 1> delay: 20
 ---- Start repair taking 20 time units
 420 hold <Bus 1> delay: 620

  . . . . . 

The line starting with "----" is the comment related to the command traced in the preceding output line.

Nice output of class instances

After the import of SimPy.SimulationTrace, all instances of classes Process and Resource (and all their subclasses) have a nice string representation like so:

   >>> class Bus(Process):
...         def __init__(self,id):
...                 Process.__init__(self,name=id)
...                 self.typ="Bus"
...                 
>>> b=Bus("Line 15")
>>> b
<Instance of Bus, id 21860960:
     .name=Line 15
     .typ=Bus
>
>>> 

This can be handy in statements like trace.ttext("Status of %s"%b).