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: https://github.com/Leroy-Xiong/WaveFlow
• Dataset DOI (metadata + SHA256): https://doi.org/10.5281/zenodo.24106732

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

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:

@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}
}