# Revenue Loss Simulator for Unapproved Layouts

## PURPOSE
A **SimPy + NumPy** discrete-event simulation that models how unapproved plot layouts
appear over time across West Godavari district panchayats, and quantifies the cumulative
revenue a panchayat loses when developers skip the mandatory 10% social-space reservation.
Each panchayat generates layouts at a stochastic arrival rate; each layout either reserves
its social space or ignores it, and the simulator sums the resulting shortfall and its rupee
value over a planning horizon. It answers the question the report only gestures at: *how
much money is leaking, and how fast?*

## WHY THIS MATTERS
The transcript says officials worry that "disregarding these rules ... is causing a
significant loss of revenue that should be accruing to the local panchayats." That is a
dynamic claim — violations accumulate — and a static spreadsheet cannot show the trend or
test policy. Simulation lets planners ask "what if enforcement cuts the violation rate in
half?" or "what if we audit one panchayat per month?" before committing staff.

## HOW TO BUILD
1. Create a `simpy.Environment` and one generator process per panchayat.
2. Each process waits `rng.exponential(...)` between layout arrivals.
3. Draw a layout area from a normal distribution and decide (Bernoulli) whether the
   developer reserves the 10% social space.
4. Accumulate shortfall and revenue loss into a shared stats dict.
5. Run the environment and return aggregate results.

Key snippet:

```python
yield env.timeout(rng.exponential(SECONDS_PER_DAY * 15))   # ~1 layout / 15 days
total_area = rng.normal(mean_area_sqm, mean_area_sqm * 0.2)
skip = rng.random() < 0.65                                  # 65% ignore the rule
shortfall = max(0.0, total_area * SOCIAL_SPACE_RATIO - (0.0 if skip else total_area * 0.10))
stats["total_loss_inr"] += shortfall * rate_per_sqm
```

## WHEN TO USE IN PRODUCTION
Use it for policy impact studies, budget-loss forecasting, and testing enforcement
scenarios across a district before deploying inspectors. Do **not** use it as an accounting
record or for individual approvals — the distributions are illustrative, so feed it real
arrival and area data before trusting any absolute number. It shines for *relative*
comparisons between policy options.

## HOW IT HELPS STUDENTS
Students learn stochastic modelling, probability distributions, and discrete-event
simulation — seeing how a governance problem becomes a runnable experiment. They practise
seeding for reproducibility and separating model assumptions from reporting, which is core
to credible data work.

## STARTER CODE
`starter/main.py` provides the SimPy environment, per-panchayat arrival processes, seeded
NumPy draws, and a `run_simulation()` entry point printing totals. Replace the hard-coded
skip-rate and area distributions at the `# TODO` markers with measured data.
