DispersiveShallowWater.jl

DispersiveShallowWater.jl is a Julia package that implements structure-preserving numerical methods for dispersive shallow water models. To date, it provides provably conservative, entropy-conserving and well-balanced numerical schemes for some dispersive shallow water models:

• the Korteweg–De Vries (KdV) equation as the prototypical example of an integrable PDE,
• the Benjamin-Bona-Mahony (BBM) equation, also known as regularized long-wave equation,
• the BBM-BBM equations with varying bottom topography,
• the dispersive shallow water model proposed by Magnus Svärd and Henrik Kalisch,
• the Serre-Green-Naghdi equations in standard and hyperbolic form.

The semidiscretizations are based on summation-by-parts (SBP) operators, which are implemented in SummationByPartsOperators.jl. To obtain fully discrete schemes, the time integration methods from OrdinaryDiffEq.jl are used to solve the resulting ordinary differential equations. Fully discrete entropy-conservative methods can be obtained by using the relaxation method provided by DispersiveShallowWater.jl. A more detailed documentation can be found online.

Installation

If you have not yet installed Julia, then you first need to download Julia. Please follow the instructions for your operating system. DispersiveShallowWater.jl works with Julia v1.10 and newer. DispersiveShallowWater.jl is a registered Julia package. Therefore, you can install it by executing the following commands from the Julia REPL

```julia julia> using Pkg

julia> Pkg.add(["DispersiveShallowWater", "OrdinaryDiffEqTsit5", "Plots"]) ```

In addition, this installs the packages OrdinaryDiffEqTsit5.jl from OrdinaryDiffEq.jl used for time-integration and Plots.jl to visualize the results. If you want to use other time integration methods than Tsit5, you can install the respective subpackage or OrdinaryDiffEq.jl, which will install every available solver. If you want to use other SBP operators than the default operators that DispersiveShallowWater.jl uses, then you also need SummationByPartsOperators.jl, which can be installed running

julia julia> Pkg.add("SummationByPartsOperators")

Usage

In the Julia REPL, first load the package DispersiveShallowWater.jl

julia julia> using DispersiveShallowWater

You can run a basic simulation that solves the BBM-BBM equations by executing

julia julia> include(default_example());

The result can be visualized by using the package Plots.jl

julia julia> using Plots julia> plot(semi => sol)

The command plot expects a Pair consisting of a Semidiscretization and an ODESolution. The visualization can also be customized, see the documentation for more details. Other examples can be found in the subdirectory examples/. A list of all examples is returned by running get_examples(). You can pass the filename of one of the examples or your own simulation file to include in order to run it, e.g., include(joinpath(examples_dir(), "svaerd_kalisch_1d", "svaerd_kalisch_1d_dingemans_relaxation.jl")).

Referencing

You can directly refer to DispersiveShallowWater.jl as

bibtex @misc{lampert2025dispersive, title={{D}ispersive{S}hallow{W}ater.jl: {S}tructure-preserving numerical methods for dispersive shallow water models}, author={Lampert, Joshua and Wittenstein, Collin and Ranocha, Hendrik}, year={2025}, howpublished={\url{https://github.com/NumericalMathematics/DispersiveShallowWater.jl}}, doi={10.5281/zenodo.10034636} }

Authors

The package is mainly developed and maintained by Joshua Lampert (University of Hamburg) with contributions from Hendrik Ranocha (Johannes Gutenberg University Mainz) and Collin Wittenstein (Johannes Gutenberg University Mainz). Some parts of this repository are based on parts of Dispersive-wave-schemes-notebooks. A Broad Class of Conservative Numerical Methods for Dispersive Wave Equations by Hendrik Ranocha, Dimitrios Mitsotakis and David Ketcheson. The code structure is inspired by Trixi.jl.

License and contributing

DispersiveShallowWater.jl is published under the MIT license (see License). We are pleased to accept contributions from everyone, preferably in the form of a PR.