README.md

metadata

license: mit
library_name: pytorch
pipeline_tag: time-series-forecasting
tags:
  - tropical-cyclone
  - weather-forecasting
  - pytorch
  - ibtracs
  - causal-inference

Trackformer1.1

Trackformer1.1 is a research model for causal tropical-cyclone track, pressure, intensity, and wind-structure inference over the western Pacific. It is not an operational warning system and must not be used for evacuation, aviation, maritime, emergency-management, or other safety-critical decisions.

What it uses

Inference accepts the observed storm history and weather analyses available at the issue time. It uses the current, 12-hour, and 24-hour analysis states to extrapolate a bounded western-Pacific pressure and flow state. The route sees a domain covering China, Japan, Taiwan, the Philippines, and the open western Pacific, so nearby lows, subtropical ridges, troughs, jets, and other storms can affect the steering field.

No positive-lead weather field, official agency forecast, or post-issue observation is passed to the model. Later observations can be used only for verification after a forecast has been generated.

Model structure

1. A causal regional state module extrapolates pressure, 500 hPa height, and 850/500/200 hPa wind from three analysis snapshots.
2. A weighted steering ensemble samples inner, deep-layer, ridge, trough, and jet views across the full western-Pacific domain and integrates the route.
3. Three primary neural experts predict maximum wind, central pressure, RMW, and directional 34/50/64 kt radii from a nine-step track window and the current four-channel analysis patch.
4. Three structure experts provide a validation-selected secondary blend.
5. Three temporal experts read only same-storm 12-hour and 24-hour analysis patches. Their residual branch is enabled only for the validated wind adjustment; pressure remains on the calibrated primary path.
6. The final intensity output is coupled to the causal pressure-map minimum, pressure deficit, 850 hPa wind, and quadrant anomaly extent. Radius outputs remain ordered as R34 >= R50 >= R64.

The public bundle contains frozen inference checkpoints and calibration state; it does not include raw weather archives or a training service.

Files

• trackformer_1_1.py - public loader and route API.
• trackformer_1_1_route.py - whole-domain causal pressure-state route.
• trackformer_1_1_intensity.py - intensity and wind-structure inference.
• trackformer_1_1_temporal.py - inference-only temporal expert architecture.
• models/trackformer_1_1/ - three expert groups, calibration, and manifest.

Quick start

python -m pip install -r requirements.txt
python - <<'PY'
import numpy as np
from trackformer_1_1 import load_intensity, forecast_pacific_state

model = load_intensity(device="cpu")
track = np.zeros((9, 54), dtype="float32")
field = np.zeros((4, 17, 17), dtype="float32")
current_structure = np.full(13, np.nan, dtype="float32")
rows, metadata = model.predict(
    track,
    field,
    current_wind=65.0,
    current_pressure=980.0,
    previous_wind=60.0,
    previous_pressure=985.0,
    current_structure=current_structure,
)
print(rows[0])
print(metadata["model"])
PY

The intensity contract is track=(9,54), field=(4,17,17), and optional history_field=(8,17,17) for the 12-hour and 24-hour analysis patches. The route contract is fields=(3,7,latitude,longitude) and pressure=(3,latitude,longitude), ordered current, 12 hours before, and 24 hours before. See models/trackformer_1_1/manifest.json for the complete contract.

Requirements and limits

CPU inference works with Python 3.10+, NumPy, PyTorch, and SciPy. A modern Mac with 8 GB RAM is a practical minimum; 16 GB RAM is preferable when decoding large analysis grids. The checkpoints are native PyTorch files. GGUF is not an appropriate format for this CNN/Transformer weather model; keep the native PyTorch weights or convert to another format only after numerical parity testing.

The model is experimental. Track and intensity errors vary by storm, basin, analysis source, and data quality. Use official meteorological agencies for real-world forecasts and warnings.