Create README.md

README.md

@@ -0,0 +1,61 @@
+# Typhoon Predict
+
+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.
+
+## Model Architecture
+
+The model combines:
+
+- 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.
+
+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.
+
+## Training Configuration
+
+The released experiment uses:
+
+- 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.
+
+The training pipeline normalizes atmospheric variables, extracts storm-centered windows, aligns ERA5 with track timestamps, and uses chronological validation to reduce temporal leakage.
+
+## Data Pipeline
+
+Training examples require:
+
+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.
+
+Cached patches can be reused to reduce repeated preprocessing and storage overhead during experiments.
+
+## 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.
+
+## 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.
+
+## 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.