# Vaccine Site Readiness & Conversion Simulator

## PURPOSE
A discrete-event simulation of the exact root causes Genie surfaces in the demo: patients arriving for injectable (vaccine) medication while **sites are not ready to administer it**, **oral-to-injectable conversion** that is slower than hoped, and **authorization delays** that hold up payment. The demo concludes that the injectable portfolio "is a problem" in Germany because site readiness lags other markets. This project turns that narrative into a tunable model so students can watch the bottleneck move when readiness or conversion changes.

## WHY THIS MATTERS
The video's real teaching is that a good answer explains the *operational why behind the numbers the dashboards don't show* — that phrase comes straight from the Germany risk report Genie finds in Google Drive. Dashboards show a drop; a simulation shows the mechanism. Building one teaches students to model cause, not just report effect.

## HOW TO BUILD
1. `pip install -r requirements.txt`.
2. Model each market as a `simpy.Environment` with a `Site` resource whose `readiness` probability (0-1) decides whether an administration slot succeeds.
3. Patients arrive via a Poisson process (NumPy), get triaged as oral or injectable with a conversion rate, then either get served, wait for authorization, or bounce.
4. Run markets in parallel, collect per-market stats (served, bounced, mean wait, auth delay), and print a summary table.
5. Sweep `readiness` across markets to reproduce the Spain/Germany underperformance.

```python
def patient(env, site, stats):
    yield env.timeout(np.random.exponential(1 / ARRIVAL_RATE))
    if np.random.random() > site.readiness:      # site not ready -> root cause
        stats["bounced"] += 1
        return
    with site.slots.request() as req:
        yield req
        yield env.timeout(np.random.normal(2, 0.3))   # administration
        stats["served"] += 1
```

## WHEN TO USE IN PRODUCTION
Use it to stress-test capacity and rollout plans (opening clinics, moving patients from orals to injectables, staffing for authorization queues) before committing budget, and to answer "what if site readiness improves by 15%?" Don't use simulation when a closed-form queue model answers the question, or when you need a live operational dashboard — SimPy is for planning and root-cause reasoning, not real-time monitoring.

## HOW IT HELPS STUDENTS
They learn discrete-event modelling, resource contention, stochastic arrivals, and experimental design (parameter sweeps). Mapping a Genie narrative to a runnable model is the bridge from "I read the analysis" to "I can reproduce and challenge it."

## STARTER CODE
`starter/main.py` is a runnable SimPy + NumPy skeleton with markets, sites, Poisson arrivals, a conversion step, an authorization delay, and `# TODO` markers for extra metrics and sweeps.
