University of Miami Wave Model (UMWM)

A tiny, fast, parallel spectral ocean wave model.

This is the reference implementation of UMWM, described by Donelan et al. (2012), with later improvements and bug fixes. UMWM solves the wave energy balance equation on a curvilinear grid. It has been used to simulate:

• Global swell and windsea
• Waves in coastal and hurricane conditions
• Wave-induced material transport (Stokes drift)
• Ancient Martian seas and methane lakes on Titan
• Waves in laboratory settings such as wave tanks

UMWM was initially designed with a primary goal of accurate and conservative momentum coupling with atmosphere and ocean circulation models. That design goal remains a priority. Further, UMWM takes a highly simplified approach to nonlinear downshifting of wave energy; this allows it to run signinficantly faster than other spectral wave models.

Getting started

Get the code

git clone https://github.com/umwm/umwm

System dependencies

• make
• A recent Fortran compiler (known to work with GNU, Intel, Cray, and IBM)
• NetCDF for I/O
• MPI for parallel processing (optional)

Building UMWM

Type make to build the serial model and auxiliary tools:

make

The default serial compiler is gfortran. Select another compiler by setting FC:

make FC=ifx
make FC=flang

The default FCFLAGS are aggressive GNU-style optimization flags: -Ofast -march=native -ffast-math -funroll-loops -Wall, or -O3 -fast when FC is nvfortran or an MPI wrapper of it. Override FCFLAGS when using another compiler that needs different optimization options:

make FC=ifx FCFLAGS="-O3 -xHost -ipo -fp-model fast=2"

Build with MPI by setting MPI=yes. This defines -DMPI and defaults to the mpif90 wrapper unless FC is set explicitly:

make MPI=yes
make MPI=yes FC=mpiifx

NetCDF Fortran flags are discovered with nf-config by default. If you have multiple NetCDF installs, point to the matching nf-config for your compiler:

make NF_CONFIG=/path/to/nf-config

As a fallback, set NETCDF to an install prefix with include and lib subdirectories, or provide the flags manually:

make NETCDF=/path/to/netcdf
make NETCDF_FFLAGS="-I/path/include" NETCDF_FLIBS="-L/path/lib -lnetcdff -lnetcdf"

Use make print-config to see the resolved compiler and NetCDF settings. make shared builds the shared library src/shared/libumwm.so with the C API used by the Python package. Executable umwm will be built in the top-level directory and auxiliary tool executables will be built in tools/. PDF documentation can be built separately with make docs.

Building for NVIDIA GPUs

Build for NVIDIA GPUs by setting GPU=yes. This needs the NVIDIA HPC SDK, for nvfortran with OpenACC and its CUDA-aware HPC-X Open MPI, and a netCDF-Fortran built with nvfortran:

module load nvhpc-hpcx-cuda13
unset FC
make GPU=yes MPI=yes NF_CONFIG=/path/to/nvfortran/netcdf-fortran/bin/nf-config

Load the HPC-X module of the SDK rather than nvhpc, so that MPI uses the UCX of the SDK, which transfers GPU memory, and unset the FC that the module exports, which would take precedence over mpif90. GPU=yes selects nvfortran (or mpif90 with MPI=yes) with the default FCFLAGS -O3 -fast, and adds the OpenACC flags -acc=gpu -gpu=$(GPU_ARCH),mem:unified also when FCFLAGS is set. GPU_ARCH is the compute capability of the GPU, cc120 (Blackwell RTX PRO) by default. The kernels of the time step, in src/umwm_domain_acc.f90, are compiled with ACC_KERNEL_FLAGS, which inline the functions of the spectral bins and limit the registers of a thread.

In the GPU build, the source time step, the forcing interpolation, the diagnostics, the ocean stress, the Stokes drift, and most of the initialization run on the GPU, and the input and output on the CPU. The fields are in unified memory, which the CPU and the GPU share, as the code has no OpenACC data directives; this needs a system where the GPU can address the memory of the CPU, as with heterogeneous memory management (HMM), for which nvidia-smi -q shows the addressing mode HMM. It supports at most 128 frequencies and 128 directions. Its results differ from those of the CPU build at the level of single-precision rounding, because the GPU raises to the dissipation power in single precision, where the CPU uses double precision, and sums over the spectrum in another order. Run it on one GPU as in serial, selecting the GPU with CUDA_VISIBLE_DEVICES:

CUDA_VISIBLE_DEVICES=0 ./umwm

The GPU build is fast for large grids, of the order of 100,000 sea cells and more; small grids, such as most example cases, use a small part of the GPU.

With MPI, the GPU build runs on several GPUs, with the same results as on one. The processes of a node share its visible GPUs, one process per GPU, or blocks of consecutive ranks if there are more processes than GPUs, and the halo is exchanged while the cells inside the tiles are integrated. Map the processes to the NUMA domains in rank order, so that each runs next to its GPU on nodes where the GPUs are numbered by NUMA domain; for example, on a node with four GPUs, two on each of two NUMA domains:

mpirun -np 4 --map-by ppr:2:numa --bind-to numa ./umwm

The MPI library should be CUDA-aware, as the HPC-X of the SDK, which copies the halo from and to the GPU; through other libraries, the halo pages migrate to the CPU and back at each time step. On two GPUs, a time step of a grid of 360,000 sea cells or more takes half the time of one GPU.

Running tests

Run the test suite from the top-level directory:

make test

The tests generate their forcing with Python (requirements.txt); set PYTHON to use a particular interpreter, for example make test PYTHON="uv run python" with the environment of the Python package.

Building with fpm

Fortran Package Manager (fpm) 0.13 or newer can build the MPI-enabled model and run its test suite. The active compiler must have matching MPI and netCDF Fortran installations discoverable through their compiler wrappers and pkg-config files.

With GNU Fortran, OpenMPI, and a system netCDF installation:

fpm build --compiler gfortran
fpm test --compiler gfortran --runner ./tests/fpm-mpi-test-runner.sh

With Intel Fortran, Intel MPI, and a netCDF-Fortran installation built with ifx, first initialize oneAPI and expose that netCDF installation:

source ~/intel/oneapi/setvars.sh
export PKG_CONFIG_PATH=/path/to/intel-netcdf/lib/pkgconfig:$PKG_CONFIG_PATH
export LD_LIBRARY_PATH=/path/to/intel-netcdf/lib:$LD_LIBRARY_PATH
fpm build --compiler ifx --build-dir build-ifx
fpm test --compiler ifx --build-dir build-ifx \
  --runner ./tests/fpm-mpi-test-runner.sh

The MPI test runner launches one process by default; set FPM_TEST_PROCESSES to override that count. It prepares the generated Rankine-vortex forcing fixture and runs tests from the tests directory, preserving the paths used by the Make suite.

Running UMWM

Running in serial mode:

./umwm

Running in parallel, for example on 16 cores:

mpiexec -n 16 ./umwm

The model runs in the current directory, reading namelists/main.nml (or the namelist given as the argument, ./umwm path/to/main.nml) and writing its output to output/. ./umwm --help lists the options.

You can read the full technical reference doc here.

Example cases

The examples directory holds a gallery of idealized cases with constant wind: fetch-limited and duration-limited growth, the fetches of JONSWAP, a laboratory wave tank, lakes on Titan and Mars with their planetary parameters, and waves over a seamount and through a field of ocean eddies, whose bathymetry and currents come with the cases. Select one with --case:

./umwm --list-cases
./umwm --case jonswap
./umwm --case titan-ontario-lacus

or with the Python command-line tool, which runs a case in a run directory named after it:

umwm cases
umwm run --case mars-jezero-lake

Python interface

The umwm Python package configures and runs the model from Python, with the model state and the output available as NumPy arrays and xarray datasets, and provides the umwm command-line tool. The time integration runs in the compiled Fortran library, so there is no performance cost. Install it from the repository (it builds the library with the same Makefile configuration, for example UMWM_MPI=yes pip install . for MPI or UMWM_GPU=yes pip install . for NVIDIA GPUs), or set up an environment with uv:

pip install .
uv sync && uv run umwm info

import umwm

config = umwm.Config()                        # the defaults of namelists/main.nml
config.domain.stoptimestr = "2026-01-01 12:00:00"
config.forcing_constant.wspd0 = 15.0

with umwm.Domain(config, workdir="runs/case1") as domain:
    domain.run()
    swh = domain.grid_field("swh")            # NumPy array (ny, nx)
    output = domain.output()                  # xarray.Dataset of the output files

umwm init runs/case1 -s domain.stoptimestr="2026-01-01 12:00:00"
umwm run runs/case1
umwm output runs/case1 --stats
umwm run --case jonswap          # an example case, in ./jonswap

See python/README.md for the documentation of the package and the command-line tool.

Papers

Papers about or using UMWM:

• Detelich, C. E., U. G. Schneck, A. G. Hayes, M. Curcic, R. V. Palermo, A. D. Ashton, J. T. Perron, J. M. Lora, and J. Steckloff, 2026: Modeling the seasonality of wind-driven hydrocarbon waves in Titan's polar lakes, J. Geophys. Res. Planets, 131(5), e2026JE009693, doi:10.1029/2026JE009693. Link

• Schneck, U. G., C. E. Detelich, M. Curcic, A. D. Ashton, A. G. Hayes, and J. T. Perron, 2026: Modeling wind-driven waves on other planets: Applications to Mars, Titan, and exoplanets, J. Geophys. Res. Planets, 131(4), e2025JE009490, doi:10.1029/2025JE009490. Link

• Barr, B. W. and S. S. Chen, 2025: Impacts of seastate-dependent sea spray heat fluxes on tropical cyclone structure and intensity in fully coupled atmosphere-wave-ocean model simulations, J. Adv. Model. Earth Syst., 17(7), e2024MS004550, doi:10.1029/2024MS004550. Link

• Barr, B. W., S. S. Chen, and C. W. Fairall, 2023: Sea-state-dependent sea spray and air-sea heat fluxes in tropical cyclones: A new parameterization for fully coupled atmosphere-wave-ocean models, J. Atmos. Sci., 80(4), 933-960, doi:10.1175/JAS-D-22-0126.1. Link

• Haza A. C., N. Paldor, T. M. Özgökmen, M. Curcic, S. S. Chen, and G. Jacobs, 2019: Wind-based estimations of ocean surface currents from massive clusters of drifters in the Gulf of Mexico, J. Geophys. Res. Oceans, 124, doi:10.1029/2018JC014813. PDF.

• Li, G., M. Curcic, M. Iskandarani, S. S. Chen, and O. M. Knio, 2019: Uncertainty propagation in coupled atmosphere-wave-ocean system: A study of Hurricane Earl (2010), Mon. Wea. Rev., 147, 221-245, doi:10.1175/MWR-D-17-0371.1. PDF

Thanks

UMWM development is currently supported by the NSF Award 2543464.

Previously, UMWM was supported by the NSF Award 1745384, the Gulf of Mexico Research Initiative, and the National Oceanographic Partnership Program.

Many thanks as well to the open source contributors:

• Tim Campbell (Naval Research Laboratory)
• Milan Curcic (University of Miami)
• Anton Darmenov (NASA Goddard Space Flight Center)
• Mark Donelan (University of Miami)
• Michael Hirsch (Scivision Inc.)
• Edoardo Mazza (University of Washington)
• Aishwarya Raman (NASA Goddard Space Flight Center)
• Dalton Kei Sasaki (University of Sao Paolo)
• Martin Schmidt (Leibniz Institute for Baltic Sea Research)
• Ashwanth Srinivasan (Tendral LLC)