# P3 — Polling Day Voter-Flow Simulation (SimPy + NumPy)

## PURPOSE
A discrete-event simulation of voter movement through a polling station on election day.
The video highlights that the Additional Commissioner inspected Chandrampalem High School
to ensure "voters do not face any inconvenience" and that ramps are ready for the elderly
and disabled. This project turns that concern into numbers: how long will the 18 polling
stations take to clear a given crowd, how do queue times change when ramp access is
restricted for less-mobile voters, and does water/power provisioning hold up.

## WHY THIS MATTERS
Readiness inspections exist to prevent bottlenecks on the day itself. A simulation lets a
control room ask "what if" before spending money: extra staff, more ramps, a second water
point. It is the cheapest way to test an operational plan.

## HOW TO BUILD
1. Install SimPy and NumPy from `requirements.txt`.
2. Model each of the 18 stations as a SimPy `Resource` with N verification booths.
3. Sample voter inter-arrival times with NumPy (deterministic seed) to get a peak crowd.
4. Give elderly/disabled voters a slower service time unless a ramp is available.
5. Run the sim and collect mean/max wait; print a summary table.

Key snippet:
```python
class Station:
    def __init__(self, env, booths):
        self.booths = simpy.Resource(env, capacity=booths)

def voter(env, station, service_mean, has_ramp):
    with station.booths.request() as req:
        yield req
        yield env.timeout(service_mean if has_ramp else service_mean * 2.5)
```

## WHEN TO USE IN PRODUCTION
Use for capacity planning: how many booths, staff, ramps, or water points a site needs for
an expected turnout. Also useful for hospital OPD queues or event gates. Do NOT use it as
a forecasting tool — it models the flow you give it, not the turnout; feed it real
historical arrivals. Do NOT oversell its precision; validate service-time assumptions with
field observation.

## HOW IT HELPS STUDENTS
Students learn discrete-event modelling, SimPy resources, reproducibility with NumPy
seeds, and deriving operational insight from a simulation — a skill rare in junior portfolios.

## STARTER CODE
`starter/main.py` sets up the environment, 18 stations, voter generators, ramp-dependent
service times, and prints wait statistics, with `# TODO` markers for scenarios.
