pakflood-lora / CODE_README.md
msherry's picture
project code, results and figures
17285c6 verified
|
Raw History Blame Contribute Delete
3.95 kB

PakFlood-LoRA: project code

Deep learning course project, MS AI, NED University of Engineering & Technology. Author: Muhammad Shahwar Uddin (CS-139/2026). Supervisor: Dr. Sharaf Hussain.

Everything runs on top of the GEOID-Flood authors' TerraTorch repository (github.com/links-ads/geoid-flood) in a Python 3.12 virtual environment (TerraTorch 1.1, PyTorch 2.7.1, PEFT 0.21.3). The scripts below are the project's own additions; the dataset (82 GB) and the full checkpoints stay on the training server, the trained rank-32 LoRA model is in assets/ of this repository as an fp16 state dict (205 MB).

Folder layout (this repository)

Path What it is
app.py, requirements.txt, samples/, samples.json, assets/ the live demo (Gradio): rebuilds the model with TerraTorch and loads the trained weights; 15 official Pakistani test tiles
PakFlood_LoRA_Colab_demo.ipynb runs the demo in Google Colab with a public link
code/ the training and evaluation pipeline (below)
code/configs/ one YAML per run, generated by make_configs.py from the authors' early-fusion Sentinel-1 config (regenerate it inside the authors' repository)
results/results.json every number in the report (test metrics, confidence intervals, cost table, population)
results/per_tile_lora_r32_all_test.csv per-tile confusion matrices of the rank-32 model on the 2,417 official test tiles
results/pop_*.csv affected population per EMSR838 tile and area of interest, per model
figures/ all figures of the report and slides

Pipeline (code/)

Script What it does
make_sa_split.py builds the South Asia hold-out, few-shot and Pakistan-test metadata CSVs from the official split
make_configs.py derives every run configuration (frozen, LoRA r16, LoRA r32, full fine-tune, CE+Dice, hold-out, few-shot)
tasks.py TerraTorch task subclass: weighted cross-entropy + Dice loss, checkpoint initialisation for the few-shot pass
run_job.sh queues a terratorch fit/test or any command on the GPU behind a lock, detached from the login session
h3_chain.sh, h12_chain.sh the ordered evaluation chains (hold-out tests, few-shot fit and tests, predictions, population)
predict_tiles.py full-tile sliding-window prediction (256/128, averaged softmax), GeoTIFF maps, per-tile confusion matrices
bootstrap.py paired bootstrap 95% confidence intervals over tiles or events
population.py WorldPop overlay: affected people and flooded area per area of interest
pack_demo.py exports the fp16 state dict and the sample tiles for the demo
plot_results.py, plot_overview.py, plot_architecture.py, make_figures.py the figures

Reproducing a run

# inside the geoid-flood repository, with the dataset under data/geoid-flood and this repo's code/ copied to pakflood/
.venv/bin/python pakflood/make_sa_split.py
.venv/bin/python pakflood/make_configs.py
bash pakflood/run_job.sh fit lora_r32_all pakflood/configs/lora_r32_all.yaml
bash pakflood/run_job.sh test test_lora_r32_all pakflood/configs/lora_r32_all.yaml workdir/pakflood/lora_r32_all/v1/checkpoints/best.ckpt
PYTHONPATH=. .venv/bin/python pakflood/predict_tiles.py workdir/pakflood/lora_r32_all/v1/checkpoints/best.ckpt preds/r32_test --events all --split test --task pakflood
.venv/bin/python pakflood/bootstrap.py r32=preds/r32_test/per_tile.csv --unit event

Headline results

Official GEOID-Flood test split (2,417 tiles, 80 events), flood IoU: frozen encoder 0.433, LoRA r16 (q, v) 0.493, LoRA r32 (all linear layers) 0.525, full fine-tune 0.525. South Asia hold-out 0.679, after few-shot with 26 tiles 0.720. Affected population for EMSR838 (Punjab, August 2025): hold-out model 795,280 vs official 766,148 (+3.8%).

Data: GEOID-Flood v1.1 (CC BY 4.0). Base model: TerraMind v1 base (IBM and ESA). Population: WorldPop 2020.