---
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}
}
```