| --- |
| license: mit |
| tags: |
| - wildfire |
| - geospatial |
| - weather |
| - earth-observation |
| - pytorch |
| - reproducibility |
| pipeline_tag: image-segmentation |
| library_name: pytorch |
| pretty_name: FireWx-FM |
| --- |
| |
| # FireWx-FM |
|
|
| FireWx-FM is a wildfire-focused gridded model for 12-hour active-fire occupancy |
| prediction over the Lower 48 United States. The released code maps a fixed |
| 16-channel tensor on a 5 km EPSG:5070 grid to an active-fire occupancy |
| probability map. |
|
|
| This Hugging Face release is the clean ICLR/technical-report companion package: |
| it includes model code, checkpoints, inference utilities, training/cache |
| templates, public data-source notes, example outputs, the ICLR manuscript |
| source, and the technical report source. |
|
|
| ## Contents |
|
|
| | Path | Purpose | |
| |---|---| |
| | `firewxfm/` | Model definition and tiled CONUS inference code. | |
| | `models/checkpoints/` | Released PyTorch checkpoints. | |
| | `models/metadata/` | Input-channel contract, normalization statistics, and run metadata. | |
| | `training/` | Cache-building, training, and metric utilities. | |
| | `training/configs/` | Path-free templates for CONUS and multi-year reruns. | |
| | `scripts/` | Data preparation, release checks, live-stack builder, seam audit, and smoke tests. | |
| | `examples/final_prediction/` | Small final probability/preview example for inspection. | |
| | `data_sources/` | Source-data provenance and access notes. | |
| | `paper/iclr_source/` | ICLR manuscript LaTeX source. | |
| | `technical_report/source/` | Technical report LaTeX source. | |
| | `artifacts/results/` | Compact public result summaries without internal filesystem paths. | |
|
|
| ## Quick Start |
|
|
| ```bash |
| python3 -m venv .venv |
| source .venv/bin/activate |
| pip install -r requirements.txt |
| python3 scripts/check_release_files.py |
| python3 scripts/smoke_inference.py --device cpu |
| ``` |
|
|
| The smoke test uses a synthetic tensor. Full scientific reproduction requires |
| the public source datasets listed in `data_sources/DATA_SOURCES.md`. |
|
|
| ## Model Input Contract |
|
|
| The model expects a channel-first tensor with shape `[16,H,W]`. |
|
|
| | Channels | Source | Role | |
| |---:|---|---| |
| | 0-9 | NOAA HRRR | Dynamic weather fields. | |
| | 10-11 | Input builder | Dynamic and static validity masks. | |
| | 12 | LANDFIRE | Fire-behavior fuel model. | |
| | 13 | LANDFIRE | Canopy cover. | |
| | 14-15 | WRC / LandScan | Housing density and population; zeroed in the no-exposure serving run. | |
|
|
| See `models/metadata/input_channels.json` and |
| `models/metadata/input_normalization_stats.json` for the exact machine-readable |
| contract. |
|
|
| ## Inference |
|
|
| Run inference from a prebuilt 16-channel stack: |
|
|
| ```bash |
| python3 -m firewxfm.serve_conus \ |
| --input-npy /path/to/input_stack_16chw.npy \ |
| --checkpoint models/checkpoints/firewxfm_2024_staticfix_region_balanced_bce_seed42.pt \ |
| --normalization-stats models/metadata/input_normalization_stats.json \ |
| --output-npy outputs/firewxfm_probability.npy |
| ``` |
|
|
| For full-map serving, use overlap-window inference with phase averaging. The |
| default settings are documented in `docs/serving_notes.md`. |
|
|
| ## Reproducibility |
|
|
| Use `REPRODUCIBILITY.md` for the exact verification path: |
|
|
| - artifact presence check, |
| - checkpoint smoke inference, |
| - ICLR source compilation, |
| - technical report source compilation, |
| - real-data cache rebuild and retraining commands. |
|
|
| Raw source data are not redistributed. This package documents where each source |
| comes from and provides path-free templates for local reproduction. |
|
|
| ## Citation |
|
|
| ```bibtex |
| @misc{firewxfm2026, |
| title = {FireWx-FM: A Wildfire Foundation Model Technical Report}, |
| author = {Xu, Yangshuang and Dai, Yuyang and Chang, Liling and Wang, Qi and Dong, Yushun}, |
| year = {2026}, |
| note = {FireWx-FM code, checkpoints, and reproducibility package} |
| } |
| ``` |
|
|
