umwm

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:

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

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. Override FCFLAGS when using a 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.

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 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:

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:

This site is open source. Improve this page.