# Rain Gauge Network Simulator for West Godavari

## PURPOSE
A SimPy + NumPy simulation that models a district rain-gauge network over a 24-hour
observation window and reproduces the pattern the video describes: moderate rainfall
in several mandals, a single peak of about 24 mm in one mandal, and most other areas
clustering near 10 mm. It simulates gauges reporting on independent schedules and
lets students see how a sparse network produces a skewed district maximum.

## WHY THIS MATTERS
The bulletin reports one number per mandal and then a district highlight. That is a
sampling problem, not just a measurement. This project makes the mechanism explicit:
each gauge is doing something at a point in time, gauges report at different
intervals, and the "district maximum" depends on which gauges happened to be read.
Students learn why weather reporting is probabilistic.

## HOW TO BUILD
Use SimPy to model each gauge as a process that wakes every reporting interval,
draws a rainfall amount from a NumPy distribution, and pushes a reading into a shared
store. Use `numpy.random.default_rng(seed)` for reproducibility. After the
environment runs for 24 simulated hours, aggregate per-mandal sums and maxima.

Key snippet:

```python
import simpy
import numpy as np

def gauge(env, name, mandal, mean_mm, store, rng, interval):
    while True:
        mm = max(0.0, rng.normal(mean_mm, mean_mm * 0.35))
        store.append((env.now, name, mandal, round(mm, 1)))
        yield env.timeout(interval)
```

## WHEN TO USE IN PRODUCTION
Use it to stress-test a real ingestion pipeline before sensors exist, to size a gauge
network, or to sanity-check whether an observed district max is plausible given
coverage. Do NOT present simulated figures as real weather data, and do NOT use it
for operational forecasting — that needs physical hydrology models, not a toy sampler.

## HOW IT HELPS STUDENTS
Students pick up discrete-event simulation, seeded randomness, and the discipline of
separating a model's parameters from its results — highly transferable to queueing,
capacity, and reliability work.

## STARTER CODE
See `starter/main.py` for the SimPy environment, gauge processes, NumPy seeding, a
district aggregation step and `# TODO` markers for spatial correlation and thresholds.
