All articles

Model Musings

SimPy FilterStore Explained: Getting Exactly What You Need

Published
Reading time
5 min

Store gives you the next item. FilterStore lets you be picky.

The Problem Store Can’t Solve

Regular Store is FIFO: first in, first out. But what if you need a specific item?

# With regular Store
store = simpy.Store(env)
store.put({'type': 'red', 'id': 1})
store.put({'type': 'blue', 'id': 2})
store.put({'type': 'red', 'id': 3})

# You can only get item 1, then 2, then 3
# No way to say "give me a blue one"

FilterStore fixes this.

Basic Usage

import simpy

env = simpy.Environment()
store = simpy.FilterStore(env, capacity=10)

# Put some items
yield store.put({'type': 'red', 'value': 1})
yield store.put({'type': 'blue', 'value': 2})
yield store.put({'type': 'red', 'value': 3})

# Get specifically a blue item
blue = yield store.get(lambda x: x['type'] == 'blue')
print(blue)  # {'type': 'blue', 'value': 2}

The filter function receives each item and returns True if it matches.

How Filtering Works

When you get() with a filter:

  1. FilterStore checks each item against your filter
  2. First matching item is returned
  3. If no match, the get blocks until a matching item arrives
# Will block until a green item is put
green = yield store.get(lambda x: x['type'] == 'green')

Real-World Example: Parts Bin

import random
import simpy

class Part:
    def __init__(self, part_type, size, quality):
        self.part_type = part_type
        self.size = size
        self.quality = quality

    def __repr__(self):
        return f"Part({self.part_type}, {self.size}, {self.quality:.2f})"

def supplier(env, bin):
    """Delivers random parts."""
    types = ['bolt', 'nut', 'washer']
    sizes = ['small', 'medium', 'large']

    while True:
        part = Part(
            random.choice(types),
            random.choice(sizes),
            random.uniform(0.8, 1.0)
        )
        yield bin.put(part)
        yield env.timeout(1)

def assembler(env, bin, needs_type, needs_size):
    """Assembles using specific parts."""
    while True:
        # Get exactly what we need
        part = yield bin.get(
            lambda p: p.part_type == needs_type and p.size == needs_size
        )
        print(f"Got {part} at {env.now}")
        yield env.timeout(5)  # Assembly time

random.seed(42)
env = simpy.Environment()
parts_bin = simpy.FilterStore(env)

env.process(supplier(env, parts_bin))
env.process(assembler(env, parts_bin, 'bolt', 'medium'))
env.process(assembler(env, parts_bin, 'nut', 'small'))

env.run(until=50)
print(f"Left in the bin: {len(parts_bin.items)} parts")

Output:

Got Part(nut, small, 0.84) at 1
Got Part(nut, small, 0.82) at 11
Got Part(bolt, medium, 0.97) at 12
Got Part(nut, small, 0.91) at 16
Got Part(bolt, medium, 0.86) at 20
Got Part(nut, small, 0.97) at 21
Got Part(nut, small, 0.93) at 26
Got Part(nut, small, 0.93) at 32
Got Part(nut, small, 0.85) at 37
Got Part(bolt, medium, 0.88) at 41
Left in the bin: 40 parts

Each assembler takes only its own part and ignores the rest. Of the 50 parts delivered, ten were wanted; the other 40 (washers, large bolts and the like) are still in the bin. A FilterStore with no capacity never turns them away, and every get() has to look past them, which is the linear search the performance section below warns about.

Multiple Criteria

Combine conditions in the filter:

# Get a large red item
item = yield store.get(
    lambda x: x['type'] == 'red' and x['size'] == 'large'
)

# Get any item with value > 10
item = yield store.get(lambda x: x['value'] > 10)

# Get by multiple possible types
item = yield store.get(lambda x: x['type'] in ['red', 'blue'])

Default Get (No Filter)

Without a filter, FilterStore behaves like regular Store:

# Get any item (FIFO)
item = yield store.get()

Checking Available Items

Peek at what’s in the store:

# All items
print(store.items)

# Check if any match
matching = [x for x in store.items if x['type'] == 'blue']
print(f"Blue items available: {len(matching)}")

But remember: checking doesn’t reserve. Another process might grab it first.

Non-Blocking Filter Get

What if you don’t want to wait?

def try_get_blue(env, store, timeout):
    get_event = store.get(lambda x: x['type'] == 'blue')
    timeout_event = env.timeout(timeout)

    result = yield get_event | timeout_event

    if get_event in result:
        return get_event.value
    else:
        get_event.cancel()
        return None

Priority with Filtering

Need priority AND filtering? Combine patterns:

class PrioritizedPart:
    def __init__(self, priority, part_type, part_id):
        self.priority = priority
        self.part_type = part_type
        self.part_id = part_id

def get_highest_priority_of_type(store, part_type):
    """Get highest priority item of specific type."""
    matching = [p for p in store.items if p.part_type == part_type]
    if not matching:
        return None
    matching.sort(key=lambda x: x.priority)
    return matching[0]

# The helper only finds the item; take that very object with a filter
best = get_highest_priority_of_type(store, 'bolt')
if best is not None:
    part = yield store.get(lambda p: p is best)

Or use a custom store class.

FilterStore vs PriorityStore

FeatureFilterStorePriorityStore
SelectionBy custom filterBy priority
Multiple criteriaYesNo
Get any itemYesYes (lowest priority)
ComplexityHigherLower

Use FilterStore when selection criteria are complex. Use PriorityStore when you just need ordering.

Example: Taxi Dispatch

import random
import simpy

class Ride:
    def __init__(self, pickup, destination, passengers):
        self.pickup = pickup
        self.destination = destination
        self.passengers = passengers

def dispatch_taxi(env, ride_queue, taxi_type, capacity):
    """Taxi only takes rides it can handle."""
    while True:
        # Only get rides within capacity
        ride = yield ride_queue.get(lambda r: r.passengers <= capacity)
        print(f"{env.now:3}: {taxi_type} takes ride for {ride.passengers} from {ride.pickup}")
        yield env.timeout(10)

random.seed(42)
env = simpy.Environment()
rides = simpy.FilterStore(env)

# Small taxi (up to 4 passengers)
env.process(dispatch_taxi(env, rides, "SmallTaxi", 4))

# Large taxi (up to 7 passengers)
env.process(dispatch_taxi(env, rides, "LargeTaxi", 7))

# Generate rides
def generate_rides(env, queue):
    for i in range(8):
        ride = Ride(f"Location{i}", f"Dest{i}", random.randint(1, 6))
        yield queue.put(ride)
        yield env.timeout(2)

env.process(generate_rides(env, rides))
env.run(until=100)

Output:

  0: LargeTaxi takes ride for 6 from Location0
  2: SmallTaxi takes ride for 1 from Location1
 10: LargeTaxi takes ride for 1 from Location2
 12: SmallTaxi takes ride for 3 from Location4
 20: LargeTaxi takes ride for 6 from Location3
 22: SmallTaxi takes ride for 2 from Location5
 30: LargeTaxi takes ride for 2 from Location6
 32: SmallTaxi takes ride for 2 from Location7

Follow the party of six at Location3. It books at 6. At 10 the large taxi takes the first ride it can handle (a single passenger from Location2), and at 12 the small taxi passes Location3 over for Location4. The six wait until 20. FilterStore hands over the first matching item in the order they were put; if the large taxi should favour large parties, say so in its filter or give large parties a store of their own.

Performance Consideration

FilterStore checks items linearly. With thousands of items, this matters.

For high-performance scenarios:

  • Keep stores small
  • Use multiple stores by category
  • Consider custom data structures

Common Gotchas

Filter Never Matches

# Blocks forever if no blue items ever arrive
blue = yield store.get(lambda x: x['type'] == 'blue')

Add timeouts for safety.

Modifying Items

item = yield store.get(lambda x: x['id'] == 5)
item['status'] = 'processed'  # Changes the object

# If you put it back, filters will see the change
yield store.put(item)

Be careful about mutating items.

Summary

FilterStore:

  • Lets you get specific items, not just FIFO
  • Filter function returns True for matching items
  • Blocks until a match is found
  • Perfect for typed queues, dispatch systems, inventory

When FIFO isn’t enough, filter.

Next Steps

Ready to build a model of your own?

The free SimPy Handbook covers the foundations; the Simulation Bootcamp covers everything else, from first principles to models a business will act on.