Model card: StormFusion-MT v2 + TrackFormer (track-only), WP-2020+ results

README.md

@@ -1,74 +1,67 @@
-# Typhoon Predict
+---
+license: mit
+library_name: pytorch
+pipeline_tag: time-series-forecasting
+tags:
+- tropical-cyclone
+- weather-forecasting
+- pytorch
+- era5
+- ibtracs
+---
 
-Typhoon Predict is an ERA5-conditioned tropical-cyclone track research model. It predicts future cyclone center positions from recent track history and a local atmospheric-state patch. The project is intended for research, experimentation, and reproducible model development.
+# StormFusion-MT & TrackFormer — tropical-cyclone forecasting
 
-## Model Architecture
+Two research checkpoints for tropical-cyclone forecasting. Each predicts, at 20 six-hourly lead
+times (6–120 h), a 17-dim state per lead: east/north storm motion (km), max wind (kt), central
+pressure (hPa), radius of max wind (km), and 34/50/64-kt wind radii in four quadrants.
 
-The model combines:
+**Research models — not an operational warning system. Do not use for evacuation, aviation,
+maritime, or emergency decisions.**
 
-- A convolutional encoder for storm-centered ERA5 atmospheric patches.
-- A bidirectional GRU for recent cyclone track history.
-- A fusion multilayer perceptron that combines the atmospheric and track representations.
-- Probabilistic output heads that predict the mean and log-scale of future latitude and longitude offsets.
-- A latent projection used to create correlated ensemble members for uncertainty-aware forecasts.
+| model | params | inputs | training data |
+|---|---|---|---|
+| StormFusion-MT v2 | 3.3M | ERA5 patches + track history | WP, 2000+, 1,337 storm-centered windows |
+| **TrackFormer** | 21M (fp16, 43MB) | **track history only (no ERA5)** | all basins, 1980+, 84,150 windows |
 
-The forecast is generated recursively for multiple lead times. The ensemble represents sampled plausible tracks; the mean track is a summary and should not be treated as a guaranteed path.
+Weights and full reproducible code (dataset builders, training, eval) are in the GitHub repo:
+**https://github.com/yu314-coder/typhoon-predict** (`models/`).
 
-## Training Configuration
+## Results — WP 2020+ held-out test (lower is better)
 
-The released experiment uses:
+| model | track km | vmax kt | pres hPa | rmw km | radius km |
+|---|---|---|---|---|---|
+| StormFusion-MT v2 (3.3M, ERA5) | 729 | 24.2 | 21.6 | 16.2 | 31.8 |
+| **TrackFormer (21M, no ERA5)** | **720** | **22.1** | 21.2 | **12.9** | 31.5 |
 
-- ERA5 reanalysis data beginning in 1979.
-- Western Pacific basin samples.
-- Four historical track steps as input.
-- Forecast lead times of 6, 12, 24, 48, 72, 96, and 120 hours.
-- Storm-centered patches with an 8 degree half-width at 0.5 degree resolution.
-- Chronological split: training through 2015 and validation through 2019.
-- Batch size 64, learning rate 2e-4, weight decay 1e-4.
-- Up to 80 epochs with early stopping patience of 12 epochs.
-- 50 ensemble members for uncertainty sampling.
+**Key finding:** a track-only model that never sees ERA5 **matches or beats** the full ERA5
+model on every metric. The expensive ERA5 atmospheric patches add little over past-track history
+plus more storms. Across experiments the pattern was consistent: **data diversity > engineered
+features > parameters** — a 17.7M ERA5 model overfit and did *worse* than the 3.3M one.
 
-The training pipeline normalizes atmospheric variables, extracts storm-centered windows, aligns ERA5 with track timestamps, and uses chronological validation to reduce temporal leakage.
+## Architectures
 
-## Data Pipeline
+- **StormFusion-MT v2** — separate inner/outer ERA5 conv encoders keeping a 3×3 grid of spatial
+  tokens, track/environment token encoders, a temporal Transformer context, learned + sinusoidal
+  lead-time queries, cross-attention decoding, and multi-task state / log-scale heads.
+- **TrackFormer** — the same decoder design, track-only: a 40-dim track-history projection →
+  Transformer context (d_model 384, 8 heads, 4+6 layers) → lead queries → dual heads. No
+  atmospheric inputs.
 
-Training examples require:
+## Usage
 
-1. Quality-controlled tropical-cyclone track fixes with timestamp, latitude, and longitude.
-2. ERA5 atmospheric fields covering the same time range.
-3. Storm-centered spatial extraction around each observed cyclone position.
-4. Historical track sequences paired with future positions at the configured lead times.
-5. Chronological train and validation splits.
+See the GitHub repo for `model_v2.py` / `train_track.py`, the checkpoints, and normalization
+stats. Inputs are per-feature standardized (stats saved with each checkpoint / dataset);
+multiply predictions by `TARGET_SCALE = [100,100,35,20,50] + [50]*12` for physical units.
 
-Cached patches can be reused to reduce repeated preprocessing and storage overhead during experiments.
+## Data
 
-## Inference
-
-The local inference script loads a PyTorch checkpoint, prepares the configured input sequence, runs ensemble sampling, and writes forecast points plus an optional HTML map. See run_inference.py and the GitHub repository for the current command-line workflow.
-
-When live ERA5 data is unavailable, the example inference path uses normalized atmospheric inputs as a software smoke test. Operational or scientific use requires real, correctly aligned atmospheric analysis data.
-
-## Minimum System Requirements
-
-For local inference with the released PyTorch checkpoint:
-
-- Operating system: macOS, Linux, or Windows
-- Python: 3.10 or newer
-- Processor: 64-bit CPU with four cores or more
-- Memory: 8 GB RAM minimum; 16 GB recommended
-- Storage: 2 GB free space for the repository, environment, checkpoint, and generated forecasts
-- GPU: not required; CPU inference is supported. Apple Silicon can use MPS when available.
-
-For faster experimentation, training, or batch inference, use a CUDA-capable NVIDIA GPU with at least 16 GB VRAM. An A100 or H100 is suitable for full training, but is not required to run the released checkpoint.
-
-## Model Formats
-
-The native release format is PyTorch. GGUF is designed primarily for transformer-style language models and is not a suitable interchange format for this custom CNN-GRU probabilistic model. ONNX or TorchScript conversion may be possible, but any converted model must be validated against the native checkpoint for numerical and forecast consistency.
+IBTrACS v04r01 best tracks (NOAA NCEI) and ERA5 reanalysis (Copernicus/ECMWF). Obtain the source
+data under its own access and licensing terms.
 
 ## Limitations
 
-This is a research model, not an operational warning system. Forecast quality depends on the training data, basin coverage, input alignment, preprocessing, and model calibration. It should not replace official meteorological agencies or emergency-management guidance.
-
-## License and Attribution
-
-Review the repository license and source-data terms before redistribution or commercial use. ERA5 data is provided by the Copernicus Climate Change Service and follows its applicable terms.
+- Absolute track error (~720 km averaged over 6–120 h) is far from operational quality.
+- The real ceiling is storm **diversity** (~13k storms have ever existed); larger models overfit.
+- Wind-radius labels are sparse; no calibration or comparison against official agency forecasts.
+- Pre-satellite track/intensity labels are lower quality.