diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 908886a2..fa7cbe2b 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.9.4","generation_timestamp":"2023-11-19T13:15:45","documenter_version":"1.1.2"}} \ No newline at end of file +{"documenter":{"julia_version":"1.9.4","generation_timestamp":"2023-11-20T11:54:03","documenter_version":"1.1.2"}} \ No newline at end of file diff --git a/dev/analysis_callback_relaxation.png b/dev/analysis_callback_relaxation.png index b9eb0573..5c76a031 100644 Binary files a/dev/analysis_callback_relaxation.png and b/dev/analysis_callback_relaxation.png differ diff --git a/dev/index.html b/dev/index.html index 27bd484e..9cc8e213 100644 --- a/dev/index.html +++ b/dev/index.html @@ -2,4 +2,4 @@ Home · DispersiveShallowWater.jl

DispersiveShallowWater.jl

Docs-stable Docs-dev Build Status Coveralls Aqua QA License: MIT DOI

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

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")).

Authors

The package is developed and maintained by Joshua Lampert and was initiated as part of the master thesis "Structure-Preserving Numerical Methods for Dispersive Shallow Water Models" (2023). 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.

+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")).

Authors

The package is developed and maintained by Joshua Lampert and was initiated as part of the master thesis "Structure-Preserving Numerical Methods for Dispersive Shallow Water Models" (2023). 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.

diff --git a/dev/license/index.html b/dev/license/index.html index 13bb988b..813042d0 100644 --- a/dev/license/index.html +++ b/dev/license/index.html @@ -1,2 +1,2 @@ -License · DispersiveShallowWater.jl

License

MIT License

Copyright (c) 2023-present Joshua Lampert <joshua.lampert@uni-hamburg.de>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

+License · DispersiveShallowWater.jl

License

MIT License

Copyright (c) 2023-present Joshua Lampert <joshua.lampert@uni-hamburg.de>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

diff --git a/dev/overview/index.html b/dev/overview/index.html index 03ce9fa5..e21ebd80 100644 --- a/dev/overview/index.html +++ b/dev/overview/index.html @@ -29,7 +29,8 @@ mesh: Mesh1D{Float64} with length 513 equations: BBMBBMVariableEquations1D initial condition: initial_condition_shoaling - boundary condition: boundary_condition_periodic

Finally, we put the mesh, the equations, the initial_condition, the solver and the boundary_conditions together in a semidiscretization semi.

Solve system of ordinary differential equations

Once we have obtained a semidiscretization, we can solve the resulting system of ordinary differential equations. To do so, we specify the time interval that we want to simulate and obtain an ODEProblem from the SciML ecosystem for ordinary differential equations by calling semidiscretize on the semidiscretization and the time span. Additionally, we can analyze the numerical solution using an AnalysisCallback. The analysis includes computing the $L^2$ error and $L^\infty$ error of the different solution's variables compared to the initial condition (or, if available, at the same time analytical solution). Additional errors can be passed by the keyword argument extra_analysis_errors. Additional integral quantities that should be analyzed can be passed by keyword argument extra_analysis_integrals. In this example we pass the conservation_error, which computes the temporal change of the total amount (i.e. integral) of the different variables over time. In addition, the integrals of the total waterheight $\eta$ waterheight_total, the velocity and the entropy are computed and saved for each time step. The total waterheight and the total velocity are linear invariants of the BBM-BBM equations, i.e. they do not change over time. The total entropy

\[\mathcal E(t; \eta, v) = \frac{1}{2}\int_\Omega g\eta^2 + (\eta + D)v^2\textrm{d}x\]

is a nonlinear invariant and should be constant over time as well. During the simulation, the AnalysisCallback will print the results to the terminal.

Finally, the ode can be solved using the interface from OrdinaryDiffEq.jl. This means, we can specify a time-stepping scheme we want to use the tolerances for the adaptive time-stepping and the time values, where the solution values should be saved. In this case, we use the adaptive explicit Runge-Kutta method Tsit5 by Tsitouras of order 5(4). Here, we save the solution at 100 equidistant points.

tspan = (0.0, 25.0)
+    boundary condition: boundary_condition_periodic
+    source terms: nothing

Finally, we put the mesh, the equations, the initial_condition, the solver and the boundary_conditions together in a semidiscretization semi.

Solve system of ordinary differential equations

Once we have obtained a semidiscretization, we can solve the resulting system of ordinary differential equations. To do so, we specify the time interval that we want to simulate and obtain an ODEProblem from the SciML ecosystem for ordinary differential equations by calling semidiscretize on the semidiscretization and the time span. Additionally, we can analyze the numerical solution using an AnalysisCallback. The analysis includes computing the $L^2$ error and $L^\infty$ error of the different solution's variables compared to the initial condition (or, if available, at the same time analytical solution). Additional errors can be passed by the keyword argument extra_analysis_errors. Additional integral quantities that should be analyzed can be passed by keyword argument extra_analysis_integrals. In this example we pass the conservation_error, which computes the temporal change of the total amount (i.e. integral) of the different variables over time. In addition, the integrals of the total waterheight $\eta$ waterheight_total, the velocity and the entropy are computed and saved for each time step. The total waterheight and the total velocity are linear invariants of the BBM-BBM equations, i.e. they do not change over time. The total entropy

\[\mathcal E(t; \eta, v) = \frac{1}{2}\int_\Omega g\eta^2 + (\eta + D)v^2\textrm{d}x\]

is a nonlinear invariant and should be constant over time as well. During the simulation, the AnalysisCallback will print the results to the terminal.

Finally, the ode can be solved using the interface from OrdinaryDiffEq.jl. This means, we can specify a time-stepping scheme we want to use the tolerances for the adaptive time-stepping and the time values, where the solution values should be saved. In this case, we use the adaptive explicit Runge-Kutta method Tsit5 by Tsitouras of order 5(4). Here, we save the solution at 100 equidistant points.

tspan = (0.0, 25.0)
 ode = semidiscretize(semi, tspan)
 analysis_callback = AnalysisCallback(semi; interval = 10,
                                      extra_analysis_errors = (:conservation_error,),
@@ -65,25 +66,25 @@
  25.0
 u: 100-element Vector{Vector{Float64}}:
  [0.0, 0.0, 0.7, 0.0, 0.0, 0.7, 0.0, 0.0, 0.7, 0.0  …  0.32339181286549706, 1.1159911034969113e-106, 0.0, 0.31754385964912274, 6.2568988186290324e-108, 0.0, 0.31169590643274847, 3.4485093610035348e-109, 0.0, 0.30584795321637426]
- [-3.3331038569420146e-56, 8.256148700914237e-57, 0.7, 3.408574917469543e-56, 3.9430359901857903e-59, 0.7, -1.283498855461488e-56, 4.5833176651100903e-57, 0.7, 9.847841549495285e-57  …  0.32339181286549706, 9.309131410519057e-55, -7.287463977686323e-55, 0.31754385964912274, -3.351840741148481e-55, 2.8398152204518467e-55, 0.31169590643274847, 9.271449493862975e-56, -9.96165653190832e-56, 0.30584795321637426]
- [-4.854851751820977e-53, 1.8098476394372179e-53, 0.7, 4.842655330441384e-53, -1.4596494155393105e-55, 0.7, -1.854466232713836e-53, 9.788170395942083e-54, 0.7, 1.4193452481157134e-53  …  0.32339181286549706, 1.2619747556762687e-51, -1.4765798512062174e-51, 0.31754385964912274, -4.641583609050213e-52, 5.871621132574207e-52, 0.31169590643274847, 1.3209285178978112e-52, -2.0982737814550583e-52, 0.30584795321637426]
- [-1.1612440680607787e-50, 5.35263534105061e-51, 0.7, 1.13205415742218e-50, -1.0908943144143306e-52, 0.7, -4.4040915311771843e-51, 2.8257939474327006e-51, 0.7, 3.363577679352945e-51  …  0.32339181286549706, 2.8189376712946925e-49, -4.04835119485468e-49, 0.31754385964912274, -1.0581989242188491e-49, 1.6416307681774006e-49, 0.31169590643274847, 3.094182712334637e-50, -5.9736834924382945e-50, 0.30584795321637426]
- [-1.1119858892051603e-48, 5.886893772032651e-49, 0.7, 1.0619542390111966e-48, -1.8735965075136485e-50, 0.7, -4.1915212392194984e-49, 3.0416529767204354e-49, 0.7, 3.1953522178457482e-49  …  0.32339181286549706, 2.533649936640755e-47, -4.151226674426741e-47, 0.31754385964912274, -9.693403044040094e-48, 1.7143537778548173e-47, 0.31169590643274847, 2.906333751091284e-48, -6.344242948802575e-48, 0.30584795321637426]
- [-6.21149925272881e-47, 3.6607319310598914e-47, 0.7, 5.815476588053866e-47, -1.5891578458235548e-48, 0.7, -2.328319709539873e-47, 1.8525177880971185e-47, 0.7, 1.771935834197097e-47  …  0.32339181286549706, 1.3288101167407954e-45, -2.406574834410681e-45, 0.31754385964912274, -5.1810555358034844e-46, 1.0122890363452135e-45, 0.31169590643274847, 1.5926502234756952e-46, -3.810135121927679e-46, 0.30584795321637426]
- [-2.3254638499356597e-45, 1.4921953486089056e-45, 0.7, 2.137213877634674e-45, -8.159202602174151e-47, 0.7, -8.674202813412648e-46, 7.40703472017319e-46, 0.7, 6.591216311711837e-46  …  0.32339181286549706, 4.68107818594664e-44, -9.168674819877262e-44, 0.31754385964912274, -1.85893754645141e-44, 3.9259948090592396e-44, 0.31169590643274847, 5.853557248622687e-45, -1.5021292549658637e-44, 0.30584795321637426]
- [-6.392817990765208e-44, 4.4001362408844663e-44, 0.7, 5.774217424390502e-44, -2.8902524453610563e-45, 0.7, -2.3744585596344e-44, 2.1453566962310837e-44, 0.7, 1.8017471182265625e-44  …  0.32339181286549706, 1.2132384122523458e-42, -2.5326739221347554e-42, 0.31754385964912274, -4.9044780008285596e-43, 1.1034158252550065e-42, 0.31169590643274847, 1.5807454470268977e-43, -4.289517692627482e-43, 0.30584795321637426]
- [-1.3787503977349084e-42, 1.0073886902318699e-42, 0.7, 1.225119386700148e-42, -7.708121099641253e-44, 0.7, -5.102249006759843e-43, 4.830053602703819e-43, 0.7, 3.866658327738276e-43  …  0.32339181286549706, 2.470475200489942e-41, -5.441183797951465e-41, 0.31754385964912274, -1.0162156575702873e-41, 2.4110379523899415e-41, 0.31169590643274847, 3.3505724544690965e-42, -9.519811861301611e-42, 0.30584795321637426]
- [-2.4329943118960967e-41, 1.8726573236243696e-41, 0.7, 2.1286192896507293e-41, -1.6338489776130404e-42, 0.7, -8.975456788392016e-42, 8.838532577148244e-42, 0.7, 6.793904425040877e-42  …  0.32339181286549706, 4.120411844968818e-40, -9.504003276507746e-40, 0.31754385964912274, -1.7241821641626938e-40, 4.281941476756354e-40, 0.31169590643274847, 5.812886482588927e-41, -1.7167524651272287e-40, 0.30584795321637426]
+ [-3.3298063320105386e-56, 8.240555184525373e-57, 0.7, 3.4052487839602066e-56, 3.8721596046450877e-59, 0.7, -1.2823114010005487e-56, 4.5746067309011375e-57, 0.7, 9.837872827117964e-57  …  0.32339181286549706, 9.300749704670396e-55, -7.275157739846947e-55, 0.31754385964912274, -3.348584246232203e-55, 2.8353792349816592e-55, 0.31169590643274847, 9.261972052395447e-56, -9.944024391145692e-56, 0.30584795321637426]
+ [-4.854627270617779e-53, 1.809712375822027e-53, 0.7, 4.842444655430691e-53, -1.4591991690482042e-55, 0.7, -1.8543823964202563e-53, 9.787480542672555e-54, 0.7, 1.4192813322404536e-53  …  0.32339181286549706, 1.2619264297387037e-51, -1.4764905451287523e-51, 0.31754385964912274, -4.641396873108809e-52, 5.871242596528972e-52, 0.31169590643274847, 1.320870503616519e-52, -2.0981320674476158e-52, 0.30584795321637426]
+ [-1.161236430780927e-50, 5.352584402349824e-51, 0.7, 1.132047190334612e-50, -1.090865546552179e-52, 0.7, -4.404063115451628e-51, 2.8257688001594547e-51, 0.7, 3.363556071973813e-51  …  0.32339181286549706, 2.8189227454109665e-49, -4.048320798927971e-49, 0.31754385964912274, -1.058192942359117e-49, 1.6416176052934605e-49, 0.31169590643274847, 3.0941636353866156e-50, -5.973632917118691e-50, 0.30584795321637426]
+ [-1.111984161777274e-48, 5.886881206722659e-49, 0.7, 1.0619527001701963e-48, -1.873587324635778e-50, 0.7, -4.191514844282648e-49, 3.04164693232564e-49, 0.7, 3.1953473695033716e-49  …  0.32339181286549706, 2.5336468214045444e-47, -4.1512198119827403e-47, 0.31754385964912274, -9.693390250020113e-48, 1.7143507420784363e-47, 0.31169590643274847, 2.906329540544282e-48, -6.344231008069559e-48, 0.30584795321637426]
+ [-6.211496280528294e-47, 3.6607296186797117e-47, 0.7, 5.81547399618812e-47, -1.5891558132848647e-48, 0.7, -2.3283186142162194e-47, 1.8525166989190623e-47, 0.7, 1.7719350053561196e-47  …  0.32339181286549706, 1.3288096197339765e-45, -2.406573671857341e-45, 0.31754385964912274, -5.181053447216573e-46, 1.0122885108901054e-45, 0.31169590643274847, 1.5926495156599105e-46, -3.8101330106319815e-46, 0.30584795321637426]
+ [-2.325463438823169e-45, 1.4921950096721943e-45, 0.7, 2.1372135258244082e-45, -8.159199150016775e-47, 0.7, -8.674201303018941e-46, 7.407033154029957e-46, 0.7, 6.59121517028004e-46  …  0.32339181286549706, 4.681077546331119e-44, -9.168673246160421e-44, 0.31754385964912274, -1.8589372716338307e-44, 3.9259940822661885e-44, 0.31169590643274847, 5.853556290472661e-45, -1.5021289571420408e-44, 0.30584795321637426]
+ [-6.392817515195469e-44, 4.4001358292248024e-44, 0.7, 5.774217024408481e-44, -2.890251970346458e-45, 0.7, -2.374458385327122e-44, 2.1453565092353564e-44, 0.7, 1.80174698666066e-44  …  0.32339181286549706, 1.2132383431986734e-42, -2.532673744979001e-42, 0.31754385964912274, -4.904477697795913e-43, 1.1034157417570076e-42, 0.31169590643274847, 1.5807453384605294e-43, -4.289517343919539e-43, 0.30584795321637426]
+ [-1.3787503503174236e-42, 1.0073886474279489e-42, 0.7, 1.2251193474315923e-42, -7.708120549579181e-44, 0.7, -5.102248833206378e-43, 4.8300534112044794e-43, 0.7, 3.8666581968804824e-43  …  0.32339181286549706, 2.4704751359942366e-41, -5.44118362661684e-41, 0.31754385964912274, -1.0162156286973175e-41, 2.41103787004135e-41, 0.31169590643274847, 3.350572348324435e-42, -9.51981151113154e-42, 0.30584795321637426]
+ [-2.4329942701782505e-41, 1.8726572845802347e-41, 0.7, 2.1286192555782036e-41, -1.633848922522654e-42, 0.7, -8.97545663579173e-42, 8.838532404784254e-42, 0.7, 6.793904310090351e-42  …  0.32339181286549706, 4.120411791612597e-40, -9.504003130525254e-40, 0.31754385964912274, -1.7241821398234909e-40, 4.281941405290549e-40, 0.31169590643274847, 5.812886390913171e-41, -1.716752434217434e-40, 0.30584795321637426]
  ⋮
- [-0.0021768568053301533, -0.005471508691304303, 0.7, -0.0010991531445136602, -0.002987187762678884, 0.7, -0.0005923337764092974, -0.0016674303283175833, 0.7, 0.0007288095726283757  …  0.32339181286549706, -0.002446501805835416, -0.01637377384830733, 0.31754385964912274, -0.0016159836137552876, -0.013551798527814731, 0.31169590643274847, -0.0024066935622708593, -0.01538599384719884, 0.30584795321637426]
- [-0.0025058754714979096, -0.008500215882787182, 0.7, -0.0018252401083375849, -0.008052197913993881, 0.7, -0.0012170710172799903, -0.006710223227505052, 0.7, -0.0004346836902189762  …  0.32339181286549706, -0.0021856746220264376, -0.01596720905195491, 0.31754385964912274, -0.0019264030106737207, -0.01340209625400597, 0.31169590643274847, -0.002238819035873412, -0.014632665884650554, 0.30584795321637426]
- [-0.0018622554232660949, -0.008813488862025442, 0.7, -0.0021123681485556486, -0.009894126107163953, 0.7, -0.0020128406188383266, -0.009049578436370461, 0.7, -0.0018802163331252983  …  0.32339181286549706, -0.0014215010258198104, -0.009963901856291016, 0.31754385964912274, -0.0019272324089571068, -0.012910684832531667, 0.31169590643274847, -0.0015105892195426023, -0.013900945522402333, 0.30584795321637426]
- [-0.0011336758604552286, -0.006535539122471458, 0.7, -0.001979219507900499, -0.0076241143777411105, 0.7, -0.00239476091896833, -0.008186003096997506, 0.7, -0.002719468672374758  …  0.32339181286549706, -0.00034224853703397964, -0.004573764010270145, 0.31754385964912274, -0.0011555137032241353, -0.011452364518071368, 0.31169590643274847, -0.0008953442781766404, -0.01289053854989343, 0.30584795321637426]
- [-0.0008511358330743565, -0.0035764780554478548, 0.7, -0.0015164577577978285, -0.0038311634821196145, 0.7, -0.001934593226221099, -0.0056446160643163846, 0.7, -0.0024032659014424714  …  0.32339181286549706, 0.00048676953199560996, -0.003240993175423114, 0.31754385964912274, -0.0001314980022209611, -0.007826563056479791, 0.31169590643274847, -0.0006596159967523573, -0.009519268041658332, 0.30584795321637426]
- [-0.0007926983849506682, -0.0017254112742892834, 0.7, -0.0009183634647563144, -0.00157814795788267, 0.7, -0.0009349159821020013, -0.0034054992530155523, 0.7, -0.001330648411503686  …  0.32339181286549706, 0.0007085992217667806, -0.003227914524735462, 0.31754385964912274, 0.0003672721353325873, -0.0027193442234355572, 0.31169590643274847, -0.0005220550795835814, -0.0041480429753825735, 0.30584795321637426]
- [-0.0005045949122517944, -0.0010626077342998552, 0.7, -0.00039778847670191155, -0.001376885520350056, 0.7, -0.00012800109379728592, -0.002200107569359619, 0.7, -0.00040759311213305543  …  0.32339181286549706, 0.0005311117049731281, -0.0007705176971118028, 0.31754385964912274, 0.0002934328821293543, 0.0014618990740307449, 0.31169590643274847, -0.00014917439661157303, 0.0005201307641517408, 0.30584795321637426]
- [7.803777012574446e-5, -0.00042936266828308986, 0.7, -4.958365526498263e-5, -0.0013994492190674305, 0.7, 8.636575719678301e-5, -0.0013855062117348023, 0.7, -0.00013921328594875684  …  0.32339181286549706, 0.00044778090104515174, 0.003410122319406289, 0.31754385964912274, 0.000206955678604383, 0.003117811982282833, 0.31169590643274847, 0.0003893407334412954, 0.002756152881021225, 0.30584795321637426]
- [0.0006073616394550401, 0.0008907054710587792, 0.7, 0.00018073121640873664, -8.67790512142538e-5, 0.7, -2.611552969232017e-5, -0.00015434992446140198, 0.7, -0.00025246394088187065  …  0.32339181286549706, 0.000657743197126916, 0.005711584342451256, 0.31754385964912274, 0.00043018536651274065, 0.0030669676280137255, 0.31169590643274847, 0.0007358879405425669, 0.003315270056768666, 0.30584795321637426]

After solving the equations, sol contains the solution for each of the three variables at every spatial point for each of the 100 points in time. The errors and integrals recorded by the AnalysisCallback can be obtained as NamedTuples by errors(analysis_callback) and integrals(analysis_callback).

Visualize results

After running the simulation, the results can be visualized using Plots.jl, which needs to be imported first. Then, we can plot the solution at the final time by calling plot on a Pair of the Semidiscretization and the corresponding ODESolution sol. The result is depicted in the following picture.

using Plots
+ [-0.002176856805330235, -0.005471508691304497, 0.7, -0.001099153144513662, -0.0029871877626791183, 0.7, -0.0005923337764093331, -0.0016674303283175998, 0.7, 0.0007288095726284696  …  0.32339181286549706, -0.0024465018058354463, -0.01637377384830735, 0.31754385964912274, -0.0016159836137553062, -0.01355179852781439, 0.31169590643274847, -0.0024066935622708515, -0.015385993847199006, 0.30584795321637426]
+ [-0.00250587547149793, -0.008500215882787284, 0.7, -0.0018252401083375962, -0.008052197913994155, 0.7, -0.0012170710172800508, -0.006710223227505286, 0.7, -0.000434683690218956  …  0.32339181286549706, -0.0021856746220264536, -0.01596720905195473, 0.31754385964912274, -0.001926403010673724, -0.013402096254005912, 0.31169590643274847, -0.002238819035873335, -0.014632665884650491, 0.30584795321637426]
+ [-0.0018622554232660391, -0.008813488862025372, 0.7, -0.0021123681485556273, -0.009894126107164069, 0.7, -0.002012840618838343, -0.009049578436370673, 0.7, -0.0018802163331253382  …  0.32339181286549706, -0.001421501025819743, -0.00996390185629101, 0.31754385964912274, -0.0019272324089571102, -0.012910684832531816, 0.31169590643274847, -0.0015105892195425286, -0.013900945522402237, 0.30584795321637426]
+ [-0.0011336758604551511, -0.006535539122471322, 0.7, -0.001979219507900437, -0.00762411437774105, 0.7, -0.0023947609189682666, -0.00818600309699748, 0.7, -0.0027194686723747835  …  0.32339181286549706, -0.00034224853703385805, -0.00457376401027034, 0.31754385964912274, -0.0011555137032241494, -0.011452364518071361, 0.31169590643274847, -0.0008953442781766002, -0.012890538549893608, 0.30584795321637426]
+ [-0.0008511358330743246, -0.003576478055447792, 0.7, -0.0015164577577977635, -0.0038311634821195746, 0.7, -0.0019345932262209958, -0.005644616064316158, 0.7, -0.002403265901442433  …  0.32339181286549706, 0.0004867695319956734, -0.0032409931754231974, 0.31754385964912274, -0.00013149800222093987, -0.00782656305647952, 0.31169590643274847, -0.0006596159967523298, -0.00951926804165878, 0.30584795321637426]
+ [-0.0007926983849506771, -0.0017254112742892866, 0.7, -0.0009183634647562862, -0.0015781479578827905, 0.7, -0.0009349159821019416, -0.00340549925301533, 0.7, -0.001330648411503606  …  0.32339181286549706, 0.0007085992217667344, -0.003227914524735306, 0.31754385964912274, 0.0003672721353326862, -0.002719344223435364, 0.31169590643274847, -0.0005220550795835429, -0.004148042975382867, 0.30584795321637426]
+ [-0.0005045949122517807, -0.0010626077342998173, 0.7, -0.00039778847670192055, -0.0013768855203502518, 0.7, -0.00012800109379730638, -0.00220010756935956, 0.7, -0.0004075931121329894  …  0.32339181286549706, 0.0005311117049730599, -0.0007705176971117157, 0.31754385964912274, 0.0002934328821294871, 0.0014618990740305471, 0.31169590643274847, -0.00014917439661154644, 0.0005201307641519544, 0.30584795321637426]
+ [7.803777012583456e-5, -0.0004293626682829821, 0.7, -4.958365526498939e-5, -0.0013994492190674875, 0.7, 8.636575719673748e-5, -0.0013855062117348852, 0.7, -0.00013921328594872933  …  0.32339181286549706, 0.0004477809010451735, 0.003410122319406037, 0.31754385964912274, 0.00020695567860444395, 0.0031178119822825095, 0.31169590643274847, 0.00038934073344127154, 0.002756152881021689, 0.30584795321637426]
+ [0.0006073616394551576, 0.000890705471058846, 0.7, 0.00018073121640876355, -8.677905121408308e-5, 0.7, -2.6115529692313e-5, -0.00015434992446148764, 0.7, -0.00025246394088185216  …  0.32339181286549706, 0.0006577431971269968, 0.005711584342450851, 0.31754385964912274, 0.00043018536651270086, 0.003066967628013788, 0.31169590643274847, 0.0007358879405425109, 0.003315270056768716, 0.30584795321637426]

After solving the equations, sol contains the solution for each of the three variables at every spatial point for each of the 100 points in time. The errors and integrals recorded by the AnalysisCallback can be obtained as NamedTuples by errors(analysis_callback) and integrals(analysis_callback).

Visualize results

After running the simulation, the results can be visualized using Plots.jl, which needs to be imported first. Then, we can plot the solution at the final time by calling plot on a Pair of the Semidiscretization and the corresponding ODESolution sol. The result is depicted in the following picture.

using Plots
 
 plot(semi => sol)
 savefig("shoaling_solution.png")
"/home/runner/work/DispersiveShallowWater.jl/DispersiveShallowWater.jl/docs/build/shoaling_solution.png"

By default, this will plot the bathymetry, but not the initial (analytical) solution. You can adjust this by passing the boolean values plot_bathymetry (if true always plot to first subplot) and plot_initial. You can also provide a conversion function that converts the solution. A conversion function should take the values of the primitive variables q at one node, and the equations as input and should return an SVector of any length as output. For a user defined conversion function, there should also exist a function varnames(conversion, equations) that returns a Tuple of the variable names used for labelling. The conversion function can, e.g., be prim2cons or waterheight_total if one only wants to plot the total waterheight. The resulting plot will have one subplot for each of the returned variables of the conversion variable. By default, the conversion function is just prim2prim, i.e. the identity.

Plotting an animation over time can, e.g., be done by the following command, which uses step to plot the solution at a specific time step.

anim = @animate for step in 1:length(sol.u)
@@ -123,25 +124,25 @@
  25.0
 u: 100-element Vector{Vector{Float64}}:
  [0.0, 0.0, 0.7, 0.0, 0.0, 0.7, 0.0, 0.0, 0.7, 0.0  …  0.32339181286549706, 1.1159911034969113e-106, 0.0, 0.31754385964912274, 6.2568988186290324e-108, 0.0, 0.31169590643274847, 3.4485093610035348e-109, 0.0, 0.30584795321637426]
- [-3.3325014986266883e-56, 8.255392228198082e-57, 0.7, 3.407895196177425e-56, 3.8901511607885443e-59, 0.7, -1.2832663802451024e-56, 4.5820738731931563e-57, 0.7, 9.845657534528379e-57  …  0.32339181286549706, 9.307306609388591e-55, -7.286237680402366e-55, 0.31754385964912274, -3.351118628183334e-55, 2.839592655743891e-55, 0.31169590643274847, 9.26932790322038e-56, -9.96019047796248e-56, 0.30584795321637426]
- [-4.85449161799413e-53, 1.8096983174886938e-53, 0.7, 4.8423004554217265e-53, -1.4594892031381318e-55, 0.7, -1.8543293895787933e-53, 9.787371675177696e-54, 0.7, 1.4192405874072862e-53  …  0.32339181286549706, 1.2618842170136206e-51, -1.476462797045149e-51, 0.31754385964912274, -4.641247015076406e-52, 5.8711467831228455e-52, 0.31169590643274847, 1.320831363658545e-52, -2.098103647975462e-52, 0.30584795321637426]
- [-1.161170518975277e-50, 5.352274387359011e-51, 0.7, 1.1319830816858637e-50, -1.0908030957324364e-52, 0.7, -4.4038133492797567e-51, 2.8256051204646724e-51, 0.7, 3.363365378534057e-51  …  0.32339181286549706, 2.8187638237054095e-49, -4.048086283192478e-49, 0.31754385964912274, -1.058133152991075e-49, 1.6415224644895143e-49, 0.31169590643274847, 3.0939883372283185e-50, -5.973286662772888e-50, 0.30584795321637426]
- [-1.1119329982517998e-48, 5.886598996240963e-49, 0.7, 1.0619041805269367e-48, -1.8734875627798872e-50, 0.7, -4.1913223867391814e-49, 3.0415020910106996e-49, 0.7, 3.1952007438570404e-49  …  0.32339181286549706, 2.533532797758821e-47, -4.1510252153639084e-47, 0.31754385964912274, -9.692951044697425e-48, 1.7142698935872605e-47, 0.31169590643274847, 2.90619669914533e-48, -6.343930176272873e-48, 0.30584795321637426]
- [-6.211340916224652e-47, 3.6606349028124054e-47, 0.7, 5.815329545593704e-47, -1.5891111597334266e-48, 0.7, -2.3282604893901166e-47, 1.8524690897292304e-47, 0.7, 1.771890796594865e-47  …  0.32339181286549706, 1.3287771285608983e-45, -2.4065128470063694e-45, 0.31754385964912274, -5.180925880067077e-46, 1.0122627638348036e-45, 0.31169590643274847, 1.5926099480991396e-46, -3.8100355466180276e-46, 0.30584795321637426]
- [-2.3254161525366872e-45, 1.4921634780482275e-45, 0.7, 2.1371704663636918e-45, -8.159009309608031e-47, 0.7, -8.674025332630818e-46, 7.406878079526365e-46, 0.7, 6.591081557118887e-46  …  0.32339181286549706, 4.68098527604015e-44, -9.16848588537043e-44, 0.31754385964912274, -1.858900280727369e-44, 3.9259131330435315e-44, 0.31169590643274847, 5.853438369248809e-45, -1.5020977308451937e-44, 0.30584795321637426]
- [-6.392704785891605e-44, 4.400055705514061e-44, 0.7, 5.774116073229896e-44, -2.890195060992707e-45, 0.7, -2.3744165990126805e-44, 2.1453177759257e-44, 0.7, 1.8017153005734223e-44  …  0.32339181286549706, 1.2132175801955254e-42, -2.532629084850283e-42, 0.31754385964912274, -4.904392992184702e-43, 1.1033961156038126e-42, 0.31169590643274847, 1.5807177123221868e-43, -4.289440444258712e-43, 0.30584795321637426]
- [-1.3787258223337722e-42, 1.0073701218104765e-42, 0.7, 1.2250977635018685e-42, -7.707966842856126e-44, 0.7, -5.1021582498825915e-43, 4.829965445331615e-43, 0.7, 3.866589600866384e-43  …  0.32339181286549706, 2.4704327051359937e-41, -5.441087305786118e-41, 0.31754385964912274, -1.0161979863364886e-41, 2.4109947493503026e-41, 0.31169590643274847, 3.3505133656285086e-42, -9.519639649686846e-42, 0.30584795321637426]
- [-2.4329533401814664e-41, 1.8726248533341496e-41, 0.7, 2.1285837724397068e-41, -1.6338185762758637e-42, 0.7, -8.975305902396223e-42, 8.838380711407404e-42, 0.7, 6.793790291492647e-42  …  0.32339181286549706, 4.120344812951605e-40, -9.503844519210547e-40, 0.31754385964912274, -1.7241538157657436e-40, 4.281869225316388e-40, 0.31169590643274847, 5.812789596917422e-41, -1.7167232293556883e-40, 0.30584795321637426]
+ [-3.332266410556691e-56, 8.250693938128724e-57, 0.7, 3.407583642309716e-56, 3.8490501278015398e-59, 0.7, -1.2832354556318063e-56, 4.5801232603284077e-57, 0.7, 9.844890923810958e-57  …  0.32339181286549706, 9.30670509753227e-55, -7.283825400163255e-55, 0.31754385964912274, -3.350861542354207e-55, 2.838655119185712e-55, 0.31169590643274847, 9.268574447724803e-56, -9.95620229491928e-56, 0.30584795321637426]
+ [-4.854545545070253e-53, 1.8097193833399515e-53, 0.7, 4.842352321849954e-53, -1.4595167657656438e-55, 0.7, -1.8543498712251333e-53, 9.787486255308402e-54, 0.7, 1.4192559489927457e-53  …  0.32339181286549706, 1.2618974617562503e-51, -1.4764810496891982e-51, 0.31754385964912274, -4.641297573080381e-52, 5.871219778928541e-52, 0.31169590643274847, 1.3208456304778785e-52, -2.098129111059335e-52, 0.30584795321637426]
+ [-1.161174020717534e-50, 5.352294982928633e-51, 0.7, 1.1319863540772265e-50, -1.0908116767888405e-52, 0.7, -4.4038264457122423e-51, 2.8256156036521797e-51, 0.7, 3.3633753287785445e-51  …  0.32339181286549706, 2.818771303094653e-49, -4.048100076844979e-49, 0.31754385964912274, -1.0581360622684687e-49, 1.6415282643014427e-49, 0.31169590643274847, 3.0939972995600496e-50, -5.973308375246117e-50, 0.30584795321637426]
+ [-1.1119340370914712e-48, 5.886606126151948e-49, 0.7, 1.0619051193616636e-48, -1.8734919750652443e-50, 0.7, -4.1913262441970204e-49, 3.0415055830255834e-49, 0.7, 3.195203669716197e-49  …  0.32339181286549706, 2.533534775326589e-47, -4.151029387758137e-47, 0.31754385964912274, -9.692959041345168e-48, 1.7142717056808075e-47, 0.31169590643274847, 2.906199272580485e-48, -6.343937197528971e-48, 0.30584795321637426]
+ [-6.211342952679108e-47, 3.660636442561326e-47, 0.7, 5.815331336869501e-47, -1.5891123999359684e-48, 0.7, -2.3282612408209723e-47, 1.852469822382361e-47, 0.7, 1.7718913654148852e-47  …  0.32339181286549706, 1.3287774802196427e-45, -2.4065136543212134e-45, 0.31754385964912274, -5.180927344176877e-46, 1.0122631249018097e-45, 0.31169590643274847, 1.592610437929165e-46, -3.8100369833174064e-46, 0.30584795321637426]
+ [-2.3254164502674176e-45, 1.49216372070005e-45, 0.7, 2.137170722072698e-45, -8.159011679159638e-47, 0.7, -8.674026426679073e-46, 7.406879206110161e-46, 0.7, 6.591082384100245e-46  …  0.32339181286549706, 4.68098574598978e-44, -9.168487035994518e-44, 0.31754385964912274, -1.8589004819059543e-44, 3.9259136618095353e-44, 0.31169590643274847, 5.853439066560083e-45, -1.502097946470543e-44, 0.30584795321637426]
+ [-6.392705132782543e-44, 4.400056006120195e-44, 0.7, 5.774116364831327e-44, -2.890195404164474e-45, 0.7, -2.3744167260793885e-44, 2.1453179125315753e-44, 0.7, 1.8017153964783695e-44  …  0.32339181286549706, 1.213217630459334e-42, -2.5326292145530362e-42, 0.31754385964912274, -4.904393213034871e-43, 1.1033961767416291e-42, 0.31169590643274847, 1.5807177915108583e-43, -4.289440699461812e-43, 0.30584795321637426]
+ [-1.3787258559015014e-42, 1.0073701524772098e-42, 0.7, 1.2250977911673285e-42, -7.707967242881186e-44, 0.7, -5.102158372622728e-43, 4.8299655820378e-43, 0.7, 3.866589693374949e-43  …  0.32339181286549706, 2.470432749855349e-41, -5.441087426494035e-41, 0.31754385964912274, -1.0161980065048432e-41, 2.410994807691375e-41, 0.31169590643274847, 3.3505134403765806e-42, -9.51963989884522e-42, 0.30584795321637426]
+ [-2.432953367861249e-41, 1.8726248798384983e-41, 0.7, 2.1285837948336777e-41, -1.6338186152122516e-42, 0.7, -8.975306003526185e-42, 8.83838082751108e-42, 0.7, 6.79379036762082e-42  …  0.32339181286549706, 4.12034484685199e-40, -9.503844614433176e-40, 0.31754385964912274, -1.7241538314594997e-40, 4.2818692725079266e-40, 0.31169590643274847, 5.812789657041895e-41, -1.7167232499767342e-40, 0.30584795321637426]
  ⋮
- [-0.002165983808856081, -0.005462316236984096, 0.7, -0.0010949955191127984, -0.00299467806241732, 0.7, -0.0005920726738235178, -0.0016630027332404838, 0.7, 0.0007264876839320407  …  0.32339181286549706, -0.0024455835509595326, -0.01631701545550817, 0.31754385964912274, -0.0016212354480479696, -0.01352891089289522, 0.31169590643274847, -0.002396885241065709, -0.015332363345197811, 0.30584795321637426]
- [-0.0024946509575851416, -0.00847430502484576, 0.7, -0.001821110826193728, -0.008025725779320123, 0.7, -0.001219316764107281, -0.006688548166333608, 0.7, -0.00043839507595224076  …  0.32339181286549706, -0.0021804302393484756, -0.01590186318296492, 0.31754385964912274, -0.0019262159652890312, -0.01340119362816945, 0.31169590643274847, -0.002232448416912382, -0.014629354103317834, 0.30584795321637426]
- [-0.0018597237172830018, -0.00878590816730318, 0.7, -0.0021080298633721463, -0.009851920630150824, 0.7, -0.002009838115979035, -0.009018710861238762, 0.7, -0.0018764289682748115  …  0.32339181286549706, -0.001417486719670132, -0.009955159836301112, 0.31754385964912274, -0.0019200772426444847, -0.0129040532827212, 0.31169590643274847, -0.0015113103521349558, -0.013907495809161192, 0.30584795321637426]
- [-0.0011382887415977813, -0.0065262409142084555, 0.7, -0.001975563757344305, -0.007603373094278423, 0.7, -0.0023866475979837957, -0.008165663953046593, 0.7, -0.002708923707548153  …  0.32339181286549706, -0.00034409204632867587, -0.00461356538213588, 0.31754385964912274, -0.0011508462467487441, -0.011431378783413432, 0.31169590643274847, -0.0008995601062786931, -0.01287496743629932, 0.30584795321637426]
- [-0.0008547943895035267, -0.003587329842034271, 0.7, -0.0015148921303084725, -0.003843847009732288, 0.7, -0.0019284466945888997, -0.005644129387757292, 0.7, -0.0023946513342133395  …  0.32339181286549706, 0.000480767436786142, -0.0032655471937218955, 0.31754385964912274, -0.0001350079069211847, -0.007808778243089802, 0.31169590643274847, -0.0006613057774831263, -0.009496236940963248, 0.30584795321637426]
- [-0.0007911392786587576, -0.0017393569555296134, 0.7, -0.0009192247258541323, -0.001601273393552956, 0.7, -0.00093602481528088, -0.0034159764533117747, 0.7, -0.0013305081833949873  …  0.32339181286549706, 0.0007042413951192368, -0.0032091589879663686, 0.31754385964912274, 0.00036098704059886087, -0.0027240845338641407, 0.31169590643274847, -0.0005197291955477552, -0.004146557210079597, 0.30584795321637426]
- [-0.0005009119017045585, -0.001064353994398852, 0.7, -0.00039971046012842034, -0.00138297076329162, 0.7, -0.00013392608631435243, -0.0022067354929193044, 0.7, -0.0004136793726673361  …  0.32339181286549706, 0.000531724088654508, -0.0007458554006886094, 0.31754385964912274, 0.0002918660500146652, 0.0014385389505504928, 0.31169590643274847, -0.00014667287237836498, 0.0004996358322930379, 0.30584795321637426]
- [7.877033748185829e-5, -0.00042112363962556993, 0.7, -5.075924767411249e-5, -0.0013861889826009084, 0.7, 8.248268091038496e-5, -0.0013829603946880003, 0.7, -0.00014394433252067082  …  0.32339181286549706, 0.00045095020034862016, 0.0034010197767581217, 0.31754385964912274, 0.00020988107240574213, 0.0030986111294807168, 0.31169590643274847, 0.0003882810307982908, 0.0027368433078829146, 0.30584795321637426]
- [0.0006041217258655209, 0.0008950650498072315, 0.7, 0.00018078926007734477, -7.445962324128559e-5, 0.7, -2.4516528465290907e-5, -0.0001493914009533525, 0.7, -0.0002513925977370608  …  0.32339181286549706, 0.0006585897415157716, 0.005679923430856877, 0.31754385964912274, 0.00043197788263921573, 0.003066796203847043, 0.31169590643274847, 0.0007320680612231734, 0.003311140575127273, 0.30584795321637426]

When you use both, an AnalysisCallback and a RelaxationCallback, note that the relaxation_callback needs to come first inside the CallbackSet as it needs to be invoked prior to the analysis_callback, such that the analysis_callback analyzes the solution with the already updated values.

Plotting the analysis_callback again, we can see that now also the entropy is conserved up to machine precision.

plot(analysis_callback)
+ [-0.0021659838088561004, -0.005462316236984093, 0.7, -0.001094995519112734, -0.0029946780624175644, 0.7, -0.0005920726738234917, -0.0016630027332406104, 0.7, 0.0007264876839320953  …  0.32339181286549706, -0.002445583550959626, -0.016317015455508944, 0.31754385964912274, -0.0016212354480480975, -0.013528910892895053, 0.31169590643274847, -0.002396885241065678, -0.015332363345197464, 0.30584795321637426]
+ [-0.0024946509575851233, -0.0084743050248458, 0.7, -0.0018211108261936442, -0.008025725779320278, 0.7, -0.0012193167641073581, -0.006688548166333666, 0.7, -0.00043839507595223084  …  0.32339181286549706, -0.002180430239348519, -0.01590186318296433, 0.31754385964912274, -0.0019262159652891774, -0.013401193628169689, 0.31169590643274847, -0.002232448416912339, -0.014629354103318216, 0.30584795321637426]
+ [-0.0018597237172830337, -0.008785908167303248, 0.7, -0.002108029863372081, -0.009851920630150779, 0.7, -0.002009838115979129, -0.009018710861238729, 0.7, -0.0018764289682747922  …  0.32339181286549706, -0.0014174867196701073, -0.00995515983630038, 0.31754385964912274, -0.0019200772426444456, -0.012904053282721581, 0.31169590643274847, -0.0015113103521349474, -0.013907495809161828, 0.30584795321637426]
+ [-0.0011382887415978525, -0.006526240914208616, 0.7, -0.00197556375734427, -0.007603373094278387, 0.7, -0.002386647597983837, -0.00816566395304658, 0.7, -0.002708923707548109  …  0.32339181286549706, -0.00034409204632861916, -0.004613565382136222, 0.31754385964912274, -0.001150846246748621, -0.011431378783413654, 0.31169590643274847, -0.0008995601062787052, -0.012874967436299362, 0.30584795321637426]
+ [-0.0008547943895035529, -0.0035873298420345387, 0.7, -0.0015148921303084792, -0.003843847009732438, 0.7, -0.0019284466945888887, -0.005644129387757395, 0.7, -0.0023946513342133087  …  0.32339181286549706, 0.00048076743678616995, -0.003265547193722709, 0.31754385964912274, -0.00013500790692120215, -0.007808778243089925, 0.31169590643274847, -0.0006613057774831114, -0.009496236940962929, 0.30584795321637426]
+ [-0.0007911392786587085, -0.001739356955529783, 0.7, -0.0009192247258541631, -0.0016012733935531107, 0.7, -0.0009360248152808343, -0.0034159764533118787, 0.7, -0.0013305081833949845  …  0.32339181286549706, 0.0007042413951192331, -0.0032091589879662194, 0.31754385964912274, 0.00036098704059875846, -0.002724084533864268, 0.31169590643274847, -0.0005197291955477037, -0.004146557210079549, 0.30584795321637426]
+ [-0.0005009119017044855, -0.0010643539943988355, 0.7, -0.0003997104601284641, -0.0013829707632916784, 0.7, -0.00013392608631431288, -0.0022067354929193777, 0.7, -0.00041367937266736314  …  0.32339181286549706, 0.0005317240886544872, -0.0007458554006874356, 0.31754385964912274, 0.0002918660500146939, 0.0014385389505501853, 0.31169590643274847, -0.00014667287237832502, 0.000499635832292766, 0.30584795321637426]
+ [7.877033748192985e-5, -0.000421123639625422, 0.7, -5.0759247674148775e-5, -0.0013861889826008653, 0.7, 8.248268091041952e-5, -0.0013829603946880502, 0.7, -0.00014394433252072245  …  0.32339181286549706, 0.0004509502003486085, 0.0034010197767588668, 0.31754385964912274, 0.0002098810724059527, 0.0030986111294803113, 0.31169590643274847, 0.0003882810307982635, 0.0027368433078829644, 0.30584795321637426]
+ [0.0006041217258656232, 0.0008950650498073326, 0.7, 0.0001807892600773303, -7.445962324119322e-5, 0.7, -2.4516528465226556e-5, -0.0001493914009533822, 0.7, -0.0002513925977371086  …  0.32339181286549706, 0.0006585897415157567, 0.0056799234308563176, 0.31754385964912274, 0.0004319778826393965, 0.003066796203846808, 0.31169590643274847, 0.0007320680612230762, 0.0033111405751278435, 0.30584795321637426]

When you use both, an AnalysisCallback and a RelaxationCallback, note that the relaxation_callback needs to come first inside the CallbackSet as it needs to be invoked prior to the analysis_callback, such that the analysis_callback analyzes the solution with the already updated values.

Plotting the analysis_callback again, we can see that now also the entropy is conserved up to machine precision.

plot(analysis_callback)
 savefig("analysis_callback_relaxation.png")
"/home/runner/work/DispersiveShallowWater.jl/DispersiveShallowWater.jl/docs/build/analysis_callback_relaxation.png"

Customize solver

In the semidiscretization created above, we used the default SBP operators, which are periodic finite difference operators. Using different SBP operators for the semidiscretization can be done leveraging SummationByPartsOperators.jl, which needs to be imported first:

using SummationByPartsOperators: legendre_derivative_operator, UniformPeriodicMesh1D, couple_discontinuously, PeriodicUpwindOperators

As an example, let us create a semidiscretization based on discontinuous Galerkin (DG) upwind operators. A semidiscretization implemented in DispersiveShallowWater.jl needs one first-derivative and one second-derivative SBP operator. To build the first-derivative operator, we first create a LegendreDerivativeOperator with polynomial degree 3 on a reference element [-1.0, 1.0] and a UniformPeriodicMesh1D for the coupling.

mesh = Mesh1D(coordinates_min, coordinates_max, N)
 accuracy_order = 4
 D_legendre = legendre_derivative_operator(-1.0, 1.0, accuracy_order)
@@ -176,7 +177,8 @@
     mesh: Mesh1D{Float64} with length 512
     equations: BBMBBMVariableEquations1D
     initial condition: initial_condition_shoaling
-    boundary condition: boundary_condition_periodic

As before, we can run the simulation by

analysis_callback = AnalysisCallback(semi; interval = 10,
+    boundary condition: boundary_condition_periodic
+    source terms: nothing

As before, we can run the simulation by

analysis_callback = AnalysisCallback(semi; interval = 10,
                                      extra_analysis_errors = (:conservation_error,),
                                      extra_analysis_integrals = (waterheight_total,
                                                                  velocity, entropy),
@@ -188,4 +190,4 @@
 anim = @animate for step in 1:length(sol.u)
     plot(semi => sol, plot_initial = true, conversion = waterheight_total, step = step, xlim = (-50, 20), ylims = [(-0.8, 0.1)])
 end
-gif(anim, "shoaling_solution_dg.gif", fps = 25)
Example block output

For more details see also the documentation of SummationByPartsOperators.jl

Additional resources

Some more examples sorted by the simulated equations can be found in the examples/ subdirectory. Especially, in examples/svaerd_kalisch_1d/ you can find Julia scripts that solve the SvaerdKalischEquations1D that were not covered in this tutorial. The same steps as described above, however, apply in the same way to these equations. Attention must be paid for these equations because they do not conserve the classical total entropy $\mathcal E$, but a modified entropy $\hat{\mathcal E}$, available as entropy_modified.

More examples, especially focussing on plotting, can be found in the scripts create_figures.jl and plot_examples.jl.

References

+gif(anim, "shoaling_solution_dg.gif", fps = 25)Example block output

For more details see also the documentation of SummationByPartsOperators.jl

Additional resources

Some more examples sorted by the simulated equations can be found in the examples/ subdirectory. Especially, in examples/svaerd_kalisch_1d/ you can find Julia scripts that solve the SvaerdKalischEquations1D that were not covered in this tutorial. The same steps as described above, however, apply in the same way to these equations. Attention must be paid for these equations because they do not conserve the classical total entropy $\mathcal E$, but a modified entropy $\hat{\mathcal E}$, available as entropy_modified.

More examples, especially focussing on plotting, can be found in the scripts create_figures.jl and plot_examples.jl.

References

diff --git a/dev/ref/index.html b/dev/ref/index.html index 13613be1..a0923ce6 100644 --- a/dev/ref/index.html +++ b/dev/ref/index.html @@ -1,28 +1,29 @@ -Reference · DispersiveShallowWater.jl

DispersiveShallowWater.jl API

DispersiveShallowWater.AbstractEquations — Type
AbstractEquations{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.

source
DispersiveShallowWater.AnalysisCallback — Type
AnalysisCallback(semi; interval=0,
+Reference · DispersiveShallowWater.jl
DispersiveShallowWater.jl API
DispersiveShallowWater.AbstractEquations — Type
AbstractEquations{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.
source
DispersiveShallowWater.AnalysisCallback — Type
AnalysisCallback(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.
source
DispersiveShallowWater.BBMBBMEquations1D — Type
BBMBBMEquations1D(gravity, D)
BBM-BBM (Benjamin–Bona–Mahony) system in one spatial dimension. The equations are given by
\[\begin{aligned}
+                       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.

source
DispersiveShallowWater.BBMBBMEquations1D — Type
BBMBBMEquations1D(gravity, D)

BBM-BBM (Benjamin–Bona–Mahony) system in one spatial dimension. The equations 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 = -D$. The water height above the bathymetry is therefore given by $h = \eta + D$.

One reference for the BBM-BBM system can be found in

source
DispersiveShallowWater.BBMBBMVariableEquations1D — Type
BBMBBMVariableEquations1D(gravity, eta0 = 1.0)

BBM-BBM (Benjamin–Bona–Mahony) system in one spatial dimension with spatially varying bathymetry. The equations are given by

\[\begin{aligned} +\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 = -D$. The water height above the bathymetry is therefore given by $h = \eta + D$.

One reference for the BBM-BBM system can be found in

source
DispersiveShallowWater.BBMBBMVariableEquations1D — Type
BBMBBMVariableEquations1D(gravity, eta0 = 1.0)

BBM-BBM (Benjamin–Bona–Mahony) system in one spatial dimension with spatially varying bathymetry. The equations are given by

\[\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}\]

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 bottom topography (bathymetry) $b = -D$. The water height above the bathymetry is therefore given by $h = \eta + D$.

One reference for the BBM-BBM system with spatially varying bathymetry can be found in

  • Samer Israwi, Henrik Kalisch, Theodoros Katsaounis, Dimitrios Mitsotakis (2022) A regularized shallow-water waves system with slip-wall boundary conditions in a basin: theory and numerical analysis DOI: 10.1088/1361-6544/ac3c29
source
DispersiveShallowWater.RelaxationCallback — Type
RelaxationCallback(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
source
DispersiveShallowWater.Semidiscretization — Method
Semidiscretization(mesh, equations, initial_condition, solver;
+\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 bottom topography (bathymetry) $b = -D$. The water height above the bathymetry is therefore given by $h = \eta + D$.
One reference for the BBM-BBM system with spatially varying bathymetry can be found in
  • Samer Israwi, Henrik Kalisch, Theodoros Katsaounis, Dimitrios Mitsotakis (2022) A regularized shallow-water waves system with slip-wall boundary conditions in a basin: theory and numerical analysis DOI: 10.1088/1361-6544/ac3c29
source
DispersiveShallowWater.RelaxationCallback — Type
RelaxationCallback(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
source
DispersiveShallowWater.Semidiscretization — Method
Semidiscretization(mesh, equations, initial_condition, solver;
+                   source_terms=nothing,
                    boundary_conditions=boundary_condition_periodic,
                    RealT=real(solver),
                    uEltype=RealT,
-                   initial_cache=NamedTuple())

Construct a semidiscretization of a PDE.

source
DispersiveShallowWater.Solver — Method
Solver(mesh, accuracy_order)

Create a solver, where the summation by parts (SBP) operators are of order accuracy_order and associated to the mesh.

source
DispersiveShallowWater.Solver — Method
Solver(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. Both summation by parts operators should be associated with the same grid.

source
DispersiveShallowWater.SvaerdKalischEquations1D — Type
SvärdKalischEquations1D(gravity, eta0 = 1.0, alpha = 0.0, beta = 0.2308939393939394, gamma = 0.04034343434343434)

Dispersive system by Svärd and Kalisch in one spatial dimension with spatially varying bathymetry. The equations are given in conservative variables by

\[\begin{aligned} + initial_cache=NamedTuple())

Construct a semidiscretization of a PDE.

source
DispersiveShallowWater.Solver — Method
Solver(mesh, accuracy_order)

Create a solver, where the summation by parts (SBP) operators are of order accuracy_order and associated to the mesh.

source
DispersiveShallowWater.Solver — Method
Solver(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. Both summation by parts operators should be associated with the same grid.

source
DispersiveShallowWater.SvaerdKalischEquations1D — Type
SvärdKalischEquations1D(gravity, eta0 = 1.0, alpha = 0.0, beta = 0.2308939393939394, gamma = 0.04034343434343434)

Dispersive system by Svärd and Kalisch in one spatial dimension with spatially varying bathymetry. The equations 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 = -D$. The water height above the bathymetry is therefore given by $h = \eta + D$.

The equations by Svärd and Kalisch are presented and analyzed in

  • Magnus Svärd, Henrik Kalisch (2023) A novel energy-bounded Boussinesq model and a well-balanced and stable numerical discretization arXiv: 2302.09924
source
DispersiveShallowWater.cons2prim — Function
cons2prim(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.

source
DispersiveShallowWater.convergence_test — Method
convergence_test([mod::Module=Main,] example::AbstractString, iterations; kwargs...)

Run iterations simulations using the setup given in example and compute the experimental order of convergence (EOC) in the $L^2$ and $L^\infty$ norm. In each iteration, the resolution of the respective mesh will be doubled. Additional keyword arguments kwargs... and the optional module mod are passed directly to trixi_include.

Adjusted from Trixi.jl.

source
DispersiveShallowWater.eachvariable — Method
eachvariable(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.

source
DispersiveShallowWater.energy_total — Function
energy_total(q, equations)

Return the total energy 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).

source
DispersiveShallowWater.energy_total_modified — Method
energy_total_modified(q, equations::SvaerdKalischEquations1D, cache)

Return the modified total energy of the primitive variables q for the SvaerdKalischEquations1D. It contains an additional term containing a derivative compared to the usual energy_total. The energy_total_modified is a conserved quantity of the Svärd-Kalisch equations.

q is a vector of the primitive variables at ALL nodes, i.e., a matrix of the correct length nvariables(equations) as first dimension and the number of nodes as length of the second dimension. cache needs to hold the first-derivative SBP operator D1.

source
DispersiveShallowWater.entropy — Function
entropy(q, equations)

Return the entropy 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).

source
DispersiveShallowWater.errors — Method
errors(analysis_callback)

Return the computed errors for each timestep as a named tuple. The shape of each entry is (nvariables, ntimesteps).

source
DispersiveShallowWater.examples_dir — Method
examples_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())
source
DispersiveShallowWater.get_name — Method
get_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"
source
DispersiveShallowWater.initial_condition_dingemans — Method
initial_condition_dingemans(x, t, equations::BBMBBMVariableEquations1D, 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.

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
source
DispersiveShallowWater.initial_condition_dingemans — Method
initial_condition_dingemans(x, t, equations::SvaerdKalischEquations1D, 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
source
DispersiveShallowWater.momentum — Method
momentum(q, equations)

Return the momentum 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).

source
DispersiveShallowWater.path_create_figures — Method
path_create_figures()

Return the path to the file that creates all figures used in the master thesis "Structure-preserving Numerical Methods for Dispersive Shallow Water Model" (2023). Executing this julia script may take a while.

Examples

include(DispersiveShallowWater.path_create_figures())
source
DispersiveShallowWater.prim2cons — Function
prim2cons(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.

source
DispersiveShallowWater.trixi_include — Method
trixi_include([mod::Module=Main,] example::AbstractString; kwargs...)

include the file example and evaluate its content in the global scope of module mod. You can override specific assignments in example by supplying keyword arguments. It's basic purpose is to make it easier to modify some parameters while running DispersiveShallowWater from the REPL. Additionally, this is used in tests to reduce the computational burden for CI while still providing examples with sensible default values for users.

Before replacing assignments in example, the keyword argument maxiters is inserted into calls to solve and DispersiveShallowWater.solve with it's default value used in the SciML ecosystem for ODEs, see the "Miscellaneous" section of the documentation.

Copied from Trixi.jl.

Examples

julia> redirect_stdout(devnull) do
+\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 = -D$. The water height above the bathymetry is therefore given by $h = \eta + D$.
The equations by Svärd and Kalisch are presented and analyzed in
  • Magnus Svärd, Henrik Kalisch (2023) A novel energy-bounded Boussinesq model and a well-balanced and stable numerical discretization arXiv: 2302.09924
source
DispersiveShallowWater.cons2prim — Function
cons2prim(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.

source
DispersiveShallowWater.convergence_test — Method
convergence_test([mod::Module=Main,] example::AbstractString, iterations; kwargs...)

Run iterations simulations using the setup given in example and compute the experimental order of convergence (EOC) in the $L^2$ and $L^\infty$ norm. In each iteration, the resolution of the respective mesh will be doubled. Additional keyword arguments kwargs... and the optional module mod are passed directly to trixi_include.

Adjusted from Trixi.jl.

source
DispersiveShallowWater.eachvariable — Method
eachvariable(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.

source
DispersiveShallowWater.energy_total — Function
energy_total(q, equations)

Return the total energy 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).

source
DispersiveShallowWater.energy_total_modified — Method
energy_total_modified(q, equations::SvaerdKalischEquations1D, cache)

Return the modified total energy of the primitive variables q for the SvaerdKalischEquations1D. It contains an additional term containing a derivative compared to the usual energy_total. The energy_total_modified is a conserved quantity of the Svärd-Kalisch equations.

q is a vector of the primitive variables at ALL nodes, i.e., a matrix of the correct length nvariables(equations) as first dimension and the number of nodes as length of the second dimension. cache needs to hold the first-derivative SBP operator D1.

source
DispersiveShallowWater.entropy — Function
entropy(q, equations)

Return the entropy 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).

source
DispersiveShallowWater.errors — Method
errors(analysis_callback)

Return the computed errors for each timestep as a named tuple. The shape of each entry is (nvariables, ntimesteps).

source
DispersiveShallowWater.examples_dir — Method
examples_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())
source
DispersiveShallowWater.get_name — Method
get_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"
source
DispersiveShallowWater.initial_condition_dingemans — Method
initial_condition_dingemans(x, t, equations::BBMBBMVariableEquations1D, 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.

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
source
DispersiveShallowWater.initial_condition_dingemans — Method
initial_condition_dingemans(x, t, equations::SvaerdKalischEquations1D, 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
source
DispersiveShallowWater.momentum — Method
momentum(q, equations)

Return the momentum 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).

source
DispersiveShallowWater.path_create_figures — Method
path_create_figures()

Return the path to the file that creates all figures used in the master thesis "Structure-preserving Numerical Methods for Dispersive Shallow Water Model" (2023). Executing this julia script may take a while.

Examples

include(DispersiveShallowWater.path_create_figures())
source
DispersiveShallowWater.prim2cons — Function
prim2cons(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.

source
DispersiveShallowWater.trixi_include — Method
trixi_include([mod::Module=Main,] example::AbstractString; kwargs...)

include the file example and evaluate its content in the global scope of module mod. You can override specific assignments in example by supplying keyword arguments. It's basic purpose is to make it easier to modify some parameters while running DispersiveShallowWater from the REPL. Additionally, this is used in tests to reduce the computational burden for CI while still providing examples with sensible default values for users.

Before replacing assignments in example, the keyword argument maxiters is inserted into calls to solve and DispersiveShallowWater.solve with it's default value used in the SciML ecosystem for ODEs, see the "Miscellaneous" section of the documentation.

Copied from Trixi.jl.

Examples

julia> redirect_stdout(devnull) do
            trixi_include(@__MODULE__, joinpath(examples_dir(), "bbm_bbm_1d", "bbm_bbm_1d_basic.jl"),
                          tspan=(0.0, 0.1))
            sol.t[end]
        end
-0.1
source
DispersiveShallowWater.varnames — Function
varnames(conversion_function, equations)

Return the list of variable names when applying conversion_function to the conserved variables associated to equations. Common choices of the conversion_function are prim2prim and prim2cons.

source
DispersiveShallowWater.velocity — Function
velocity(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).

source
DispersiveShallowWater.waterheight — Function
waterheight(q, equations)

Return the waterheight of the primitive variables q for a given set of equations, i.e. the waterheight above the bathymetry.

q is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations).

source
DispersiveShallowWater.waterheight_total — Function
waterheight_total(q, equations)

Return the total waterheight of the primitive variables q for a given set of equations, i.e. the waterheight plus the bathymetry.

q is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations).

source
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

Internal use only

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.

source
+0.1source
DispersiveShallowWater.tstops — Method
tstops(analysis_callback)

Return the time values that correspond to the saved values of the errors and integrals.

source
DispersiveShallowWater.varnames — Function
varnames(conversion_function, equations)

Return the list of variable names when applying conversion_function to the conserved variables associated to equations. Common choices of the conversion_function are prim2prim and prim2cons.

source
DispersiveShallowWater.velocity — Function
velocity(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).

source
DispersiveShallowWater.waterheight — Function
waterheight(q, equations)

Return the waterheight of the primitive variables q for a given set of equations, i.e. the waterheight above the bathymetry.

q is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations).

source
DispersiveShallowWater.waterheight_total — Function
waterheight_total(q, equations)

Return the total waterheight of the primitive variables q for a given set of equations, i.e. the waterheight plus the bathymetry.

q is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations).

source
SummationByPartsOperators.grid — Method
grid(semi)

Get the grid of a semidiscretization.

source
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

Internal use only

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.

source
diff --git a/dev/reproduce/index.html b/dev/reproduce/index.html index 0d3f1b96..82c9b8dc 100644 --- a/dev/reproduce/index.html +++ b/dev/reproduce/index.html @@ -1,4 +1,4 @@ Reproduce figures · DispersiveShallowWater.jl

How to reproduce the figures

In order to reproduce all figures used in the master thesis "Structure-Preserving Numerical Methods for Dispersive Shallow Water Models" (2023) by Joshua Lampert execute the file located at the path DispersiveShallowWater.path_create_figures(). From the Julia REPL, this can be done by:

julia> using DispersiveShallowWater
 julia> include(DispersiveShallowWater.path_create_figures())

Note that for one figure Trixi.jl is needed, so download Trixi.jl first:

julia> using Pkg
-julia> Pkg.add("Trixi")

Executing the script may take a while. It will generate a folder out/ with certain subfolders containing the figures. If you want to modify the plots or only produce a subset of plots, you can download the script create_figures.jl, modify it accordingly and run it by:

julia> include("create_figures.jl")
+julia> Pkg.add("Trixi")

Executing the script may take a while. It will generate a folder out/ with certain subfolders containing the figures. If you want to modify the plots or only produce a subset of plots, you can download the script create_figures.jl, modify it accordingly and run it by:

julia> include("create_figures.jl")
diff --git a/dev/search_index.js b/dev/search_index.js index cfa5682c..d66fadce 100644 --- a/dev/search_index.js +++ b/dev/search_index.js @@ -1,3 +1,3 @@ var documenterSearchIndex = {"docs": -[{"location":"license/#License","page":"License","title":"License","text":"","category":"section"},{"location":"license/","page":"License","title":"License","text":"MIT License","category":"page"},{"location":"license/","page":"License","title":"License","text":"Copyright (c) 2023-present Joshua Lampert ","category":"page"},{"location":"license/","page":"License","title":"License","text":"Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:","category":"page"},{"location":"license/","page":"License","title":"License","text":"The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.","category":"page"},{"location":"license/","page":"License","title":"License","text":"THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.","category":"page"},{"location":"reproduce/#How-to-reproduce-the-figures","page":"Reproduce figures","title":"How to reproduce the figures","text":"","category":"section"},{"location":"reproduce/","page":"Reproduce figures","title":"Reproduce figures","text":"In order to reproduce all figures used in the master thesis \"Structure-Preserving Numerical Methods for Dispersive Shallow Water Models\" (2023) by Joshua Lampert execute the file located at the path DispersiveShallowWater.path_create_figures(). From the Julia REPL, this can be done by:","category":"page"},{"location":"reproduce/","page":"Reproduce figures","title":"Reproduce figures","text":"julia> using DispersiveShallowWater\njulia> include(DispersiveShallowWater.path_create_figures())","category":"page"},{"location":"reproduce/","page":"Reproduce figures","title":"Reproduce figures","text":"Note that for one figure Trixi.jl is needed, so download Trixi.jl first:","category":"page"},{"location":"reproduce/","page":"Reproduce figures","title":"Reproduce figures","text":"julia> using Pkg\njulia> Pkg.add(\"Trixi\")","category":"page"},{"location":"reproduce/","page":"Reproduce figures","title":"Reproduce figures","text":"Executing the script may take a while. It will generate a folder out/ with certain subfolders containing the figures. If you want to modify the plots or only produce a subset of plots, you can download the script create_figures.jl, modify it accordingly and run it by:","category":"page"},{"location":"reproduce/","page":"Reproduce figures","title":"Reproduce figures","text":"julia> include(\"create_figures.jl\")","category":"page"},{"location":"overview/#Running-a-simulation","page":"Overview","title":"Running a simulation","text":"","category":"section"},{"location":"overview/#Introduction","page":"Overview","title":"Introduction","text":"","category":"section"},{"location":"overview/","page":"Overview","title":"Overview","text":"In this tutorial we describe how to numerically solve the BBM-BBM (Benjamin-Bona-Mahony) equations with variable bottom topography in one dimension, which has been proposed in [IsrawiKalischKatsaounisMitsotakis2021] for two spatial dimensions. The equations describe a dispersive shallow water model, i.e. they extend the well-known shallow water equations in the sense that dispersion is modeled. The shallow water equations are a system of first order hyperbolic partial differential equations that can be written in the form of a balance law. In contrast, the BBM-BBM equations additionally include third-order mixed derivatives. In primitive variables q = (eta v) they can be written as:","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"beginaligned\n eta_t + ((eta + D)v)_x - frac16(D^2eta_xt)_x = 0\n v_t + geta_x + left(frac12v^2right)_x - frac16(D^2v_t)_xx = 0\nendaligned","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"Here, eta = h + b describes the total water height, h the water height above the bottom topography (bathymetry), b = -D the bathymetry and v the velocity in horizontal direction. The gravitational acceleration is denoted as g. A sketch of the water height and the bathymetry can be found below.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"(Image: )","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"In order to conduct a numerical simulation with DispersiveShallowWater.jl, we perform the following steps.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"First, we load the necessary libraries:","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"using DispersiveShallowWater, OrdinaryDiffEq","category":"page"},{"location":"overview/#Define-physical-setup","page":"Overview","title":"Define physical setup","text":"","category":"section"},{"location":"overview/","page":"Overview","title":"Overview","text":"As a first step of a numerical simulation, we define the physical setup we want to solve. This includes the set of equations, potentially including physical parameters, initial and boundary conditions as well as the domain. In the following example, the initial condition describes a travelling wave that moves towards a beach, which is modeled by a linearly increasing bathymetry.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"equations = BBMBBMVariableEquations1D(gravity_constant = 9.81)\n\nfunction initial_condition_shoaling(x, t, equations::BBMBBMVariableEquations1D, mesh)\n A = 0.07 # amplitude of wave\n x0 = -30 # initial center\n eta = A * exp(-0.1*(x - x0)^2)\n v = 0\n D = x <= 0.0 ? 0.7 : 0.7 - 1/50 * x\n return SVector(eta, v, D)\nend\n\ninitial_condition = initial_condition_shoaling\nboundary_conditions = boundary_condition_periodic\n\ncoordinates_min = -130.0\ncoordinates_max = 20.0\nN = 512\nmesh = Mesh1D(coordinates_min, coordinates_max, N + 1)","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"The first line specifies that we want to solve the BBM-BBM equations with variable bathymetry using a gravitational acceleration g = 981. Afterwards, we define the initial condition, which is described as a function with the spatial variable x, the time t, the equations and a mesh as parameters. If an analytical solution is available, the time variable t can be used, and the initial condition can serve as an analytical solution to be compared with the numerical solution. Otherwise, you can just keep the time variable unused. An initial condition in DispersiveShallowWater.jl is supposed to return an SVector holding the values for each of the unknown variables. Since the bathymetry is treated as a variable (with time derivative 0) for convenience, we need to provide the value for the primitive variables eta and v as well as for D.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"Next, we choose periodic boundary conditions since, up to now, DispersiveShallowWater.jl only provides support for this type of boundary conditions. Lastly, we define the physical domain as the interval from -130 to 20 and we choose 512 intermediate nodes. The mesh is homogeneous, i.e. the distance between each two nodes is constant. We choose the left boundary very far to the left in order to avoid an interaction of the left- and right-travelling waves.","category":"page"},{"location":"overview/#Define-numerical-solver","page":"Overview","title":"Define numerical solver","text":"","category":"section"},{"location":"overview/","page":"Overview","title":"Overview","text":"In the next step, we build a Semidiscretization that bundles all ingredients for the spatial discretization of the model. Especially, we need to define a Solver. The simplest way to define a solver is to call the constructor by providing the mesh and a desired order of accuracy. In the following example, we use an accuracy order of 4. The default constructor simply creates periodic first- and second-derivative central finite difference summation by parts operators of the provided order of accuracy. How to use other summation by parts operators, is described in the section on how to customize the solver.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"solver = Solver(mesh, 4)\n\nsemi = Semidiscretization(mesh, equations, initial_condition, solver, boundary_conditions = boundary_conditions)","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"Finally, we put the mesh, the equations, the initial_condition, the solver and the boundary_conditions together in a semidiscretization semi.","category":"page"},{"location":"overview/#Solve-system-of-ordinary-differential-equations","page":"Overview","title":"Solve system of ordinary differential equations","text":"","category":"section"},{"location":"overview/","page":"Overview","title":"Overview","text":"Once we have obtained a semidiscretization, we can solve the resulting system of ordinary differential equations. To do so, we specify the time interval that we want to simulate and obtain an ODEProblem from the SciML ecosystem for ordinary differential equations by calling semidiscretize on the semidiscretization and the time span. Additionally, we can analyze the numerical solution using an AnalysisCallback. The analysis includes computing the L^2 error and L^infty error of the different solution's variables compared to the initial condition (or, if available, at the same time analytical solution). Additional errors can be passed by the keyword argument extra_analysis_errors. Additional integral quantities that should be analyzed can be passed by keyword argument extra_analysis_integrals. In this example we pass the conservation_error, which computes the temporal change of the total amount (i.e. integral) of the different variables over time. In addition, the integrals of the total waterheight eta waterheight_total, the velocity and the entropy are computed and saved for each time step. The total waterheight and the total velocity are linear invariants of the BBM-BBM equations, i.e. they do not change over time. The total entropy","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"mathcal E(t eta v) = frac12int_Omega geta^2 + (eta + D)v^2textrmdx","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"is a nonlinear invariant and should be constant over time as well. During the simulation, the AnalysisCallback will print the results to the terminal.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"Finally, the ode can be solved using the interface from OrdinaryDiffEq.jl. This means, we can specify a time-stepping scheme we want to use the tolerances for the adaptive time-stepping and the time values, where the solution values should be saved. In this case, we use the adaptive explicit Runge-Kutta method Tsit5 by Tsitouras of order 5(4). Here, we save the solution at 100 equidistant points.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"tspan = (0.0, 25.0)\node = semidiscretize(semi, tspan)\nanalysis_callback = AnalysisCallback(semi; interval = 10,\n extra_analysis_errors = (:conservation_error,),\n extra_analysis_integrals = (waterheight_total,\n velocity, entropy),\n io = devnull)\ncallbacks = CallbackSet(analysis_callback)\n\nsaveat = range(tspan..., length = 100)\nsol = solve(ode, Tsit5(), abstol = 1e-7, reltol = 1e-7,\n save_everystep = false, callback = callbacks, saveat = saveat)","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"After solving the equations, sol contains the solution for each of the three variables at every spatial point for each of the 100 points in time. The errors and integrals recorded by the AnalysisCallback can be obtained as NamedTuples by errors(analysis_callback) and integrals(analysis_callback).","category":"page"},{"location":"overview/#visualize_results","page":"Overview","title":"Visualize results","text":"","category":"section"},{"location":"overview/","page":"Overview","title":"Overview","text":"After running the simulation, the results can be visualized using Plots.jl, which needs to be imported first. Then, we can plot the solution at the final time by calling plot on a Pair of the Semidiscretization and the corresponding ODESolution sol. The result is depicted in the following picture.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"using Plots\n\nplot(semi => sol)\nsavefig(\"shoaling_solution.png\")","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"(Image: )","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"By default, this will plot the bathymetry, but not the initial (analytical) solution. You can adjust this by passing the boolean values plot_bathymetry (if true always plot to first subplot) and plot_initial. You can also provide a conversion function that converts the solution. A conversion function should take the values of the primitive variables q at one node, and the equations as input and should return an SVector of any length as output. For a user defined conversion function, there should also exist a function varnames(conversion, equations) that returns a Tuple of the variable names used for labelling. The conversion function can, e.g., be prim2cons or waterheight_total if one only wants to plot the total waterheight. The resulting plot will have one subplot for each of the returned variables of the conversion variable. By default, the conversion function is just prim2prim, i.e. the identity.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"Plotting an animation over time can, e.g., be done by the following command, which uses step to plot the solution at a specific time step.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"anim = @animate for step in 1:length(sol.u)\n plot(semi => sol, plot_initial = true, conversion = waterheight_total, step = step, xlim = (-50, 20), ylims = [(-0.8, 0.1)])\nend\ngif(anim, \"shoaling_solution.gif\", fps = 25)","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"It is also possible to plot the solution variables at a fixed spatial point over time by calling plot(semi => sol, x) for some x-value, see plot_examples.jl for some examples.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"Often, it is interesting to have a look at how the quantities that are recorded by the AnalysisCallback evolve in time. To this end, you can plot the AnalysisCallback by","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"plot(analysis_callback)\nsavefig(\"analysis_callback.png\")","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"This creates the following figure:","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"(Image: )","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"You can see that the linear invariants int_Omegaetatextrmdx and int_Omega vtextrmdx are indeed conserved exactly. The entropy, however, starts growing at around t = 17 and rises up to approximately 5e-5. This is because of the fact that, during the time integration, a nonlinear invariant is not necessarily conserved, even if the semidiscretization conserves the quantity exactly. How to obtain a fully-discrete structure-preserving numerical scheme is explained in the following section.","category":"page"},{"location":"overview/#Use-entropy-conserving-time-integration","page":"Overview","title":"Use entropy-conserving time integration","text":"","category":"section"},{"location":"overview/","page":"Overview","title":"Overview","text":"To obtain entropy-conserving time-stepping schemes DispersiveShallowWater.jl uses the relaxation method introduced in [Ketcheson2019] and further developed in [RanochaSayyariDalcinParsaniKetcheson2020]. The relaxation method is implemented as a RelaxationCallback, which takes a function representing the conserved quantity as the keyword argument invariant. Therefore, we can run the same example as above, but using relaxation on the entropy by simply adding another callback to the CallbackSet:","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"analysis_callback = AnalysisCallback(semi; interval = 10,\n extra_analysis_errors = (:conservation_error,),\n extra_analysis_integrals = (waterheight_total,\n velocity, entropy),\n io = devnull)\nrelaxation_callback = RelaxationCallback(invariant = entropy)\ncallbacks = CallbackSet(relaxation_callback, analysis_callback)\nsol = solve(ode, Tsit5(), abstol = 1e-7, reltol = 1e-7,\n save_everystep = false, callback = callbacks, saveat = saveat)","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"When you use both, an AnalysisCallback and a RelaxationCallback, note that the relaxation_callback needs to come first inside the CallbackSet as it needs to be invoked prior to the analysis_callback, such that the analysis_callback analyzes the solution with the already updated values.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"Plotting the analysis_callback again, we can see that now also the entropy is conserved up to machine precision.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"plot(analysis_callback)\nsavefig(\"analysis_callback_relaxation.png\")","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"(Image: )","category":"page"},{"location":"overview/#customize_solver","page":"Overview","title":"Customize solver","text":"","category":"section"},{"location":"overview/","page":"Overview","title":"Overview","text":"In the semidiscretization created above, we used the default SBP operators, which are periodic finite difference operators. Using different SBP operators for the semidiscretization can be done leveraging SummationByPartsOperators.jl, which needs to be imported first:","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"using SummationByPartsOperators: legendre_derivative_operator, UniformPeriodicMesh1D, couple_discontinuously, PeriodicUpwindOperators","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"As an example, let us create a semidiscretization based on discontinuous Galerkin (DG) upwind operators. A semidiscretization implemented in DispersiveShallowWater.jl needs one first-derivative and one second-derivative SBP operator. To build the first-derivative operator, we first create a LegendreDerivativeOperator with polynomial degree 3 on a reference element [-1.0, 1.0] and a UniformPeriodicMesh1D for the coupling.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"mesh = Mesh1D(coordinates_min, coordinates_max, N)\naccuracy_order = 4\nD_legendre = legendre_derivative_operator(-1.0, 1.0, accuracy_order)\nuniform_mesh = UniformPeriodicMesh1D(mesh.xmin, mesh.xmax, div(mesh.N, accuracy_order))","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"Upwind DG operators in negative, central and positive operators can be obtained by couple_discontinuously","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"central = couple_discontinuously(D_legendre, uniform_mesh)\nminus = couple_discontinuously(D_legendre, uniform_mesh, Val(:minus))\nplus = couple_discontinuously(D_legendre, uniform_mesh, Val(:plus))\nD1 = PeriodicUpwindOperators(minus, central, plus)","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"In order to still have an entropy-conserving semidiscretization the second-derivative SBP operator needs to be","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"using SparseArrays: sparse\nD2 = sparse(plus) * sparse(minus)","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"The Solver object can now be created by passing the two SBP operators to the constructor, which, in turn, can be used to construct a Semidiscretization:","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"solver = Solver(D1, D2)\nsemi = Semidiscretization(mesh, equations, initial_condition, solver, boundary_conditions = boundary_conditions)","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"As before, we can run the simulation by","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"analysis_callback = AnalysisCallback(semi; interval = 10,\n extra_analysis_errors = (:conservation_error,),\n extra_analysis_integrals = (waterheight_total,\n velocity, entropy),\n io = devnull)\nrelaxation_callback = RelaxationCallback(invariant = entropy)\ncallbacks = CallbackSet(relaxation_callback, analysis_callback)\nsol = solve(ode, Tsit5(), abstol = 1e-7, reltol = 1e-7,\n save_everystep = false, callback = callbacks, saveat = saveat)\nanim = @animate for step in 1:length(sol.u)\n plot(semi => sol, plot_initial = true, conversion = waterheight_total, step = step, xlim = (-50, 20), ylims = [(-0.8, 0.1)])\nend\ngif(anim, \"shoaling_solution_dg.gif\", fps = 25)","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"For more details see also the documentation of SummationByPartsOperators.jl","category":"page"},{"location":"overview/#Additional-resources","page":"Overview","title":"Additional resources","text":"","category":"section"},{"location":"overview/","page":"Overview","title":"Overview","text":"Some more examples sorted by the simulated equations can be found in the examples/ subdirectory. Especially, in examples/svaerd_kalisch_1d/ you can find Julia scripts that solve the SvaerdKalischEquations1D that were not covered in this tutorial. The same steps as described above, however, apply in the same way to these equations. Attention must be paid for these equations because they do not conserve the classical total entropy mathcal E, but a modified entropy hatmathcal E, available as entropy_modified.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"More examples, especially focussing on plotting, can be found in the scripts create_figures.jl and plot_examples.jl.","category":"page"},{"location":"overview/#References","page":"Overview","title":"References","text":"","category":"section"},{"location":"overview/","page":"Overview","title":"Overview","text":"[IsrawiKalischKatsaounisMitsotakis2021]: Israwi, Kalisch, Katsaounis, Mitsotakis (2021). A regularized shallow-water waves system with slip-wall boundary conditions in a basin: theory and numerical analysis. DOI: 10.1088/1361-6544/ac3c29","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"[Ketcheson2019]: Ketcheson (2019): Relaxation Runge-Kutta Methods: Conservation and stability for Inner-Product Norms. DOI: 10.1137/19M1263662","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"[RanochaSayyariDalcinParsaniKetcheson2020]: Ranocha, Sayyari, Dalcin, Parsani, Ketcheson (2020): Relaxation Runge–Kutta Methods: Fully-Discrete Explicit Entropy-Stable Schemes for the Compressible Euler and Navier–Stokes Equations DOI: 10.1137/19M1263480","category":"page"},{"location":"ref/#DispersiveShallowWater.jl-API","page":"Reference","title":"DispersiveShallowWater.jl API","text":"","category":"section"},{"location":"ref/","page":"Reference","title":"Reference","text":"CurrentModule = DispersiveShallowWater","category":"page"},{"location":"ref/","page":"Reference","title":"Reference","text":"Modules = [DispersiveShallowWater]","category":"page"},{"location":"ref/#DispersiveShallowWater.boundary_condition_periodic","page":"Reference","title":"DispersiveShallowWater.boundary_condition_periodic","text":"boundary_condition_periodic = DispersiveShallowWater.BoundaryConditionPeriodic()\n\nA singleton struct indicating periodic boundary conditions.\n\n\n\n\n\n","category":"constant"},{"location":"ref/#DispersiveShallowWater.AbstractEquations","page":"Reference","title":"DispersiveShallowWater.AbstractEquations","text":"AbstractEquations{NDIMS, NVARS}\n\nAn 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.\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.AbstractSolver","page":"Reference","title":"DispersiveShallowWater.AbstractSolver","text":"AbstractSolver\n\nAn abstract supertype of specific solvers.\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.AnalysisCallback","page":"Reference","title":"DispersiveShallowWater.AnalysisCallback","text":"AnalysisCallback(semi; interval=0,\n extra_analysis_errors=Symbol[],\n extra_analysis_integrals=(),\n io=stdout)\n\nAnalyze 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,).\n\nFurther 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.\n\nDuring the Simulation, the AnalysisCallback will print information to io.\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.BBMBBMEquations1D","page":"Reference","title":"DispersiveShallowWater.BBMBBMEquations1D","text":"BBMBBMEquations1D(gravity, D)\n\nBBM-BBM (Benjamin–Bona–Mahony) system in one spatial dimension. The equations are given by\n\nbeginaligned\n eta_t + ((eta + D)v)_x - frac16D^2eta_xxt = 0\n v_t + geta_x + left(frac12v^2right)_x - frac16D^2v_xxt = 0\nendaligned\n\nThe 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 = -D. The water height above the bathymetry is therefore given by h = eta + D.\n\nOne reference for the BBM-BBM system can be found in\n\nJerry L. Bona, Min Chen (1998) A Boussinesq system for two-way propagation of nonlinear dispersive waves DOI: 10.1016/S0167-2789(97)00249-2\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.BBMBBMVariableEquations1D","page":"Reference","title":"DispersiveShallowWater.BBMBBMVariableEquations1D","text":"BBMBBMVariableEquations1D(gravity, eta0 = 1.0)\n\nBBM-BBM (Benjamin–Bona–Mahony) system in one spatial dimension with spatially varying bathymetry. The equations are given by\n\nbeginaligned\n eta_t + ((eta + D)v)_x - frac16(D^2eta_xt)_x = 0\n v_t + geta_x + left(frac12v^2right)_x - frac16(D^2v_t)_xx = 0\nendaligned\n\nThe 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 bottom topography (bathymetry) b = -D. The water height above the bathymetry is therefore given by h = eta + D.\n\nOne reference for the BBM-BBM system with spatially varying bathymetry can be found in\n\nSamer Israwi, Henrik Kalisch, Theodoros Katsaounis, Dimitrios Mitsotakis (2022) A regularized shallow-water waves system with slip-wall boundary conditions in a basin: theory and numerical analysis DOI: 10.1088/1361-6544/ac3c29\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.Mesh1D","page":"Reference","title":"DispersiveShallowWater.Mesh1D","text":"Mesh1D\n\nStruct that holds the information for a simple homogeneous one-dimensional mesh.\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.Mesh1D-Tuple{Any, Any, Any}","page":"Reference","title":"DispersiveShallowWater.Mesh1D","text":"Mesh1D(xmin, xmax, N)\n\nCreate a simple homogeneous one-dimensional mesh from xmin to xmax with N nodes.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.RelaxationCallback","page":"Reference","title":"DispersiveShallowWater.RelaxationCallback","text":"RelaxationCallback(invariant)\n\nUse 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.\n\nReference\n\nHendrik 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\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.Semidiscretization","page":"Reference","title":"DispersiveShallowWater.Semidiscretization","text":"Semidiscretization\n\nA struct containing everything needed to describe a spatial semidiscretization of an equation.\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.Semidiscretization-NTuple{4, Any}","page":"Reference","title":"DispersiveShallowWater.Semidiscretization","text":"Semidiscretization(mesh, equations, initial_condition, solver;\n boundary_conditions=boundary_condition_periodic,\n RealT=real(solver),\n uEltype=RealT,\n initial_cache=NamedTuple())\n\nConstruct a semidiscretization of a PDE.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.Solver","page":"Reference","title":"DispersiveShallowWater.Solver","text":"Solver\n\nA struct that holds the summation by parts (SBP) operators that are used for the spatial discretization.\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.Solver-Tuple{Any, Any}","page":"Reference","title":"DispersiveShallowWater.Solver","text":"Solver(mesh, accuracy_order)\n\nCreate a solver, where the summation by parts (SBP) operators are of order accuracy_order and associated to the mesh.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.Solver-Union{Tuple{RealT}, Tuple{SummationByPartsOperators.AbstractDerivativeOperator{RealT}, Union{AbstractMatrix{RealT}, SummationByPartsOperators.AbstractDerivativeOperator{RealT}}}} where RealT","page":"Reference","title":"DispersiveShallowWater.Solver","text":"Solver(D1, D2)\n\nCreate 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. Both summation by parts operators should be associated with the same grid.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.SvaerdKalischEquations1D","page":"Reference","title":"DispersiveShallowWater.SvaerdKalischEquations1D","text":"SvärdKalischEquations1D(gravity, eta0 = 1.0, alpha = 0.0, beta = 0.2308939393939394, gamma = 0.04034343434343434)\n\nDispersive system by Svärd and Kalisch in one spatial dimension with spatially varying bathymetry. The equations are given in conservative variables by\n\nbeginaligned\n h_t + (hv)_x = (hatalpha(hatalpha(h + b)_x)_x)_x\n (hv)_t + (hv^2)_x + gh(h + b)_x = (hatalpha v(hatalpha(h + b)_x)_x)_x + (hatbeta v_x)_xt + frac12(hatgamma v_x)_xx + frac12(hatgamma v_xx)_x\nendaligned\n\nwhere hatalpha^2 = alphasqrtgdd^2, hatbeta = beta d^3, hatgamma = gammasqrtgdd^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\n\nbeginaligned\n eta_t + ((eta + D)v)_x = (hatalpha(hatalphaeta_x)_x)_x\n v_t(eta + D) - v((eta + D)v)_x + ((eta + D)v^2)_x + g(eta + D)eta_x = (hatalpha v(hatalphaeta_x)_x)_x - v(hatalpha(hatalphaeta_x)_x)_x + (hatbeta v_x)_xt + frac12(hatgamma v_x)_xx + frac12(hatgamma v_xx)_x\nendaligned\n\nThe 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 = -D. The water height above the bathymetry is therefore given by h = eta + D.\n\nThe equations by Svärd and Kalisch are presented and analyzed in\n\nMagnus Svärd, Henrik Kalisch (2023) A novel energy-bounded Boussinesq model and a well-balanced and stable numerical discretization arXiv: 2302.09924\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.cons2prim","page":"Reference","title":"DispersiveShallowWater.cons2prim","text":"cons2prim(u, equations)\n\nConvert 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.\n\n\n\n\n\n","category":"function"},{"location":"ref/#DispersiveShallowWater.convergence_test-Tuple{Module, AbstractString, Any}","page":"Reference","title":"DispersiveShallowWater.convergence_test","text":"convergence_test([mod::Module=Main,] example::AbstractString, iterations; kwargs...)\n\nRun iterations simulations using the setup given in example and compute the experimental order of convergence (EOC) in the L^2 and L^infty norm. In each iteration, the resolution of the respective mesh will be doubled. Additional keyword arguments kwargs... and the optional module mod are passed directly to trixi_include.\n\nAdjusted from Trixi.jl.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.default_analysis_errors-Tuple{DispersiveShallowWater.AbstractEquations}","page":"Reference","title":"DispersiveShallowWater.default_analysis_errors","text":"default_analysis_errors(equations)\n\nDefault analysis errors used by the AnalysisCallback.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.default_analysis_integrals-Tuple{DispersiveShallowWater.AbstractEquations}","page":"Reference","title":"DispersiveShallowWater.default_analysis_integrals","text":"default_analysis_integrals(equations)\n\nDefault analysis integrals used by the AnalysisCallback.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.default_example-Tuple{}","page":"Reference","title":"DispersiveShallowWater.default_example","text":"default_example()\n\nReturn the path to an example that can be used to quickly see DispersiveShallowWater.jl in action. See also examples_dir and get_examples.\n\nCopied from Trixi.jl.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.discharge-Tuple{Any, DispersiveShallowWater.AbstractEquations}","page":"Reference","title":"DispersiveShallowWater.discharge","text":"discharge(q, equations)\n\nSee momentum.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.eachvariable-Tuple{DispersiveShallowWater.AbstractEquations}","page":"Reference","title":"DispersiveShallowWater.eachvariable","text":"eachvariable(equations::AbstractEquations)\n\nReturn 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.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.energy_total","page":"Reference","title":"DispersiveShallowWater.energy_total","text":"energy_total(q, equations)\n\nReturn the total energy of the primitive variables q for a given set of equations.\n\nq is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations).\n\n\n\n\n\n","category":"function"},{"location":"ref/#DispersiveShallowWater.energy_total_modified-Tuple{Any, SvaerdKalischEquations1D, Any}","page":"Reference","title":"DispersiveShallowWater.energy_total_modified","text":"energy_total_modified(q, equations::SvaerdKalischEquations1D, cache)\n\nReturn the modified total energy of the primitive variables q for the SvaerdKalischEquations1D. It contains an additional term containing a derivative compared to the usual energy_total. The energy_total_modified is a conserved quantity of the Svärd-Kalisch equations.\n\nq is a vector of the primitive variables at ALL nodes, i.e., a matrix of the correct length nvariables(equations) as first dimension and the number of nodes as length of the second dimension. cache needs to hold the first-derivative SBP operator D1.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.entropy","page":"Reference","title":"DispersiveShallowWater.entropy","text":"entropy(q, equations)\n\nReturn the entropy of the primitive variables q for a given set of equations.\n\nq is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations).\n\n\n\n\n\n","category":"function"},{"location":"ref/#DispersiveShallowWater.entropy_modified-Tuple{Any, SvaerdKalischEquations1D, Any}","page":"Reference","title":"DispersiveShallowWater.entropy_modified","text":"entropy_modified(q, equations::SvaerdKalischEquations1D, cache)\n\nAlias for energy_total_modified.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.errors-Union{Tuple{SciMLBase.DiscreteCallback{Condition, Affect!}}, Tuple{Affect!}, Tuple{Condition}} where {Condition, Affect!<:AnalysisCallback}","page":"Reference","title":"DispersiveShallowWater.errors","text":"errors(analysis_callback)\n\nReturn the computed errors for each timestep as a named tuple. The shape of each entry is (nvariables, ntimesteps).\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.examples_dir-Tuple{}","page":"Reference","title":"DispersiveShallowWater.examples_dir","text":"examples_dir()\n\nReturn 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.\n\nCopied from Trixi.jl.\n\nExamples\n\nreaddir(examples_dir())\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.get_examples-Tuple{}","page":"Reference","title":"DispersiveShallowWater.get_examples","text":"get_examples()\n\nReturn a list of all examples that are provided by DispersiveShallowWater.jl. See also examples_dir and default_example.\n\nCopied from Trixi.jl.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.get_name-Tuple{DispersiveShallowWater.AbstractEquations}","page":"Reference","title":"DispersiveShallowWater.get_name","text":"get_name(equations::AbstractEquations)\n\nReturn the canonical, human-readable name for the given system of equations.\n\nExamples\n\njulia> DispersiveShallowWater.get_name(BBMBBMEquations1D(gravity_constant=1.0))\n\"BBMBBMEquations1D\"\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_convergence_test-Tuple{Any, Any, BBMBBMEquations1D, Any}","page":"Reference","title":"DispersiveShallowWater.initial_condition_convergence_test","text":"initial_condition_convergence_test(x, t, equations::BBMBBMEquations1D, mesh)\n\nA travelling-wave solution used for convergence tests in a periodic domain.\n\nFor details see Example 5 in Section 3 from (here adapted for dimensional equations):\n\nMin Chen (1997) Exact Traveling-Wave Solutions to Bidirectional Wave Equations DOI: 10.1023/A:1026667903256\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_convergence_test-Tuple{Any, Any, BBMBBMVariableEquations1D, Any}","page":"Reference","title":"DispersiveShallowWater.initial_condition_convergence_test","text":"initial_condition_convergence_test(x, t, equations::BBMBBMVariableEquations1D, mesh)\n\nA travelling-wave solution used for convergence tests in a periodic domain. The bathymetry is constant.\n\nFor details see Example 5 in Section 3 from (here adapted for dimensional equations):\n\nMin Chen (1997) Exact Traveling-Wave Solutions to Bidirectional Wave Equations DOI: 10.1023/A:1026667903256\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_dingemans-Tuple{Any, Any, BBMBBMVariableEquations1D, Any}","page":"Reference","title":"DispersiveShallowWater.initial_condition_dingemans","text":"initial_condition_dingemans(x, t, equations::BBMBBMVariableEquations1D, mesh)\n\nThe 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.\n\nReferences:\n\nMagnus Svärd, Henrik Kalisch (2023) A novel energy-bounded Boussinesq model and a well-balanced and stable numerical discretization arXiv: 2302.09924\nMaarten W. Dingemans (1994) Comparison of computations with Boussinesq-like models and laboratory measurements link\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_dingemans-Tuple{Any, Any, SvaerdKalischEquations1D, Any}","page":"Reference","title":"DispersiveShallowWater.initial_condition_dingemans","text":"initial_condition_dingemans(x, t, equations::SvaerdKalischEquations1D, mesh)\n\nThe 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.\n\nReferences:\n\nMagnus Svärd, Henrik Kalisch (2023) A novel energy-bounded Boussinesq model and a well-balanced and stable numerical discretization arXiv: 2302.09924\nMaarten W. Dingemans (1994) Comparison of computations with Boussinesq-like models and laboratory measurements link\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.integrals-Union{Tuple{SciMLBase.DiscreteCallback{Condition, Affect!}}, Tuple{Affect!}, Tuple{Condition}} where {Condition, Affect!<:AnalysisCallback}","page":"Reference","title":"DispersiveShallowWater.integrals","text":"integrals(analysis_callback)\n\nReturn the computed integrals for each timestep as a named tuple.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.momentum-Tuple{Any, DispersiveShallowWater.AbstractEquations}","page":"Reference","title":"DispersiveShallowWater.momentum","text":"momentum(q, equations)\n\nReturn the momentum of the primitive variables q for a given set of equations, i.e. the waterheight times the velocity.\n\nq is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations).\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.path_create_figures-Tuple{}","page":"Reference","title":"DispersiveShallowWater.path_create_figures","text":"path_create_figures()\n\nReturn the path to the file that creates all figures used in the master thesis \"Structure-preserving Numerical Methods for Dispersive Shallow Water Model\" (2023). Executing this julia script may take a while.\n\nExamples\n\ninclude(DispersiveShallowWater.path_create_figures())\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.prim2cons","page":"Reference","title":"DispersiveShallowWater.prim2cons","text":"prim2cons(q, equations)\n\nConvert 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.\n\n\n\n\n\n","category":"function"},{"location":"ref/#DispersiveShallowWater.prim2prim-Tuple{Any, DispersiveShallowWater.AbstractEquations}","page":"Reference","title":"DispersiveShallowWater.prim2prim","text":"prim2prim(q, equations)\n\nReturn the primitive variables q. While this function is as trivial as identity, it is also as useful.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.semidiscretize-Tuple{Semidiscretization, Any}","page":"Reference","title":"DispersiveShallowWater.semidiscretize","text":"semidiscretize(semi::Semidiscretization, tspan)\n\nWrap the semidiscretization semi as an ODE problem in the time interval tspan that can be passed to solve from the SciML ecosystem.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.trixi_include-Tuple{Module, AbstractString}","page":"Reference","title":"DispersiveShallowWater.trixi_include","text":"trixi_include([mod::Module=Main,] example::AbstractString; kwargs...)\n\ninclude the file example and evaluate its content in the global scope of module mod. You can override specific assignments in example by supplying keyword arguments. It's basic purpose is to make it easier to modify some parameters while running DispersiveShallowWater from the REPL. Additionally, this is used in tests to reduce the computational burden for CI while still providing examples with sensible default values for users.\n\nBefore replacing assignments in example, the keyword argument maxiters is inserted into calls to solve and DispersiveShallowWater.solve with it's default value used in the SciML ecosystem for ODEs, see the \"Miscellaneous\" section of the documentation.\n\nCopied from Trixi.jl.\n\nExamples\n\njulia> redirect_stdout(devnull) do\n trixi_include(@__MODULE__, joinpath(examples_dir(), \"bbm_bbm_1d\", \"bbm_bbm_1d_basic.jl\"),\n tspan=(0.0, 0.1))\n sol.t[end]\n end\n0.1\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.tstops-Union{Tuple{SciMLBase.DiscreteCallback{Condition, Affect!}}, Tuple{Affect!}, Tuple{Condition}} where {Condition, Affect!<:AnalysisCallback}","page":"Reference","title":"DispersiveShallowWater.tstops","text":"tstops(analysis_callback)\n\nReturn the time values that correspond to the saved values of the errors and integrals.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.varnames","page":"Reference","title":"DispersiveShallowWater.varnames","text":"varnames(conversion_function, equations)\n\nReturn the list of variable names when applying conversion_function to the conserved variables associated to equations. Common choices of the conversion_function are prim2prim and prim2cons.\n\n\n\n\n\n","category":"function"},{"location":"ref/#DispersiveShallowWater.velocity","page":"Reference","title":"DispersiveShallowWater.velocity","text":"velocity(q, equations)\n\nReturn the velocity of the primitive variables q for a given set of equations.\n\nq is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations).\n\n\n\n\n\n","category":"function"},{"location":"ref/#DispersiveShallowWater.waterheight","page":"Reference","title":"DispersiveShallowWater.waterheight","text":"waterheight(q, equations)\n\nReturn the waterheight of the primitive variables q for a given set of equations, i.e. the waterheight above the bathymetry.\n\nq is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations).\n\n\n\n\n\n","category":"function"},{"location":"ref/#DispersiveShallowWater.waterheight_total","page":"Reference","title":"DispersiveShallowWater.waterheight_total","text":"waterheight_total(q, equations)\n\nReturn the total waterheight of the primitive variables q for a given set of equations, i.e. the waterheight plus the bathymetry.\n\nq is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations).\n\n\n\n\n\n","category":"function"},{"location":"ref/#SummationByPartsOperators.grid-Tuple{Semidiscretization}","page":"Reference","title":"SummationByPartsOperators.grid","text":"grid(semi)\n\nGet the grid of a semidiscretization.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.@autoinfiltrate","page":"Reference","title":"DispersiveShallowWater.@autoinfiltrate","text":"@autoinfiltrate\n@autoinfiltrate condition::Bool\n\nInvoke 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.\n\nAs 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.\n\nNote: For this macro to work, the Infiltrator.jl package needs to be installed in your current Julia environment stack.\n\nSee also: Infiltrator.jl\n\nwarning: Internal use only\nPlease 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.\n\n\n\n\n\n","category":"macro"},{"location":"#DispersiveShallowWater.jl","page":"Home","title":"DispersiveShallowWater.jl","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"(Image: Docs-stable) (Image: Docs-dev) (Image: Build Status) (Image: Coveralls) (Image: Aqua QA) (Image: License: MIT) (Image: DOI)","category":"page"},{"location":"","page":"Home","title":"Home","text":"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:","category":"page"},{"location":"","page":"Home","title":"Home","text":"the BBM-BBM equations with varying bottom topography,\nthe dispersive shallow water model proposed by Magnus Svärd and Henrik Kalisch.","category":"page"},{"location":"","page":"Home","title":"Home","text":"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.","category":"page"},{"location":"#Installation","page":"Home","title":"Installation","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"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","category":"page"},{"location":"","page":"Home","title":"Home","text":"julia> using Pkg\n\njulia> Pkg.add([\"DispersiveShallowWater\", \"OrdinaryDiffEq\", \"Plots\"])","category":"page"},{"location":"","page":"Home","title":"Home","text":"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","category":"page"},{"location":"","page":"Home","title":"Home","text":"julia> Pkg.add(\"SummationByPartsOperators\")","category":"page"},{"location":"#Usage","page":"Home","title":"Usage","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"In the Julia REPL, first load the package DispersiveShallowWater.jl","category":"page"},{"location":"","page":"Home","title":"Home","text":"julia> using DispersiveShallowWater","category":"page"},{"location":"","page":"Home","title":"Home","text":"You can run a basic simulation that solves the BBM-BBM equations by executing","category":"page"},{"location":"","page":"Home","title":"Home","text":"julia> include(default_example());","category":"page"},{"location":"","page":"Home","title":"Home","text":"The result can be visualized by using the package Plots.jl","category":"page"},{"location":"","page":"Home","title":"Home","text":"julia> using Plots\njulia> plot(semi => sol)","category":"page"},{"location":"","page":"Home","title":"Home","text":"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\")).","category":"page"},{"location":"#Authors","page":"Home","title":"Authors","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"The package is developed and maintained by Joshua Lampert and was initiated as part of the master thesis \"Structure-Preserving Numerical Methods for Dispersive Shallow Water Models\" (2023). 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.","category":"page"},{"location":"#License-and-contributing","page":"Home","title":"License and contributing","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"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.","category":"page"}] +[{"location":"license/#License","page":"License","title":"License","text":"","category":"section"},{"location":"license/","page":"License","title":"License","text":"MIT License","category":"page"},{"location":"license/","page":"License","title":"License","text":"Copyright (c) 2023-present Joshua Lampert ","category":"page"},{"location":"license/","page":"License","title":"License","text":"Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:","category":"page"},{"location":"license/","page":"License","title":"License","text":"The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.","category":"page"},{"location":"license/","page":"License","title":"License","text":"THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.","category":"page"},{"location":"reproduce/#How-to-reproduce-the-figures","page":"Reproduce figures","title":"How to reproduce the figures","text":"","category":"section"},{"location":"reproduce/","page":"Reproduce figures","title":"Reproduce figures","text":"In order to reproduce all figures used in the master thesis \"Structure-Preserving Numerical Methods for Dispersive Shallow Water Models\" (2023) by Joshua Lampert execute the file located at the path DispersiveShallowWater.path_create_figures(). From the Julia REPL, this can be done by:","category":"page"},{"location":"reproduce/","page":"Reproduce figures","title":"Reproduce figures","text":"julia> using DispersiveShallowWater\njulia> include(DispersiveShallowWater.path_create_figures())","category":"page"},{"location":"reproduce/","page":"Reproduce figures","title":"Reproduce figures","text":"Note that for one figure Trixi.jl is needed, so download Trixi.jl first:","category":"page"},{"location":"reproduce/","page":"Reproduce figures","title":"Reproduce figures","text":"julia> using Pkg\njulia> Pkg.add(\"Trixi\")","category":"page"},{"location":"reproduce/","page":"Reproduce figures","title":"Reproduce figures","text":"Executing the script may take a while. It will generate a folder out/ with certain subfolders containing the figures. If you want to modify the plots or only produce a subset of plots, you can download the script create_figures.jl, modify it accordingly and run it by:","category":"page"},{"location":"reproduce/","page":"Reproduce figures","title":"Reproduce figures","text":"julia> include(\"create_figures.jl\")","category":"page"},{"location":"overview/#Running-a-simulation","page":"Overview","title":"Running a simulation","text":"","category":"section"},{"location":"overview/#Introduction","page":"Overview","title":"Introduction","text":"","category":"section"},{"location":"overview/","page":"Overview","title":"Overview","text":"In this tutorial we describe how to numerically solve the BBM-BBM (Benjamin-Bona-Mahony) equations with variable bottom topography in one dimension, which has been proposed in [IsrawiKalischKatsaounisMitsotakis2021] for two spatial dimensions. The equations describe a dispersive shallow water model, i.e. they extend the well-known shallow water equations in the sense that dispersion is modeled. The shallow water equations are a system of first order hyperbolic partial differential equations that can be written in the form of a balance law. In contrast, the BBM-BBM equations additionally include third-order mixed derivatives. In primitive variables q = (eta v) they can be written as:","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"beginaligned\n eta_t + ((eta + D)v)_x - frac16(D^2eta_xt)_x = 0\n v_t + geta_x + left(frac12v^2right)_x - frac16(D^2v_t)_xx = 0\nendaligned","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"Here, eta = h + b describes the total water height, h the water height above the bottom topography (bathymetry), b = -D the bathymetry and v the velocity in horizontal direction. The gravitational acceleration is denoted as g. A sketch of the water height and the bathymetry can be found below.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"(Image: )","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"In order to conduct a numerical simulation with DispersiveShallowWater.jl, we perform the following steps.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"First, we load the necessary libraries:","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"using DispersiveShallowWater, OrdinaryDiffEq","category":"page"},{"location":"overview/#Define-physical-setup","page":"Overview","title":"Define physical setup","text":"","category":"section"},{"location":"overview/","page":"Overview","title":"Overview","text":"As a first step of a numerical simulation, we define the physical setup we want to solve. This includes the set of equations, potentially including physical parameters, initial and boundary conditions as well as the domain. In the following example, the initial condition describes a travelling wave that moves towards a beach, which is modeled by a linearly increasing bathymetry.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"equations = BBMBBMVariableEquations1D(gravity_constant = 9.81)\n\nfunction initial_condition_shoaling(x, t, equations::BBMBBMVariableEquations1D, mesh)\n A = 0.07 # amplitude of wave\n x0 = -30 # initial center\n eta = A * exp(-0.1*(x - x0)^2)\n v = 0\n D = x <= 0.0 ? 0.7 : 0.7 - 1/50 * x\n return SVector(eta, v, D)\nend\n\ninitial_condition = initial_condition_shoaling\nboundary_conditions = boundary_condition_periodic\n\ncoordinates_min = -130.0\ncoordinates_max = 20.0\nN = 512\nmesh = Mesh1D(coordinates_min, coordinates_max, N + 1)","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"The first line specifies that we want to solve the BBM-BBM equations with variable bathymetry using a gravitational acceleration g = 981. Afterwards, we define the initial condition, which is described as a function with the spatial variable x, the time t, the equations and a mesh as parameters. If an analytical solution is available, the time variable t can be used, and the initial condition can serve as an analytical solution to be compared with the numerical solution. Otherwise, you can just keep the time variable unused. An initial condition in DispersiveShallowWater.jl is supposed to return an SVector holding the values for each of the unknown variables. Since the bathymetry is treated as a variable (with time derivative 0) for convenience, we need to provide the value for the primitive variables eta and v as well as for D.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"Next, we choose periodic boundary conditions since, up to now, DispersiveShallowWater.jl only provides support for this type of boundary conditions. Lastly, we define the physical domain as the interval from -130 to 20 and we choose 512 intermediate nodes. The mesh is homogeneous, i.e. the distance between each two nodes is constant. We choose the left boundary very far to the left in order to avoid an interaction of the left- and right-travelling waves.","category":"page"},{"location":"overview/#Define-numerical-solver","page":"Overview","title":"Define numerical solver","text":"","category":"section"},{"location":"overview/","page":"Overview","title":"Overview","text":"In the next step, we build a Semidiscretization that bundles all ingredients for the spatial discretization of the model. Especially, we need to define a Solver. The simplest way to define a solver is to call the constructor by providing the mesh and a desired order of accuracy. In the following example, we use an accuracy order of 4. The default constructor simply creates periodic first- and second-derivative central finite difference summation by parts operators of the provided order of accuracy. How to use other summation by parts operators, is described in the section on how to customize the solver.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"solver = Solver(mesh, 4)\n\nsemi = Semidiscretization(mesh, equations, initial_condition, solver, boundary_conditions = boundary_conditions)","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"Finally, we put the mesh, the equations, the initial_condition, the solver and the boundary_conditions together in a semidiscretization semi.","category":"page"},{"location":"overview/#Solve-system-of-ordinary-differential-equations","page":"Overview","title":"Solve system of ordinary differential equations","text":"","category":"section"},{"location":"overview/","page":"Overview","title":"Overview","text":"Once we have obtained a semidiscretization, we can solve the resulting system of ordinary differential equations. To do so, we specify the time interval that we want to simulate and obtain an ODEProblem from the SciML ecosystem for ordinary differential equations by calling semidiscretize on the semidiscretization and the time span. Additionally, we can analyze the numerical solution using an AnalysisCallback. The analysis includes computing the L^2 error and L^infty error of the different solution's variables compared to the initial condition (or, if available, at the same time analytical solution). Additional errors can be passed by the keyword argument extra_analysis_errors. Additional integral quantities that should be analyzed can be passed by keyword argument extra_analysis_integrals. In this example we pass the conservation_error, which computes the temporal change of the total amount (i.e. integral) of the different variables over time. In addition, the integrals of the total waterheight eta waterheight_total, the velocity and the entropy are computed and saved for each time step. The total waterheight and the total velocity are linear invariants of the BBM-BBM equations, i.e. they do not change over time. The total entropy","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"mathcal E(t eta v) = frac12int_Omega geta^2 + (eta + D)v^2textrmdx","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"is a nonlinear invariant and should be constant over time as well. During the simulation, the AnalysisCallback will print the results to the terminal.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"Finally, the ode can be solved using the interface from OrdinaryDiffEq.jl. This means, we can specify a time-stepping scheme we want to use the tolerances for the adaptive time-stepping and the time values, where the solution values should be saved. In this case, we use the adaptive explicit Runge-Kutta method Tsit5 by Tsitouras of order 5(4). Here, we save the solution at 100 equidistant points.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"tspan = (0.0, 25.0)\node = semidiscretize(semi, tspan)\nanalysis_callback = AnalysisCallback(semi; interval = 10,\n extra_analysis_errors = (:conservation_error,),\n extra_analysis_integrals = (waterheight_total,\n velocity, entropy),\n io = devnull)\ncallbacks = CallbackSet(analysis_callback)\n\nsaveat = range(tspan..., length = 100)\nsol = solve(ode, Tsit5(), abstol = 1e-7, reltol = 1e-7,\n save_everystep = false, callback = callbacks, saveat = saveat)","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"After solving the equations, sol contains the solution for each of the three variables at every spatial point for each of the 100 points in time. The errors and integrals recorded by the AnalysisCallback can be obtained as NamedTuples by errors(analysis_callback) and integrals(analysis_callback).","category":"page"},{"location":"overview/#visualize_results","page":"Overview","title":"Visualize results","text":"","category":"section"},{"location":"overview/","page":"Overview","title":"Overview","text":"After running the simulation, the results can be visualized using Plots.jl, which needs to be imported first. Then, we can plot the solution at the final time by calling plot on a Pair of the Semidiscretization and the corresponding ODESolution sol. The result is depicted in the following picture.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"using Plots\n\nplot(semi => sol)\nsavefig(\"shoaling_solution.png\")","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"(Image: )","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"By default, this will plot the bathymetry, but not the initial (analytical) solution. You can adjust this by passing the boolean values plot_bathymetry (if true always plot to first subplot) and plot_initial. You can also provide a conversion function that converts the solution. A conversion function should take the values of the primitive variables q at one node, and the equations as input and should return an SVector of any length as output. For a user defined conversion function, there should also exist a function varnames(conversion, equations) that returns a Tuple of the variable names used for labelling. The conversion function can, e.g., be prim2cons or waterheight_total if one only wants to plot the total waterheight. The resulting plot will have one subplot for each of the returned variables of the conversion variable. By default, the conversion function is just prim2prim, i.e. the identity.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"Plotting an animation over time can, e.g., be done by the following command, which uses step to plot the solution at a specific time step.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"anim = @animate for step in 1:length(sol.u)\n plot(semi => sol, plot_initial = true, conversion = waterheight_total, step = step, xlim = (-50, 20), ylims = [(-0.8, 0.1)])\nend\ngif(anim, \"shoaling_solution.gif\", fps = 25)","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"It is also possible to plot the solution variables at a fixed spatial point over time by calling plot(semi => sol, x) for some x-value, see plot_examples.jl for some examples.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"Often, it is interesting to have a look at how the quantities that are recorded by the AnalysisCallback evolve in time. To this end, you can plot the AnalysisCallback by","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"plot(analysis_callback)\nsavefig(\"analysis_callback.png\")","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"This creates the following figure:","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"(Image: )","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"You can see that the linear invariants int_Omegaetatextrmdx and int_Omega vtextrmdx are indeed conserved exactly. The entropy, however, starts growing at around t = 17 and rises up to approximately 5e-5. This is because of the fact that, during the time integration, a nonlinear invariant is not necessarily conserved, even if the semidiscretization conserves the quantity exactly. How to obtain a fully-discrete structure-preserving numerical scheme is explained in the following section.","category":"page"},{"location":"overview/#Use-entropy-conserving-time-integration","page":"Overview","title":"Use entropy-conserving time integration","text":"","category":"section"},{"location":"overview/","page":"Overview","title":"Overview","text":"To obtain entropy-conserving time-stepping schemes DispersiveShallowWater.jl uses the relaxation method introduced in [Ketcheson2019] and further developed in [RanochaSayyariDalcinParsaniKetcheson2020]. The relaxation method is implemented as a RelaxationCallback, which takes a function representing the conserved quantity as the keyword argument invariant. Therefore, we can run the same example as above, but using relaxation on the entropy by simply adding another callback to the CallbackSet:","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"analysis_callback = AnalysisCallback(semi; interval = 10,\n extra_analysis_errors = (:conservation_error,),\n extra_analysis_integrals = (waterheight_total,\n velocity, entropy),\n io = devnull)\nrelaxation_callback = RelaxationCallback(invariant = entropy)\ncallbacks = CallbackSet(relaxation_callback, analysis_callback)\nsol = solve(ode, Tsit5(), abstol = 1e-7, reltol = 1e-7,\n save_everystep = false, callback = callbacks, saveat = saveat)","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"When you use both, an AnalysisCallback and a RelaxationCallback, note that the relaxation_callback needs to come first inside the CallbackSet as it needs to be invoked prior to the analysis_callback, such that the analysis_callback analyzes the solution with the already updated values.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"Plotting the analysis_callback again, we can see that now also the entropy is conserved up to machine precision.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"plot(analysis_callback)\nsavefig(\"analysis_callback_relaxation.png\")","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"(Image: )","category":"page"},{"location":"overview/#customize_solver","page":"Overview","title":"Customize solver","text":"","category":"section"},{"location":"overview/","page":"Overview","title":"Overview","text":"In the semidiscretization created above, we used the default SBP operators, which are periodic finite difference operators. Using different SBP operators for the semidiscretization can be done leveraging SummationByPartsOperators.jl, which needs to be imported first:","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"using SummationByPartsOperators: legendre_derivative_operator, UniformPeriodicMesh1D, couple_discontinuously, PeriodicUpwindOperators","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"As an example, let us create a semidiscretization based on discontinuous Galerkin (DG) upwind operators. A semidiscretization implemented in DispersiveShallowWater.jl needs one first-derivative and one second-derivative SBP operator. To build the first-derivative operator, we first create a LegendreDerivativeOperator with polynomial degree 3 on a reference element [-1.0, 1.0] and a UniformPeriodicMesh1D for the coupling.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"mesh = Mesh1D(coordinates_min, coordinates_max, N)\naccuracy_order = 4\nD_legendre = legendre_derivative_operator(-1.0, 1.0, accuracy_order)\nuniform_mesh = UniformPeriodicMesh1D(mesh.xmin, mesh.xmax, div(mesh.N, accuracy_order))","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"Upwind DG operators in negative, central and positive operators can be obtained by couple_discontinuously","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"central = couple_discontinuously(D_legendre, uniform_mesh)\nminus = couple_discontinuously(D_legendre, uniform_mesh, Val(:minus))\nplus = couple_discontinuously(D_legendre, uniform_mesh, Val(:plus))\nD1 = PeriodicUpwindOperators(minus, central, plus)","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"In order to still have an entropy-conserving semidiscretization the second-derivative SBP operator needs to be","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"using SparseArrays: sparse\nD2 = sparse(plus) * sparse(minus)","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"The Solver object can now be created by passing the two SBP operators to the constructor, which, in turn, can be used to construct a Semidiscretization:","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"solver = Solver(D1, D2)\nsemi = Semidiscretization(mesh, equations, initial_condition, solver, boundary_conditions = boundary_conditions)","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"As before, we can run the simulation by","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"analysis_callback = AnalysisCallback(semi; interval = 10,\n extra_analysis_errors = (:conservation_error,),\n extra_analysis_integrals = (waterheight_total,\n velocity, entropy),\n io = devnull)\nrelaxation_callback = RelaxationCallback(invariant = entropy)\ncallbacks = CallbackSet(relaxation_callback, analysis_callback)\nsol = solve(ode, Tsit5(), abstol = 1e-7, reltol = 1e-7,\n save_everystep = false, callback = callbacks, saveat = saveat)\nanim = @animate for step in 1:length(sol.u)\n plot(semi => sol, plot_initial = true, conversion = waterheight_total, step = step, xlim = (-50, 20), ylims = [(-0.8, 0.1)])\nend\ngif(anim, \"shoaling_solution_dg.gif\", fps = 25)","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"For more details see also the documentation of SummationByPartsOperators.jl","category":"page"},{"location":"overview/#Additional-resources","page":"Overview","title":"Additional resources","text":"","category":"section"},{"location":"overview/","page":"Overview","title":"Overview","text":"Some more examples sorted by the simulated equations can be found in the examples/ subdirectory. Especially, in examples/svaerd_kalisch_1d/ you can find Julia scripts that solve the SvaerdKalischEquations1D that were not covered in this tutorial. The same steps as described above, however, apply in the same way to these equations. Attention must be paid for these equations because they do not conserve the classical total entropy mathcal E, but a modified entropy hatmathcal E, available as entropy_modified.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"More examples, especially focussing on plotting, can be found in the scripts create_figures.jl and plot_examples.jl.","category":"page"},{"location":"overview/#References","page":"Overview","title":"References","text":"","category":"section"},{"location":"overview/","page":"Overview","title":"Overview","text":"[IsrawiKalischKatsaounisMitsotakis2021]: Israwi, Kalisch, Katsaounis, Mitsotakis (2021). A regularized shallow-water waves system with slip-wall boundary conditions in a basin: theory and numerical analysis. DOI: 10.1088/1361-6544/ac3c29","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"[Ketcheson2019]: Ketcheson (2019): Relaxation Runge-Kutta Methods: Conservation and stability for Inner-Product Norms. DOI: 10.1137/19M1263662","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"[RanochaSayyariDalcinParsaniKetcheson2020]: Ranocha, Sayyari, Dalcin, Parsani, Ketcheson (2020): Relaxation Runge–Kutta Methods: Fully-Discrete Explicit Entropy-Stable Schemes for the Compressible Euler and Navier–Stokes Equations DOI: 10.1137/19M1263480","category":"page"},{"location":"ref/#DispersiveShallowWater.jl-API","page":"Reference","title":"DispersiveShallowWater.jl API","text":"","category":"section"},{"location":"ref/","page":"Reference","title":"Reference","text":"CurrentModule = DispersiveShallowWater","category":"page"},{"location":"ref/","page":"Reference","title":"Reference","text":"Modules = [DispersiveShallowWater]","category":"page"},{"location":"ref/#DispersiveShallowWater.boundary_condition_periodic","page":"Reference","title":"DispersiveShallowWater.boundary_condition_periodic","text":"boundary_condition_periodic = DispersiveShallowWater.BoundaryConditionPeriodic()\n\nA singleton struct indicating periodic boundary conditions.\n\n\n\n\n\n","category":"constant"},{"location":"ref/#DispersiveShallowWater.AbstractEquations","page":"Reference","title":"DispersiveShallowWater.AbstractEquations","text":"AbstractEquations{NDIMS, NVARS}\n\nAn 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.\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.AbstractSolver","page":"Reference","title":"DispersiveShallowWater.AbstractSolver","text":"AbstractSolver\n\nAn abstract supertype of specific solvers.\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.AnalysisCallback","page":"Reference","title":"DispersiveShallowWater.AnalysisCallback","text":"AnalysisCallback(semi; interval=0,\n extra_analysis_errors=Symbol[],\n extra_analysis_integrals=(),\n io=stdout)\n\nAnalyze 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,).\n\nFurther 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.\n\nDuring the Simulation, the AnalysisCallback will print information to io.\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.BBMBBMEquations1D","page":"Reference","title":"DispersiveShallowWater.BBMBBMEquations1D","text":"BBMBBMEquations1D(gravity, D)\n\nBBM-BBM (Benjamin–Bona–Mahony) system in one spatial dimension. The equations are given by\n\nbeginaligned\n eta_t + ((eta + D)v)_x - frac16D^2eta_xxt = 0\n v_t + geta_x + left(frac12v^2right)_x - frac16D^2v_xxt = 0\nendaligned\n\nThe 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 = -D. The water height above the bathymetry is therefore given by h = eta + D.\n\nOne reference for the BBM-BBM system can be found in\n\nJerry L. Bona, Min Chen (1998) A Boussinesq system for two-way propagation of nonlinear dispersive waves DOI: 10.1016/S0167-2789(97)00249-2\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.BBMBBMVariableEquations1D","page":"Reference","title":"DispersiveShallowWater.BBMBBMVariableEquations1D","text":"BBMBBMVariableEquations1D(gravity, eta0 = 1.0)\n\nBBM-BBM (Benjamin–Bona–Mahony) system in one spatial dimension with spatially varying bathymetry. The equations are given by\n\nbeginaligned\n eta_t + ((eta + D)v)_x - frac16(D^2eta_xt)_x = 0\n v_t + geta_x + left(frac12v^2right)_x - frac16(D^2v_t)_xx = 0\nendaligned\n\nThe 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 bottom topography (bathymetry) b = -D. The water height above the bathymetry is therefore given by h = eta + D.\n\nOne reference for the BBM-BBM system with spatially varying bathymetry can be found in\n\nSamer Israwi, Henrik Kalisch, Theodoros Katsaounis, Dimitrios Mitsotakis (2022) A regularized shallow-water waves system with slip-wall boundary conditions in a basin: theory and numerical analysis DOI: 10.1088/1361-6544/ac3c29\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.Mesh1D","page":"Reference","title":"DispersiveShallowWater.Mesh1D","text":"Mesh1D\n\nStruct that holds the information for a simple homogeneous one-dimensional mesh.\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.Mesh1D-Tuple{Any, Any, Any}","page":"Reference","title":"DispersiveShallowWater.Mesh1D","text":"Mesh1D(xmin, xmax, N)\n\nCreate a simple homogeneous one-dimensional mesh from xmin to xmax with N nodes.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.RelaxationCallback","page":"Reference","title":"DispersiveShallowWater.RelaxationCallback","text":"RelaxationCallback(invariant)\n\nUse 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.\n\nReference\n\nHendrik 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\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.Semidiscretization","page":"Reference","title":"DispersiveShallowWater.Semidiscretization","text":"Semidiscretization\n\nA struct containing everything needed to describe a spatial semidiscretization of an equation.\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.Semidiscretization-NTuple{4, Any}","page":"Reference","title":"DispersiveShallowWater.Semidiscretization","text":"Semidiscretization(mesh, equations, initial_condition, solver;\n source_terms=nothing,\n boundary_conditions=boundary_condition_periodic,\n RealT=real(solver),\n uEltype=RealT,\n initial_cache=NamedTuple())\n\nConstruct a semidiscretization of a PDE.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.Solver","page":"Reference","title":"DispersiveShallowWater.Solver","text":"Solver\n\nA struct that holds the summation by parts (SBP) operators that are used for the spatial discretization.\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.Solver-Tuple{Any, Any}","page":"Reference","title":"DispersiveShallowWater.Solver","text":"Solver(mesh, accuracy_order)\n\nCreate a solver, where the summation by parts (SBP) operators are of order accuracy_order and associated to the mesh.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.Solver-Union{Tuple{RealT}, Tuple{SummationByPartsOperators.AbstractDerivativeOperator{RealT}, Union{AbstractMatrix{RealT}, SummationByPartsOperators.AbstractDerivativeOperator{RealT}}}} where RealT","page":"Reference","title":"DispersiveShallowWater.Solver","text":"Solver(D1, D2)\n\nCreate 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. Both summation by parts operators should be associated with the same grid.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.SvaerdKalischEquations1D","page":"Reference","title":"DispersiveShallowWater.SvaerdKalischEquations1D","text":"SvärdKalischEquations1D(gravity, eta0 = 1.0, alpha = 0.0, beta = 0.2308939393939394, gamma = 0.04034343434343434)\n\nDispersive system by Svärd and Kalisch in one spatial dimension with spatially varying bathymetry. The equations are given in conservative variables by\n\nbeginaligned\n h_t + (hv)_x = (hatalpha(hatalpha(h + b)_x)_x)_x\n (hv)_t + (hv^2)_x + gh(h + b)_x = (hatalpha v(hatalpha(h + b)_x)_x)_x + (hatbeta v_x)_xt + frac12(hatgamma v_x)_xx + frac12(hatgamma v_xx)_x\nendaligned\n\nwhere hatalpha^2 = alphasqrtgdd^2, hatbeta = beta d^3, hatgamma = gammasqrtgdd^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\n\nbeginaligned\n eta_t + ((eta + D)v)_x = (hatalpha(hatalphaeta_x)_x)_x\n v_t(eta + D) - v((eta + D)v)_x + ((eta + D)v^2)_x + g(eta + D)eta_x = (hatalpha v(hatalphaeta_x)_x)_x - v(hatalpha(hatalphaeta_x)_x)_x + (hatbeta v_x)_xt + frac12(hatgamma v_x)_xx + frac12(hatgamma v_xx)_x\nendaligned\n\nThe 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 = -D. The water height above the bathymetry is therefore given by h = eta + D.\n\nThe equations by Svärd and Kalisch are presented and analyzed in\n\nMagnus Svärd, Henrik Kalisch (2023) A novel energy-bounded Boussinesq model and a well-balanced and stable numerical discretization arXiv: 2302.09924\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.cons2prim","page":"Reference","title":"DispersiveShallowWater.cons2prim","text":"cons2prim(u, equations)\n\nConvert 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.\n\n\n\n\n\n","category":"function"},{"location":"ref/#DispersiveShallowWater.convergence_test-Tuple{Module, AbstractString, Any}","page":"Reference","title":"DispersiveShallowWater.convergence_test","text":"convergence_test([mod::Module=Main,] example::AbstractString, iterations; kwargs...)\n\nRun iterations simulations using the setup given in example and compute the experimental order of convergence (EOC) in the L^2 and L^infty norm. In each iteration, the resolution of the respective mesh will be doubled. Additional keyword arguments kwargs... and the optional module mod are passed directly to trixi_include.\n\nAdjusted from Trixi.jl.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.default_analysis_errors-Tuple{DispersiveShallowWater.AbstractEquations}","page":"Reference","title":"DispersiveShallowWater.default_analysis_errors","text":"default_analysis_errors(equations)\n\nDefault analysis errors used by the AnalysisCallback.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.default_analysis_integrals-Tuple{DispersiveShallowWater.AbstractEquations}","page":"Reference","title":"DispersiveShallowWater.default_analysis_integrals","text":"default_analysis_integrals(equations)\n\nDefault analysis integrals used by the AnalysisCallback.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.default_example-Tuple{}","page":"Reference","title":"DispersiveShallowWater.default_example","text":"default_example()\n\nReturn the path to an example that can be used to quickly see DispersiveShallowWater.jl in action. See also examples_dir and get_examples.\n\nCopied from Trixi.jl.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.discharge-Tuple{Any, DispersiveShallowWater.AbstractEquations}","page":"Reference","title":"DispersiveShallowWater.discharge","text":"discharge(q, equations)\n\nSee momentum.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.eachvariable-Tuple{DispersiveShallowWater.AbstractEquations}","page":"Reference","title":"DispersiveShallowWater.eachvariable","text":"eachvariable(equations::AbstractEquations)\n\nReturn 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.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.energy_total","page":"Reference","title":"DispersiveShallowWater.energy_total","text":"energy_total(q, equations)\n\nReturn the total energy of the primitive variables q for a given set of equations.\n\nq is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations).\n\n\n\n\n\n","category":"function"},{"location":"ref/#DispersiveShallowWater.energy_total_modified-Tuple{Any, SvaerdKalischEquations1D, Any}","page":"Reference","title":"DispersiveShallowWater.energy_total_modified","text":"energy_total_modified(q, equations::SvaerdKalischEquations1D, cache)\n\nReturn the modified total energy of the primitive variables q for the SvaerdKalischEquations1D. It contains an additional term containing a derivative compared to the usual energy_total. The energy_total_modified is a conserved quantity of the Svärd-Kalisch equations.\n\nq is a vector of the primitive variables at ALL nodes, i.e., a matrix of the correct length nvariables(equations) as first dimension and the number of nodes as length of the second dimension. cache needs to hold the first-derivative SBP operator D1.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.entropy","page":"Reference","title":"DispersiveShallowWater.entropy","text":"entropy(q, equations)\n\nReturn the entropy of the primitive variables q for a given set of equations.\n\nq is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations).\n\n\n\n\n\n","category":"function"},{"location":"ref/#DispersiveShallowWater.entropy_modified-Tuple{Any, SvaerdKalischEquations1D, Any}","page":"Reference","title":"DispersiveShallowWater.entropy_modified","text":"entropy_modified(q, equations::SvaerdKalischEquations1D, cache)\n\nAlias for energy_total_modified.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.errors-Union{Tuple{SciMLBase.DiscreteCallback{Condition, Affect!}}, Tuple{Affect!}, Tuple{Condition}} where {Condition, Affect!<:AnalysisCallback}","page":"Reference","title":"DispersiveShallowWater.errors","text":"errors(analysis_callback)\n\nReturn the computed errors for each timestep as a named tuple. The shape of each entry is (nvariables, ntimesteps).\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.examples_dir-Tuple{}","page":"Reference","title":"DispersiveShallowWater.examples_dir","text":"examples_dir()\n\nReturn 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.\n\nCopied from Trixi.jl.\n\nExamples\n\nreaddir(examples_dir())\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.get_examples-Tuple{}","page":"Reference","title":"DispersiveShallowWater.get_examples","text":"get_examples()\n\nReturn a list of all examples that are provided by DispersiveShallowWater.jl. See also examples_dir and default_example.\n\nCopied from Trixi.jl.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.get_name-Tuple{DispersiveShallowWater.AbstractEquations}","page":"Reference","title":"DispersiveShallowWater.get_name","text":"get_name(equations::AbstractEquations)\n\nReturn the canonical, human-readable name for the given system of equations.\n\nExamples\n\njulia> DispersiveShallowWater.get_name(BBMBBMEquations1D(gravity_constant=1.0))\n\"BBMBBMEquations1D\"\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_convergence_test-Tuple{Any, Any, BBMBBMEquations1D, Any}","page":"Reference","title":"DispersiveShallowWater.initial_condition_convergence_test","text":"initial_condition_convergence_test(x, t, equations::BBMBBMEquations1D, mesh)\n\nA travelling-wave solution used for convergence tests in a periodic domain.\n\nFor details see Example 5 in Section 3 from (here adapted for dimensional equations):\n\nMin Chen (1997) Exact Traveling-Wave Solutions to Bidirectional Wave Equations DOI: 10.1023/A:1026667903256\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_convergence_test-Tuple{Any, Any, BBMBBMVariableEquations1D, Any}","page":"Reference","title":"DispersiveShallowWater.initial_condition_convergence_test","text":"initial_condition_convergence_test(x, t, equations::BBMBBMVariableEquations1D, mesh)\n\nA travelling-wave solution used for convergence tests in a periodic domain. The bathymetry is constant.\n\nFor details see Example 5 in Section 3 from (here adapted for dimensional equations):\n\nMin Chen (1997) Exact Traveling-Wave Solutions to Bidirectional Wave Equations DOI: 10.1023/A:1026667903256\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_dingemans-Tuple{Any, Any, BBMBBMVariableEquations1D, Any}","page":"Reference","title":"DispersiveShallowWater.initial_condition_dingemans","text":"initial_condition_dingemans(x, t, equations::BBMBBMVariableEquations1D, mesh)\n\nThe 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.\n\nReferences:\n\nMagnus Svärd, Henrik Kalisch (2023) A novel energy-bounded Boussinesq model and a well-balanced and stable numerical discretization arXiv: 2302.09924\nMaarten W. Dingemans (1994) Comparison of computations with Boussinesq-like models and laboratory measurements link\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_dingemans-Tuple{Any, Any, SvaerdKalischEquations1D, Any}","page":"Reference","title":"DispersiveShallowWater.initial_condition_dingemans","text":"initial_condition_dingemans(x, t, equations::SvaerdKalischEquations1D, mesh)\n\nThe 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.\n\nReferences:\n\nMagnus Svärd, Henrik Kalisch (2023) A novel energy-bounded Boussinesq model and a well-balanced and stable numerical discretization arXiv: 2302.09924\nMaarten W. Dingemans (1994) Comparison of computations with Boussinesq-like models and laboratory measurements link\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_manufactured-Tuple{Any, Any, BBMBBMEquations1D, Any}","page":"Reference","title":"DispersiveShallowWater.initial_condition_manufactured","text":"initial_condition_manufactured(x, t, equations::BBMBBMEquations1D, mesh)\n\nA smooth manufactured solution in combination with source_terms_manufactured.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_manufactured-Tuple{Any, Any, BBMBBMVariableEquations1D, Any}","page":"Reference","title":"DispersiveShallowWater.initial_condition_manufactured","text":"initial_condition_manufactured(x, t, equations::BBMBBMVariableEquations1D, mesh)\n\nA smooth manufactured solution in combination with source_terms_manufactured.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_manufactured-Tuple{Any, Any, SvaerdKalischEquations1D, Any}","page":"Reference","title":"DispersiveShallowWater.initial_condition_manufactured","text":"initial_condition_manufactured(x, t, equations::SvaerdKalischEquations1D, mesh)\n\nA smooth manufactured solution in combination with source_terms_manufactured.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.integrals-Union{Tuple{SciMLBase.DiscreteCallback{Condition, Affect!}}, Tuple{Affect!}, Tuple{Condition}} where {Condition, Affect!<:AnalysisCallback}","page":"Reference","title":"DispersiveShallowWater.integrals","text":"integrals(analysis_callback)\n\nReturn the computed integrals for each timestep as a named tuple.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.momentum-Tuple{Any, DispersiveShallowWater.AbstractEquations}","page":"Reference","title":"DispersiveShallowWater.momentum","text":"momentum(q, equations)\n\nReturn the momentum of the primitive variables q for a given set of equations, i.e. the waterheight times the velocity.\n\nq is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations).\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.path_create_figures-Tuple{}","page":"Reference","title":"DispersiveShallowWater.path_create_figures","text":"path_create_figures()\n\nReturn the path to the file that creates all figures used in the master thesis \"Structure-preserving Numerical Methods for Dispersive Shallow Water Model\" (2023). Executing this julia script may take a while.\n\nExamples\n\ninclude(DispersiveShallowWater.path_create_figures())\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.prim2cons","page":"Reference","title":"DispersiveShallowWater.prim2cons","text":"prim2cons(q, equations)\n\nConvert 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.\n\n\n\n\n\n","category":"function"},{"location":"ref/#DispersiveShallowWater.prim2prim-Tuple{Any, DispersiveShallowWater.AbstractEquations}","page":"Reference","title":"DispersiveShallowWater.prim2prim","text":"prim2prim(q, equations)\n\nReturn the primitive variables q. While this function is as trivial as identity, it is also as useful.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.semidiscretize-Tuple{Semidiscretization, Any}","page":"Reference","title":"DispersiveShallowWater.semidiscretize","text":"semidiscretize(semi::Semidiscretization, tspan)\n\nWrap the semidiscretization semi as an ODE problem in the time interval tspan that can be passed to solve from the SciML ecosystem.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.source_terms_manufactured-Tuple{Any, Any, Any, BBMBBMEquations1D}","page":"Reference","title":"DispersiveShallowWater.source_terms_manufactured","text":"source_terms_manufactured(q, x, t, equations::BBMBBMEquations1D, mesh)\n\nA smooth manufactured solution in combination with initial_condition_manufactured.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.source_terms_manufactured-Tuple{Any, Any, Any, BBMBBMVariableEquations1D}","page":"Reference","title":"DispersiveShallowWater.source_terms_manufactured","text":"source_terms_manufactured(q, x, t, equations::BBMBBMVariableEquations1D, mesh)\n\nA smooth manufactured solution in combination with initial_condition_manufactured.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.source_terms_manufactured-Tuple{Any, Any, Any, SvaerdKalischEquations1D}","page":"Reference","title":"DispersiveShallowWater.source_terms_manufactured","text":"source_terms_manufactured(q, x, t, equations::SvaerdKalischEquations1D, mesh)\n\nA smooth manufactured solution in combination with initial_condition_manufactured.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.trixi_include-Tuple{Module, AbstractString}","page":"Reference","title":"DispersiveShallowWater.trixi_include","text":"trixi_include([mod::Module=Main,] example::AbstractString; kwargs...)\n\ninclude the file example and evaluate its content in the global scope of module mod. You can override specific assignments in example by supplying keyword arguments. It's basic purpose is to make it easier to modify some parameters while running DispersiveShallowWater from the REPL. Additionally, this is used in tests to reduce the computational burden for CI while still providing examples with sensible default values for users.\n\nBefore replacing assignments in example, the keyword argument maxiters is inserted into calls to solve and DispersiveShallowWater.solve with it's default value used in the SciML ecosystem for ODEs, see the \"Miscellaneous\" section of the documentation.\n\nCopied from Trixi.jl.\n\nExamples\n\njulia> redirect_stdout(devnull) do\n trixi_include(@__MODULE__, joinpath(examples_dir(), \"bbm_bbm_1d\", \"bbm_bbm_1d_basic.jl\"),\n tspan=(0.0, 0.1))\n sol.t[end]\n end\n0.1\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.tstops-Union{Tuple{SciMLBase.DiscreteCallback{Condition, Affect!}}, Tuple{Affect!}, Tuple{Condition}} where {Condition, Affect!<:AnalysisCallback}","page":"Reference","title":"DispersiveShallowWater.tstops","text":"tstops(analysis_callback)\n\nReturn the time values that correspond to the saved values of the errors and integrals.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.varnames","page":"Reference","title":"DispersiveShallowWater.varnames","text":"varnames(conversion_function, equations)\n\nReturn the list of variable names when applying conversion_function to the conserved variables associated to equations. Common choices of the conversion_function are prim2prim and prim2cons.\n\n\n\n\n\n","category":"function"},{"location":"ref/#DispersiveShallowWater.velocity","page":"Reference","title":"DispersiveShallowWater.velocity","text":"velocity(q, equations)\n\nReturn the velocity of the primitive variables q for a given set of equations.\n\nq is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations).\n\n\n\n\n\n","category":"function"},{"location":"ref/#DispersiveShallowWater.waterheight","page":"Reference","title":"DispersiveShallowWater.waterheight","text":"waterheight(q, equations)\n\nReturn the waterheight of the primitive variables q for a given set of equations, i.e. the waterheight above the bathymetry.\n\nq is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations).\n\n\n\n\n\n","category":"function"},{"location":"ref/#DispersiveShallowWater.waterheight_total","page":"Reference","title":"DispersiveShallowWater.waterheight_total","text":"waterheight_total(q, equations)\n\nReturn the total waterheight of the primitive variables q for a given set of equations, i.e. the waterheight plus the bathymetry.\n\nq is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations).\n\n\n\n\n\n","category":"function"},{"location":"ref/#SummationByPartsOperators.grid-Tuple{Semidiscretization}","page":"Reference","title":"SummationByPartsOperators.grid","text":"grid(semi)\n\nGet the grid of a semidiscretization.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.@autoinfiltrate","page":"Reference","title":"DispersiveShallowWater.@autoinfiltrate","text":"@autoinfiltrate\n@autoinfiltrate condition::Bool\n\nInvoke 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.\n\nAs 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.\n\nNote: For this macro to work, the Infiltrator.jl package needs to be installed in your current Julia environment stack.\n\nSee also: Infiltrator.jl\n\nwarning: Internal use only\nPlease 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.\n\n\n\n\n\n","category":"macro"},{"location":"#DispersiveShallowWater.jl","page":"Home","title":"DispersiveShallowWater.jl","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"(Image: Docs-stable) (Image: Docs-dev) (Image: Build Status) (Image: Coveralls) (Image: Aqua QA) (Image: License: MIT) (Image: DOI)","category":"page"},{"location":"","page":"Home","title":"Home","text":"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:","category":"page"},{"location":"","page":"Home","title":"Home","text":"the BBM-BBM equations with varying bottom topography,\nthe dispersive shallow water model proposed by Magnus Svärd and Henrik Kalisch.","category":"page"},{"location":"","page":"Home","title":"Home","text":"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.","category":"page"},{"location":"#Installation","page":"Home","title":"Installation","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"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","category":"page"},{"location":"","page":"Home","title":"Home","text":"julia> using Pkg\n\njulia> Pkg.add([\"DispersiveShallowWater\", \"OrdinaryDiffEq\", \"Plots\"])","category":"page"},{"location":"","page":"Home","title":"Home","text":"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","category":"page"},{"location":"","page":"Home","title":"Home","text":"julia> Pkg.add(\"SummationByPartsOperators\")","category":"page"},{"location":"#Usage","page":"Home","title":"Usage","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"In the Julia REPL, first load the package DispersiveShallowWater.jl","category":"page"},{"location":"","page":"Home","title":"Home","text":"julia> using DispersiveShallowWater","category":"page"},{"location":"","page":"Home","title":"Home","text":"You can run a basic simulation that solves the BBM-BBM equations by executing","category":"page"},{"location":"","page":"Home","title":"Home","text":"julia> include(default_example());","category":"page"},{"location":"","page":"Home","title":"Home","text":"The result can be visualized by using the package Plots.jl","category":"page"},{"location":"","page":"Home","title":"Home","text":"julia> using Plots\njulia> plot(semi => sol)","category":"page"},{"location":"","page":"Home","title":"Home","text":"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\")).","category":"page"},{"location":"#Authors","page":"Home","title":"Authors","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"The package is developed and maintained by Joshua Lampert and was initiated as part of the master thesis \"Structure-Preserving Numerical Methods for Dispersive Shallow Water Models\" (2023). 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.","category":"page"},{"location":"#License-and-contributing","page":"Home","title":"License and contributing","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"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.","category":"page"}] }