--- license: cc-by-4.0 language: - en library_name: pytorch tags: - ocean-waves - wave-prediction - flow-matching - unstructured-mesh - coastal-hazard - hong-kong --- # WaveFlow **Probabilistic ocean-wave and water-level prediction on unstructured meshes** ยท v1.0.0 WaveFlow is a conditional flow-matching model for ensemble prediction of significant wave height, peak period, mean direction and water level on unstructured coastal/global meshes, conditioned on atmospheric fields (ERA5 reanalysis for pretraining, IFS ensemble forecasts for prediction) and optional tide phase. This repository hosts the three final checkpoints and the mesh/statistics assets. The model, training loop, sampling code and exact configs are in the GitHub repository: - **Code, training and deployment docs**: - **Dataset DOI** (metadata + SHA256): ## Models | File | Domain | Variables | Params | Epoch | |---|---|---|---|---| | `weights/waveflow-hk-4var-ep49.pt` | Hong Kong waters | Hs, Tp, Dm, water level | 45.7 M | 49 | | `weights/waveflow-global-hs-ep99.pt` | global ocean | Hs | 465 M | 99 | | `weights/waveflow-global-4var-ep199.pt` | global ocean | Hs, Tp, Dm, water level | 966 M | 199 | All checkpoints store the **EMA weights baked into `model_state_dict`**, with the non-EMA buffers preserved. Load them with `training.use_ema=false` and `sampling.use_ema_for_sampling=false`. ## Quick start ```bash git clone https://github.com/Leroy-Xiong/WaveFlow.git cd WaveFlow conda env create -f environment.yml conda activate waveflow python reproduce.py setup --download # weights, assets and case forcing python reproduce.py infer fig3f # example: global Hs, 10 members ``` For your own inputs, run `main.py --mode sample` with the released config and checkpoint; `-o sampling.atm_source=ens -o sampling.ens_dir=...` switches to IFS ENS forecast forcing (see `TRAINING.md` for the per-member file layout). See the GitHub `README.md` and `WEIGHTS.md` for the exact command, data layout and GPU requirements. Training/fine-tuning on your own hindcast is documented in `TRAINING.md`. ## Files and checksums ``` weights/waveflow-hk-4var-ep49.pt 183.1 MB weights/waveflow-global-hs-ep99.pt 1,881.0 MB weights/waveflow-global-4var-ep199.pt 3,883.3 MB assets.tar.gz 22.1 MB forcing/waveflow-v1.0.0-forcing-cases.tar.gz 234 MB MANIFEST.json / SHA256SUMS ``` Verify with `sha256sum -c SHA256SUMS`. `assets.tar.gz` restores the mesh coordinates, patch clusters, normalization statistics and ocean boundary under `data/`; the forcing archive restores the ERA5 case slices and the Ragasa IFS ENS members used by the released recipes. ## Licence and citation Weights: **CC BY 4.0**. Code: **MIT**. Third-party assets retain their own licences (see `THIRD_PARTY.md`). If you use WaveFlow, please cite the manuscript and the dataset record: ```bibtex @misc{waveflow2026, title = {WaveFlow: probabilistic ocean-wave and water-level prediction on unstructured meshes}, year = {2026}, doi = {10.5281/zenodo.24106732}, url = {https://github.com/Leroy-Xiong/WaveFlow} } ```