DispersiveShallowWater.jl API
DispersiveShallowWater.DispersiveShallowWater
— ModuleDispersiveShallowWater
DispersiveShallowWater.jl is a Julia package that implements structure-preserving numerical methods for dispersive shallow water models. It provides provably conservative, entropy-conserving, and well-balanced numerical schemes for some dispersive shallow water models.
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.
See also: DispersiveShallowWater.jl
Equations
DispersiveShallowWater.BBMEquation1D
— TypeBBMEquation1D(; gravity_constant, D = 1.0, eta0 = 0.0, split_form = true)
BBM (Benjamin–Bona–Mahony) equation in one spatial dimension. The equation is given by
\[\begin{aligned} \eta_t + \sqrt{gD}\eta_x + \frac{3}{2}\sqrt{\frac{g}{D}}\eta\eta_x - \frac{1}{6}D^2\eta_{xxt} &= 0. \end{aligned}\]
The unknown quantity of the BBM equation is the total water height $\eta$. The gravitational constant is denoted by g
and the constant bottom topography (bathymetry) $b = \eta_0 - D$, where $\eta_0$ is the constant still-water surface and $D$ the still-water depth. The water height above the bathymetry is therefore given by $h = \eta - \eta_0 + D$. The BBM equation is only implemented for $\eta_0 = 0$.
The equations only support a flat bathymetry.
The BBM equation is first described in Benjamin, Bona, and Mahony (1972). The semidiscretization implemented here is developed in Ranocha, Mitsotakis, and Ketcheson (2020) for split_form = true
and in Linders, Ranocha, and Birken (2023) for split_form = false
. If split_form
is true
, a split form in the semidiscretization is used, which conserves
- the total water mass (integral of $h$) as a linear invariant
- a quadratic invariant (integral of $1/2\eta(\eta - 1/6D^2\eta_{xx})$ or for periodic boundary conditions equivalently $1/2(\eta^2 + 1/6D^2\eta_x^2)$), which is called here
energy_total_modified
(andentropy_modified
) because it contains derivatives of the solution
for periodic boundary conditions. If split_form
is false
the semidiscretization conserves
- the total water mass (integral of $h$) as a linear invariant
- the Hamiltonian (integral of $1/4\sqrt{g/D}\eta^3 + 1/2\sqrt{gD}\eta^2$) (see
hamiltonian
)
for periodic boundary conditions.
- Thomas B. Benjamin, Jerry L. Bona and John J. Mahony (1972) Model equations for long waves in nonlinear dispersive systems DOI: 10.1098/rsta.1972.0032
- Hendrik Ranocha, Dimitrios Mitsotakis and David I. Ketcheson (2020) A Broad Class of Conservative Numerical Methods for Dispersive Wave Equations DOI: 10.4208/cicp.OA-2020-0119
- Viktor Linders, Hendrik Ranocha and Philipp Birken (2023) Resolving entropy growth from iterative methods DOI: 10.1007/s10543-023-00992-w
DispersiveShallowWater.energy_total_modified!
— Methodenergy_total_modified!(e, q_global, equations::BBMEquation1D, cache)
Return the modified total energy e
of the primitive variables q_global
for the BBMEquation1D
. The energy_total_modified
is a conserved quantity (for periodic boundary conditions).
It is given by
\[\frac{1}{2} \eta(\eta - \frac{1}{6}D^2\eta_{xx}).\]
q_global
is a vector of the primitive variables at ALL nodes. cache
needs to hold the SBP operators used by the solver
.
See also energy_total_modified
.
DispersiveShallowWater.hamiltonian!
— Methodhamiltonian!(H, q_global, equations::BBMEquation1D, cache)
Return the Hamiltonian H
of the primitive variables q_global
for the BBMEquation1D
. The Hamiltonian is given by
\[\frac{1}{4}\sqrt{\frac{g}{D}}\eta^3 + \frac{1}{2}\sqrt{gD}\eta^2.\]
q_global
is a vector of the primitive variables at ALL nodes.
See also hamiltonian
.
DispersiveShallowWater.initial_condition_convergence_test
— Methodinitial_condition_convergence_test(x, t, equations::BBMEquation1D, mesh)
A travelling-wave solution used for convergence tests in a periodic domain, here generalized for dimensional variables.
See section 4.1.3 in (there is an error in paper: it should be sech^2
instead of cosh
):
- Hendrik Ranocha, Dimitrios Mitsotakis and David I. Ketcheson (2020) A Broad Class of Conservative Numerical Methods for Dispersive Wave Equations DOI: 10.4208/cicp.OA-2020-0119
DispersiveShallowWater.initial_condition_manufactured
— Methodinitial_condition_manufactured(x, t, equations::BBMEquation1D, mesh)
A smooth manufactured solution in combination with source_terms_manufactured
.
DispersiveShallowWater.source_terms_manufactured
— Methodsource_terms_manufactured(q, x, t, equations::BBMEquation1D, mesh)
A smooth manufactured solution in combination with initial_condition_manufactured
.
DispersiveShallowWater.BBMBBMEquations1D
— TypeBBMBBMEquations1D(; bathymetry_type = bathymetry_variable,
gravity_constant, eta0 = 0.0)
BBM-BBM (Benjamin–Bona–Mahony) system in one spatial dimension. The equations for flat bathymetry are given by
\[\begin{aligned} \eta_t + ((\eta + D)v)_x - \frac{1}{6}D^2\eta_{xxt} &= 0,\\ v_t + g\eta_x + \left(\frac{1}{2}v^2\right)_x - \frac{1}{6}D^2v_{xxt} &= 0. \end{aligned}\]
The unknown quantities of the BBM-BBM equations are the total water height $\eta$ and the velocity $v$. The gravitational constant is denoted by g
and the constant bottom topography (bathymetry) $b = \eta_0 - D$. The water height above the bathymetry is therefore given by $h = \eta - \eta_0 + D$. The BBM-BBM equations are only implemented for $\eta_0 = 0$.
Two types of bathymetry_type
are supported:
bathymetry_flat
: flat bathymetry (typically $b = 0$ everywhere)bathymetry_variable
: general variable bathymetry
For the general case of variable vathymetry the BBM-BBM equations are
\[\begin{aligned} \eta_t + ((\eta + D)v)_x - \frac{1}{6}(D^2\eta_{xt})_x &= 0,\\ v_t + g\eta_x + \left(\frac{1}{2}v^2\right)_x - \frac{1}{6}(D^2v_t)_{xx} &= 0. \end{aligned}\]
One reference for the BBM-BBM system can be found in Bona et al. (1998). The semidiscretization implemented here was developed for flat bathymetry in Ranocha et al. (2020) and generalized for a variable bathymetry in Lampert and Ranocha (2024). It conserves
- the total water mass (integral of $h$) as a linear invariant
- the total velocity (integral of $v$) as a linear invariant for flat bathymetry
- the total energy
for periodic boundary conditions (see Lampert, Ranocha). For reflecting boundary conditions, the semidiscretization conserves
- the total water (integral of $h$) as a linear invariant
- the total energy.
Additionally, it is well-balanced for the lake-at-rest stationary solution, see Lampert and Ranocha (2024).
- Jerry L. Bona, Min Chen (1998) A Boussinesq system for two-way propagation of nonlinear dispersive waves DOI: 10.1016/S0167-2789(97)00249-2
- Hendrik Ranocha, Dimitrios Mitsotakis, David I. Ketcheson (2020) A Broad Class of Conservative Numerical Methods for Dispersive Wave Equations DOI: 10.4208/cicp.OA-2020-0119
- Joshua Lampert, Hendrik Ranocha (2024) Structure-Preserving Numerical Methods for Two Nonlinear Systems of Dispersive Wave Equations DOI: 10.48550/arXiv.2402.16669
DispersiveShallowWater.initial_condition_convergence_test
— Methodinitial_condition_convergence_test(x, t, equations::BBMBBMEquations1D, mesh)
A travelling-wave solution used for convergence tests in a periodic domain. The bathymetry is constant.
For details see Example 5 in Section 3 from (here adapted for dimensional equations):
- Min Chen (1997) Exact Traveling-Wave Solutions to Bidirectional Wave Equations DOI: 10.1023/A:1026667903256
DispersiveShallowWater.initial_condition_dingemans
— Methodinitial_condition_dingemans(x, t, equations::BBMBBMEquations1D, mesh)
The initial condition that uses the dispersion relation of the Euler equations to approximate waves generated by a wave maker as it is done by experiments of Dingemans. The topography is a trapezoidal.
The initial condition for the water height is translated to be around 0, which is needed for the simulation because the BBMBBMEquations1D
are only implemented for $\eta_0 = 0$.
References:
- Magnus Svärd, Henrik Kalisch (2023) A novel energy-bounded Boussinesq model and a well-balanced and stable numerical discretization arXiv: 2302.09924
- Maarten W. Dingemans (1994) Comparison of computations with Boussinesq-like models and laboratory measurements link
DispersiveShallowWater.initial_condition_manufactured
— Methodinitial_condition_manufactured(x, t, equations::BBMBBMEquations1D, mesh)
A smooth manufactured solution in combination with source_terms_manufactured
.
DispersiveShallowWater.initial_condition_manufactured_reflecting
— Methodinitial_condition_manufactured_reflecting(x, t, equations::BBMBBMEquations1D, mesh)
A smooth manufactured solution for reflecting boundary conditions in combination with source_terms_manufactured_reflecting
.
DispersiveShallowWater.source_terms_manufactured
— Methodsource_terms_manufactured(q, x, t, equations::BBMBBMEquations1D, mesh)
A smooth manufactured solution in combination with initial_condition_manufactured
.
DispersiveShallowWater.source_terms_manufactured_reflecting
— Methodsource_terms_manufactured_reflecting(q, x, t, equations::BBMBBMEquations1D, mesh)
A smooth manufactured solution for reflecting boundary conditions in combination with initial_condition_manufactured_reflecting
.
DispersiveShallowWater.bathymetry_flat
— Constantbathymetry_flat = DispersiveShallowWater.BathymetryFlat()
A singleton struct indicating a flat bathymetry.
See also bathymetry_mild_slope
and bathymetry_variable
.
DispersiveShallowWater.bathymetry_mild_slope
— Constantbathymetry_mild_slope = DispersiveShallowWater.BathymetryMildSlope()
A singleton struct indicating a variable bathymetry with mild-slope approximation. Typically, this means that some terms like $b_x^2$ are neglected.
See also bathymetry_flat
and bathymetry_variable
.
DispersiveShallowWater.bathymetry_variable
— Constantbathymetry_variable = DispersiveShallowWater.BathymetryVariable()
A singleton struct indicating a variable bathymetry (without mild-slope approximation).
See also bathymetry_flat
and bathymetry_mild_slope
.
DispersiveShallowWater.AbstractEquations
— TypeAbstractEquations{NDIMS, NVARS}
An abstract supertype of specific equations such as the BBM-BBM equations. The type parameters encode the number of spatial dimensions (NDIMS
) and the number of primary variables (NVARS
) of the physics model.
See also AbstractShallowWaterEquations
.
DispersiveShallowWater.AbstractShallowWaterEquations
— TypeAbstractShallowWaterEquations{NDIMS, NVARS}
An abstract supertype of all equation system that contain the classical shallow water equations as a subsystem, e.g., the BBMBBMEquations1D
, the SvaerdKalischEquations1D
, and the SerreGreenNaghdiEquations1D
. In 1D, the shallow water equations with flat bathymetry are given by
\[\begin{aligned} h_t + (h v)_x &= 0,\\ h v_t + \frac{1}{2} g (h^2)_x + \frac{1}{2} h (v^2)_x &= 0, \end{aligned}\]
where $h$ is the waterheight
, $v$ the velocity
, and $g$ the gravity_constant
.
DispersiveShallowWater.bathymetry
— Methodbathymetry(q, equations)
Return the bathymetry of the primitive variables q
for a given set of equations
.
q
is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations)
.
DispersiveShallowWater.cons2prim
— Methodcons2prim(u, equations)
Convert the conserved variables u
to the primitive variables for a given set of equations
. u
is a vector type of the correct length nvariables(equations)
. Notice the function doesn't include any error checks for the purpose of efficiency, so please make sure your input is correct. The inverse conversion is performed by prim2cons
.
DispersiveShallowWater.default_analysis_errors
— Methoddefault_analysis_errors(equations)
Default analysis errors used by the AnalysisCallback
.
DispersiveShallowWater.default_analysis_integrals
— Methoddefault_analysis_integrals(equations)
Default analysis integrals used by the AnalysisCallback
.
DispersiveShallowWater.discharge
— Methoddischarge(q, equations)
See momentum
.
DispersiveShallowWater.eachvariable
— Methodeachvariable(equations::AbstractEquations)
Return an iterator over the indices that specify the location in relevant data structures for the variables in equations
. In particular, not the variables themselves are returned.
DispersiveShallowWater.energy_total
— Methodenergy_total(q, equations)
Return the total energy of the primitive variables q
for a given set of equations
. For all AbstractShallowWaterEquations
, the total energy is given by the sum of the kinetic and potential energy of the shallow water subsystem, i.e.,
\[\frac{1}{2} h v^2 + \frac{1}{2} g \eta^2\]
in 1D, where $h$ is the waterheight
, $\eta = h + b$ the waterheight_total
, $v$ the velocity
, and $g$ the gravity_constant
.
q
is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations)
.
DispersiveShallowWater.energy_total_modified!
— Methodenergy_total_modified!(e, q_global, equations, cache)
In-place version of energy_total_modified
.
DispersiveShallowWater.energy_total_modified
— Methodenergy_total_modified(q_global, equations, cache)
Return the modified total energy of the primitive variables q_global
for the equations
. This modified total energy is a conserved quantity and can contain additional terms compared to the usual energy_total
. For example, for the SvaerdKalischEquations1D
and the SerreGreenNaghdiEquations1D
, it contains additional terms depending on the derivative of the velocity $v_x$ modeling non-hydrostatic contributions. For equations which are not AbstractShallowWaterEquations
, the modified total energy does not have to be an extension of the usual energy_total
and does not have to be related to a physical energy. However, it is still a conserved quantity for appropriate boundary conditions and may contain derivatives of the solution.
q_global
is a vector of the primitive variables at ALL nodes. cache
needs to hold the SBP operators used by the solver
if non-hydrostatic terms are present.
Internally, this function allocates a vector for the output and calls DispersiveShallowWater.energy_total_modified!
.
DispersiveShallowWater.entropy
— Methodentropy(q, equations)
Return the entropy of the primitive variables q
for a given set of equations
. For all AbstractShallowWaterEquations
, the entropy
is just the energy_total
.
q
is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations)
.
DispersiveShallowWater.entropy_modified!
— Methodentropy_modified!(e, q_global, equations, cache)
In-place version of entropy_modified
.
DispersiveShallowWater.entropy_modified
— Methodentropy_modified(q_global, equations, cache)
Alias for energy_total_modified
.
DispersiveShallowWater.get_name
— Methodget_name(equations::AbstractEquations)
Return the canonical, human-readable name for the given system of equations.
Examples
julia> DispersiveShallowWater.get_name(BBMBBMEquations1D(gravity_constant=1.0))
"BBMBBMEquations1D-BathymetryVariable"
DispersiveShallowWater.gravity_constant
— Methodgravity_constant(equations)
Return the gravity constant $g$ for a given set of equations
.
DispersiveShallowWater.hamiltonian
— Methodhamiltonian(q_global, equations, cache)
Return the Hamiltonian of the primitive variables q_global
for the equations
. The Hamiltonian is a conserved quantity and may contain derivatives of the solution.
q_global
is a vector of the primitive variables at ALL nodes. cache
needs to hold the SBP operators used by the solver
if non-hydrostatic terms are present.
Internally, this function allocates a vector for the output and calls DispersiveShallowWater.hamiltonian!
.
This function is not necessarily implemented for all equations. See DispersiveShallowWater.hamiltonian!
for further details of equations supporting it.
DispersiveShallowWater.hyperbolic_approximation_limit
— MethodDispersiveShallowWater.hyperbolic_approximation_limit(equations)
If the equations are a hyperbolic approximation of another set of equations, return the equations of the limit system. Otherwise, return the input equations.
See also is_hyperbolic_appproximation
and prim2phys
.
This function is mostly used for some internal dispatch. For example, it allows to return a reduced set of variables from initial conditions for hyperbolic approximations.
DispersiveShallowWater.initial_condition_dingemans
— Methodinitial_condition_dingemans(x, t, equations::AbstractShallowWaterEquations, mesh)
The initial condition that uses the dispersion relation of the Euler equations to approximate waves generated by a wave maker as it is done by experiments of Dingemans. The topography is a trapezoidal. It is assumed that equations.eta0 = 0.8
.
References:
- Magnus Svärd, Henrik Kalisch (2023) A novel energy-bounded Boussinesq model and a well-balanced and stable numerical discretization arXiv: 2302.09924
- Maarten W. Dingemans (1994) Comparison of computations with Boussinesq-like models and laboratory measurements link
DispersiveShallowWater.initial_condition_discontinuous_well_balancedness
— Methodinitial_condition_discontinuous_well_balancedness(x, t, equations::AbstractShallowWaterEquations, mesh)
Setup a truly discontinuous bottom topography function for this academic lake-at-rest test case of well-balancedness, i.e. eta
is constant and v
is zero everywhere. The error for this lake-at-rest test case ∫|η-η₀|
should be around machine roundoff.
DispersiveShallowWater.is_hyperbolic_appproximation
— MethodDispersiveShallowWater.is_hyperbolic_appproximation(equations)
Returns Val{true}()
if the equations are a hyperbolic approximation of another set of equations and Val{false}()
otherwise (default). For example, the HyperbolicSerreGreenNaghdiEquations1D
are a hyperbolic approximation of the SerreGreenNaghdiEquations1D
.
See also hyperbolic_approximation_limit
and prim2phys
.
This function is mostly used for some internal dispatch. For example, it allows to return a reduced set of variables from initial conditions for hyperbolic approximations.
DispersiveShallowWater.lake_at_rest_error
— Methodlake_at_rest_error(q, equations)
Calculate the error for the "lake-at-rest" test case where the waterheight_total
$\eta = h + b$ should be a constant value over time (given by the value $\eta_0$ passed to the equations
when constructing them).
DispersiveShallowWater.momentum
— Methodmomentum(q, equations)
Return the momentum/discharge of the primitive variables q
for a given set of equations
, i.e., the waterheight
times the velocity
.
q
is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations)
.
DispersiveShallowWater.prim2cons
— Methodprim2cons(q, equations)
Convert the primitive variables q
to the conserved variables for a given set of equations
. q
is a vector type of the correct length nvariables(equations)
. Notice the function doesn't include any error checks for the purpose of efficiency, so please make sure your input is correct. The inverse conversion is performed by cons2prim
.
DispersiveShallowWater.prim2phys
— Methodprim2phys(q, equations)
Convert the primitive variables q
to the physically meaningful variables for a given set of equations
. By default, this is the same as prim2prim
for most equations. However, some equations like the HyperbolicSerreGreenNaghdiEquations1D
return a reduced set of variables since they are a hyperbolic approximation of another set of equations (in this case the SerreGreenNaghdiEquations1D
).
See also is_hyperbolic_appproximation
and hyperbolic_approximation_limit
.
q
is a vector type of the correct length nvariables(equations)
. Notice the function doesn't include any error checks for the purpose of efficiency, so please make sure your input is correct.
DispersiveShallowWater.prim2prim
— Methodprim2prim(q, equations)
Return the primitive variables q
. While this function is as trivial as identity
, it is also as useful.
DispersiveShallowWater.still_water_surface
— Methodstill_water_surface(q, equations)
Return the still water surface $\eta_0$ (lake at rest) for a given set of equations
.
DispersiveShallowWater.varnames
— Functionvarnames(conversion_function, equations)
Return the list of variable names when applying conversion_function
to the primitive variables associated to equations
. Common choices of the conversion_function
are prim2prim
, prim2cons
, and prim2phys
.
DispersiveShallowWater.velocity
— Methodvelocity(q, equations)
Return the velocity of the primitive variables q
for a given set of equations
.
q
is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations)
.
DispersiveShallowWater.waterheight
— Methodwaterheight(q, equations)
Return the waterheight of the primitive variables q
for a given set of equations
, i.e., the waterheight $h$ above the bathymetry $b$.
q
is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations)
.
See also waterheight_total
, bathymetry
.
DispersiveShallowWater.waterheight_total
— Methodwaterheight_total(q, equations)
Return the total waterheight of the primitive variables q
for a given set of equations
, i.e., the waterheight
$h$ plus the bathymetry
$b$.
q
is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations)
.
DispersiveShallowWater.HyperbolicSerreGreenNaghdiEquations1D
— TypeHyperbolicSerreGreenNaghdiEquations1D(; bathymetry_type = bathymetry_mild_slope,
gravity_constant,
eta0 = 0.0,
lambda)
Hyperbolic approximation of the Serre-Green-Naghdi system in one spatial dimension. The equations for flat bathymetry are given by
\[\begin{aligned} h_t + (h v)_x &= 0,\\ h v_t + \frac{1}{2} g (h^2)_x + \frac{1}{2} h (v^2)_x + \biggl( \frac{\lambda}{3} H (1 - H / h) \biggr)_x &= 0,\\ h w_t + h v w_x &= \lambda (1 - H / h),\\ H_t + H_x u &= w. \end{aligned}\]
The unknown quantities of the hyperbolized Serre-Green-Naghdi equations are the total water height $\eta = h + b$ and the velocity $v$. The gravitational constant is denoted by g
and the bottom topography (bathymetry) $b = \eta_0 - D$. The water height above the bathymetry is therefore given by $h = \eta - \eta_0 + D$. The total water height is therefore given by $\eta = h + b$.
There are two additional variables $w \approx -h v_x$ and $H \approx h$ compared to the SerreGreenNaghdiEquations1D
. In the original papers of Gavrilyuk et al., the variable $H$ is called $\eta$. Here, we use $\eta$ for the total water height and $H$ for auxiliary variable introduced in the hyperbolic approximation.
The HyperbolicSerreGreenNaghdiEquations1D
allow two options for specifying initial conditions:
- Returning the full set of variables
q = (η, v, D, w, H)
- Returning a reduced set of variables
q = (η, v, D)
as required for the limit systemSerreGreenNaghdiEquations1D
of the hyperbolic approximation. The remaining variablesw
andH
are initialized using the default initialization $w \approx -h v_x$ and $H \approx h$ using the derivative operator of thesolver
.
The relaxation parameter lambda
($\lambda$) introduced to obtain this hyperbolic approximation of the SerreGreenNaghdiEquations1D
influences the stiffness of the system. For $\lambda \to \infty$, the hyperbolic Serre-Green-Naghdi equations converge (at least formally) to the original SerreGreenNaghdiEquations1D
. However, the wave speeds of the hyperbolic system increase with increasing $\lambda$, so that explicit time integration methods become more expensive.
Two types of bathymetry_type
are supported:
bathymetry_flat
: flat bathymetry (typically $b = 0$ everywhere)bathymetry_mild_slope
: variable bathymetry with mild-slope approximation
For the mild-slope approximation, the Serre-Green-Naghdi equations are
\[\begin{aligned} h_t + (h v)_x &= 0,\\ h v_t + \frac{1}{2} g (h^2)_x + \frac{1}{2} h (v^2)_x + \biggl( \frac{\lambda}{3} H (1 - H / h) \biggr)_x + \biggl( g h + \frac{\lambda}{2} (1 - H / h) \biggr) b_x &= 0,\\ h w_t + h v w_x &= \lambda (1 - H / h),\\ H_t + H_x u + \frac{3}{2} b_x v &= w. \end{aligned}\]
References for the hyperbolized Serre-Green-Naghdi system can be found in
- Favrie and Gavrilyuk. A rapid numerical method for solving Serre-Green-Naghdi equations describing long free surface gravity waves DOI: 10.1088/1361-6544/aa712d
- Busto, Dumbser, Escalante, Favrie, and Gavrilyuk. On High Order ADER Discontinuous Galerkin Schemes for First Order Hyperbolic Reformulations of Nonlinear Dispersive Systems DOI: 10.1007/s10915-021-01429-8
The semidiscretization implemented here conserves
- the total water mass (integral of $h$) as a linear invariant
- the total modified energy
for periodic boundary conditions (see Ranocha and Ricchiuto (2024)). Additionally, it is well-balanced for the lake-at-rest stationary solution, see
- Hendrik Ranocha and Mario Ricchiuto (2024) Structure-preserving approximations of the Serre-Green-Naghdi equations in standard and hyperbolic form arXiv: 2408.02665
DispersiveShallowWater.energy_total_modified!
— MethodDispersiveShallowWater.energy_total_modified!(e, q_global, equations::HyperbolicSerreGreenNaghdiEquations1D, cache)
Return the modified total energy e
of the primitive variables q_global
for the HyperbolicSerreGreenNaghdiEquations1D
. It contains additional terms compared to the usual energy_total
modeling non-hydrostatic contributions. The energy_total_modified
is a conserved quantity (for periodic boundary conditions).
For a bathymetry_mild_slope
(and a bathymetry_flat
), the total modified energy is given by
\[\frac{1}{2} g \eta^2 + \frac{1}{2} h v^2 + \frac{1}{6} h w^2 + \frac{\lambda}{6} h (1 - \eta / h)^2.\]
q_global
is a vector of the primitive variables at ALL nodes.
See also energy_total_modified
.
DispersiveShallowWater.initial_condition_manufactured
— Methodinitial_condition_manufactured(x, t, equations::HyperbolicSerreGreenNaghdiEquations1D, mesh)
A smooth manufactured solution in combination with source_terms_manufactured
, see
- Hendrik Ranocha and Mario Ricchiuto (2024) Structure-preserving approximations of the Serre-Green-Naghdi equations in standard and hyperbolic form arXiv: 2408.02665
DispersiveShallowWater.initial_condition_soliton
— Methodinitial_condition_soliton(x, t, equations::HyperbolicSerreGreenNaghdiEquations1D, mesh)
A soliton solution of the SerreGreenNaghdiEquations1D
used for convergence tests in a periodic domain. This is physically the same as initial_condition_convergence_test
for the SerreGreenNaghdiEquations1D
. Please note that this is not an exact solution of the HyperbolicSerreGreenNaghdiEquations1D
(only in the limit of the relaxation parameter $\lambda \to \infty$).
See also initial_condition_convergence_test
.
DispersiveShallowWater.prim2phys
— Methodprim2phys(q, equations::HyperbolicSerreGreenNaghdiEquations1D)
Return the physical variables $\eta, v, D$ used also by the SerreGreenNaghdiEquations1D
from the main variables q
for the HyperbolicSerreGreenNaghdiEquations1D
.
DispersiveShallowWater.source_terms_manufactured
— Methodsource_terms_manufactured(q, x, t, equations::HyperbolicSerreGreenNaghdiEquations1D, mesh)
A smooth manufactured solution in combination with initial_condition_manufactured
.
DispersiveShallowWater.SerreGreenNaghdiEquations1D
— TypeSerreGreenNaghdiEquations1D(; bathymetry_type = bathymetry_variable,
gravity_constant, eta0 = 0.0)
Serre-Green-Naghdi system in one spatial dimension. The equations for flat bathymetry are given by
\[\begin{aligned} h_t + (h v)_x &= 0,\\ h v_t - \frac{1}{3} (h^3 v_{tx})_x + \frac{1}{2} g (h^2)_x + \frac{1}{2} h (v^2)_x + p_x &= 0,\\ p &= \frac{1}{3} h^3 v_{x}^2 - \frac{1}{3} h^3 v v_{xx}. \end{aligned}\]
The unknown quantities of the Serre-Green-Naghdi equations are the total water height $\eta = h + b$ and the velocity $v$. The gravitational constant is denoted by g
and the bottom topography (bathymetry) $b = \eta_0 - D$. The water height above the bathymetry is therefore given by $h = \eta - \eta_0 + D$. The total water height is therefore given by $\eta = h + b$.
Three types of bathymetry_type
are supported:
bathymetry_flat
: flat bathymetry (typically $b = 0$ everywhere)bathymetry_mild_slope
: variable bathymetry with mild-slope approximationbathymetry_variable
: general variable bathymetry
For the mild-slope approximation, the Serre-Green-Naghdi equations are
\[\begin{aligned} h_t + (h v)_x &= 0,\\ h v_t - \frac{1}{3} (h^3 v_{tx})_x + \frac{1}{2} (h^2 b_x u_t)_x - \frac{1}{2} h^2 b_x u_{tx} + \frac{3}{4} h b_x^2 u_t + \frac{1}{2} g (h^2)_x + g h b_x + \frac{1}{2} h (v^2)_x + p_x + \frac{3}{2} \frac{p}{h} b_x &= 0,\\ p &= \frac{1}{3} h^3 v_{x}^2 - \frac{1}{3} h^3 v v_{xx} + \frac{1}{2} h^2 v (b_x v)_x. \end{aligned}\]
For the general case of variable vathymetry without mild-slope approximation, the Serre-Green-Naghdi equations are
\[\begin{aligned} h_t + (h v)_x &= 0,\\ h v_t - \frac{1}{3} (h^3 v_{tx})_x + \frac{1}{2} (h^2 b_x u_t)_x - \frac{1}{2} h^2 b_x u_{tx} + h b_x^2 u_t + \frac{1}{2} g (h^2)_x + g h b_x + \frac{1}{2} h (v^2)_x + p_x + \frac{3}{2} \frac{p}{h} b_x + \psi b_x &= 0,\\ p &= \frac{1}{3} h^3 v_{x}^2 - \frac{1}{3} h^3 v v_{xx} + \frac{1}{2} h^2 v (b_x v)_x,\\ \psi &= \frac{1}{4} h v (b_x v)_x. \end{aligned}\]
References for the Serre-Green-Naghdi system can be found in
- Serre (1953) Contribution â l'étude des écoulements permanents et variables dans les canaux DOI: 10.1051/lhb/1953034
- Green and Naghdi (1976) A derivation of equations for wave propagation in water of variable depth DOI: 10.1017/S0022112076002425
The semidiscretization implemented here conserves
- the total water mass (integral of $h$) as a linear invariant
- the total momentum (integral of $h v$) as a nonlinear invariant if the bathymetry is constant
- the total modified energy
for periodic boundary conditions (see Ranocha and Ricchiuto (2024)). Additionally, it is well-balanced for the lake-at-rest stationary solution, see
- Hendrik Ranocha and Mario Ricchiuto (2024) Structure-preserving approximations of the Serre-Green-Naghdi equations in standard and hyperbolic form arXiv: 2408.02665
DispersiveShallowWater.energy_total_modified!
— MethodDispersiveShallowWater.energy_total_modified!(e, q_global, equations::SerreGreenNaghdiEquations1D, cache)
Return the modified total energy e
of the primitive variables q_global
for the SerreGreenNaghdiEquations1D
. It contains an additional term containing a derivative compared to the usual energy_total
modeling non-hydrostatic contributions. The energy_total_modified
is a conserved quantity (for periodic boundary conditions).
For a bathymetry_flat
the total modified energy is given by
\[\frac{1}{2} g \eta^2 + \frac{1}{2} h v^2 + \frac{1}{6} h^3 v_x^2.\]
For a bathymetry_mild_slope
the total modified energy is given by
\[\frac{1}{2} g \eta^2 + \frac{1}{2} h v^2 + \frac{1}{6} h (-h v_x + 1.5 v b_x)^2.\]
For a bathymetry_variable
the total modified energy has the additional term
\[+ \frac{1}{8} h (v b_x)^2.\]
q_global
is a vector of the primitive variables at ALL nodes. cache
needs to hold the SBP operators used by the solver
.
See also energy_total_modified
.
DispersiveShallowWater.initial_condition_convergence_test
— Methodinitial_condition_convergence_test(x, t, equations::SerreGreenNaghdiEquations1D, mesh)
A soliton solution used for convergence tests in a periodic domain.
DispersiveShallowWater.SvaerdKalischEquations1D
— TypeSvaerdKalischEquations1D(; bathymetry_type = bathymetry_variable,
gravity_constant, eta0 = 0.0, alpha = 0.0,
beta = 0.2308939393939394, gamma = 0.04034343434343434)
Dispersive system by Svärd and Kalisch (2023) in one spatial dimension. The equations for variable bathymetry are given in conservative variables by
\[\begin{aligned} h_t + (hv)_x &= (\hat\alpha(\hat\alpha(h + b)_x)_x)_x,\\ (hv)_t + (hv^2)_x + gh(h + b)_x &= (\hat\alpha v(\hat\alpha(h + b)_x)_x)_x + (\hat\beta v_x)_{xt} + \frac{1}{2}(\hat\gamma v_x)_{xx} + \frac{1}{2}(\hat\gamma v_{xx})_x, \end{aligned}\]
where $\hat\alpha^2 = \alpha\sqrt{gD}D^2$, $\hat\beta = \beta D^3$, $\hat\gamma = \gamma\sqrt{gD}D^3$. The coefficients $\alpha$, $\beta$ and $\gamma$ are provided in dimensionless form and $D = \eta_0 - b$ is the still-water depth and eta0
is the still-water surface (lake-at-rest). The equations can be rewritten in primitive variables as
\[\begin{aligned} \eta_t + ((\eta + D)v)_x &= (\hat\alpha(\hat\alpha\eta_x)_x)_x,\\ v_t(\eta + D) - v((\eta + D)v)_x + ((\eta + D)v^2)_x + g(\eta + D)\eta_x &= (\hat\alpha v(\hat\alpha\eta_x)_x)_x - v(\hat\alpha(\hat\alpha\eta_x)_x)_x + (\hat\beta v_x)_{xt} + \frac{1}{2}(\hat\gamma v_x)_{xx} + \frac{1}{2}(\hat\gamma v_{xx})_x. \end{aligned}\]
The unknown quantities of the Svärd-Kalisch equations are the total water height $\eta$ and the velocity $v$. The gravitational constant is denoted by g
and the bottom topography (bathymetry) $b = \eta_0 - D$. The water height above the bathymetry is therefore given by $h = \eta - \eta_0 + D$.
Currently, the equations only support a general variable bathymetry, see bathymetry_variable
.
SvärdKalischEquations1D
is an alias for SvaerdKalischEquations1D
.
The equations by Svärd and Kalisch are presented and analyzed in Svärd and Kalisch (2023). The semidiscretization implemented here conserves
- the total water mass (integral of $h$) as a linear invariant
- the total momentum (integral of $h v$) as a nonlinear invariant for flat bathymetry
- the total modified energy
for periodic boundary conditions (see Lampert, Ranocha). Additionally, it is well-balanced for the lake-at-rest stationary solution, see Lampert and Ranocha (2024).
- Magnus Svärd, Henrik Kalisch (2023) A novel energy-bounded Boussinesq model and a well-balanced and stable numerical discretization arXiv: 2302.09924
- Joshua Lampert, Hendrik Ranocha (2024) Structure-Preserving Numerical Methods for Two Nonlinear Systems of Dispersive Wave Equations DOI: 10.48550/arXiv.2402.16669
DispersiveShallowWater.energy_total_modified!
— MethodDispersiveShallowWater.energy_total_modified!(e, q_global, equations::SvaerdKalischEquations1D, cache)
Return the modified total energy e
of the primitive variables q_global
for the SvaerdKalischEquations1D
. It contains an additional term containing a derivative compared to the usual energy_total
modeling non-hydrostatic contributions. The energy_total_modified
is a conserved quantity (for periodic boundary conditions).
It is given by
\[\frac{1}{2} g \eta^2 + \frac{1}{2} h v^2 + \frac{1}{2} \hat\beta v_x^2.\]
q_global
is a vector of the primitive variables at ALL nodes. cache
needs to hold the SBP operators used by the solver
.
See also energy_total_modified
.
DispersiveShallowWater.initial_condition_manufactured
— Methodinitial_condition_manufactured(x, t, equations::SvaerdKalischEquations1D, mesh)
A smooth manufactured solution in combination with source_terms_manufactured
.
DispersiveShallowWater.initial_condition_manufactured_reflecting
— Methodinitial_condition_manufactured_reflecting(x, t, equations::SvaerdKalischEquations1D, mesh)
A smooth manufactured solution for reflecting boundary conditions in combination with source_terms_manufactured_reflecting
.
DispersiveShallowWater.source_terms_manufactured
— Methodsource_terms_manufactured(q, x, t, equations::SvaerdKalischEquations1D, mesh)
A smooth manufactured solution in combination with initial_condition_manufactured
.
DispersiveShallowWater.source_terms_manufactured_reflecting
— Methodsource_terms_manufactured_reflecting(q, x, t, equations::SvaerdKalischEquations1D, mesh)
A smooth manufactured solution for reflecting boundary conditions in combination with initial_condition_manufactured_reflecting
.
Mesh
DispersiveShallowWater.Mesh1D
— TypeMesh1D
Struct that holds the information for a simple homogeneous one-dimensional mesh.
DispersiveShallowWater.Mesh1D
— MethodMesh1D(xmin, xmax, N)
Create a simple homogeneous one-dimensional mesh from xmin
to xmax
with N
nodes.
Boundary conditions
DispersiveShallowWater.boundary_condition_periodic
— Constantboundary_condition_periodic = DispersiveShallowWater.BoundaryConditionPeriodic()
A singleton struct indicating periodic boundary conditions.
DispersiveShallowWater.boundary_condition_reflecting
— Constantboundary_condition_reflecting = DispersiveShallowWater.BoundaryConditionReflecting()
A singleton struct indicating reflecting boundary conditions.
Solver
DispersiveShallowWater.AbstractSolver
— TypeAbstractSolver
An abstract supertype of specific solvers.
DispersiveShallowWater.Solver
— TypeSolver
A struct
that holds the summation-by-parts (SBP) operators that are used for the spatial discretization.
DispersiveShallowWater.Solver
— MethodSolver(mesh, accuracy_order)
Create a solver, where the summation-by-parts (SBP) operators are of order accuracy_order
and associated to the mesh
.
DispersiveShallowWater.Solver
— MethodSolver(D1, D2)
Create a solver, where D1
is an AbstractDerivativeOperator
from SummationByPartsOperators.jl of first derivative_order
and D2
is an AbstractDerivativeOperator
of second derivative_order
or an AbstractMatrix
. It can also be nothing
if no second derivative is used by the discretization. Both summation-by-parts operators should be associated with the same grid.
Semidiscretization
DispersiveShallowWater.Semidiscretization
— TypeSemidiscretization
A struct
containing everything needed to describe a spatial semidiscretization of an equation.
DispersiveShallowWater.Semidiscretization
— MethodSemidiscretization(mesh, equations, initial_condition, solver;
source_terms=nothing,
boundary_conditions=boundary_condition_periodic,
RealT=real(solver),
uEltype=RealT,
initial_cache=(tmp1 = Array{RealT}(undef, nnodes(mesh)),))
Construct a semidiscretization of a PDE.
DispersiveShallowWater.semidiscretize
— Methodsemidiscretize(semi::Semidiscretization, tspan)
Wrap the semidiscretization semi
as an ODE problem in the time interval tspan
that can be passed to solve
from the SciML ecosystem.
SummationByPartsOperators.grid
— Methodgrid(semi)
Get the grid of a semidiscretization.
Callbacks
DispersiveShallowWater.AnalysisCallback
— TypeAnalysisCallback(semi; interval=0,
extra_analysis_errors=Symbol[],
extra_analysis_integrals=(),
io=stdout)
Analyze a numerical solution every interval
time steps. The L2- and the L∞-norm for each component are computed by default. Additional errors can be computed, e.g. by passing extra_analysis_errors = (:conservation_error,)
.
Further scalar functions func
in extra_analysis_integrals
are applied to the numerical solution and integrated over the computational domain. Some examples for this are entropy
, and energy_total
. You can also write your own function with the same signature as the examples listed above and pass it via extra_analysis_integrals
. The computed errors and intergrals are saved for each timestep and can be obtained by calling errors
and integrals
.
During the Simulation, the AnalysisCallback
will print information to io
.
DispersiveShallowWater.errors
— Methoderrors(analysis_callback)
Return the computed errors for each timestep as a named tuple. The shape of each entry is (nvariables, ntimesteps).
DispersiveShallowWater.integrals
— Methodintegrals(analysis_callback)
Return the computed integrals for each timestep as a named tuple.
DispersiveShallowWater.tstops
— Methodtstops(analysis_callback)
Return the time values that correspond to the saved values of the errors
and integrals
.
DispersiveShallowWater.RelaxationCallback
— TypeRelaxationCallback(invariant)
Use a relaxation method in time in order to exactly preserve the (nonlinear) invariant
for a conservative semidiscretization. A possible choice for invariant
is invariant = entropy
.
Reference
- Hendrik Ranocha, Mohammed Sayyari, Lisandro Dalcin, Matteo Parsani, David I. Ketcheson (2020) Relaxation Runge–Kutta Methods: Fully-Discrete Explicit Entropy-Stable Schemes for the Compressible Euler and Navier–Stokes Equations DOI: 10.1137/19M1263480
DispersiveShallowWater.SummaryCallback
— TypeSummaryCallback(io::IO = stdout)
Create and return a callback that resets the timer at the beginning of a simulation and prints the timer values at the end of the simulation.
Utilities
DispersiveShallowWater.convergence_test
— Methodconvergence_test([mod::Module=Main,] example::AbstractString, iterations; io::IO = stdout, kwargs...)
convergence_test([mod::Module=Main,] example::AbstractString, Ns::AbstractVector; io::IO = stdout, kwargs...)
Run multiple simulations using the setup given in example
and compute the experimental order of convergence (EOC) in the $L^2$ and $L^\infty$ norm. If iterations
is passed as integer, in each iteration, the resolution of the respective mesh will be doubled. If Ns
is passed as vector, the simulations will be run for each value of Ns
. Additional keyword arguments kwargs...
and the optional module mod
are passed directly to trixi_include
.
Adjusted from Trixi.jl.
DispersiveShallowWater.default_example
— Methoddefault_example()
Return the path to an example that can be used to quickly see DispersiveShallowWater.jl in action. See also examples_dir
and get_examples
.
Copied from Trixi.jl.
DispersiveShallowWater.examples_dir
— Methodexamples_dir()
Return the directory where the example files provided with DispersiveShallowWater.jl are located. If DispersiveShallowWater is installed as a regular package (with ]add DispersiveShallowWater
), these files are read-only and should not be modified. To find out which files are available, use, e.g., readdir
.
Copied from Trixi.jl.
Examples
readdir(examples_dir())
DispersiveShallowWater.get_examples
— Methodget_examples()
Return a list of all examples that are provided by DispersiveShallowWater.jl. See also examples_dir
and default_example
.
Copied from Trixi.jl.
DispersiveShallowWater.@autoinfiltrate
— Macro@autoinfiltrate
@autoinfiltrate condition::Bool
Invoke the @infiltrate
macro of the package Infiltrator.jl to create a breakpoint for ad-hoc interactive debugging in the REPL. If the optional argument condition
is given, the breakpoint is only enabled if condition
evaluates to true
.
As opposed to using Infiltrator.@infiltrate
directly, this macro does not require Infiltrator.jl to be added as a dependency to DispersiveShallowWater.jl. As a bonus, the macro will also attempt to load the Infiltrator module if it has not yet been loaded manually.
Note: For this macro to work, the Infiltrator.jl package needs to be installed in your current Julia environment stack.
See also: Infiltrator.jl
Please note that this macro is intended for internal use only. It is not part of the public API of DispersiveShallowWater.jl, and it thus can altered (or be removed) at any time without it being considered a breaking change.