Documentation for SimPy¶

Upgrading from SimPy 2¶

If you are already familiar with SimPy 2, please read the Guide Porting from SimPy 2 to 3.

What’s Next¶

Now that you’ve installed SimPy, you probably want to simulate something. The next section will introduce you to SimPy’s basic concepts.

Our First Process¶

Our first example will be a car process. The car will alternately drive and park for a while. When it starts driving (or parking), it will print the current simulation time.

So let’s start:

>>> def car(env):
...     while True:
...         print('Start parking at %d' % env.now)
...         parking_duration = 5
...         yield env.timeout(parking_duration)
...
...         print('Start driving at %d' % env.now)
...         trip_duration = 2
...         yield env.timeout(trip_duration)

Our car process requires a reference to an Environment (env) in order to create new events. The car‘s behavior is described in an infinite loop. Remember, this function is a generator. Though it will never terminate, it will pass the control flow back to the simulation once a yield statement is reached. Once the yielded event is triggered (“it occurs”), the simulation will resume the function at this statement.

As I said before, our car switches between the states parking and driving. It announces its new state by printing a message and the current simulation time (as returned by the Environment.now property). It then calls the Environment.timeout() factory function to create a Timeout event. This event describes the point in time the car is done parking (or driving, respectively). By yielding the event, it signals the simulation that it wants to wait for the event to occur.

Now that the behavior of our car has been modeled, lets create an instance of it and see how it behaves:

>>> import simpy
>>> env = simpy.Environment()
>>> env.process(car(env))
<Process(car) object at 0x...>
>>> env.run(until=15)
Start parking at 0
Start driving at 5
Start parking at 7
Start driving at 12
Start parking at 14

The first thing we need to do is to create an instance of Environment. This instance is passed into our car process function. Calling it creates a process generator that needs to be started and added to the environment via Environment.process().

Note, that at this time, none of the code of our process function is being executed. Its execution is merely scheduled at the current simulation time.

The Process returned by process() can be used for process interactions (we will cover that in the next section, so we will ignore it for now).

Finally, we start the simulation by calling run() and passing an end time to it.

What’s Next?¶

You should now be familiar with Simpy’s terminology and basic concepts. In the next section, we will cover process interaction.

Waiting for a Process¶

As it happens, a SimPy Process can be used like an event (technically, a process actually is an event). If you yield it, you are resumed once the process has finished. Imagine a car-wash simulation where cars enter the car-wash and wait for the washing process to finish. Or an airport simulation where passengers have to wait until a security check finishes.

Lets assume that the car from our last example magically became an electric vehicle. Electric vehicles usually take a lot of time charging their batteries after a trip. They have to wait until their battery is charged before they can start driving again.

We can model this with an additional charge() process for our car. Therefore, we refactor our car to be a class with two process methods: run() (which is the original car() process function) and charge().

The run process is automatically started when Car is instantiated. A new charge process is started every time the vehicle starts parking. By yielding the Process instance that Environment.process() returns, the run process starts waiting for it to finish:

>>> class Car(object):
...     def __init__(self, env):
...         self.env = env
...         # Start the run process everytime an instance is created.
...         self.action = env.process(self.run())
...
...     def run(self):
...         while True:
...             print('Start parking and charging at %d' % self.env.now)
...             charge_duration = 5
...             # We yield the process that process() returns
...             # to wait for it to finish
...             yield self.env.process(self.charge(charge_duration))
...
...             # The charge process has finished and
...             # we can start driving again.
...             print('Start driving at %d' % self.env.now)
...             trip_duration = 2
...             yield self.env.timeout(trip_duration)
...
...     def charge(self, duration):
...         yield self.env.timeout(duration)

Starting the simulation is straight forward again: We create an environment, one (or more) cars and finally call meth:~Environment.simulate().

>>> import simpy
>>> env = simpy.Environment()
>>> car = Car(env)
>>> env.run(until=15)
Start parking and charging at 0
Start driving at 5
Start parking and charging at 7
Start driving at 12
Start parking and charging at 14

Interrupting Another Process¶

Imagine, you don’t want to wait until your electric vehicle is fully charged but want to interrupt the charging process and just start driving instead.

SimPy allows you to interrupt a running process by calling its interrupt() method:

>>> def driver(env, car):
...     yield env.timeout(3)
...     car.action.interrupt()

The driver process has a reference to the car’s action process. After waiting for 3 time steps, it interrupts that process.

Interrupts are thrown into process functions as Interrupt exceptions that can (should) be handled by the interrupted process. The process can than decide what to do next (e.g., continuing to wait for the original event or yielding a new event):

>>> class Car(object):
...     def __init__(self, env):
...         self.env = env
...         self.action = env.process(self.run())
...
...     def run(self):
...         while True:
...             print('Start parking and charging at %d' % self.env.now)
...             charge_duration = 5
...             # We may get interrupted while charging the battery
...             try:
...                 yield self.env.process(self.charge(charge_duration))
...             except simpy.Interrupt:
...                 # When we received an interrupt, we stop charing and
...                 # switch to the "driving" state
...                 print('Was interrupted. Hope, the battery is full enough ...')
...
...             print('Start driving at %d' % self.env.now)
...             trip_duration = 2
...             yield self.env.timeout(trip_duration)
...
...     def charge(self, duration):
...         yield self.env.timeout(duration)

When you compare the output of this simulation with the previous example, you’ll notice that the car now starts driving at time 3 instead of 5:

>>> env = simpy.Environment()
>>> car = Car(env)
>>> env.process(driver(env, car))
<Process(driver) object at 0x...>
>>> env.run(until=15)
Start parking and charging at 0
Was interrupted. Hope, the battery is full enough ...
Start driving at 3
Start parking and charging at 5
Start driving at 10
Start parking and charging at 12

What’s Next¶

We just demonstrated two basic methods for process interactions—waiting for a process and interrupting a process. Take a look at the Topical Guides or the Process API reference for more details.

In the next section we will cover the basic usage of shared resources.

Basic Resource Usage¶

We’ll slightly modify our electric vehicle process car that we introduced in the last sections.

The car will now drive to a battery charging station (BCS) and request one of its two charging spots. If both of these spots are currently in use, it waits until one of them becomes available again. It then starts charging its battery and leaves the station afterwards:

>>> def car(env, name, bcs, driving_time, charge_duration):
...     # Simulate driving to the BCS
...     yield env.timeout(driving_time)
...
...     # Request one of its charging spots
...     print('%s arriving at %d' % (name, env.now))
...     with bcs.request() as req:
...         yield req
...
...         # Charge the battery
...         print('%s starting to charge at %s' % (name, env.now))
...         yield env.timeout(charge_duration)
...         print('%s leaving the bcs at %s' % (name, env.now))

The resource’s request() method generates an event that lets you wait until the resource becomes available again. If you are resumed, you “own” the resource until you release it.

If you use the resource with the with statement as shown above, the resource is automatically being released. If you call request() without with, you are responsible to call release() once you are done using the resource.

When you release a resource, the next waiting process is resumed and now “owns” one of the resource’s slots. The basic Resource sorts waiting processes in a FIFO (first in—first out) way.

A resource needs a reference to an Environment and a capacity when it is created:

>>> import simpy
>>> env = simpy.Environment()
>>> bcs = simpy.Resource(env, capacity=2)

We can now create the car processes and pass a reference to our resource as well as some additional parameters to them:

>>> for i in range(4):
...     env.process(car(env, 'Car %d' % i, bcs, i*2, 5))
<Process(car) object at 0x...>
<Process(car) object at 0x...>
<Process(car) object at 0x...>
<Process(car) object at 0x...>

Finally, we can start the simulation. Since the car processes all terminate on their own in this simulation, we don’t need to specify an until time—the simulation will automatically stop when there are no more events left:

>>> env.run()
Car 0 arriving at 0
Car 0 starting to charge at 0
Car 1 arriving at 2
Car 1 starting to charge at 2
Car 2 arriving at 4
Car 0 leaving the bcs at 5
Car 2 starting to charge at 5
Car 3 arriving at 6
Car 1 leaving the bcs at 7
Car 3 starting to charge at 7
Car 2 leaving the bcs at 10
Car 3 leaving the bcs at 12

Note that the first two cars can start charging immediately after they arrive at the BCS, while cars 2 an 3 have to wait.

What’s Next¶

You should now be familiar with SimPy’s basic concepts. The next section shows you how you can proceed with using SimPy from here on.

How SimPy works¶

If you break SimPy down, it is just an asynchronous event dispatcher. You generate events and schedule them at a given simulation time. Events are sorted by priority, simulation time, and an increasing event id. An event also has a list of callbacks, which are executed when the event is triggered and processed by the event loop. Events may also have a return value.

The components involved in this are the Environment, events and the process functions that you write.

Process functions implement your simulation model, that is, they define the behavior of your simulation. They are plain Python generator functions that yield instances of Event.

The environment stores these events in its event list and keeps track of the current simulation time.

If a process function yields an event, SimPy adds the process to the event’s callbacks and suspends the process until the event is triggered and processed. When a process waiting for an event is resumed, it will also receive the event’s value.

Here is a very simple example that illustrates all this; the code is more verbose than it needs to be to make things extra clear. You find a compact version of it at the end of this section:

>>> import simpy
>>>
>>> def example(env):
...     event = simpy.events.Timeout(env, delay=1, value=42)
...     value = yield event
...     print('now=%d, value=%d' % (env.now, value))
>>>
>>> env = simpy.Environment()
>>> example_gen = example(env)
>>> p = simpy.events.Process(env, example_gen)
>>>
>>> env.run()
now=1, value=42

The example() process function above first creates a Timeout event. It passes the environment, a delay, and a value to it. The Timeout schedules itself at now + delay (that’s why the environment is required); other event types usually schedule themselves at the current simulation time.

The process function then yields the event and thus gets suspended. It is resumed, when SimPy processes the Timeout event. The process function also receives the event’s value (42) – this is, however, optional, so yield event would have been okay if the you were not interested in the value or if the event had no value at all.

Finally, the process function prints the current simulation time (that is accessible via the environment’s now attribute) and the Timeout’s value.

If all required process functions are defined, you can instantiate all objects for your simulation. In most cases, you start by creating an instance of Environment, because you’ll need to pass it around a lot when creating everything else.

Starting a process function involves two things:

1. You have to call the process function to create a generator object. (This will not execute any code of that function yet. Please read The Python yield keyword explained, to understand why this is the case.)
2. You then create an instance of Process and pass the environment and the generator object to it. This will schedule an Initialize event at the current simulation time which starts the execution of the process function. The process instance is also an event that is triggered when the process function returns. The guide to events explains why this is handy.

Finally, you can start SimPy’s event loop. By default, it will run as long as there are events in the event list, but you can also let it stop earlier by providing an until argument (see Simulation control).

The following guides describe the environment and its interactions with events and process functions in more detail.

“Best practice” version of the example above¶

>>> import simpy
>>>
>>> def example(env):
...     value = yield env.timeout(1, value=42)
...     print('now=%d, value=%d' % (env.now, value))
>>>
>>> env = simpy.Environment()
>>> p = env.process(example(env))
>>> env.run()
now=1, value=42

Simulation control¶

SimPy is very flexible in terms of simulation execution. You can run your simulation until there are no more events, until a certain simulation time is reached, or until a certain event is triggered. You can also step through the simulation event by event. Furthermore, you can mix these things as you like.

For example, you could run your simulation until an interesting event occurs. You could then step through the simulation event by event for a while; and finally run the simulation until there are no more events left and your processes have all terminated.

The most important method here is Environment.run():

• If you call it without any argument (env.run()), it steps through the simulation until there are no more events left.

  Warning

  If your processes run forever (while True: yield env.timeout(1)), this method will never terminate (unless you kill your script by e.g., pressing Ctrl-C).

• In most cases it is advisable to stop your simulation when it reaches a certain simulation time. Therefore, you can pass the desired time via the until parameter, e.g.: env.run(until=10).

  The simulation will then stop when the internal clock reaches 10 but will not process any events scheduled for time 10. This is similar to a new environment where the clock is 0 but (obviously) no events have yet been processed.

  If you want to integrate your simulation in a GUI and want to draw a process bar, you can repeatedly call this function with increasing until values and update your progress bar after each call:

  for i in range(100):
      env.run(until=i)
      progressbar.update(i)
  

• Instead of passing a number to run(), you can also pass any event to it. run() will then return when the event has been processed.

  Assuming that the current time is 0, env.run(until=env.timeout(5)) is equivalent to env.run(until=5).

  You can also pass other types of events (remember, that a Process is an event, too):

  >>> import simpy
  >>>
  >>> def my_proc(env):
  ...     yield env.timeout(1)
  ...     return 'Monty Python’s Flying Circus'
  >>>
  >>> env = simpy.Environment()
  >>> proc = env.process(my_proc(env))
  >>> env.run(until=proc)
  'Monty Python’s Flying Circus'
  

To step through the simulation event by event, the environment offers peek() and step().

peek() returns the time of the next scheduled event of infinity (float('inf')) of no more event is scheduled.

step() processes the next scheduled event. It raises an EmptySchedule exception if no event is available.

In a typical use case, you use these methods in a loop like:

until = 10
while env.peek() < until:
   env.step()

State access¶

The environment allows you to get the current simulation time via the Environment.now property. The simulation time is a number without unit and is increased via Timeout events.

By default, now starts at 0, but you can pass an initial_time to the Environment to use something else.

The property Environment.active_process is comparable to os.getpid() and is either None or pointing at the currently active Process. A process is active when its process function is being executed. It becomes inactive (or suspended) when it yields an event.

Thus, it only makes sense to access this property from within a process function or a function that is called by your process function:

>>> def subfunc(env):
...     print(env.active_process)  # will print "p1"
>>>
>>> def my_proc(env):
...     while True:
...         print(env.active_process)  # will print "p1"
...         subfunc(env)
...         yield env.timeout(1)
>>>
>>> env = simpy.Environment()
>>> p1 = env.process(my_proc(env))
>>> env.active_process  # None
>>> env.step()
<Process(my_proc) object at 0x...>
<Process(my_proc) object at 0x...>
>>> env.active_process  # None

An exemplary use case for this is the resource system: If a process function calls request() to request a resource, the resource determines the requesting process via env.active_process. Take a look at the code to see how we do this :-).

Event creation¶

To create events, you normally have to import simpy.events, instantiate the event class and pass a reference to the environment to it. To reduce the amount of typing, the Environment provides some shortcuts for event creation. For example, Environment.event() is equivalent to simpy.events.Event(env).

Other shortcuts are:

• Environment.process()
• Environment.timeout()
• Environment.all_of()
• Environment.any_of()

More details on what the events do can be found in the guide to events.

Miscellaneous¶

Since Python 3.3, a generator function can have a return value:

def my_proc(env):
    yield env.timeout(1)
    return 42

In SimPy, this can be used to provide return values for processes that can be used by other processes:

def other_proc(env):
    ret_val = yield env.process(my_proc(env))
    assert ret_val == 42

Internally, Python passes the return value as parameter to the StopIteration exception that it raises when a generator is exhausted. So in Python 2.7 and 3.2 you could replace the return 42 with a raise StopIteration(42) to achieve the same result.

To keep your code more readable, the environment provides the method exit() to do exactly this:

def my_proc(env):
    yield env.timeout(1)
    env.exit(42)  # Py2 equivalent to "return 42"

Event basics¶

SimPy events are very similar – if not identical — to deferreds, futures or promises. Instances of the class Event are used to describe any kind of events. Events can be in one of the following states. An event

• might happen (not triggered),
• is going to happen (triggered) or
• has happened (processed).

They traverse these states exactly once in that order. Events are also tightly bound to time and time causes events to advance their state.

Initially, events are not triggered and just objects in memory.

If an event gets triggered, it is scheduled at a given time and inserted into SimPy’s event queue. The property Event.triggered becomes True.

As long as the event is not processed, you can add callbacks to an event. Callbacks are callables that accept an event as parameter and are stored in the Event.callbacks list.

An event becomes processed when SimPy pops it from the event queue and calls all of its callbacks. It is now no longer possible to add callbacks. The property Event.processed becomes True.

Events also have a value. The value can be set before or when the event is triggered and can be retrieved via Event.value or, within a process, by yielding the event (value = yield event).

>>> import simpy
>>>
>>> def my_callback(event):
...     print('Called back from', event)
...
>>> env = simpy.Environment()
>>> event = env.event()
>>> event.callbacks.append(my_callback)
>>> event.callbacks
[<function my_callback at 0x...>]

Example usages for Event¶

The simple mechanics outlined above provide a great flexibility in the way events (even the basic Event) can be used.

One example for this is that events can be shared. They can be created by a process or outside of the context of a process. They can be passed to other processes and chained:

>>> class School:
...     def __init__(self, env):
...         self.env = env
...         self.class_ends = env.event()
...         self.pupil_procs = [env.process(self.pupil()) for i in range(3)]
...         self.bell_proc = env.process(self.bell())
...
...     def bell(self):
...         for i in range(2):
...             yield self.env.timeout(45)
...             self.class_ends.succeed()
...             self.class_ends = self.env.event()
...             print()
...
...     def pupil(self):
...         for i in range(2):
...             print(' \o/', end='')
...             yield self.class_ends
...
>>> school = School(env)
>>> env.run()
 \o/ \o/ \o/
 \o/ \o/ \o/

This can also be used like the passivate / reactivate known from SimPy 2. The pupils passivate when class begins and are reactivated when the bell rings.

Let time pass by: the Timeout¶

To actually let time pass in a simulation, there is the timeout event. A timeout has two parameters: a delay and an optional value: Timeout(delay, value=None). It triggers itself during its creation and schedules itself at now + delay. Thus, the succeed() and fail() methods cannot be called again and you have to pass the event value to it when you create the timeout.

The delay can be any kind of number, usually an int or float as long as it supports comparison and addition.

Processes are events, too¶

SimPy processes (as created by Process or env.process()) have the nice property of being events, too.

That means, that a process can yield another process. It will then be resumed when the other process ends. The event’s value will be the return value of that process:

>>> def sub(env):
...     yield env.timeout(1)
...     return 23
...
>>> def parent(env):
...     ret = yield env.process(sub(env))
...     return ret
...
>>> env.run(env.process(parent(env)))
23

The example above will only work in Python >= 3.3. As a workaround for older Python versions, you can use env.exit(23) with the same effect.

When a process is created, it schedules an Initialize event which will start the execution of the process when triggered. You usually won’t have to deal with this type of event.

If you don’t want a process to start immediately but after a certain delay, you can use simpy.util.start_delayed(). This method returns a helper process that uses a timeout before actually starting a process.

The example from above, but with a delayed start of sub():

>>> from simpy.util import start_delayed
>>>
>>> def sub(env):
...     yield env.timeout(1)
...     return 23
...
>>> def parent(env):
...     start = env.now
...     sub_proc = yield start_delayed(env, sub(env), delay=3)
...     assert env.now - start == 3
...
...     ret = yield sub_proc
...     return ret
...
>>> env.run(env.process(parent(env)))
23

Waiting for multiple events at once¶

Sometimes, you want to wait for more than one event at the same time. For example, you may want to wait for a resource, but not for an unlimited amount of time. Or you may want to wait until all a set of events has happened.

SimPy therefore offers the AnyOf and AllOf events which both are a Condition event.

Both take a list of events as an argument and are triggered if at least one or all of them of them are triggered.

>>> from simpy.events import AnyOf, AllOf, Event
>>> events = [Event(env) for i in range(3)]
>>> a = AnyOf(env, events)  # Triggers if at least one of "events" is triggered.
>>> b = AllOf(env, events)  # Triggers if all each of "events" is triggered.

The value of a condition event is an ordered dictionary with an entry for every triggered event. In the case of AllOf, the size of that dictionary will always be the same as the length of the event list. The value dict of AnyOf will have at least one entry. In both cases, the event instances are used as keys and the event values will be the values.

As a shorthand for AllOf and AnyOf, you can also use the logical operators & (and) and | (or):

>>> def test_condition(env):
...     t1, t2 = env.timeout(1, value='spam'), env.timeout(2, value='eggs')
...     ret = yield t1 | t2
...     assert ret == {t1: 'spam'}
...
...     t1, t2 = env.timeout(1, value='spam'), env.timeout(2, value='eggs')
...     ret = yield t1 & t2
...     assert ret == {t1: 'spam', t2: 'eggs'}
...
...     # You can also concatenate & and |
...     e1, e2, e3 = [env.timeout(i) for i in range(3)]
...     yield (e1 | e2) & e3
...     assert all(e.triggered for e in [e1, e2, e3])
...
>>> proc = env.process(test_condition(env))
>>> env.run()

The order of condition results is identical to the order in which the condition events were specified. This allows the following idiom for conveniently fetching the values of multiple events specified in an and condition (including AllOf):

>>> def fetch_values_of_multiple_events(env):
...     t1, t2 = env.timeout(1, value='spam'), env.timeout(2, value='eggs')
...     r1, r2 = (yield t1 & t2).values()
...     assert r1 == 'spam' and r2 == 'eggs'
...
>>> proc = env.process(fetch_values_of_multiple_events(env))
>>> env.run()

Sleep until woken up¶

Imagine you want to model an electric vehicle with an intelligent battery-charging controller. While the vehicle is driving, the controller can be passive but needs to be reactivate once the vehicle is connected to the power grid in order to charge the battery.

In SimPy 2, this pattern was known as passivate / reactivate. In SimPy 3, you can accomplish that with a simple, shared Event:

>>> from random import seed, randint
>>> seed(23)
>>>
>>> import simpy
>>>
>>> class EV:
...     def __init__(self, env):
...         self.env = env
...         self.drive_proc = env.process(self.drive(env))
...         self.bat_ctrl_proc = env.process(self.bat_ctrl(env))
...         self.bat_ctrl_reactivate = env.event()
...
...     def drive(self, env):
...         while True:
...             # Drive for 20-40 min
...             yield env.timeout(randint(20, 40))
...
...             # Park for 1–6 hours
...             print('Start parking at', env.now)
...             self.bat_ctrl_reactivate.succeed()  # "reactivate"
...             self.bat_ctrl_reactivate = env.event()
...             yield env.timeout(randint(60, 360))
...             print('Stop parking at', env.now)
...
...     def bat_ctrl(self, env):
...         while True:
...             print('Bat. ctrl. passivating at', env.now)
...             yield self.bat_ctrl_reactivate  # "passivate"
...             print('Bat. ctrl. reactivated at', env.now)
...
...             # Intelligent charging behavior here …
...             yield env.timeout(randint(30, 90))
...
>>> env = simpy.Environment()
>>> ev = EV(env)
>>> env.run(until=150)
Bat. ctrl. passivating at 0
Start parking at 29
Bat. ctrl. reactivated at 29
Bat. ctrl. passivating at 60
Stop parking at 131

Since bat_ctrl() just waits for a normal event, we no longer call this pattern passivate / reactivate in SimPy 3.

Waiting for another process to terminate¶

The example above has a problem: it may happen that the vehicles wants to park for a shorter duration than it takes to charge the battery (this is the case if both, charging and parking would take 60 to 90 minutes).

To fix this problem we have to slightly change our model. A new bat_ctrl() will be started every time the EV starts parking. The EV then waits until the parking duration is over and until the charging has stopped:

>>> class EV:
...     def __init__(self, env):
...         self.env = env
...         self.drive_proc = env.process(self.drive(env))
...
...     def drive(self, env):
...         while True:
...             # Drive for 20-40 min
...             yield env.timeout(randint(20, 40))
...
...             # Park for 1–6 hours
...             print('Start parking at', env.now)
...             charging = env.process(self.bat_ctrl(env))
...             parking = env.timeout(randint(60, 360))
...             yield charging & parking
...             print('Stop parking at', env.now)
...
...     def bat_ctrl(self, env):
...         print('Bat. ctrl. started at', env.now)
...         # Intelligent charging behavior here …
...         yield env.timeout(randint(30, 90))
...         print('Bat. ctrl. done at', env.now)
...
>>> env = simpy.Environment()
>>> ev = EV(env)
>>> env.run(until=310)
Start parking at 29
Bat. ctrl. started at 29
Bat. ctrl. done at 83
Stop parking at 305

Again, nothing new (if you’ve read the Events guide) and special is happening. SimPy processes are events, too, so you can yield them and will thus wait for them to get triggered. You can also wait for two events at the same time by concatenating them with & (see Waiting for multiple events at once).

Interrupting another process¶

As usual, we now have another problem: Imagine, a trip is very urgent, but with the current implementation, we always need to wait until the battery is fully charged. If we could somehow interrupt that ...

Fortunate coincidence, there is indeed a way to do exactly this. You can call interrupt() on a Process. This will throw an Interrupt exception into that process, resuming it immediately:

>>> class EV:
...     def __init__(self, env):
...         self.env = env
...         self.drive_proc = env.process(self.drive(env))
...
...     def drive(self, env):
...         while True:
...             # Drive for 20-40 min
...             yield env.timeout(randint(20, 40))
...
...             # Park for 1 hour
...             print('Start parking at', env.now)
...             charging = env.process(self.bat_ctrl(env))
...             parking = env.timeout(60)
...             yield charging | parking
...             if not charging.triggered:
...                 # Interrupt charging if not already done.
...                 charging.interrupt('Need to go!')
...             print('Stop parking at', env.now)
...
...     def bat_ctrl(self, env):
...         print('Bat. ctrl. started at', env.now)
...         try:
...             yield env.timeout(randint(60, 90))
...             print('Bat. ctrl. done at', env.now)
...         except simpy.Interrupt as i:
...             # Onoes! Got interrupted before the charging was done.
...             print('Bat. ctrl. interrupted at', env.now, 'msg:',
...                   i.cause)
...
>>> env = simpy.Environment()
>>> ev = EV(env)
>>> env.run(until=100)
Start parking at 31
Bat. ctrl. started at 31
Stop parking at 91
Bat. ctrl. interrupted at 91 msg: Need to go!

What process.interrupt() actually does is scheduling an Interruption event for immediate execution. If this event is executed it will remove the victim process’ _resume() method from the callbacks of the event that it is currently waiting for (see target). Following that it will throw the Interrupt exception into the process.

Since we don’t to anything special to the original target event of the process, the interrupted process can yield the same event again after catching the Interrupt – Imagine someone waiting for a shop to open. The person may get interrupted by a phone call. After finishing the call, he or she checks if the shop already opened and either enters or continues to wait.

The basic concept of resources¶

All resources share the same basic concept: The resource itself is some kind of a container with a, usually limited, capacity. Processes can either try to put something into the resource or try to get something out. If the resource is full or empty, they have to queue up and wait.

This is roughly, how every resource looks like:

BaseResource(capacity):
   put_queue
   get_queue

   put(): event
   get(): event

Every resources a maximum capacity and two queues, one for processes that want to put something into it and one for processes that want to get something out. The put() and get() methods both return an event that is triggered when the corresponding action was successful.

Resources¶

Resources can be used by a limited number of processes at a time (e.g., a gas station with a limited number of fuel pumps). Processes request these resources to become a user (or to “own” them) and have to release them once they are done (e.g., vehicles arrive at the gas station, use a fuel-pump, if one is available, and leave when they are done).

Requesting a resources is modeled as “putting a process’ token into the resources” and releasing a resources correspondingly as “getting a process’ token out of the resource”. Thus, calling request()/release() is equivalent to calling put()/get(). Releasing a resource will always succeed immediately.

SimPy implements three resource types:

1. Resource
2. PriorityResource, where queueing processes are sorted by priority
3. PreemptiveResource, where processes additionally may preempt other processes with a lower priority

>>> import simpy
>>>
>>> def resource_user(env, resource):
...     request = resource.request()  # Generate a request event
...     yield request                 # Wait for access
...     yield env.timeout(1)          # Do something
...     resource.release(request)     # Release the resource
...
>>> env = simpy.Environment()
>>> res = simpy.Resource(env, capacity=1)
>>> user = env.process(resource_user(env, res))
>>> env.run()

>>> def resource_user(env, resource):
...     with resource.request() as req:  # Generate a request event
...         yield req                    # Wait for access
...         yield env.timeout(1)         # Do something
...                                      # Resource released automatically
>>> user = env.process(resource_user(env, res))
>>> env.run()

>>> res = simpy.Resource(env, capacity=1)
>>>
>>> def print_stats(res):
...     print('%d of %d slots are allocated.' % (res.count, res.capacity))
...     print('  Users:', res.users)
...     print('  Queued events:', res.queue)
>>>
>>>
>>> def user(res):
...     print_stats(res)
...     with res.request() as req:
...         yield req
...         print_stats(res)
...     print_stats(res)
>>>
>>> procs = [env.process(user(res)), env.process(user(res))]
>>> env.run()
0 of 1 slots are allocated.
  Users: []
  Queued events: []
1 of 1 slots are allocated.
  Users: [<Request() object at 0x...>]
  Queued events: [<Request() object at 0x...>]
1 of 1 slots are allocated.
  Users: [<Request() object at 0x...>]
  Queued events: [<Request() object at 0x...>]
0 of 1 slots are allocated.
  Users: []
  Queued events: [<Request() object at 0x...>]
1 of 1 slots are allocated.
  Users: [<Request() object at 0x...>]
  Queued events: []
0 of 1 slots are allocated.
  Users: []
  Queued events: []

>>> def resource_user(name, env, resource, wait, prio):
...     yield env.timeout(wait)
...     with resource.request(priority=prio) as req:
...         print('%s requesting at %s with priority=%s' % (name, env.now, prio))
...         yield req
...         print('%s got resource at %s' % (name, env.now))
...         yield env.timeout(3)
...
>>> env = simpy.Environment()
>>> res = simpy.PriorityResource(env, capacity=1)
>>> p1 = env.process(resource_user(1, env, res, wait=0, prio=0))
>>> p2 = env.process(resource_user(2, env, res, wait=1, prio=0))
>>> p3 = env.process(resource_user(3, env, res, wait=2, prio=-1))
>>> env.run()
1 requesting at 0 with priority=0
1 got resource at 0
2 requesting at 1 with priority=0
3 requesting at 2 with priority=-1
3 got resource at 3
2 got resource at 6

>>> def resource_user(name, env, resource, wait, prio):
...     yield env.timeout(wait)
...     with resource.request(priority=prio) as req:
...         print('%s requesting at %s with priority=%s' % (name, env.now, prio))
...         yield req
...         print('%s got resource at %s' % (name, env.now))
...         try:
...             yield env.timeout(3)
...         except simpy.Interrupt as interrupt:
...             by = interrupt.cause.by
...             usage = env.now - interrupt.cause.usage_since
...             print('%s got preempted by %s at %s after %s' %
...                   (name, by, env.now, usage))
...
>>> env = simpy.Environment()
>>> res = simpy.PreemptiveResource(env, capacity=1)
>>> p1 = env.process(resource_user(1, env, res, wait=0, prio=0))
>>> p2 = env.process(resource_user(2, env, res, wait=1, prio=0))
>>> p3 = env.process(resource_user(3, env, res, wait=2, prio=-1))
>>> env.run()
1 requesting at 0 with priority=0
1 got resource at 0
2 requesting at 1 with priority=0
3 requesting at 2 with priority=-1
1 got preempted by <Process(resource_user) object at 0x...> at 2 after 2
3 got resource at 2
2 got resource at 5

>>> def user(name, env, res, prio, preempt):
...     with res.request(priority=prio, preempt=preempt) as req:
...         try:
...             print('%s requesting at %d' % (name, env.now))
...             yield req
...             print('%s got resource at %d' % (name, env.now))
...             yield env.timeout(3)
...         except simpy.Interrupt:
...             print('%s got preempted at %d' % (name, env.now))
>>>
>>> env = simpy.Environment()
>>> res = simpy.PreemptiveResource(env, capacity=1)
>>> A = env.process(user('A', env, res, prio=0, preempt=True))
>>> env.run(until=1)  # Give A a head start
A requesting at 0
A got resource at 0
>>> B = env.process(user('B', env, res, prio=-2, preempt=False))
>>> C = env.process(user('C', env, res, prio=-1, preempt=True))
>>> env.run()
B requesting at 1
C requesting at 1
B got resource at 3
C got resource at 6

Containers¶

Containers help you modelling the production and consumption of a homogeneous, undifferentiated bulk. It may either be continuous (like water) or discrete (like apples).

You can use this, for example, to model the gas / petrol tank of a gas station. Tankers increase the amount of gasoline in the tank while cars decrease it.

The following example is a very simple model of a gas station with a limited number of fuel dispensers (modeled as Resource) and a tank modeled as Container:

>>> class GasStation:
...     def __init__(self, env):
...         self.fuel_dispensers = simpy.Resource(env, capacity=2)
...         self.gas_tank = simpy.Container(env, init=100, capacity=1000)
...         self.mon_proc = env.process(self.monitor_tank(env))
...
...     def monitor_tank(self, env):
...         while True:
...             if self.gas_tank.level < 100:
...                 print('Calling tanker at %s' % env.now)
...                 env.process(tanker(env, self))
...             yield env.timeout(15)
>>>
>>>
>>> def tanker(env, gas_station):
...     yield env.timeout(10)  # Need 10 Minutes to arrive
...     print('Tanker arriving at %s' % env.now)
...     amount = gas_station.gas_tank.capacity - gas_station.gas_tank.level
...     yield gas_station.gas_tank.put(amount)
>>>
>>>
>>> def car(name, env, gas_station):
...     print('Car %s arriving at %s' % (name, env.now))
...     with gas_station.fuel_dispensers.request() as req:
...         yield req
...         print('Car %s starts refueling at %s' % (name, env.now))
...         yield gas_station.gas_tank.get(40)
...         yield env.timeout(5)
...         print('Car %s done refueling at %s' % (name, env.now))
>>>
>>>
>>> def car_generator(env, gas_station):
...     for i in range(4):
...         env.process(car(i, env, gas_station))
...         yield env.timeout(5)
>>>
>>>
>>> env = simpy.Environment()
>>> gas_station = GasStation(env)
>>> car_gen = env.process(car_generator(env, gas_station))
>>> env.run(35)
Car 0 arriving at 0
Car 0 starts refueling at 0
Car 1 arriving at 5
Car 0 done refueling at 5
Car 1 starts refueling at 5
Car 2 arriving at 10
Car 1 done refueling at 10
Car 2 starts refueling at 10
Calling tanker at 15
Car 3 arriving at 15
Car 3 starts refueling at 15
Tanker arriving at 25
Car 2 done refueling at 30
Car 3 done refueling at 30

Containers allow you to retrieve their current level as well as their capacity (see GasStation.monitor_tank() and tanker()). You can also access the list of waiting events via the put_queue and get_queue attributes (similar to Resource.queue).

Stores¶

Using Stores you can model the production and consumption of concrete objects (in contrast to the rather abstract “amount” stored in containers). A single Store can even contain multiple types of objects.

Beside Store, there is a FilterStore that lets you use a custom function to filter the objects you get out of the store.

Here is a simple example modelling a generic producer/consumer scenario:

>>> def producer(env, store):
...     for i in range(100):
...         yield env.timeout(2)
...         yield store.put('spam %s' % i)
...         print('Produced spam at', env.now)
>>>
>>>
>>> def consumer(name, env, store):
...     while True:
...         yield env.timeout(1)
...         print(name, 'requesting spam at', env.now)
...         item = yield store.get()
...         print(name, 'got', item, 'at', env.now)
>>>
>>>
>>> env = simpy.Environment()
>>> store = simpy.Store(env, capacity=2)
>>>
>>> prod = env.process(producer(env, store))
>>> consumers = [env.process(consumer(i, env, store)) for i in range(2)]
>>>
>>> env.run(until=5)
0 requesting spam at 1
1 requesting spam at 1
Produced spam at 2
0 got spam 0 at 2
0 requesting spam at 3
Produced spam at 4
1 got spam 1 at 4

As with the other resource types, you can get a store’s capacity via the capacity attribute. The attribute items points to the list of items currently available in the store. The put and get queues can be accessed via the put_queue and get_queue attributes.

FilterStore can, for example, be used to model machine shops where machines have varying attributes. This can be useful if the homogeneous slots of a Resource are not what you need:

>>> from collections import namedtuple
>>>
>>> Machine = namedtuple('Machine', 'size, duration')
>>> m1 = Machine(1, 2)  # Small and slow
>>> m2 = Machine(2, 1)  # Big and fast
>>>
>>> env = simpy.Environment()
>>> machine_shop = simpy.FilterStore(env, capacity=2)
>>> machine_shop.items = [m1, m2]  # Pre-populate the machine shop
>>>
>>> def user(name, env, ms, size):
...     machine = yield ms.get(lambda machine: machine.size == size)
...     print(name, 'got', machine, 'at', env.now)
...     yield env.timeout(machine.duration)
...     yield ms.put(machine)
...     print(name, 'released', machine, 'at', env.now)
>>>
>>>
>>> users = [env.process(user(i, env, machine_shop, (i % 2) + 1))
...          for i in range(3)]
>>> env.run()
0 got Machine(size=1, duration=2) at 0
1 got Machine(size=2, duration=1) at 0
1 released Machine(size=2, duration=1) at 1
0 released Machine(size=1, duration=2) at 2
2 got Machine(size=1, duration=2) at 2
2 released Machine(size=1, duration=2) at 4

Imports¶

In SimPy 2, you had to decide at import-time whether you wanted to use a normal simulation (SimPy.Simulation), a real-time simulation (SimPy.SimulationRT) or something else. You usually had to import Simulation (or SimulationRT), Process and some of the SimPy keywords (hold or passivate, for example) from that package.

In SimPy 3, you usually need to import much less classes and modules (for example, all keywords are gone). In most use cases you will now only need to import simpy.

SimPy 2

from Simpy.Simulation import Simulation, Process, hold

SimPy 3

import simpy

The Simulation* classes¶

SimPy 2 encapsulated the simulation state in a Simulation* class (e.g., Simulation, SimulationRT or SimulationTrace). This class also had a simulate() method that executed a normal simulation, a real-time simulation or something else (depending on the particular class).

There was a global Simulation instance that was automatically created when you imported SimPy. You could also instantiate it on your own to uses SimPy’s object-orient API. This led to some confusion and problems, because you had to pass the Simulation instance around when you were using the object-oriented API but not if you were using the procedural API.

In SimPy 3, an Environment replaces Simulation and RealtimeEnvironment replaces SimulationRT. You always need to instantiate an environment. There’s no more global state.

To execute a simulation, you call the environment’s run() method.

SimPy 2

# Procedural API
from SimPy.Simulation import initialize, simulate

initialize()
# Start processes
simulate(until=10)

# Object-oriented API
from SimPy.Simulation import Simulation

sim = Simulation()
# Start processes
sim.simulate(until=10)

SimPy3

import simpy

env = simpy.Environment()
# Start processes
env.run(until=10)

Defining a Process¶

Processes had to inherit the Process base class in SimPy 2. Subclasses had to implement at least a so called Process Execution Method (PEM) (which is basically a generator function) and in most cases __init__(). Each process needed to know the Simulation instance it belonged to. This reference was passed implicitly in the procedural API and had to be passed explicitly in the object-oriented API. Apart from some internal problems, this made it quite cumbersome to define a simple process.

Processes were started by passing the Process and a generator instance created by the generator function to either the global activate() function or the corresponding Simulation method.

A process in SimPy 3 is a Python generator (no matter if it’s defined on module level or as an instance method) wrapped in a Process instance. The generator usually requires a reference to a Environment to interact with, but this is completely optional.

Processes are can be started by creating a Process instance and passing the generator to it. The environment provides a shortcut for this: process().

SimPy 2

# Procedural API
from Simpy.Simulation import Process

class MyProcess(Process):
    def __init__(self, another_param):
        super().__init__()
        self.another_param = another_param

    def generator_function(self):
        """Implement the process' behavior."""
        yield something

initialize()
proc = Process('Spam')
activate(proc, proc.generator_function())

# Object-oriented API
from SimPy.Simulation import Simulation, Process

class MyProcess(Process):
    def __init__(self, sim, another_param):
        super().__init__(sim=sim)
        self.another_param = another_param

    def generator_function(self):
        """Implement the process' behaviour."""
        yield something

sim = Simulation()
proc = Process(sim, 'Spam')
sim.activate(proc, proc.generator_function())

SimPy 3

import simpy

def generator_function(env, another_param):
    """Implement the process' behavior."""
    yield something

env = simpy.Environment()
proc = env.process(generator_function(env, 'Spam'))

SimPy Keywords (hold etc.)¶

In SimPy 2, processes created new events by yielding a SimPy Keyword and some additional parameters (at least self). These keywords had to be imported from SimPy.Simulation* if they were used. Internally, the keywords were mapped to a function that generated the according event.

In SimPy 3, you directly yield events if you want to wait for an event to occur. You can instantiate an event directly or use the shortcuts provided by Environment.

Generally, whenever a process yields an event, the execution of the process is suspended and resumed once the event has been triggered. To motivate this understanding, some of the events were renamed. For example, the hold keyword meant to wait until some time has passed. In terms of events this means that a timeout has happened. Therefore hold has been replaced by a Timeout event.

SimPy 2

yield hold, self, duration
yield passivate, self
yield request, self, resource
yield release, self, resource
yield waitevent, self, event
yield waitevent, self, [event_a, event_b, event_c]
yield queueevent, self, event_list
yield get, self, level, amount
yield put, self, level, amount

SimPy 3

yield env.timeout(duration)        # hold: renamed
yield env.event()                  # passivate: renamed
yield resource.request()           # Request is now bound to class Resource
resource.release()                 # Release no longer needs to be yielded
yield event                        # waitevent: just yield the event
yield env.all_of([event_a, event_b, event_c])  # waitvent
yield env.any_of([event_a, event_b, event_c])  # queuevent
yield container.get(amount)        # Level is now called Container
yield container.put(amount)

yield event_a | event_b            # Wait for either a or b. This is new.
yield event_a & event_b            # Wait for a and b. This is new.
yield env.process(calculation(env))  # Wait for the process calculation to
                                     # to finish.

yield waituntil, self, cond_func

def waituntil(env, cond_func, delay=1):
    while not cond_func():
        yield env.timeout(delay)

# Usage:
yield waituntil(env, cond_func)

Interrupts¶

In SimPy 2, interrupt() was a method of the interrupting process. The victim of the interrupt had to be passed as an argument.

The victim was not directly notified of the interrupt but had to check if the interrupted flag was set. Afterwards, it had to reset the interrupt via interruptReset(). You could manually set the interruptCause attribute of the victim.

Explicitly checking for an interrupt is obviously error prone as it is too easy to be forgotten.

In SimPy 3, you call interrupt() on the victim process. You can optionally supply a cause. An Interrupt is then thrown into the victim process, which has to handle the interrupt via try: ... except Interrupt: ....

SimPy 2

class Interrupter(Process):
    def __init__(self, victim):
        super().__init__()
        self.victim = victim

    def run(self):
        yield hold, self, 1
        self.interrupt(self.victim_proc)
        self.victim_proc.interruptCause = 'Spam'

class Victim(Process):
    def run(self):
        yield hold, self, 10
        if self.interrupted:
            cause = self.interruptCause
            self.interruptReset()

SimPy 3

def interrupter(env, victim_proc):
    yield env.timeout(1)
    victim_proc.interrupt('Spam')

def victim(env):
    try:
        yield env.timeout(10)
    except Interrupt as interrupt:
        cause = interrupt.cause

Conclusion¶

This guide is by no means complete. If you run into problems, please have a look at the other guides, the examples or the API Reference. You are also very welcome to submit improvements. Just create a pull request at bitbucket.