WaveFlow / README.md
tikitaka0345's picture
Upload README.md with huggingface_hub
e79f01b verified
|
Raw History Blame Contribute Delete
3.28 kB
---
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**:
<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
```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}
}
```