docs/scenarios.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
# Scenarios

Four predefined scenarios ship with the build. Each one returns a fully-formed
`SimulationConfig` from `src/iohmm_evac/scenarios.py`. The CLI exposes them
via `--scenario {name}`. Adding a new scenario is a one-function change — see
[`development.md`](development.md).

| Name                 | What changes vs. baseline                                       | Intended figure |
|----------------------|------------------------------------------------------------------|-----------------|
| `baseline`           | Spec defaults: voluntary at t=60, mandatory at t=84, N_cap=1500. | Fig. 3 (state shares over time). |
| `early-warning`      | Voluntary pulled to t=48, mandatory to t=72.                     | Counterfactual where pre-storm orders go out 12h earlier. |
| `targeted-messaging` | Risk multiplier 1.5 applied to households in zones A and B.      | Counterfactual where authorities focus messaging on coastal-zone households. |
| `contraflow`         | Network capacity raised: N_cap = 2500.                           | Counterfactual where contraflow operations open more outbound lanes. |

## Baseline

Lays the calibration target. All other scenarios are diffs against it. Tune
the baseline first; the others should respond to single-knob changes after
that.

## Early warning

Implementation: a `TimelineParams` with `voluntary_hour=48, mandatory_hour=72`
substituted into the otherwise-default config. Expected effect:

* Departures begin earlier.
* `tir` distributions in ER shift earlier.
* The terminal SH share at landfall is similar but reached sooner.

## Targeted messaging

Implementation: a `PopulationParams` with `targeted_zone_multiplier=1.5`
substituted in. The simulator picks this up via a per-household risk
multiplier when computing $\rho_{i,t}$. Build 3.5 widened the targeted set
from zone A only ($d_i < 5$ km) to zones A *and* B ($d_i < 20$ km, ~60% of
the population), simulating a coastal-zone messaging campaign. Households
in zone C ($d_i \ge 20$ km) are unaffected. Rationale: at the original
zone-A-only configuration the targeted population (~10%) was too small for
the scenario to differ visibly from baseline at the aggregate metric level.

## Contraflow

Implementation: a `FeedbackParams` with `n_cap=2500`. Expected effect:
congestion `c_t` saturates later, so `ER→SH` arrivals come faster and
`PR→ER` is less suppressed.