# FireWx-FM Inference Contract

This document defines the final serving contract for the released FireWx-FM CONUS model.

## Native Grid

- Domain: Lower-48 CONUS.
- CRS: EPSG:5070.
- Native resolution: 5 km grid cells.
- Prediction target: 12-hour active-fire occupancy probability.
- Tensor order: `[channel, y, x]`.
- Input shape: `[16, H, W]`.

The model remains gridded. County or sub-county outputs are produced by post-inference aggregation from the native 5 km probability grid.

## Channel Order

| Index | Name | Source | Description | Unit |
|---:|---|---|---|---|
| 0 | `t2m` | NOAA HRRR | 2 m air temperature | K |
| 1 | `d2m` | NOAA HRRR | 2 m dew point temperature | K |
| 2 | `u10` | NOAA HRRR | 10 m eastward wind component | m s-1 |
| 3 | `v10` | NOAA HRRR | 10 m northward wind component | m s-1 |
| 4 | `cape` | NOAA HRRR | CAPE, 0-3000 m above-ground layer | J kg-1 |
| 5 | `sp` | NOAA HRRR | Surface pressure | Pa |
| 6 | `blh` | NOAA HRRR | Boundary-layer height | m |
| 7 | `vis` | NOAA HRRR | Visibility | m |
| 8 | `prate` | NOAA HRRR | Precipitation rate | kg m-2 s-1 |
| 9 | `tp` | NOAA HRRR | Accumulated precipitation | kg m-2 |
| 10 | `dynamic_valid` | Input builder | Dynamic weather validity fraction | 0-1 |
| 11 | `static_valid` | Input builder | Static-layer validity fraction after reprojection | 0-1 |
| 12 | `fuel_fbfm40` | LANDFIRE | Fire-behavior fuel model | category code |
| 13 | `canopy_cover` | LANDFIRE | Canopy cover | percent |
| 14 | `housing_density` | Wildfire Risk to Communities | Housing-unit density | provider native |
| 15 | `population` | LandScan | Population | persons |

Machine-readable metadata is stored in [`models/metadata/input_channels.json`](../models/metadata/input_channels.json).

## Normalization

The final model uses train-split z-score normalization for continuous channels. In the released training template this covers HRRR channels `0-9`, canopy cover channel `13`, and exposure channels `14-15`. The inference script applies the statistics from:

```text
models/metadata/input_normalization_stats.json
```

The expected statistics format is the one written by `training/train_cold_tiled_mainline.py`: a JSON object with `enabled`, `method`, `eps`, and a `channels` list containing `index`, `mean`, and `std`.

## Validity Masks

The two mask channels are part of the input contract.

- `dynamic_valid` records dynamic weather-input validity after the cache-building step.
- `static_valid` records the fraction of static layers with valid values after reprojection.

These masks are not model outputs. They are input features that let the model distinguish true zeros from sanitized missing values.

## Final Serving Settings

The released serving run uses:

- Checkpoint: `models/checkpoints/firewxfm_2024_staticfix_region_balanced_bce_seed42.pt`.
- Window: `256`.
- Stride: `64`.
- Halo: `32`.
- Phase shifts: all combinations of `0,4,8,12` along y and x.
- Zeroed channels after normalization: `14,15`.

Production live preprocessing should use `scripts/build_5km_input_stack.py` to
repair the 16-channel stack with the corrected static cache before inference.

The phase ensemble averages shifted overlapping-window predictions. This reduces dependence on tile origin during full-domain inference.

## Output

The model output is a probability map in `[H, W]` order with values in `[0, 1]`. GeoTIFF writing is intentionally kept outside `firewxfm.serve_conus` so users can preserve their own transform, CRS, and mask handling.