XBeach learning tutorial
These notebooks show how to set up and run XBeach with rompy-xbeach, which extends rompy with everything specific to XBeach.
The collection has two parts:
- Tutorial: an ordered path from zero to a complete, running model. Start here if you are new to rompy or rompy-xbeach.
- Examples: self-contained notebooks on specific features. Pick the one you need and adapt it to your data.
Getting started
You need Python with rompy, rompy-xbeach, Jupyter, cartopy and wavespectra. See the installation guide.
The example data is in notebooks/xbeach/data/, so the notebooks run from a clone of this repository without further setup. Each notebook writes its files to a local _output/ folder, which is safe to delete.
To run XBeach, the notebooks use the public Docker image ghcr.io/rom-py/xbeach, so you only need Docker installed and running. Cells that run XBeach are skipped if Docker is not available, and everything else still works. If you have your own XBeach installation, see Running XBeach.
Note
The pages on this site show the outputs stored in the notebooks, including the results of the XBeach runs. The documentation build does not run the notebooks or XBeach.
Tutorial
Work through these in order:
| # | Notebook | You will learn |
|---|---|---|
| 1 | Your first XBeach model | The whole workflow: grid, bathymetry, waves, physics, generate and run |
| 2 | Defining the model grid | Placing and orienting an XBeach grid correctly |
| 3 | Bathymetry from your data | Reading, interpolating and extending bathymetry |
| 4 | Adding forcing | Wave, wind and water level forcing from datasets |
| 5 | Choosing model settings | Physics, boundaries, sediment and output components |
| 6 | A complete storm-impact setup | A realistic model built from real forcing data |
| 7 | Configuration as YAML and the rompy CLI | The same model as a YAML file, run from the command line |
Examples
Grid and bathymetry
| Notebook | Shows |
|---|---|
| Grid plotting and export | Coastlines, projections, overlays, and saving grids to KML or GeoJSON |
| Data sources | Every source type: GeoTIFF, NetCDF, XYZ, intake, spectra, tidal constituents, CSV |
| Bathymetry options | Depth convention, interpolation, and seaward and lateral extension |
Wave boundaries
| Notebook | Shows |
|---|---|
| Constant and bichromatic waves | Constant waves, bichromatic wave groups, no waves |
| Wave boundaries from spectra | JONSWAP, JONSWAP table and SWAN boundaries from 2D spectra, and common settings |
| Wave boundaries from parameters | JONSWAP boundaries from Hs, Tp and direction at stations, on grids or from a CSV |
| Existing files and reuse | Boundary files made elsewhere, and reusing boundaries from a previous run |
Wind and water levels
| Notebook | Shows |
|---|---|
| Wind forcing | Gridded, station and point winds, and switching wind on |
| Water level forcing | Tide from constituents, water level data, and surge plus tide |
Model components
| Notebook | Shows |
|---|---|
| Physics | Wave models, breakers, friction, viscosity, roller, vegetation, numerics |
| Sediment and morphology | Transport, morfac, avalanching, bed composition, hard layers, groundwater |
| Flow and tide boundaries | Boundary types on each side of the grid, and water level boundaries |
| Output | Map, point and run-up output, timing and hotstart files |
Workflows
| Notebook | Shows |
|---|---|
| Data selection options | The rompy options shared by all forcing classes: coords, variables, filters, time cropping |
| Hotstart and chained runs | Continuing a simulation from a saved model state |
| Running XBeach | Local and Docker backends, MPI, and rompy run |
| Parameter sweep | Generating and comparing a set of model variants |