# Dasara/Diwali Crowd-Flow & Stampede-Risk Simulator (SimPy + NumPy)

## PURPOSE
The Warangal police advisory warned of stampede risk when markets and malls fill during
Dasara and Diwali, and insisted that emergency exits "must always be kept ready." This
project simulates a festival venue as a discrete-event model so you can test, offline, how
a crowd behaves under different arrival rates and exit configurations — and see exactly how
many blocked exits or underequipped gates turn a busy evening into a dangerous one.

## WHY THIS MATTERS
The advisory is a prevention argument, but prevention claims are hard to verify without a
model. A SimPy simulation converts "keep exits ready" from a slogan into a measurable
variable: run the venue with all exits open versus half closed, and compare peak occupancy
and evacuation clearing time. This is the reasoning behind advance security requirements.

## HOW TO BUILD
1. `pip install simpy numpy`.
2. Model the venue as a `simpy.Store` capacity cap; arrivals use a Poisson process via
   `numpy.random.default_rng(seed)` for determinism.
3. Each gate is a `simpy.Resource` (a checkpoint an attendee passes through).
4. Exit readiness is a simple multiplier on exit throughput when emergency exits are off.
5. Record peak occupancy each tick; compute a risk band from occupancy vs. safe capacity.
6. Evacuation step: at a trigger time, route everyone through open exits and time the clear.

Key snippet:
```python
def visitor(env, gate, venue, rng, stats):
    with gate.request() as req:
        yield req
        if len(venue.items) >= venue.capacity:
            stats["turned_away"] += 1
            return
        yield venue.put(1)
    yield env.timeout(rng.exponential(45))   # dwell time in venue
    yield venue.get(1)
```

## WHEN TO USE IN PRODUCTION
Use it for capacity planning before a festival, exit-layout A/B studies, and drilling
"what if an exit is blocked" scenarios. It is a planning tool, not a live controller — do
not wire it to real-time gate counters expecting second-by-second accuracy, and avoid it
when reliable arrival/dwell data is unavailable, since results are only as good as the rate
assumptions.

## HOW IT HELPS STUDENTS
You learn discrete-event modeling, seeded reproducibility, resource contention, and how to
translate a policy statement into a testable hypothesis — a rare and interview-friendly
skill set.

## STARTER CODE
See `starter/main.py` for the SimPy venue model, a NumPy arrival generator, and `# TODO`
markers for multi-gate routing and evacuation timing.
