docs/00-overview.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
# Overview

This project simulates synthetic hurricane-evacuation household behavior. It
implements a **data-generating process (DGP)** designed to be paired with an
Input-Output Hidden Markov Model (IO-HMM) fit in a later build. The DGP
produces five-state latent trajectories per household over an hourly timeline
leading up to landfall, plus three observed emission channels (departure
indicator, displacement, communication count) and the static covariates and
exogenous timeline that drove them.

The DGP is intentionally implementable as an IO-HMM, with two pieces of
state-internal bookkeeping (an `evac_path` label set on first SH entry, and a
time-in-state counter while in ER) treated as auxiliary attributes rather than
additional latent states. Two endogenous feedbacks — network congestion and
peer-departure share — feed transitions at step *t* using lagged (t−1) state.

## Pipeline

```
                 ┌──────────────┐    ┌────────────┐
                 │  population  │    │  timeline  │
                 │  synthesis   │    │ (forecast, │
                 │  (covariates)│    │  warnings) │
                 └──────┬───────┘    └──────┬─────┘
                        │                   │
                        ▼                   ▼
                 ┌──────────────────────────────┐
                 │       per-step loop          │
                 │   transitions  +  emissions  │
                 │   ↑ feedback at lag t-1 ↑    │
                 └──────┬───────────────────────┘
                        │
                        ▼
                 ┌──────────────────────────┐
                 │   SimulationResult       │
                 │   (states, D, X, C, ...) │
                 └──────────┬───────────────┘
                            │
                            ▼
                  Parquet + TOML sidecar
                            │
                            ▼
                   (later builds: IO-HMM
                    fit, network coupling,
                    figures)
```

## Pointers

* DGP specification: [`dgp/`](dgp/) — split by responsibility (one file per
  subsystem).
* Scenarios: [`scenarios.md`](scenarios.md).
* CLI examples: [`cli.md`](cli.md).
* Development setup: [`development.md`](development.md).