making an ocean wave forecast model run faster on graphics cards, without changing its answers · website · português
Important
Used by the Federal University of Santa Catarina (UFSC). The operational wave forecast of LabECO/UFSC, ondaseventos.ufsc.br, is the first user of ww3-gpu; marola is the second.
Wave forecasts come from a computer model. WAVEWATCH III® (WW3) is the ocean wave model that the United States weather agency (NOAA, the National Oceanic and Atmospheric Administration) and many research groups use to forecast waves. It divides the ocean into a grid of points. At each point it stores how much wave energy travels in each direction and at each wave period (this table is called the wave spectrum). Then, step by step in time, it calculates how the wind adds energy, how breaking waves remove it, how waves exchange energy with each other, and how the energy travels across the grid.
That calculation is slow. WW3 is written in Fortran, a programming language for scientific computing, and it runs on ordinary processors (CPUs). A finer grid or a longer forecast costs more computing time, so a faster model gives a forecast sooner, a finer grid, or more forecasts for the same cost.
Graphics cards can do it faster. A GPU (graphics processing unit) is a chip with thousands of small cores that do the same calculation on many data points at once. A wave model does the same calculation at every grid point, so it fits a GPU well. WW3 has no official GPU version.
We rewrite the slowest parts of WW3 in C++ with Kokkos, a library that lets one copy of the code run on CPU cores or on an NVIDIA GPU. We rewrite one routine (a self-contained piece of the model) at a time, and we start with the routine that uses the most run time.
The one rule: the answers must not change. Each rewritten routine must give exactly the same numbers as the original Fortran, to the last binary digit ("bit for bit"), inside the same program. If the numbers differ, the rewrite is wrong. Identical numbers mean the faster code changes nothing that a forecaster relies on.
To make the comparison easy, we do not edit WW3 itself. A copy of WW3 (a fork) adds a switch to each rewritten routine. At run time you choose the original Fortran or the new code, run the same case twice, and compare the output files byte by byte.
The numbers below are from kokkos/PORT_STATUS.md, the ledger of the
port, regenerated by just port-score. The share of run time is measured on a 9 520-point test
grid on one CPU core.
| Stage | Routines of WW3 | Share of run time they cover |
|---|---|---|
| rewritten: a C++ version exists | 344 of 1 023 | 99.3 % |
| connected: WW3 calls the C++ version when its switch is on | 72 | 99.3 % |
| checked against WW3's own test suite | 14 | 48.6 % |
What has been shown, and what has not:
- Shown: the routine that used the most time (
W3SNL1, the energy exchange between waves) gives byte-identical output to the Fortran on all 100 single-core test cases of WW3's own test suite that use it, on a CPU. - Shown: on one graphics card (NVIDIA RTX 4090), that routine took 0.047 ms for 1 000 grid points, against 24.96 ms on one CPU core (benchmark record). That is the calculation alone: with the copies of the data to the card and back, one call took 0.75 ms, so the project is moving to code that keeps the data on the card for the whole run.
- Early: with the whole time step in C++ on a CPU, the 9 520-point case ran in 17.98 s against 41.92 s for the Fortran (2.33 times faster), with identical output. This is a single run on a busy machine, not yet a proper benchmark (log entry).
- Not yet: the full model has not run on a GPU. Most connected routines have not yet passed WW3's own test suite; that check is planned for a later validation phase (decision record).
Throughout the repository, (v) marks a claim that was checked against a source and ⚠ marks
one that was not.
| What | Read |
|---|---|
| Preprint, Wave models on GPUs (not peer reviewed), by Matheus Hoffmann, Pedro Veras Guimarães, PhD (UFSC) and Pedro Cruz, D.Sc. (UFRJ). It compares this C++ port with a Rust rewrite of WW3 held to the same rule | aiXiv:2611.01104, PDF, PDF in Portuguese, source |
| Undergraduate project proposal, Electrical Engineering Department (DEL), Federal University of Rio de Janeiro (UFRJ), co-advised at LabECO/UFSC | PDF in Portuguese, PDF in English, source |
| Progress record for NOAA's wave modellers: the CPU results, their limits, and what is not shown yet | Markdown, PDF |
| Short report in plain Portuguese for the Teleinformatics and Automation Group (GTA) of DEL/UFRJ | |
| Software archive, every release with its own DOI (digital object identifier) | Zenodo, release notes |
| Website, with the progress of the port | wave.piabrota.art |
You need Nix (a package manager that installs the exact compiler versions) and just (a command runner). Docker works too; see the detailed guide.
git clone --recurse-submodules https://github.com/h0ffmann/ww3-gpu.git && cd ww3-gpu
just submodule-init # fetch the pinned toolchain (once per clone)
just smoke # run a small WW3 case with the Fortran, then with the C++ code, and compare (seconds)
just port-score # how much of WW3 runs on the C++ codejust alone lists every task.
| If you want to | Read |
|---|---|
| look up a term or abbreviation | docs/GLOSSARY.md |
| see how the repository runs WW3, the run modes, test cases, Docker images and health checks | docs/REPO_GUIDE_202611.md, the detailed guide |
| see the state of each routine | kokkos/PORT_STATUS.md |
| see the system in figures | docs/WW3_GPU_VS_NOAA_202610.md |
| know what blocks operational use | docs/PRODUCTION_READINESS_202610.md |
| read the decisions and the research log | docs/ADRs.md, docs/log/ |
| contribute, or work here with a coding agent | CONTRIBUTING.md, AGENTS.md |
- marola (marola.dev) is an open, non-profit platform for sea conditions and bathing-water quality at Brazilian beaches, by the same author. Running a detailed wave model for its own bays is its planned next step, and this repository is the groundwork.
- chaceon is WW3 rewritten in Rust, held to the same bit-for-bit rule.
- The only other published GPU port of WW3 is Ikuyajolu et al. (2023), about 1.3 times faster than 42 CPU cores; it was not merged into WW3.
- More, with every link of the Zenodo record:
RELATED_WORK.md.
Cite the concept DOI 10.5281/zenodo.23221351; it always
points to the latest release. GitHub's Cite this repository button exports APA and BibTeX from
CITATION.cff. The ABNT form is in the
detailed guide.
@software{hoffmann_ww3gpu,
author = {Hoffmann, Matheus},
title = {{WW3 GPU Lab: agentic coding and agentic research on a bit-for-bit GPU port of WAVEWATCH III}},
year = {2026},
publisher = {Zenodo},
doi = {10.5281/zenodo.23221351},
url = {https://github.com/h0ffmann/ww3-gpu}
}Cite WW3 itself separately, as the WAVEWATCH III Development Group's user manual for the version you ran.
This repository is MIT (LICENSE). The C++ files translated from WW3's Fortran are
derived works of WW3 and are LGPL-3.0-or-later, as each file's header says. No WW3 source is
copied here; scripts download it. The full split is in NOTICE and
LICENSES/.
WAVEWATCH III® is a registered trademark of NOAA's National Weather Service, used here only to name that software. This is an independent project, not affiliated with, sponsored by or endorsed by NOAA.