docs/sweep.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
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
# Scenario sweep

Build 3 ships an end-to-end orchestration step that runs every predefined
scenario, computes [network metrics](network.md) for each, and bundles the
outputs into a single directory ready for Fig. 4 and Fig. 5.

The sweep does **not** involve inference — no EM, no fitting. Build 4 adds
bootstrap uncertainty on top of the same artifacts.

## Run

```bash
uv run iohmm-evac sweep run --output-dir ./output/sweep/ --seed 0
```

Default flags: all four scenarios, `--seed 0`, `--n-households 10000`,
`--n-hours 120`. Override any of them on the command line. Use
`--scenarios baseline,contraflow` to run a subset for quick iteration.

The sweep is sequential — each scenario takes about a second at default
size, and parallelizing four sub-second runs is not worth the orchestration
overhead.

## Inspect

```bash
uv run iohmm-evac sweep summary --input-dir ./output/sweep/
```

Prints a per-scenario table::

```
scenario             delay_hr   peak_er_share   peak_er_hour   overflow   failed_evac
baseline             5082.2     0.087           99             5202       378
early-warning        4618.5     0.094           74             6017       197
targeted-messaging   4852.4     0.085           99             5144       388
contraflow           2996.3     0.063           97             5668       307
```

(Numbers above are illustrative.) Build 3.5 swapped the original
`clearance_hr` column for `peak_er_share` / `peak_er_hour`; see
[network.md](network.md) for why.

## Plot

```bash
uv run iohmm-evac report sweep-all \
    --input-dir ./output/sweep/ \
    --output-dir ./output/figures/
```

Writes `sweep_departures.png` (Fig. 4: cumulative departures across
scenarios) and `sweep_network.png` (Fig. 5: 2x2 panel of network metrics).
Single-figure variants:

```bash
iohmm-evac report sweep-departures --input-dir DIR [--output PATH]
iohmm-evac report sweep-network    --input-dir DIR [--output PATH]
```

## Output layout

```
output/sweep/
├── baseline/
│   ├── observations.parquet
│   ├── observations.population.parquet
│   ├── observations.timeline.parquet
│   ├── observations.config.toml
│   └── network_metrics.toml
├── early-warning/
│   └── (same structure)
├── targeted-messaging/
│   └── (same structure)
├── contraflow/
│   └── (same structure)
└── sweep.toml
```

`sweep.toml` records the package version, seed, household count, hour
horizon, and the list of scenarios actually run. `network_metrics.toml`
inside each scenario directory carries the scalar metrics plus the per-hour
diagnostic arrays from [network.md](network.md).

## Same-seed semantics

Every scenario in a sweep is run under the **same** RNG seed, intentionally:
this makes cross-scenario differences attributable to the scenario-specific
input changes (warning timing, coastal-zone risk multiplier, network
capacity) rather than to RNG drift. Two sweeps with the same seed produce
bit-identical observations parquets per scenario.

See [scenarios.md](scenarios.md) for a full description of what each
scenario changes vs. baseline.