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 two dispersive shallow water models:

• the BBM-BBM equations with varying bottom topography,
• the dispersive shallow water model proposed by Magnus Svärd and Henrik Kalisch.

The semidiscretizations are based on summation by parts (SBP) operators, which are implemented in SummationByPartsOperators.jl. In order 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.8 and newer. DispersiveShallowWater.jl is a registered Julia package. Therefore, you can install it by executing the following commands from the Julia REPL

julia> using Pkg

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

In addition, this installs the packages OrdinaryDiffEq.jl used for time-integration and Plots.jl to visualize the results. 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> Pkg.add("SummationByPartsOperators")

Usage

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

julia> using DispersiveShallowWater

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

julia> include(default_example());

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

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

@misc{lampert2023dispersive,
  title={{D}ispersive{S}hallow{W}ater.jl: {S}tructure-preserving numerical
         methods for dispersive shallow water models},
  author={Lampert, Joshua},
  year={2023},
  month={10},
  howpublished={\url{https://github.com/JoshuaLampert/DispersiveShallowWater.jl}},
  doi={10.5281/zenodo.10034636}
}

Authors

The package is developed and maintained by Joshua Lampert (University of Hamburg). 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.