# Yadadri Water Crisis Simulator — Groundwater Depletion & Tanker Allocation (SimPy)

## PURPOSE
A discrete-event simulation of the exact scenario in the video: groundwater levels drop
across Yadadri district, 44 villages run dry, and 50 rented private borewells plus tanker
trips must keep households above a drinking-water minimum. The simulator models daily
demand, borewell yield decay, tanker travel time, and dispatching policy, then reports how
many village-days fall into crisis under each strategy.

## WHY THIS MATTERS
The video describes a response, not a plan: officials reacted "immediately" and rented
borewells. A student can't rerun reality, but they can simulate it. This project teaches
that emergency logistics is a queueing-and-scarcity problem — finite supply arriving over
time to stochastic demand — and that policy choice (nearest-first vs worst-first) changes
outcomes measurably. That is the lesson behind the reported crisis.

## HOW TO BUILD
1. `pip install simpy numpy`
2. Each village is a SimPy process generating a daily water request (NumPy-sampled demand).
3. The 50 borewells are a shared `simpy.Resource` with a capacity and a yield rate.
4. A dispatcher process allocates tanker trips each day using a chosen priority rule.
5. Log shortfalls per village-day and summarise.

```python
import simpy, numpy as np

def village(env, name, need_lpd, wells, log):
    while True:
        litres = yield wells.get()          # wait for a borewell slot
        served = min(need_lpd, litres)      # stub: borewell yield caps service
        log.append((env.now, name, need_lpd - served))
        yield env.timeout(1)                # next day
        wells.put(1)

env = simpy.Environment()
wells = simpy.Resource(env, capacity=50)    # the 50 rented private borewells
env.run(until=30)
```

## WHEN TO USE IN PRODUCTION
Use it to compare allocation policies before committing tankers, to stress-test a district
plan against a hotter summer, or to size how many borewells a crisis truly needs. Do NOT use
it for billing, for real-time dispatch, or where you have live sensor telemetry — a
simulation is a planning tool, not a live controller.

## HOW IT HELPS STUDENTS
Students learn SimPy processes, resources and timeouts, stochastic demand via NumPy, and how
to turn a news statement into a falsifiable model with tunable parameters.

## STARTER CODE
`starter/main.py` holds a runnable skeleton with TODO markers for priority dispatch,
yield decay, and a Matplotlib summary plot.
