# Harvest-Stage Rain Risk Simulator

## PURPOSE
A discrete-event simulation (SimPy + NumPy) that models the next two days of weather over Bhadradri Kothagudem district as a sequence of hourly states — clear, cloudy, thunder-and-lightning, light rain — and estimates the probability that rain lands on crops still in the harvesting stage. It answers the question officials raised in the bulletin: given a two-day light-rain forecast, how exposed is a farmer who has not yet harvested?

## WHY THIS MATTERS
The video is fundamentally about uncertainty: weather "has turned cool all of a sudden", rain "may occur in several places", and the correct response depends on timing. Simulation is the right tool for turning a probabilistic forecast into a decision. Students learn to convert prose ("thunder and lightning for the next two days") into an event model with rates and states, and to reason about risk instead of a single yes/no.

## HOW TO BUILD
1. Represent each place as a SimPy process that steps hour by hour for 48 hours and draws a state from a NumPy RNG using per-hour transition probabilities.
2. Track "rain-hours" and whether any rain overlapped the harvest window.
3. Run N replications, then report the fraction of runs where harvest-stage crop got wet and the average rain-hours.

```python
import simpy, numpy as np

def weather(env, rng, hours=48, p_rain=0.12, p_thunder=0.2, log=None):
    for _ in range(hours):
        u = rng.random()
        state = "rain" if u < p_rain else ("thunder" if u < p_rain + p_thunder else "clear")
        if state == "rain" and log is not None:
            log.append(1)
        yield env.timeout(1)

def simulate(n=1000, seed=7):
    rng = np.random.default_rng(seed)
    exposed = 0
    for _ in range(n):
        log: list[int] = []
        env = simpy.Environment()
        env.process(weather(env, rng, log=log))
        env.run()
        if sum(log) > 0:
            exposed += 1
    return exposed / n
```

## WHEN TO USE IN PRODUCTION
Use it for planning: insurance/indemnity models, extension-office "expected exposure" dashboards, or teaching what a forecast actually means. Do NOT use it as an authoritative weather prediction — it consumes forecast probabilities, it does not generate them, and its parameters must be calibrated to real IMD statistics before any operational use.

## HOW IT HELPS STUDENTS
Learners practise SimPy environment/process design, NumPy random sampling with a fixed seed for reproducibility, Monte-Carlo reasoning, and translating a narrative forecast into measurable risk. These are core skills for any stochastic system or decision-support tool.

## STARTER CODE
See `starter/main.py` for a deterministic, seeded SimPy simulation with per-place runs and `# TODO` markers for calibrating probabilities from real data.
