UE-surrogates

Исследовательский репозиторий по суррогатному моделированию транспортных потоков пользовательского равновесия (UE) на одной фиксированной сети и прототипу bilevel-задачи проектирования пропускных способностей поверх этих суррогатов. Сделан в рамках магистерской диссертации.

О чём проект

Решается задача быстрой аппроксимации оператора равновесия

X* = UE(G, T0, C, D)

где G — фиксированный граф, T0 — времена свободного хода, C — пропускные способности рёбер, D — OD-спрос. Источник истины — точный солвер LeBlanc (code/leblanc.py, портирован с Matlab из Ageev_LeBlanc/). ML-модели обучаются на его выходах и валидируются относительно него.

В репозитории два параллельных ML-пайплайна:

• code/ml_model/ — суррогаты нижнего уровня X* = UE(G, T0, C, D).
• code/bilevel_end2end/ — сквозной суррогат для bilevel-задачи: f_theta(D, budget, invest_weight) -> C*.

Также есть исследовательский bilevel-прототип верхнего уровня code/bilevel_problem/ с жадным покоординатным поиском пропускных способностей.

Структура

code/
  leblanc.py            оракульный UE-солвер
  exec.py               эталонная фиксированная сеть (T0, C, D)
  generator/            генерация HDF5-датасета сценариев
  ml_model/             суррогаты UE (MLP, KAN, HeteroGNN(+KAN), Graph Transformer, Wardrop HGNN)
  bilevel_problem/      bilevel-прототип проектирования пропускных способностей
  bilevel_end2end/      сквозной bilevel-суррогат
  data/                 активные UE-сплиты (train/val/test/test_hard.h5)
  best_models/          курируемые тренировочные чекпойнты
  best_eval/            курируемые сырые eval-прогоны
  best_eval_exactproj/  eval-прогоны с точной балансовой проекцией
  tests/                pytest-набор
Ageev_LeBlanc/          эталонная Matlab-реализация LeBlanc

Быстрый старт

Окружение — Python 3, venv лежит в code/venv/.

code\venv\Scripts\Activate.ps1
python -m pip install -r code/requirements.txt

Сгенерировать датасет:

python code/generator/build_dataset.py --output-dir code/data --preset standard --seed 42 `
  --workers 8 --chunk-size 32 `
  --train-size 20000 --val-size 2500 --test-size 2500 --test-hard-size 2500 `
  --overwrite --no-resume
python code/generator/sanity_check.py code/data --check-conservation

Обучить суррогат (пример с Graph Transformer):

python code/ml_model/train.py --model graph_transformer_ue --data-root code/data `
  --epochs 100 --batch-size 32 --lr 1e-3 --patience 20 --seed 42 --device auto `
  --gt-d-model 128 --gt-heads 4 --gt-layers 4 --gt-ff-hidden 256 --gt-lap-pe-dim 4

Оценить с точной балансовой проекцией:

python code/ml_model/eval.py --checkpoint code/runs/<run>/best.pt --model graph_transformer_ue `
  --data-root code/data --splits test test_hard --batch-size 32 --seed 42 --device auto `
  --apply-exact-balance-projection --balance-projection-iters 2

Сквозное обучение bilevel-задачи (генерация bilevel-датасета на точном LeBlanc, обучение Graph Transformer как f_theta(D, budget, invest_weight) -> C*, переоценка дизайнов точным LeBlanc):

python code/bilevel_end2end/build_dataset.py --output-dir code/data_bilevel_end2end --data-root code/data `
  --train-size 1024 --val-size 128 --test-size 128 --test-hard-size 128 --overwrite

python code/bilevel_end2end/train.py --model graph_transformer_ue --data-root code/data_bilevel_end2end `
  --epochs 80 --batch-size 16 --lr 5e-4 --patience 20 --seed 42 --device auto `
  --gt-d-model 128 --gt-heads 4 --gt-layers 4 --gt-ff-hidden 256 --gt-lap-pe-dim 4 `
  --lambda-design 1.0 --lambda-z 0.5 --lambda-support 0.2 --lambda-budget 0.1 `
  --experiment-name bilevel_end2end_gt --batch-progress

python code/bilevel_end2end/evaluate.py --checkpoint code/runs/<run>/best.pt `
  --data-root code/data_bilevel_end2end --splits test test_hard --device auto

Запустить тесты:

python -m pytest -q

Полный набор команд по моделям и режимам — в commands.md.

Основные результаты

После точной балансовой проекции лучший практический результат показывает Graph Transformer UE: test R2 = 0.9923, test_hard R2 = 0.8379, латентность одного сценария ~2.7 ms против ~786 ms у LeBlanc (ускорение ~300x на test и ~410x на test_hard).

Документация

• commands.md — шпаргалка по обучению, оценке и инференсу.