# Abduction Response Simulator: Patrol Search Toward Palnadu

## PURPOSE
A SimPy + NumPy discrete-event simulation of the first 24 hours after a kidnapping report.
It models how quickly a city police control room — as in the Vijayawada case — can trace
and reach a victim transported out of the city toward a neighbouring district such as
Palnadu, given a limited number of patrol units, checkpoint queues and imperfect clue
arrival from technical evidence.

## WHY THIS MATTERS
The transcript tells us three things that are simulation parameters: the incident happened
late on a Sunday night (low shift staffing), the victim was moved out of Vijayawada into
Palnadu district, and police used "modern technical evidence very effectively" to locate
him and rescue him unharmed on Monday. This project teaches students that rescue time is a
queueing and coverage problem, not luck — and that clue latency is usually the dominant
term.

## HOW TO BUILD
1. Represent units, checkpoints and search zones as SimPy resources and processes.
2. Emit clue arrivals from a Poisson process; each clue matures after a random delay
   (call-record, camera analysis) before it unlocks a search zone.
3. Sample mobilisation and travel times with NumPy lognormal/choice distributions.
4. Run N replications with different seeds and report mean/percentile time-to-rescue and
   utilisation per unit.

```python
def clue_generator(env, matcher, rng, maturity_hours):
    while True:
        yield env.timeout(rng.exponential(0.5))
        env.process(matcher.mature(env.now + maturity_hours))
```

## WHEN TO USE IN PRODUCTION
Use it for patrol-coverage planning, "what if we add two checkpoints on the Palnadu
highway?" studies, and shift-roster sizing for night incidents. Do NOT use it to predict
individual outcomes, and do not feed it real victim data — parameters are aggregate
estimates, not personal records.

## HOW IT HELPS STUDENTS
Students learn discrete-event simulation, stochastic modelling, Monte-Carlo replication and
sensitivity analysis — the exact toolkit for operations-research and public-safety
analytics roles, plus how to reason about variance instead of a single number.

## STARTER CODE
`starter/main.py` builds the SimPy environment, clue pipeline, patrol resource and a
`run_once()` Monte-Carlo driver with `# TODO` markers for calibration and plotting.
