simpy

# SimPy - Discrete Event Simulation

SimPy allows you to model real-world processes as Python generators. Components in SimPy (like customers, cars, or data packets) are "processes" that interact with each other and with limited "resources" (like servers, parking spots, or bandwidth).

## When to Use

- **Modeling queuing systems** (Bank tellers, call centers, hospital emergency rooms)
- **Simulating supply chains and logistics** (Warehouses, transport networks)
- **Analyzing manufacturing processes** (Assembly lines, machine maintenance)
- **Network simulation** (Packet routing, server load balancing)
- **Project management** (Task dependencies, resource allocation)
- **Any system where "events" occur at specific points in time rather than continuously**

## Reference Documentation

**Official docs**: https://simpy.readthedocs.io/  
**GitHub**: https://github.com/simpy/simpy  
**Search patterns**: `simpy.Environment`, `simpy.Resource`, `env.process`, `yield env.timeout`

## Core Principles

### Virtual Time

SimPy uses an internal clock starting at 0. Time moves forward only when an event is processed. Between events, "nothing" happens, so simulating 100 years takes seconds if only a few events occur.

### Processes as Generators

Processes are standard Python functions using `yield`. When a process yields an event, SimPy suspends it until that event occurs.

### Resources

Three types of shared objects:
- **Resource**: Limited number of slots (e.g., a counter)
- **Container**: For bulk matter (e.g., a gas tank, RAM)
- **Store**: For distinct objects (e.g., a buffer of messages)

## Quick Reference

### Installation

```bash
pip install simpy
```

### Standard Imports

```python
import simpy
import random
```

### Basic Pattern - A Simple Process

```python
import simpy

def clock(env, name, tick):
    while True:
        print(f"{name} at {env.now}")
        # 'yield' tells SimPy to wait for this event
        yield env.timeout(tick)

# 1. Create Environment
env = simpy.Environment()

# 2. Add Process
env.process(clock(env, 'Fast', 0.5))
env.process(clock(env, 'Slow', 1.0))

# 3. Run for 2 units of virtual time
env.run(until=2.1)
```

## Critical Rules

### ✅ DO

- **Use `yield env.timeout(n)`** - This is the only way to advance time for a process. Never use `time.sleep()`.
- **Use `with resource.request() as req:`** - This ensures a resource is automatically released even if the process is interrupted or fails.
- **Set a random seed** - Always use `random.seed(42)` for reproducible simulations.
- **Pass the `env` object** - Every process and resource needs a reference to the environment to track time.
- **Use `env.run(until=...)`** - Always define a stopping condition, otherwise a `while True` simulation will run forever.
- **Collect data in lists** - Store timestamps and event details in external lists for post-simulation analysis (e.g., with Pandas).

### ❌ DON'T

- **Use real-world time** - simpy is for virtual time. `env.now` is your only clock.
- **Modify the environment directly** - Interact with it only through processes and events.
- **Forget to yield** - If you don't yield an event inside a loop, you create an infinite loop at the same instant in virtual time, hanging the simulation.
- **Block the event loop** - Heavy CPU calculations inside a process should be rare; they "stop" the virtual clock of the entire simulation while the CPU works.

## Anti-Patterns (NEVER)

```python
import simpy
import time

# ❌ BAD: Using real sleep
def bad_process(env):
    time.sleep(1) # This stops the REAL clock, but virtual time doesn't move!
    yield env.timeout(1)

# ✅ GOOD: Use virtual timeout
def good_process(env):
    yield env.timeout(1) # Moves virtual clock forward instantly

# ❌ BAD: Infinite loop without yielding
# def hang_forever(env):
#     while True:
#         x = 1 + 1 # No yield = simulation clock stuck at current env.now

# ❌ BAD: Manual resource release (Dangerous)
def risky_request(env, res):
    req = res.request()
    yield req
    # If something fails here, the resource is never released
    res.release(req)

# ✅ GOOD: Using context manager
def safe_request(env, res):
    with res.request() as req:
        yield req
        # Resource automatically released when exiting 'with'
```

## Resources and Queues (simpy.Resource)

### Managing Shared Capacity

```python
def car(env, name, bcs, driving_time, charge_time):
    # Simulate driving to the station
    yield env.timeout(driving_time)

    print(f'{name} arriving at {env.now}')
    # Request one of the charging spots
    with bcs.request() as req:
        yield req
        print(f'{name} starting to charge at {env.now}')
        yield env.timeout(charge_time)
        print(f'{name} leaving at {env.now}')

env = simpy.Environment()
# Battery Charging Station with 2 spots
bcs = simpy.Resource(env, capacity=2)

for i in range(4):
    env.process(car(env, f'Car {i}', bcs, i*2, 5))

env.run()
```

## Advanced Resources: Containers and Stores

### Containers (Liquids/Bulk)

```python
# Modeling a gas station tank
gas_tank = simpy.Container(env, capacity=1000, init=500)

def refuel(env, gas_tank):
    yield gas_tank.put(400) # Add fuel

def car(env, gas_tank):
    yield gas_tank.get(40) # Consume fuel
```

### Stores (Distinct Objects)

```python
# Modeling a producer-consumer buffer
buffer = simpy.Store(env, capacity=10)

def producer(env, buffer):
    yield buffer.put(f'Widget at {env.now}')

def consumer(env, buffer):
    item = yield buffer.get()
    print(f'Consumed {item}')
```

## Event Synchronization

### Waiting for Multiple Events

```python
# Wait for BOTH events
yield env.timeout(10) & other_process_event

# Wait for EITHER event
yield env.timeout(10) | other_process_event
```

## Practical Workflows

### 1. Hospital Emergency Room Model

```python
def patient(env, name, nurse, doctor):
    arrival_time = env.now
    
    # 1. Wait for Nurse (Triage)
    with nurse.request() as req:
        yield req
        yield env.timeout(random.expovariate(1/5)) # 5 mins avg
        
    # 2. Wait for Doctor (Treatment)
    with doctor.request() as req:
        yield req
        yield env.timeout(random.normalvariate(20, 5)) # 20 mins avg
        
    wait_times.append(env.now - arrival_time)

wait_times = []
env = simpy.Environment()
nurse = simpy.Resource(env, capacity=2)
doctor = simpy.Resource(env, capacity=1)
# ... launch processes ...
```

### 2. Machine Failure and Repair

```python
def machine(env, repairman):
    while True:
        try:
            # Working phase
            working_time = 100
            yield env.timeout(working_time)
        except simpy.Interrupt:
            # Interrupted by failure
            with repairman.request() as req:
                yield req
                yield env.timeout(10) # Repair time

def break_machine(env, machine_proc):
    while True:
        yield env.timeout(random.uniform(50, 200))
        machine_proc.interrupt()
```

### 3. Server Request Handling (Data Collection)

```python
import pandas as pd

log = []

def request(env, server):
    start_wait = env.now
    with server.request() as req:
        yield req
        wait = env.now - start_wait
        service_time = random.expovariate(1.0)
        yield env.timeout(service_time)
        
        log.append({
            'arrival': start_wait,
            'wait': wait,
            'service': service_time,
            'finish': env.now
        })

# After simulation:
# df = pd.DataFrame(log)
# print(df['wait'].mean())
```

## Performance Optimization

### Using simpy.PriorityResource

In systems where some events are more important (e.g., critical patients), use `PriorityResource`.

```python
res = simpy.PriorityResource(env, capacity=1)
with res.request(priority=0) as req: # Lower number = higher priority
    yield req
```

### Monitoring Large Simulations

Avoid printing to the console in high-speed simulations. Instead, use a data collection list and process it with NumPy/Pandas after the `env.run()` finishes.

## Common Pitfalls and Solutions

### The "Stuck Process"

If your code reaches a logic branch where no `yield` occurs in a `while True` loop, SimPy freezes.

```python
# ❌ Problem:
def logic_error(env):
    while True:
        if condition:
            yield env.timeout(1)
        # Else? If condition is false, we loop forever at same time point!

# ✅ Solution:
def logic_fixed(env):
    while True:
        if condition:
            yield env.timeout(1)
        else:
            yield env.timeout(0.1) # Or some default wait
```

### Multiple Environments

Never mix objects (Resources, Processes) from different environments. Every component must belong to the same `simpy.Environment()` instance.

### Interruption Timing

When interrupting a process, the interrupt happens at the current virtual time. Be careful with what the interrupted process was yielding (it will receive a `simpy.Interrupt` exception).

## Best Practices

1. **Always use context managers for resources** - `with resource.request() as req:` ensures proper cleanup
2. **Set random seeds for reproducibility** - Use `random.seed(42)` at the start of simulations
3. **Collect data externally** - Store event data in lists/dictionaries, not just print statements
4. **Define clear stopping conditions** - Always use `env.run(until=...)` with a specific time limit
5. **Use virtual time only** - Never mix `time.sleep()` or real-world time with SimPy
6. **Test with small simulations first** - Verify logic before running large-scale simulations
7. **Document your processes** - Clearly name processes and resources for debugging
8. **Handle interruptions properly** - Use try/except blocks when processes can be interrupted

SimPy turns Python's generator syntax into a powerful engine for modeling time and scarcity. It allows scientists and engineers to experiment with "What if?" scenarios for complex systems without the cost or risk of physical trials.