# Indiramma Housing Construction Pipeline Simulator (SimPy + NumPy)

## PURPOSE
A discrete-event simulation of the Indiramma housing construction pipeline: land
clearance, foundation, structure, roofing, and handover for thousands of sanctioned
houses across Telangana districts. The transcript says construction "is continuing
without interruption" and that the government will not step back even if
"financial difficulties arise" — this simulator answers the operational question
behind that promise: how many houses can actually be completed per quarter, and
what happens to handover times when the budget is squeezed?

## WHY THIS MATTERS
A welfare promise becomes real only when throughput is modelled. Contractor crews,
material supply, and sanction money are finite. SimPy lets students see queueing
effects directly: if monthly sanctions drop, work-in-progress grows, cycle time
stretches, and families wait longer — even though nothing was "cancelled." Numeric
evidence beats rhetoric when defending a housing budget.

## HOW TO BUILD
1. `pip install simpy numpy matplotlib`.
2. Model crews as `simpy.Resource` with a fixed capacity per district.
3. Each house is a process that requests a crew for each of five build stages.
4. Draw stage durations from NumPy distributions (e.g. triangular for roofing).
5. Run N replications, collect handover times with `env.now`, aggregate percentiles.
6. Sweep `monthly_sanction_budget` and plot handovers completed vs. budget.

Key snippet:

```python
def build_house(env, house_id, crews, stats, rng):
    start = env.now
    for stage, (lo, mode, hi) in STAGES.items():
        with crews.request() as req:
            yield req                      # wait for a free crew
            with crews.request() as _:
                yield env.timeout(rng.triangular(lo, mode, hi))
        stats.setdefault(stage, []).append(env.now)
    stats["cycle_time"].append(env.now - start)
    stats["handovers"].append((house_id, env.now))
```

## WHEN TO USE IN PRODUCTION
Use it for capacity planning before a scheme year: how many crews to hire, how much
material buffer to hold, which districts will slip. Use it in policy briefings to
show the cost of a budget cut in days-of-delay. Do NOT use a stochastic simulation
as a contractual schedule or for per-house cost accounting — it gives distributions,
not commitments. Do NOT use it where stage durations are unknown and unmeasurable.

## HOW IT HELPS STUDENTS
Students learn discrete-event modelling, resource contention, Monte Carlo
replication, percentile reporting, and translating a policy statement into
measurable throughput — core skills for operations and civic-tech analyst roles.

## STARTER CODE
See `starter/main.py` — a runnable SimPy model with a NumPy RNG, a budget sweep,
deterministic seeds, and `# TODO` markers.
