From 124f44effdb8d42b73423c6b1c6a185d6b025d4e Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Wed, 11 Sep 2024 13:52:41 +0000 Subject: [PATCH] build based on 253223b --- previews/PR150/.documenter-siteinfo.json | 2 +- previews/PR150/changelog/index.html | 2 +- previews/PR150/changelog_tmp/index.html | 2 +- previews/PR150/code_of_conduct/index.html | 2 +- previews/PR150/contributing/index.html | 2 +- previews/PR150/development/index.html | 2 +- previews/PR150/index.html | 2 +- previews/PR150/license/index.html | 2 +- previews/PR150/overview/index.html | 2 +- previews/PR150/ref-trixibase/index.html | 2 +- previews/PR150/ref/index.html | 26 +++++++++++------------ previews/PR150/search_index.js | 2 +- 12 files changed, 24 insertions(+), 24 deletions(-) diff --git a/previews/PR150/.documenter-siteinfo.json b/previews/PR150/.documenter-siteinfo.json index dc27ba57..dcb2ab84 100644 --- a/previews/PR150/.documenter-siteinfo.json +++ b/previews/PR150/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.9.4","generation_timestamp":"2024-09-11T13:05:14","documenter_version":"1.7.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.9.4","generation_timestamp":"2024-09-11T13:52:36","documenter_version":"1.7.0"}} \ No newline at end of file diff --git a/previews/PR150/changelog/index.html b/previews/PR150/changelog/index.html index 22764725..72fec85f 100644 --- a/previews/PR150/changelog/index.html +++ b/previews/PR150/changelog/index.html @@ -1,2 +1,2 @@ -Changelog · DispersiveShallowWater.jl
GitHub

Changelog

DispersiveShallowWater.jl follows the interpretation of semantic versioning (semver) used in the Julia ecosystem. Notable changes will be documented in this file for human readability.

Changes in the v0.4 lifecycle

Added

  • Add BBMEquation1D (#150).

Changes when updating to v0.5 from v0.4.x

Changed

  • The BBMBBMVariableEquations1D were removed and BBMBBMEquations1D now supports a bathymetry_type to choose between a flat and a variable bathymetry (#147).
  • The default of bathymetry_type for the SerreGreenNaghdiEquations1D changed from bathymetry_flat to bathymetry_variable (#147).
  • bathymetry_type is now a keyword argument for all equations instead of a positional argument (#147).
  • The initial_condition_dingemans for the SerreGreenNaghdiEquations1D and HyperbolicSerreGreenNaghdiEquations1D was changed a bit to be more consistent with the other equations (#147).

Changes in the v0.4 lifecycle

Added

  • The SerreGreenNaghdiEquations1D were added for different types of bathymetry (#127, #135).
  • The HyperbolicSerreGreenNaghdiEquations1D were added for different types of bathymetry (#139).
  • The abstract interface AbstractShallowWaterEquations was added to unify several systems such as the SerreGreenNaghdiEquations1D, the BBMBBMEquations1D, and the SvärdKalischEquations1D (#127).
  • A new conversion function prim2phys was introduced, defaulting to prim2prim. prim2phys is the default conversion function for plotting.

Changes when updating to v0.4 from v0.3.x

Changed

  • Use ArrayPartition from RecursiveArrayTools.jl to store the solution of the ODEProblem (#118).

Changes in the v0.3 lifecycle

Added

  • Add possibility to pass vector of Ns to convergence_test (#113).
  • Performance improvements by using factorized matrices for linear systems solves (#108, #112, #114).
  • Reflecting boundary conditions are added for the BBM-BBM equations (#104, #109).
  • Fix for the BBMBBMVariableEquations1D, where the still water surface was neglected leading to a bug in the Dingemans setup (#91).

Changes when updating to v0.3 from v0.2.x

Changed

  • Add keyword argument start_from when plotting AnalysisCallback (#87).
  • Manufactured solution for Svärd-Kalisch equations uses a variable bathymetry (#84).

Changes in the v0.2 lifecycle

Added

  • Add SummaryCallback (#75).

Changes when updating to v0.2 from v0.1.x

Changed

  • The code from the master thesis of Joshua Lampert was separated (#69).
  • Add support for source terms (#65).
  • A higher order interpolation is used when plotting the solution at a value x outside the grid (#64).
+Changelog · DispersiveShallowWater.jl
GitHub

Changelog

DispersiveShallowWater.jl follows the interpretation of semantic versioning (semver) used in the Julia ecosystem. Notable changes will be documented in this file for human readability.

Changes in the v0.4 lifecycle

Added

  • Add BBMEquation1D (#150).

Changes when updating to v0.5 from v0.4.x

Changed

  • The BBMBBMVariableEquations1D were removed and BBMBBMEquations1D now supports a bathymetry_type to choose between a flat and a variable bathymetry (#147).
  • The default of bathymetry_type for the SerreGreenNaghdiEquations1D changed from bathymetry_flat to bathymetry_variable (#147).
  • bathymetry_type is now a keyword argument for all equations instead of a positional argument (#147).
  • The initial_condition_dingemans for the SerreGreenNaghdiEquations1D and HyperbolicSerreGreenNaghdiEquations1D was changed a bit to be more consistent with the other equations (#147).

Changes in the v0.4 lifecycle

Added

  • The SerreGreenNaghdiEquations1D were added for different types of bathymetry (#127, #135).
  • The HyperbolicSerreGreenNaghdiEquations1D were added for different types of bathymetry (#139).
  • The abstract interface AbstractShallowWaterEquations was added to unify several systems such as the SerreGreenNaghdiEquations1D, the BBMBBMEquations1D, and the SvärdKalischEquations1D (#127).
  • A new conversion function prim2phys was introduced, defaulting to prim2prim. prim2phys is the default conversion function for plotting.

Changes when updating to v0.4 from v0.3.x

Changed

  • Use ArrayPartition from RecursiveArrayTools.jl to store the solution of the ODEProblem (#118).

Changes in the v0.3 lifecycle

Added

  • Add possibility to pass vector of Ns to convergence_test (#113).
  • Performance improvements by using factorized matrices for linear systems solves (#108, #112, #114).
  • Reflecting boundary conditions are added for the BBM-BBM equations (#104, #109).
  • Fix for the BBMBBMVariableEquations1D, where the still water surface was neglected leading to a bug in the Dingemans setup (#91).

Changes when updating to v0.3 from v0.2.x

Changed

  • Add keyword argument start_from when plotting AnalysisCallback (#87).
  • Manufactured solution for Svärd-Kalisch equations uses a variable bathymetry (#84).

Changes in the v0.2 lifecycle

Added

  • Add SummaryCallback (#75).

Changes when updating to v0.2 from v0.1.x

Changed

  • The code from the master thesis of Joshua Lampert was separated (#69).
  • Add support for source terms (#65).
  • A higher order interpolation is used when plotting the solution at a value x outside the grid (#64).
diff --git a/previews/PR150/changelog_tmp/index.html b/previews/PR150/changelog_tmp/index.html index 92157153..a291b8b3 100644 --- a/previews/PR150/changelog_tmp/index.html +++ b/previews/PR150/changelog_tmp/index.html @@ -1,2 +1,2 @@ -Changelog · DispersiveShallowWater.jl
GitHub

Changelog

DispersiveShallowWater.jl follows the interpretation of semantic versioning (semver) used in the Julia ecosystem. Notable changes will be documented in this file for human readability.

Changes in the v0.4 lifecycle

Added

  • Add BBMEquation1D (#150).

Changes when updating to v0.5 from v0.4.x

Changed

  • The BBMBBMVariableEquations1D were removed and BBMBBMEquations1D now supports a bathymetry_type to choose between a flat and a variable bathymetry (#147).
  • The default of bathymetry_type for the SerreGreenNaghdiEquations1D changed from bathymetry_flat to bathymetry_variable (#147).
  • bathymetry_type is now a keyword argument for all equations instead of a positional argument (#147).
  • The initial_condition_dingemans for the SerreGreenNaghdiEquations1D and HyperbolicSerreGreenNaghdiEquations1D was changed a bit to be more consistent with the other equations (#147).

Changes in the v0.4 lifecycle

Added

  • The SerreGreenNaghdiEquations1D were added for different types of bathymetry (#127, #135).
  • The HyperbolicSerreGreenNaghdiEquations1D were added for different types of bathymetry (#139).
  • The abstract interface AbstractShallowWaterEquations was added to unify several systems such as the SerreGreenNaghdiEquations1D, the BBMBBMEquations1D, and the SvärdKalischEquations1D (#127).
  • A new conversion function prim2phys was introduced, defaulting to prim2prim. prim2phys is the default conversion function for plotting.

Changes when updating to v0.4 from v0.3.x

Changed

  • Use ArrayPartition from RecursiveArrayTools.jl to store the solution of the ODEProblem (#118).

Changes in the v0.3 lifecycle

Added

  • Add possibility to pass vector of Ns to convergence_test (#113).
  • Performance improvements by using factorized matrices for linear systems solves (#108, #112, #114).
  • Reflecting boundary conditions are added for the BBM-BBM equations (#104, #109).
  • Fix for the BBMBBMVariableEquations1D, where the still water surface was neglected leading to a bug in the Dingemans setup (#91).

Changes when updating to v0.3 from v0.2.x

Changed

  • Add keyword argument start_from when plotting AnalysisCallback (#87).
  • Manufactured solution for Svärd-Kalisch equations uses a variable bathymetry (#84).

Changes in the v0.2 lifecycle

Added

  • Add SummaryCallback (#75).

Changes when updating to v0.2 from v0.1.x

Changed

  • The code from the master thesis of Joshua Lampert was separated (#69).
  • Add support for source terms (#65).
  • A higher order interpolation is used when plotting the solution at a value x outside the grid (#64).
+Changelog · DispersiveShallowWater.jl
GitHub

Changelog

DispersiveShallowWater.jl follows the interpretation of semantic versioning (semver) used in the Julia ecosystem. Notable changes will be documented in this file for human readability.

Changes in the v0.4 lifecycle

Added

  • Add BBMEquation1D (#150).

Changes when updating to v0.5 from v0.4.x

Changed

  • The BBMBBMVariableEquations1D were removed and BBMBBMEquations1D now supports a bathymetry_type to choose between a flat and a variable bathymetry (#147).
  • The default of bathymetry_type for the SerreGreenNaghdiEquations1D changed from bathymetry_flat to bathymetry_variable (#147).
  • bathymetry_type is now a keyword argument for all equations instead of a positional argument (#147).
  • The initial_condition_dingemans for the SerreGreenNaghdiEquations1D and HyperbolicSerreGreenNaghdiEquations1D was changed a bit to be more consistent with the other equations (#147).

Changes in the v0.4 lifecycle

Added

  • The SerreGreenNaghdiEquations1D were added for different types of bathymetry (#127, #135).
  • The HyperbolicSerreGreenNaghdiEquations1D were added for different types of bathymetry (#139).
  • The abstract interface AbstractShallowWaterEquations was added to unify several systems such as the SerreGreenNaghdiEquations1D, the BBMBBMEquations1D, and the SvärdKalischEquations1D (#127).
  • A new conversion function prim2phys was introduced, defaulting to prim2prim. prim2phys is the default conversion function for plotting.

Changes when updating to v0.4 from v0.3.x

Changed

  • Use ArrayPartition from RecursiveArrayTools.jl to store the solution of the ODEProblem (#118).

Changes in the v0.3 lifecycle

Added

  • Add possibility to pass vector of Ns to convergence_test (#113).
  • Performance improvements by using factorized matrices for linear systems solves (#108, #112, #114).
  • Reflecting boundary conditions are added for the BBM-BBM equations (#104, #109).
  • Fix for the BBMBBMVariableEquations1D, where the still water surface was neglected leading to a bug in the Dingemans setup (#91).

Changes when updating to v0.3 from v0.2.x

Changed

  • Add keyword argument start_from when plotting AnalysisCallback (#87).
  • Manufactured solution for Svärd-Kalisch equations uses a variable bathymetry (#84).

Changes in the v0.2 lifecycle

Added

  • Add SummaryCallback (#75).

Changes when updating to v0.2 from v0.1.x

Changed

  • The code from the master thesis of Joshua Lampert was separated (#69).
  • Add support for source terms (#65).
  • A higher order interpolation is used when plotting the solution at a value x outside the grid (#64).
diff --git a/previews/PR150/code_of_conduct/index.html b/previews/PR150/code_of_conduct/index.html index 52e716db..af1489e3 100644 --- a/previews/PR150/code_of_conduct/index.html +++ b/previews/PR150/code_of_conduct/index.html @@ -1,2 +1,2 @@ -Code of Conduct · DispersiveShallowWater.jl
GitHub

Code of Conduct

Contributor Covenant Code of Conduct

Our Pledge

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

Our Standards

Examples of behavior that contributes to a positive environment for our community include:

  • Demonstrating empathy and kindness toward other people
  • Being respectful of differing opinions, viewpoints, and experiences
  • Giving and gracefully accepting constructive feedback
  • Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
  • Focusing on what is best not just for us as individuals, but for the overall community

Examples of unacceptable behavior include:

  • The use of sexualized language or imagery, and sexual attention or advances of any kind
  • Trolling, insulting or derogatory comments, and personal or political attacks
  • Public or private harassment
  • Publishing others' private information, such as a physical or email address, without their explicit permission
  • Other conduct which could reasonably be considered inappropriate in a professional setting

Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.

Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.

Scope

This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to Joshua Lampert or Hendrik Ranocha. All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the reporter of any incident.

Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:

1. Correction

Community Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.

Consequence: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.

2. Warning

Community Impact: A violation through a single incident or series of actions.

Consequence: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.

3. Temporary Ban

Community Impact: A serious violation of community standards, including sustained inappropriate behavior.

Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.

4. Permanent Ban

Community Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.

Consequence: A permanent ban from any sort of public interaction within the community.

Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0.

Community Impact Guidelines were inspired by Mozilla's code of conduct enforcement ladder.

[homepage]: https://www.contributor-covenant.org

For answers to common questions about this code of conduct, see the FAQ. Translations are also available there.

+Code of Conduct · DispersiveShallowWater.jl
GitHub

Code of Conduct

Contributor Covenant Code of Conduct

Our Pledge

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

Our Standards

Examples of behavior that contributes to a positive environment for our community include:

  • Demonstrating empathy and kindness toward other people
  • Being respectful of differing opinions, viewpoints, and experiences
  • Giving and gracefully accepting constructive feedback
  • Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
  • Focusing on what is best not just for us as individuals, but for the overall community

Examples of unacceptable behavior include:

  • The use of sexualized language or imagery, and sexual attention or advances of any kind
  • Trolling, insulting or derogatory comments, and personal or political attacks
  • Public or private harassment
  • Publishing others' private information, such as a physical or email address, without their explicit permission
  • Other conduct which could reasonably be considered inappropriate in a professional setting

Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.

Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.

Scope

This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to Joshua Lampert or Hendrik Ranocha. All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the reporter of any incident.

Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:

1. Correction

Community Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.

Consequence: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.

2. Warning

Community Impact: A violation through a single incident or series of actions.

Consequence: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.

3. Temporary Ban

Community Impact: A serious violation of community standards, including sustained inappropriate behavior.

Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.

4. Permanent Ban

Community Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.

Consequence: A permanent ban from any sort of public interaction within the community.

Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0.

Community Impact Guidelines were inspired by Mozilla's code of conduct enforcement ladder.

[homepage]: https://www.contributor-covenant.org

For answers to common questions about this code of conduct, see the FAQ. Translations are also available there.

diff --git a/previews/PR150/contributing/index.html b/previews/PR150/contributing/index.html index 36ed9813..33bc5d83 100644 --- a/previews/PR150/contributing/index.html +++ b/previews/PR150/contributing/index.html @@ -35,4 +35,4 @@ are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. + this project or the open source license(s) involved. diff --git a/previews/PR150/development/index.html b/previews/PR150/development/index.html index 4b1f3990..35f73f11 100644 --- a/previews/PR150/development/index.html +++ b/previews/PR150/development/index.html @@ -4,4 +4,4 @@ mkdir run cd run julia --project=. -e 'using Pkg; Pkg.develop(PackageSpec(path=".."))' # Install local DispersiveShallowWater.jl clone -julia --project=. -e 'using Pkg; Pkg.add(["OrdinaryDiffEq", "Plots", "SummationByPartsOperators"])' # Install additional packages

If you use other packages for executing DispersiveShallowWater.jl, you can add them to the project in the run directory in an analogous way as above. To use the Julia project within run, be sure to start the Julia REPL by

julia --project=.

if already inside the the run directory or julia --project=run if in the main directory of the repo.

Preview of the documentation

If you want to build the documentation locally, you can run

julia --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'

once from the DispersiveShallowWater.jl main directory to tell Documenter.jl to build the documentation of your local clone. To build the documentation, run

julia --project=docs --color=yes docs/make.jl

The resulting .html files can then be found in docs/build/ and you can look at them by opening them in a browser. For pull requests from the main repository (i.e. not from a fork), the documentation is automatically built and can be previewed under https://joshualampert.github.io/DispersiveShallowWater.jl/previews/PRXXX/ where XXX is the number of the pull request.

+julia --project=. -e 'using Pkg; Pkg.add(["OrdinaryDiffEq", "Plots", "SummationByPartsOperators"])' # Install additional packages

If you use other packages for executing DispersiveShallowWater.jl, you can add them to the project in the run directory in an analogous way as above. To use the Julia project within run, be sure to start the Julia REPL by

julia --project=.

if already inside the the run directory or julia --project=run if in the main directory of the repo.

Preview of the documentation

If you want to build the documentation locally, you can run

julia --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'

once from the DispersiveShallowWater.jl main directory to tell Documenter.jl to build the documentation of your local clone. To build the documentation, run

julia --project=docs --color=yes docs/make.jl

The resulting .html files can then be found in docs/build/ and you can look at them by opening them in a browser. For pull requests from the main repository (i.e. not from a fork), the documentation is automatically built and can be previewed under https://joshualampert.github.io/DispersiveShallowWater.jl/previews/PRXXX/ where XXX is the number of the pull request.

diff --git a/previews/PR150/index.html b/previews/PR150/index.html index 3cb2180a..b8c2dd9a 100644 --- a/previews/PR150/index.html +++ b/previews/PR150/index.html @@ -10,4 +10,4 @@ month={10}, howpublished={\url{https://github.com/JoshuaLampert/DispersiveShallowWater.jl}}, doi={10.5281/zenodo.10034636} -}

Authors

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

License and contributing

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

+}

Authors

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

License and contributing

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

diff --git a/previews/PR150/license/index.html b/previews/PR150/license/index.html index 0cbd564c..b84b020e 100644 --- a/previews/PR150/license/index.html +++ b/previews/PR150/license/index.html @@ -1,2 +1,2 @@ -License · DispersiveShallowWater.jl
GitHub

License

MIT License

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

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
GitHub

License

MIT License

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

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/previews/PR150/overview/index.html b/previews/PR150/overview/index.html index 3ced9c83..196e8ff8 100644 --- a/previews/PR150/overview/index.html +++ b/previews/PR150/overview/index.html @@ -187,4 +187,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)
[ Info: Saved animation to /home/runner/work/DispersiveShallowWater.jl/DispersiveShallowWater.jl/docs/build/shoaling_solution_dg.gif

shoaling solution DG

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 from the reproducibility repository of the master thesis of Joshua Lampert.

References

+gif(anim, "shoaling_solution_dg.gif", fps = 25)
[ Info: Saved animation to /home/runner/work/DispersiveShallowWater.jl/DispersiveShallowWater.jl/docs/build/shoaling_solution_dg.gif

shoaling solution DG

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 from the reproducibility repository of the master thesis of Joshua Lampert.

References

diff --git a/previews/PR150/ref-trixibase/index.html b/previews/PR150/ref-trixibase/index.html index d820b55c..df33854d 100644 --- a/previews/PR150/ref-trixibase/index.html +++ b/previews/PR150/ref-trixibase/index.html @@ -7,4 +7,4 @@ sol.t[end] end [ Info: You just called `trixi_include`. Julia may now compile the code, please be patient. -0.1source
TrixiBase.@trixi_timeit — Macro
@trixi_timeit timer() "some label" expression

Basically the same as a special case of @timeit_debug from TimerOutputs.jl, but without try ... finally ... end block. Thus, it's not exception-safe, but it also avoids some related performance problems. Since we do not use exception handling in Trixi.jl, that's not really an issue.

All @trixi_timeit timings can be disabled with disable_debug_timings. The timings should then be optimized away, allowing for truly zero-overhead.

See also disable_debug_timings, enable_debug_timings.

source
+0.1source
TrixiBase.@trixi_timeit — Macro
@trixi_timeit timer() "some label" expression

Basically the same as a special case of @timeit_debug from TimerOutputs.jl, but without try ... finally ... end block. Thus, it's not exception-safe, but it also avoids some related performance problems. Since we do not use exception handling in Trixi.jl, that's not really an issue.

All @trixi_timeit timings can be disabled with disable_debug_timings. The timings should then be optimized away, allowing for truly zero-overhead.

See also disable_debug_timings, enable_debug_timings.

source
diff --git a/previews/PR150/ref/index.html b/previews/PR150/ref/index.html index d253d8a5..5e558776 100644 --- a/previews/PR150/ref/index.html +++ b/previews/PR150/ref/index.html @@ -1,18 +1,18 @@ -DispersiveShallowWater · DispersiveShallowWater.jl
GitHub

DispersiveShallowWater.jl API

DispersiveShallowWater.DispersiveShallowWater — Module
DispersiveShallowWater

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

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

See also: DispersiveShallowWater.jl

source

Equations

DispersiveShallowWater.BBMEquation1D — Type
BBMEquation1D(; bathymetry_type = bathymetry_flat, eta0 = 0.0)

BBM (Benjamin–Bona–Mahony) equation in one spatial dimension. The equations are given by

\[\begin{aligned} +DispersiveShallowWater · DispersiveShallowWater.jl

GitHub

DispersiveShallowWater.jl API

DispersiveShallowWater.DispersiveShallowWater — Module
DispersiveShallowWater

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

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

See also: DispersiveShallowWater.jl

source

Equations

DispersiveShallowWater.BBMEquation1D — Type
BBMEquation1D(; bathymetry_type = bathymetry_flat, eta0 = 0.0)

BBM (Benjamin–Bona–Mahony) equation in one spatial dimension. The equations are given by

\[\begin{aligned} \eta_t + \eta\eta_x + \eta_x - \eta_{xxt} &= 0. -\end{aligned}\]

The unknown quantity of the BBM equation is the total water height $\eta$. The water height is given by $h = \eta - \eta_0$, where $\eta_0$ is the constant still-water surface.

Currently, the equations only support a flat bathymetry $b = 0$, see bathymetry_flat.

The BBM equation is first described in Benjamin, Bona, and Mahony (1972). The semidiscretization implemented here is developed in Ranocha, Mitsotakis, and Ketcheson (2020). It conserves

  • the total water mass (integral of $h$) as a linear invariant
  • the total modified energy

for periodic boundary conditions.

  • Thomas B. Benjamin, Jerry L. Bona and John J. Mahony (1972) Model equations for long waves in nonlinear dispersive systems DOI: 10.1098/rsta.1972.0032
  • Hendrik Ranocha, Dimitrios Mitsotakis and David I. Ketcheson (2020) A Broad Class of Conservative Numerical Methods for Dispersive Wave Equations DOI: 10.4208/cicp.OA-2020-0119
source
DispersiveShallowWater.energy_total_modified! — Method
energy_total_modified!(e, q, equations::BBMEquation1D, cache)

Return the modified total energy e of the primitive variables q_global for the BBMEquation1D. The energy_total_modified is a conserved quantity (for periodic boundary conditions).

It is given by

\[\frac{1}{2} \eta^2 + \frac{1}{2} \eta_x^2.\]

q_global is a vector of the primitive variables at ALL nodes. cache needs to hold the SBP operators used by the solver.

See also energy_total_modified.

source
DispersiveShallowWater.initial_condition_convergence_test — Method
initial_condition_convergence_test(x, t, equations::BBMEquation1D, mesh)

A travelling-wave solution used for convergence tests in a periodic domain.

See section 4.1.3 in (there is an error in paper: it should be sech^2 instead of cosh):

  • Hendrik Ranocha, Dimitrios Mitsotakis and David I. Ketcheson (2020) A Broad Class of Conservative Numerical Methods for Dispersive Wave Equations DOI: 10.4208/cicp.OA-2020-0119
source
DispersiveShallowWater.BBMBBMEquations1D — Type
BBMBBMEquations1D(; bathymetry_type = bathymetry_variable,
+\end{aligned}\]
The unknown quantity of the BBM equation is the total water height $\eta$. The water height is given by $h = \eta - \eta_0$, where $\eta_0$ is the constant still-water surface.
Currently, the equations only support a flat bathymetry $b = 0$, see bathymetry_flat.
The BBM equation is first described in Benjamin, Bona, and Mahony (1972). The semidiscretization implemented here is developed in Ranocha, Mitsotakis, and Ketcheson (2020). It conserves
  • the total water mass (integral of $h$) as a linear invariant
  • a quadratic invariant (integral of $\eta^2 + \eta_x^2$), which is called here energy_total_modified (and entropy_modified) because it contains derivatives of the solution
for periodic boundary conditions.
  • Thomas B. Benjamin, Jerry L. Bona and John J. Mahony (1972) Model equations for long waves in nonlinear dispersive systems DOI: 10.1098/rsta.1972.0032
  • Hendrik Ranocha, Dimitrios Mitsotakis and David I. Ketcheson (2020) A Broad Class of Conservative Numerical Methods for Dispersive Wave Equations DOI: 10.4208/cicp.OA-2020-0119
source
DispersiveShallowWater.energy_total_modified! — Method
energy_total_modified!(e, q, equations::BBMEquation1D, cache)

Return the modified total energy e of the primitive variables q_global for the BBMEquation1D. The energy_total_modified is a conserved quantity (for periodic boundary conditions).

It is given by

\[\frac{1}{2} \eta^2 + \frac{1}{2} \eta_x^2.\]

q_global is a vector of the primitive variables at ALL nodes. cache needs to hold the SBP operators used by the solver.

See also energy_total_modified.

source
DispersiveShallowWater.initial_condition_convergence_test — Method
initial_condition_convergence_test(x, t, equations::BBMEquation1D, mesh)

A travelling-wave solution used for convergence tests in a periodic domain.

See section 4.1.3 in (there is an error in paper: it should be sech^2 instead of cosh):

  • Hendrik Ranocha, Dimitrios Mitsotakis and David I. Ketcheson (2020) A Broad Class of Conservative Numerical Methods for Dispersive Wave Equations DOI: 10.4208/cicp.OA-2020-0119
source
DispersiveShallowWater.BBMBBMEquations1D — Type
BBMBBMEquations1D(; bathymetry_type = bathymetry_variable,
                   gravity_constant, eta0 = 0.0)

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

\[\begin{aligned} \eta_t + ((\eta + D)v)_x - \frac{1}{6}D^2\eta_{xxt} &= 0,\\ v_t + g\eta_x + \left(\frac{1}{2}v^2\right)_x - \frac{1}{6}D^2v_{xxt} &= 0. \end{aligned}\]

The unknown quantities of the BBM-BBM equations are the total water height $\eta$ and the velocity $v$. The gravitational constant is denoted by g and the constant bottom topography (bathymetry) $b = \eta_0 - D$. The water height above the bathymetry is therefore given by $h = \eta - \eta_0 + D$. The BBM-BBM equations are only implemented for $\eta_0 = 0$.

Two types of bathymetry_type are supported:

For the general case of variable vathymetry the BBM-BBM equations are

\[\begin{aligned} \eta_t + ((\eta + D)v)_x - \frac{1}{6}(D^2\eta_{xt})_x &= 0,\\ v_t + g\eta_x + \left(\frac{1}{2}v^2\right)_x - \frac{1}{6}(D^2v_t)_{xx} &= 0. -\end{aligned}\]

One reference for the BBM-BBM system can be found in Bona et al. (1998). The semidiscretization implemented here was developed for flat bathymetry in Ranocha et al. (2020) and generalized for a variable bathymetry in Lampert and Ranocha (2024). It conserves

  • the total water mass (integral of $h$) as a linear invariant
  • the total velocity (integral of $v$) as a linear invariant for flat bathymetry
  • the total energy

for periodic boundary conditions (see Lampert, Ranocha). For reflecting boundary conditions, the semidiscretization conserves

  • the total water (integral of $h$) as a linear invariant
  • the total energy.

Additionally, it is well-balanced for the lake-at-rest stationary solution, see Lampert and Ranocha (2024).

  • Jerry L. Bona, Min Chen (1998) A Boussinesq system for two-way propagation of nonlinear dispersive waves DOI: 10.1016/S0167-2789(97)00249-2
  • Hendrik Ranocha, Dimitrios Mitsotakis, David I. Ketcheson (2020) A Broad Class of Conservative Numerical Methods for Dispersive Wave Equations DOI: 10.4208/cicp.OA-2020-0119
  • Joshua Lampert, Hendrik Ranocha (2024) Structure-Preserving Numerical Methods for Two Nonlinear Systems of Dispersive Wave Equations DOI: 10.48550/arXiv.2402.16669
source
DispersiveShallowWater.initial_condition_dingemans — Method
initial_condition_dingemans(x, t, equations::BBMBBMEquations1D, mesh)

The initial condition that uses the dispersion relation of the Euler equations to approximate waves generated by a wave maker as it is done by experiments of Dingemans. The topography is a trapezoidal.

Translation of water height

The initial condition for the water height is translated to be around 0, which is needed for the simulation because the BBMBBMEquations1D are only implemented for $\eta_0 = 0$.

References:

  • Magnus Svärd, Henrik Kalisch (2023) A novel energy-bounded Boussinesq model and a well-balanced and stable numerical discretization arXiv: 2302.09924
  • Maarten W. Dingemans (1994) Comparison of computations with Boussinesq-like models and laboratory measurements link
source
DispersiveShallowWater.AbstractShallowWaterEquations — Type
AbstractShallowWaterEquations{NDIMS, NVARS}

An abstract supertype of all equation system that contain the classical shallow water equations as a subsystem, e.g., the BBMBBMEquations1D, the SvaerdKalischEquations1D, and the SerreGreenNaghdiEquations1D. In 1D, the shallow water equations with flat bathymetry are given by

\[\begin{aligned} +\end{aligned}\]

One reference for the BBM-BBM system can be found in Bona et al. (1998). The semidiscretization implemented here was developed for flat bathymetry in Ranocha et al. (2020) and generalized for a variable bathymetry in Lampert and Ranocha (2024). It conserves

  • the total water mass (integral of $h$) as a linear invariant
  • the total velocity (integral of $v$) as a linear invariant for flat bathymetry
  • the total energy

for periodic boundary conditions (see Lampert, Ranocha). For reflecting boundary conditions, the semidiscretization conserves

  • the total water (integral of $h$) as a linear invariant
  • the total energy.

Additionally, it is well-balanced for the lake-at-rest stationary solution, see Lampert and Ranocha (2024).

  • Jerry L. Bona, Min Chen (1998) A Boussinesq system for two-way propagation of nonlinear dispersive waves DOI: 10.1016/S0167-2789(97)00249-2
  • Hendrik Ranocha, Dimitrios Mitsotakis, David I. Ketcheson (2020) A Broad Class of Conservative Numerical Methods for Dispersive Wave Equations DOI: 10.4208/cicp.OA-2020-0119
  • Joshua Lampert, Hendrik Ranocha (2024) Structure-Preserving Numerical Methods for Two Nonlinear Systems of Dispersive Wave Equations DOI: 10.48550/arXiv.2402.16669
source
DispersiveShallowWater.initial_condition_dingemans — Method
initial_condition_dingemans(x, t, equations::BBMBBMEquations1D, mesh)

The initial condition that uses the dispersion relation of the Euler equations to approximate waves generated by a wave maker as it is done by experiments of Dingemans. The topography is a trapezoidal.

Translation of water height

The initial condition for the water height is translated to be around 0, which is needed for the simulation because the BBMBBMEquations1D are only implemented for $\eta_0 = 0$.

References:

  • Magnus Svärd, Henrik Kalisch (2023) A novel energy-bounded Boussinesq model and a well-balanced and stable numerical discretization arXiv: 2302.09924
  • Maarten W. Dingemans (1994) Comparison of computations with Boussinesq-like models and laboratory measurements link
source
DispersiveShallowWater.AbstractShallowWaterEquations — Type
AbstractShallowWaterEquations{NDIMS, NVARS}

An abstract supertype of all equation system that contain the classical shallow water equations as a subsystem, e.g., the BBMBBMEquations1D, the SvaerdKalischEquations1D, and the SerreGreenNaghdiEquations1D. In 1D, the shallow water equations with flat bathymetry are given by

\[\begin{aligned} h_t + (h v)_x &= 0,\\ h v_t + \frac{1}{2} g (h^2)_x + \frac{1}{2} h (v^2)_x &= 0, -\end{aligned}\]

where $h$ is the waterheight, $v$ the velocity, and $g$ the gravity_constant.

source
DispersiveShallowWater.bathymetry — Method
bathymetry(q, equations)

Return the bathymetry of the primitive variables q for a given set of equations.

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

source
DispersiveShallowWater.cons2prim — Method
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.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 — Method
energy_total(q, equations)

Return the total energy of the primitive variables q for a given set of equations. For all AbstractShallowWaterEquations, the total energy is given by the sum of the kinetic and potential energy of the shallow water subsystem, i.e.,

\[\frac{1}{2} h v^2 + \frac{1}{2} g \eta^2\]

in 1D, where $h$ is the waterheight, $\eta = h + b$ the waterheight_total, $v$ the velocity, and $g$ the gravity_constant.

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

source
DispersiveShallowWater.energy_total_modified — Method
energy_total_modified(q_global, equations, cache)

Return the modified total energy of the primitive variables q_global for the equations. This modified total energy is a conserved quantity and can contain additional terms compared to the usual energy_total. For example, for the SvaerdKalischEquations1D and the SerreGreenNaghdiEquations1D, it contains additional terms depending on the derivative of the velocity $v_x$ modeling non-hydrostatic contributions.

q_global is a vector of the primitive variables at ALL nodes. cache needs to hold the SBP operators used by the solver if non-hydrostatic terms are present.

Internally, this function allocates a vector for the output and calls DispersiveShallowWater.energy_total_modified!.

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-BathymetryVariable"
source
DispersiveShallowWater.hyperbolic_approximation_limit — Method
DispersiveShallowWater.hyperbolic_approximation_limit(equations)

If the equations are a hyperbolic approximation of another set of equations, return the equations of the limit system. Otherwise, return the input equations.

See also is_hyperbolic_appproximation and prim2phys.

Implementation details

This function is mostly used for some internal dispatch. For example, it allows to return a reduced set of variables from initial conditions for hyperbolic approximations.

source
DispersiveShallowWater.initial_condition_dingemans — Method
initial_condition_dingemans(x, t, equations::AbstractShallowWaterEquations, mesh)

The initial condition that uses the dispersion relation of the Euler equations to approximate waves generated by a wave maker as it is done by experiments of Dingemans. The topography is a trapezoidal. It is assumed that equations.eta0 = 0.8.

References:

  • Magnus Svärd, Henrik Kalisch (2023) A novel energy-bounded Boussinesq model and a well-balanced and stable numerical discretization arXiv: 2302.09924
  • Maarten W. Dingemans (1994) Comparison of computations with Boussinesq-like models and laboratory measurements link
source
DispersiveShallowWater.initial_condition_discontinuous_well_balancedness — Method
initial_condition_discontinuous_well_balancedness(x, t, equations::AbstractShallowWaterEquations, mesh)

Setup a truly discontinuous bottom topography function for this academic lake-at-rest test case of well-balancedness, i.e. eta is constant and v is zero everywhere. The error for this lake-at-rest test case ∫|η-η₀| should be around machine roundoff.

source
DispersiveShallowWater.is_hyperbolic_appproximation — Method
DispersiveShallowWater.is_hyperbolic_appproximation(equations)

Returns Val{true}() if the equations are a hyperbolic approximation of another set of equations and Val{false}() otherwise (default). For example, the HyperbolicSerreGreenNaghdiEquations1D are a hyperbolic approximation of the SerreGreenNaghdiEquations1D.

See also hyperbolic_approximation_limit and prim2phys.

Implementation details

This function is mostly used for some internal dispatch. For example, it allows to return a reduced set of variables from initial conditions for hyperbolic approximations.

source
DispersiveShallowWater.momentum — Method
momentum(q, equations)

Return the momentum/discharge of the primitive variables q for a given set of equations, i.e., the waterheight times the velocity.

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

source
DispersiveShallowWater.prim2cons — Method
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.prim2phys — Method
prim2phys(q, equations)

Convert the primitive variables q to the physically meaningful variables for a given set of equations. By default, this is the same as prim2prim for most equations. However, some equations like the HyperbolicSerreGreenNaghdiEquations1D return a reduced set of variables since they are a hyperbolic approximation of another set of equations (in this case the SerreGreenNaghdiEquations1D).

See also is_hyperbolic_appproximation and hyperbolic_approximation_limit.

q is a vector type of the correct length nvariables(equations). Notice the function doesn't include any error checks for the purpose of efficiency, so please make sure your input is correct.

source
DispersiveShallowWater.velocity — Method
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 — Method
waterheight(q, equations)

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

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

See also waterheight_total, bathymetry.

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

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

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

source
DispersiveShallowWater.bathymetry — Method
bathymetry(q, equations)

Return the bathymetry of the primitive variables q for a given set of equations.

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

source
DispersiveShallowWater.cons2prim — Method
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.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 — Method
energy_total(q, equations)

Return the total energy of the primitive variables q for a given set of equations. For all AbstractShallowWaterEquations, the total energy is given by the sum of the kinetic and potential energy of the shallow water subsystem, i.e.,

\[\frac{1}{2} h v^2 + \frac{1}{2} g \eta^2\]

in 1D, where $h$ is the waterheight, $\eta = h + b$ the waterheight_total, $v$ the velocity, and $g$ the gravity_constant.

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

source
DispersiveShallowWater.energy_total_modified — Method
energy_total_modified(q_global, equations, cache)

Return the modified total energy of the primitive variables q_global for the equations. This modified total energy is a conserved quantity and can contain additional terms compared to the usual energy_total. For example, for the SvaerdKalischEquations1D and the SerreGreenNaghdiEquations1D, it contains additional terms depending on the derivative of the velocity $v_x$ modeling non-hydrostatic contributions. For equations, which are not AbstractShallowWaterEquations, the modified total energy does not have to be an extension of the usual energy_total and does not have to be related to a physical energy. However, it is still a conserved quantity and contains derivatives of the solution.

q_global is a vector of the primitive variables at ALL nodes. cache needs to hold the SBP operators used by the solver if non-hydrostatic terms are present.

Internally, this function allocates a vector for the output and calls DispersiveShallowWater.energy_total_modified!.

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-BathymetryVariable"
source
DispersiveShallowWater.hyperbolic_approximation_limit — Method
DispersiveShallowWater.hyperbolic_approximation_limit(equations)

If the equations are a hyperbolic approximation of another set of equations, return the equations of the limit system. Otherwise, return the input equations.

See also is_hyperbolic_appproximation and prim2phys.

Implementation details

This function is mostly used for some internal dispatch. For example, it allows to return a reduced set of variables from initial conditions for hyperbolic approximations.

source
DispersiveShallowWater.initial_condition_dingemans — Method
initial_condition_dingemans(x, t, equations::AbstractShallowWaterEquations, mesh)

The initial condition that uses the dispersion relation of the Euler equations to approximate waves generated by a wave maker as it is done by experiments of Dingemans. The topography is a trapezoidal. It is assumed that equations.eta0 = 0.8.

References:

  • Magnus Svärd, Henrik Kalisch (2023) A novel energy-bounded Boussinesq model and a well-balanced and stable numerical discretization arXiv: 2302.09924
  • Maarten W. Dingemans (1994) Comparison of computations with Boussinesq-like models and laboratory measurements link
source
DispersiveShallowWater.initial_condition_discontinuous_well_balancedness — Method
initial_condition_discontinuous_well_balancedness(x, t, equations::AbstractShallowWaterEquations, mesh)

Setup a truly discontinuous bottom topography function for this academic lake-at-rest test case of well-balancedness, i.e. eta is constant and v is zero everywhere. The error for this lake-at-rest test case ∫|η-η₀| should be around machine roundoff.

source
DispersiveShallowWater.is_hyperbolic_appproximation — Method
DispersiveShallowWater.is_hyperbolic_appproximation(equations)

Returns Val{true}() if the equations are a hyperbolic approximation of another set of equations and Val{false}() otherwise (default). For example, the HyperbolicSerreGreenNaghdiEquations1D are a hyperbolic approximation of the SerreGreenNaghdiEquations1D.

See also hyperbolic_approximation_limit and prim2phys.

Implementation details

This function is mostly used for some internal dispatch. For example, it allows to return a reduced set of variables from initial conditions for hyperbolic approximations.

source
DispersiveShallowWater.momentum — Method
momentum(q, equations)

Return the momentum/discharge of the primitive variables q for a given set of equations, i.e., the waterheight times the velocity.

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

source
DispersiveShallowWater.prim2cons — Method
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.prim2phys — Method
prim2phys(q, equations)

Convert the primitive variables q to the physically meaningful variables for a given set of equations. By default, this is the same as prim2prim for most equations. However, some equations like the HyperbolicSerreGreenNaghdiEquations1D return a reduced set of variables since they are a hyperbolic approximation of another set of equations (in this case the SerreGreenNaghdiEquations1D).

See also is_hyperbolic_appproximation and hyperbolic_approximation_limit.

q is a vector type of the correct length nvariables(equations). Notice the function doesn't include any error checks for the purpose of efficiency, so please make sure your input is correct.

source
DispersiveShallowWater.velocity — Method
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 — Method
waterheight(q, equations)

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

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

See also waterheight_total, bathymetry.

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

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

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

source
DispersiveShallowWater.HyperbolicSerreGreenNaghdiEquations1D — Type
HyperbolicSerreGreenNaghdiEquations1D(; bathymetry_type = bathymetry_mild_slope,
                                       gravity_constant,
                                       eta0 = 0.0,
                                       lambda)

Hyperbolic approximation of the Serre-Green-Naghdi system in one spatial dimension. The equations for flat bathymetry are given by

\[\begin{aligned} @@ -28,8 +28,8 @@ + \biggl( g h + \frac{\lambda}{2} (1 - H / h) \biggr) b_x &= 0,\\ h w_t + h v w_x &= \lambda (1 - H / h),\\ H_t + H_x u + \frac{3}{2} b_x v &= w. -\end{aligned}\]

References for the hyperbolized Serre-Green-Naghdi system can be found in

  • Favrie and Gavrilyuk. A rapid numerical method for solving Serre-Green-Naghdi equations describing long free surface gravity waves DOI: 10.1088/1361-6544/aa712d
  • Busto, Dumbser, Escalante, Favrie, and Gavrilyuk. On High Order ADER Discontinuous Galerkin Schemes for First Order Hyperbolic Reformulations of Nonlinear Dispersive Systems DOI: 10.1007/s10915-021-01429-8

The semidiscretization implemented here conserves

  • the total water mass (integral of $h$) as a linear invariant
  • the total modified energy

for periodic boundary conditions (see Ranocha and Ricchiuto (2024)). Additionally, it is well-balanced for the lake-at-rest stationary solution, see

  • Hendrik Ranocha and Mario Ricchiuto (2024) Structure-preserving approximations of the Serre-Green-Naghdi equations in standard and hyperbolic form arXiv: 2408.02665
source
DispersiveShallowWater.energy_total_modified! — Method
DispersiveShallowWater.energy_total_modified!(e, q_global, equations::HyperbolicSerreGreenNaghdiEquations1D, cache)

Return the modified total energy e of the primitive variables q_global for the HyperbolicSerreGreenNaghdiEquations1D. It contains additional terms compared to the usual energy_total modeling non-hydrostatic contributions. The energy_total_modified is a conserved quantity (for periodic boundary conditions).

For a bathymetry_mild_slope (and a bathymetry_flat), the total modified energy is given by

\[\frac{1}{2} g \eta^2 + \frac{1}{2} h v^2 + -\frac{1}{6} h w^2 + \frac{\lambda}{6} h (1 - \eta / h)^2.\]

q_global is a vector of the primitive variables at ALL nodes.

See also energy_total_modified.

source
DispersiveShallowWater.initial_condition_soliton — Method
initial_condition_soliton(x, t, equations::HyperbolicSerreGreenNaghdiEquations1D, mesh)

A soliton solution of the SerreGreenNaghdiEquations1D used for convergence tests in a periodic domain. This is physically the same as initial_condition_convergence_test for the SerreGreenNaghdiEquations1D. Please note that this is not an exact solution of the HyperbolicSerreGreenNaghdiEquations1D (only in the limit of the relaxation parameter $\lambda \to \infty$).

See also initial_condition_convergence_test.

source
DispersiveShallowWater.SerreGreenNaghdiEquations1D — Type
SerreGreenNaghdiEquations1D(; bathymetry_type = bathymetry_variable,
+\end{aligned}\]
References for the hyperbolized Serre-Green-Naghdi system can be found in
  • Favrie and Gavrilyuk. A rapid numerical method for solving Serre-Green-Naghdi equations describing long free surface gravity waves DOI: 10.1088/1361-6544/aa712d
  • Busto, Dumbser, Escalante, Favrie, and Gavrilyuk. On High Order ADER Discontinuous Galerkin Schemes for First Order Hyperbolic Reformulations of Nonlinear Dispersive Systems DOI: 10.1007/s10915-021-01429-8
The semidiscretization implemented here conserves
  • the total water mass (integral of $h$) as a linear invariant
  • the total modified energy
for periodic boundary conditions (see Ranocha and Ricchiuto (2024)). Additionally, it is well-balanced for the lake-at-rest stationary solution, see
  • Hendrik Ranocha and Mario Ricchiuto (2024) Structure-preserving approximations of the Serre-Green-Naghdi equations in standard and hyperbolic form arXiv: 2408.02665
source
DispersiveShallowWater.energy_total_modified! — Method
DispersiveShallowWater.energy_total_modified!(e, q_global, equations::HyperbolicSerreGreenNaghdiEquations1D, cache)

Return the modified total energy e of the primitive variables q_global for the HyperbolicSerreGreenNaghdiEquations1D. It contains additional terms compared to the usual energy_total modeling non-hydrostatic contributions. The energy_total_modified is a conserved quantity (for periodic boundary conditions).

For a bathymetry_mild_slope (and a bathymetry_flat), the total modified energy is given by

\[\frac{1}{2} g \eta^2 + \frac{1}{2} h v^2 + +\frac{1}{6} h w^2 + \frac{\lambda}{6} h (1 - \eta / h)^2.\]

q_global is a vector of the primitive variables at ALL nodes.

See also energy_total_modified.

source
DispersiveShallowWater.initial_condition_soliton — Method
initial_condition_soliton(x, t, equations::HyperbolicSerreGreenNaghdiEquations1D, mesh)

A soliton solution of the SerreGreenNaghdiEquations1D used for convergence tests in a periodic domain. This is physically the same as initial_condition_convergence_test for the SerreGreenNaghdiEquations1D. Please note that this is not an exact solution of the HyperbolicSerreGreenNaghdiEquations1D (only in the limit of the relaxation parameter $\lambda \to \infty$).

See also initial_condition_convergence_test.

source
DispersiveShallowWater.SerreGreenNaghdiEquations1D — Type
SerreGreenNaghdiEquations1D(; bathymetry_type = bathymetry_variable,
                             gravity_constant, eta0 = 0.0)

Serre-Green-Naghdi system in one spatial dimension. The equations for flat bathymetry are given by

\[\begin{aligned} h_t + (h v)_x &= 0,\\ h v_t - \frac{1}{3} (h^3 v_{tx})_x + \frac{1}{2} g (h^2)_x + \frac{1}{2} h (v^2)_x + p_x &= 0,\\ @@ -49,7 +49,7 @@ p &= \frac{1}{3} h^3 v_{x}^2 - \frac{1}{3} h^3 v v_{xx} + \frac{1}{2} h^2 v (b_x v)_x,\\ \psi &= \frac{1}{4} h v (b_x v)_x. -\end{aligned}\]

References for the Serre-Green-Naghdi system can be found in

The semidiscretization implemented here conserves

  • the total water mass (integral of $h$) as a linear invariant
  • the total momentum (integral of $h v$) as a nonlinear invariant if the bathymetry is constant
  • the total modified energy

for periodic boundary conditions (see Ranocha and Ricchiuto (2024)). Additionally, it is well-balanced for the lake-at-rest stationary solution, see

  • Hendrik Ranocha and Mario Ricchiuto (2024) Structure-preserving approximations of the Serre-Green-Naghdi equations in standard and hyperbolic form arXiv: 2408.02665
source
DispersiveShallowWater.energy_total_modified! — Method
DispersiveShallowWater.energy_total_modified!(e, q_global, equations::SerreGreenNaghdiEquations1D, cache)

Return the modified total energy e of the primitive variables q_global for the SerreGreenNaghdiEquations1D. It contains an additional term containing a derivative compared to the usual energy_total modeling non-hydrostatic contributions. The energy_total_modified is a conserved quantity (for periodic boundary conditions).

For a bathymetry_flat the total modified energy is given by

\[\frac{1}{2} g \eta^2 + \frac{1}{2} h v^2 + \frac{1}{6} h^3 v_x^2.\]

For a bathymetry_mild_slope the total modified energy is given by

\[\frac{1}{2} g \eta^2 + \frac{1}{2} h v^2 + \frac{1}{6} h (-h v_x + 1.5 v b_x)^2.\]

For a bathymetry_variable the total modified energy has the additional term

\[+ \frac{1}{8} h (v b_x)^2.\]

q_global is a vector of the primitive variables at ALL nodes. cache needs to hold the SBP operators used by the solver.

See also energy_total_modified.

source
DispersiveShallowWater.SvaerdKalischEquations1D — Type
SvaerdKalischEquations1D(; bathymetry_type = bathymetry_variable,
+\end{aligned}\]
References for the Serre-Green-Naghdi system can be found in
The semidiscretization implemented here conserves
  • the total water mass (integral of $h$) as a linear invariant
  • the total momentum (integral of $h v$) as a nonlinear invariant if the bathymetry is constant
  • the total modified energy
for periodic boundary conditions (see Ranocha and Ricchiuto (2024)). Additionally, it is well-balanced for the lake-at-rest stationary solution, see
  • Hendrik Ranocha and Mario Ricchiuto (2024) Structure-preserving approximations of the Serre-Green-Naghdi equations in standard and hyperbolic form arXiv: 2408.02665
source
DispersiveShallowWater.energy_total_modified! — Method
DispersiveShallowWater.energy_total_modified!(e, q_global, equations::SerreGreenNaghdiEquations1D, cache)

Return the modified total energy e of the primitive variables q_global for the SerreGreenNaghdiEquations1D. It contains an additional term containing a derivative compared to the usual energy_total modeling non-hydrostatic contributions. The energy_total_modified is a conserved quantity (for periodic boundary conditions).

For a bathymetry_flat the total modified energy is given by

\[\frac{1}{2} g \eta^2 + \frac{1}{2} h v^2 + \frac{1}{6} h^3 v_x^2.\]

For a bathymetry_mild_slope the total modified energy is given by

\[\frac{1}{2} g \eta^2 + \frac{1}{2} h v^2 + \frac{1}{6} h (-h v_x + 1.5 v b_x)^2.\]

For a bathymetry_variable the total modified energy has the additional term

\[+ \frac{1}{8} h (v b_x)^2.\]

q_global is a vector of the primitive variables at ALL nodes. cache needs to hold the SBP operators used by the solver.

See also energy_total_modified.

source
DispersiveShallowWater.SvaerdKalischEquations1D — Type
SvaerdKalischEquations1D(; bathymetry_type = bathymetry_variable,
                          gravity_constant, eta0 = 0.0, alpha = 0.0,
                          beta = 0.2308939393939394, gamma = 0.04034343434343434)

Dispersive system by Svärd and Kalisch (2023) in one spatial dimension. The equations for variable bathymetry are given in conservative variables by

\[\begin{aligned} h_t + (hv)_x &= (\hat\alpha(\hat\alpha(h + b)_x)_x)_x,\\ @@ -57,14 +57,14 @@ \end{aligned}\]

where $\hat\alpha^2 = \alpha\sqrt{gD}D^2$, $\hat\beta = \beta D^3$, $\hat\gamma = \gamma\sqrt{gD}D^3$. The coefficients $\alpha$, $\beta$ and $\gamma$ are provided in dimensionless form and $D = \eta_0 - b$ is the still-water depth and eta0 is the still-water surface (lake-at-rest). The equations can be rewritten in primitive variables as

\[\begin{aligned} \eta_t + ((\eta + D)v)_x &= (\hat\alpha(\hat\alpha\eta_x)_x)_x,\\ v_t(\eta + D) - v((\eta + D)v)_x + ((\eta + D)v^2)_x + g(\eta + D)\eta_x &= (\hat\alpha v(\hat\alpha\eta_x)_x)_x - v(\hat\alpha(\hat\alpha\eta_x)_x)_x + (\hat\beta v_x)_{xt} + \frac{1}{2}(\hat\gamma v_x)_{xx} + \frac{1}{2}(\hat\gamma v_{xx})_x. -\end{aligned}\]

The unknown quantities of the Svärd-Kalisch equations are the total water height $\eta$ and the velocity $v$. The gravitational constant is denoted by g and the bottom topography (bathymetry) $b = \eta_0 - D$. The water height above the bathymetry is therefore given by $h = \eta - \eta_0 + D$.

Currently, the equations only support a general variable bathymetry, see bathymetry_variable.

SvärdKalischEquations1D is an alias for SvaerdKalischEquations1D.

The equations by Svärd and Kalisch are presented and analyzed in Svärd and Kalisch (2023). The semidiscretization implemented here conserves

  • the total water mass (integral of $h$) as a linear invariant
  • the total momentum (integral of $h v$) as a nonlinear invariant for flat bathymetry
  • the total modified energy

for periodic boundary conditions (see Lampert, Ranocha). Additionally, it is well-balanced for the lake-at-rest stationary solution, see Lampert and Ranocha (2024).

  • Magnus Svärd, Henrik Kalisch (2023) A novel energy-bounded Boussinesq model and a well-balanced and stable numerical discretization arXiv: 2302.09924
  • Joshua Lampert, Hendrik Ranocha (2024) Structure-Preserving Numerical Methods for Two Nonlinear Systems of Dispersive Wave Equations DOI: 10.48550/arXiv.2402.16669
source
DispersiveShallowWater.energy_total_modified! — Method
DispersiveShallowWater.energy_total_modified!(e, q_global, equations::SvaerdKalischEquations1D, cache)

Return the modified total energy e of the primitive variables q_global for the SvaerdKalischEquations1D. It contains an additional term containing a derivative compared to the usual energy_total modeling non-hydrostatic contributions. The energy_total_modified is a conserved quantity (for periodic boundary conditions).

It is given by

\[\frac{1}{2} g \eta^2 + \frac{1}{2} h v^2 + \frac{1}{2} \hat\beta v_x^2.\]

q_global is a vector of the primitive variables at ALL nodes. cache needs to hold the SBP operators used by the solver.

See also energy_total_modified.

source

Mesh

Boundary conditions

Solver

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. It can also be nothing if no second derivative is used by the discretization. Both summation-by-parts operators should be associated with the same grid.

source

Semidiscretization

DispersiveShallowWater.Semidiscretization — Method
Semidiscretization(mesh, equations, initial_condition, solver;
+\end{aligned}\]
The unknown quantities of the Svärd-Kalisch equations are the total water height $\eta$ and the velocity $v$. The gravitational constant is denoted by g and the bottom topography (bathymetry) $b = \eta_0 - D$. The water height above the bathymetry is therefore given by $h = \eta - \eta_0 + D$.
Currently, the equations only support a general variable bathymetry, see bathymetry_variable.
SvärdKalischEquations1D is an alias for SvaerdKalischEquations1D.
The equations by Svärd and Kalisch are presented and analyzed in Svärd and Kalisch (2023). The semidiscretization implemented here conserves
  • the total water mass (integral of $h$) as a linear invariant
  • the total momentum (integral of $h v$) as a nonlinear invariant for flat bathymetry
  • the total modified energy
for periodic boundary conditions (see Lampert, Ranocha). Additionally, it is well-balanced for the lake-at-rest stationary solution, see Lampert and Ranocha (2024).
  • Magnus Svärd, Henrik Kalisch (2023) A novel energy-bounded Boussinesq model and a well-balanced and stable numerical discretization arXiv: 2302.09924
  • Joshua Lampert, Hendrik Ranocha (2024) Structure-Preserving Numerical Methods for Two Nonlinear Systems of Dispersive Wave Equations DOI: 10.48550/arXiv.2402.16669
source
DispersiveShallowWater.energy_total_modified! — Method
DispersiveShallowWater.energy_total_modified!(e, q_global, equations::SvaerdKalischEquations1D, cache)

Return the modified total energy e of the primitive variables q_global for the SvaerdKalischEquations1D. It contains an additional term containing a derivative compared to the usual energy_total modeling non-hydrostatic contributions. The energy_total_modified is a conserved quantity (for periodic boundary conditions).

It is given by

\[\frac{1}{2} g \eta^2 + \frac{1}{2} h v^2 + \frac{1}{2} \hat\beta v_x^2.\]

q_global is a vector of the primitive variables at ALL nodes. cache needs to hold the SBP operators used by the solver.

See also energy_total_modified.

source

Mesh

Boundary conditions

Solver

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. It can also be nothing if no second derivative is used by the discretization. Both summation-by-parts operators should be associated with the same grid.

source

Semidiscretization

DispersiveShallowWater.Semidiscretization — Method
Semidiscretization(mesh, equations, initial_condition, solver;
                    source_terms=nothing,
                    boundary_conditions=boundary_condition_periodic,
                    RealT=real(solver),
                    uEltype=RealT,
-                   initial_cache=(tmp1 = Array{RealT}(undef, nnodes(mesh)),))

Construct a semidiscretization of a PDE.

source

Callbacks

Callbacks

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.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.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.SummaryCallback — Type
SummaryCallback(io::IO = stdout)

Create and return a callback that resets the timer at the beginning of a simulation and prints the timer values at the end of the simulation.

source

Utilities

DispersiveShallowWater.convergence_test — Method
convergence_test([mod::Module=Main,] example::AbstractString, iterations; io::IO = stdout, kwargs...)
-convergence_test([mod::Module=Main,] example::AbstractString, Ns::AbstractVector; io::IO = stdout, kwargs...)

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

Adjusted from Trixi.jl.

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.@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
+ 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.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.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.SummaryCallback — Type
SummaryCallback(io::IO = stdout)

Create and return a callback that resets the timer at the beginning of a simulation and prints the timer values at the end of the simulation.

source

Utilities

DispersiveShallowWater.convergence_test — Method
convergence_test([mod::Module=Main,] example::AbstractString, iterations; io::IO = stdout, kwargs...)
+convergence_test([mod::Module=Main,] example::AbstractString, Ns::AbstractVector; io::IO = stdout, kwargs...)

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

Adjusted from Trixi.jl.

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.@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/previews/PR150/search_index.js b/previews/PR150/search_index.js index 53ea6d27..91ce4885 100644 --- a/previews/PR150/search_index.js +++ b/previews/PR150/search_index.js @@ -1,3 +1,3 @@ var documenterSearchIndex = {"docs": -[{"location":"changelog_tmp/","page":"Changelog","title":"Changelog","text":"EditURL = \"https://github.com/JoshuaLampert/DispersiveShallowWater.jl/blob/main/CHANGELOG.md\"","category":"page"},{"location":"changelog_tmp/#Changelog","page":"Changelog","title":"Changelog","text":"","category":"section"},{"location":"changelog_tmp/","page":"Changelog","title":"Changelog","text":"DispersiveShallowWater.jl follows the interpretation of semantic versioning (semver) used in the Julia ecosystem. Notable changes will be documented in this file for human readability.","category":"page"},{"location":"changelog_tmp/#Changes-in-the-v0.4-lifecycle","page":"Changelog","title":"Changes in the v0.4 lifecycle","text":"","category":"section"},{"location":"changelog_tmp/#Added","page":"Changelog","title":"Added","text":"","category":"section"},{"location":"changelog_tmp/","page":"Changelog","title":"Changelog","text":"Add BBMEquation1D (#150).","category":"page"},{"location":"changelog_tmp/#Changes-when-updating-to-v0.5-from-v0.4.x","page":"Changelog","title":"Changes when updating to v0.5 from v0.4.x","text":"","category":"section"},{"location":"changelog_tmp/#Changed","page":"Changelog","title":"Changed","text":"","category":"section"},{"location":"changelog_tmp/","page":"Changelog","title":"Changelog","text":"The BBMBBMVariableEquations1D were removed and BBMBBMEquations1D now supports a bathymetry_type to choose between a flat and a variable bathymetry (#147).\nThe default of bathymetry_type for the SerreGreenNaghdiEquations1D changed from bathymetry_flat to bathymetry_variable (#147).\nbathymetry_type is now a keyword argument for all equations instead of a positional argument (#147).\nThe initial_condition_dingemans for the SerreGreenNaghdiEquations1D and HyperbolicSerreGreenNaghdiEquations1D was changed a bit to be more consistent with the other equations (#147).","category":"page"},{"location":"changelog_tmp/#Changes-in-the-v0.4-lifecycle-2","page":"Changelog","title":"Changes in the v0.4 lifecycle","text":"","category":"section"},{"location":"changelog_tmp/#Added-2","page":"Changelog","title":"Added","text":"","category":"section"},{"location":"changelog_tmp/","page":"Changelog","title":"Changelog","text":"The SerreGreenNaghdiEquations1D were added for different types of bathymetry (#127, #135).\nThe HyperbolicSerreGreenNaghdiEquations1D were added for different types of bathymetry (#139).\nThe abstract interface AbstractShallowWaterEquations was added to unify several systems such as the SerreGreenNaghdiEquations1D, the BBMBBMEquations1D, and the SvärdKalischEquations1D (#127).\nA new conversion function prim2phys was introduced, defaulting to prim2prim. prim2phys is the default conversion function for plotting.","category":"page"},{"location":"changelog_tmp/#Changes-when-updating-to-v0.4-from-v0.3.x","page":"Changelog","title":"Changes when updating to v0.4 from v0.3.x","text":"","category":"section"},{"location":"changelog_tmp/#Changed-2","page":"Changelog","title":"Changed","text":"","category":"section"},{"location":"changelog_tmp/","page":"Changelog","title":"Changelog","text":"Use ArrayPartition from RecursiveArrayTools.jl to store the solution of the ODEProblem (#118).","category":"page"},{"location":"changelog_tmp/#Changes-in-the-v0.3-lifecycle","page":"Changelog","title":"Changes in the v0.3 lifecycle","text":"","category":"section"},{"location":"changelog_tmp/#Added-3","page":"Changelog","title":"Added","text":"","category":"section"},{"location":"changelog_tmp/","page":"Changelog","title":"Changelog","text":"Add possibility to pass vector of Ns to convergence_test (#113).\nPerformance improvements by using factorized matrices for linear systems solves (#108, #112, #114).\nReflecting boundary conditions are added for the BBM-BBM equations (#104, #109).\nFix for the BBMBBMVariableEquations1D, where the still water surface was neglected leading to a bug in the Dingemans setup (#91).","category":"page"},{"location":"changelog_tmp/#Changes-when-updating-to-v0.3-from-v0.2.x","page":"Changelog","title":"Changes when updating to v0.3 from v0.2.x","text":"","category":"section"},{"location":"changelog_tmp/#Changed-3","page":"Changelog","title":"Changed","text":"","category":"section"},{"location":"changelog_tmp/","page":"Changelog","title":"Changelog","text":"Add keyword argument start_from when plotting AnalysisCallback (#87).\nManufactured solution for Svärd-Kalisch equations uses a variable bathymetry (#84).","category":"page"},{"location":"changelog_tmp/#Changes-in-the-v0.2-lifecycle","page":"Changelog","title":"Changes in the v0.2 lifecycle","text":"","category":"section"},{"location":"changelog_tmp/#Added-4","page":"Changelog","title":"Added","text":"","category":"section"},{"location":"changelog_tmp/","page":"Changelog","title":"Changelog","text":"Add SummaryCallback (#75).","category":"page"},{"location":"changelog_tmp/#Changes-when-updating-to-v0.2-from-v0.1.x","page":"Changelog","title":"Changes when updating to v0.2 from v0.1.x","text":"","category":"section"},{"location":"changelog_tmp/#Changed-4","page":"Changelog","title":"Changed","text":"","category":"section"},{"location":"changelog_tmp/","page":"Changelog","title":"Changelog","text":"The code from the master thesis of Joshua Lampert was separated (#69).\nAdd support for source terms (#65).\nA higher order interpolation is used when plotting the solution at a value x outside the grid (#64).","category":"page"},{"location":"ref-trixibase/#TrixiBase.jl-API","page":"TrixiBase","title":"TrixiBase.jl API","text":"","category":"section"},{"location":"ref-trixibase/","page":"TrixiBase","title":"TrixiBase","text":"CurrentModule = TrixiBase","category":"page"},{"location":"ref-trixibase/","page":"TrixiBase","title":"TrixiBase","text":"Modules = [TrixiBase]","category":"page"},{"location":"ref-trixibase/#TrixiBase.disable_debug_timings-Tuple{}","page":"TrixiBase","title":"TrixiBase.disable_debug_timings","text":"disable_debug_timings()\n\nDisable all @trixi_timeit timings. The timings should be optimized away, allowing for truly zero-overhead. Enable timings again with enable_debug_timings.\n\nSee also enable_debug_timings, @trixi_timeit.\n\n\n\n\n\n","category":"method"},{"location":"ref-trixibase/#TrixiBase.enable_debug_timings-Tuple{}","page":"TrixiBase","title":"TrixiBase.enable_debug_timings","text":"enable_debug_timings()\n\nEnable all @trixi_timeit timings (default behavior).\n\nSee also disable_debug_timings, @trixi_timeit.\n\n\n\n\n\n","category":"method"},{"location":"ref-trixibase/#TrixiBase.timer-Tuple{}","page":"TrixiBase","title":"TrixiBase.timer","text":"timer()\n\nMain timer for global timing, e.g., to be used with @trixi_timeit.\n\n\n\n\n\n","category":"method"},{"location":"ref-trixibase/#TrixiBase.trixi_include-Tuple{Module, AbstractString}","page":"TrixiBase","title":"TrixiBase.trixi_include","text":"trixi_include([mod::Module=Main,] elixir::AbstractString; kwargs...)\n\ninclude the file elixir and evaluate its content in the global scope of module mod. You can override specific assignments in elixir by supplying keyword arguments. Its basic purpose is to make it easier to modify some parameters while running simulations 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 elixir, the keyword argument maxiters is inserted into calls to solve with it's default value used in the SciML ecosystem for ODEs, see the \"Miscellaneous\" section of the documentation.\n\nExamples\n\njulia> using TrixiBase, Trixi\n\njulia> redirect_stdout(devnull) do\n trixi_include(@__MODULE__, joinpath(examples_dir(), \"tree_1d_dgsem\", \"elixir_advection_extended.jl\"),\n tspan=(0.0, 0.1))\n sol.t[end]\n end\n[ Info: You just called `trixi_include`. Julia may now compile the code, please be patient.\n0.1\n\n\n\n\n\n","category":"method"},{"location":"ref-trixibase/#TrixiBase.@trixi_timeit-Tuple{Any, Any, Any}","page":"TrixiBase","title":"TrixiBase.@trixi_timeit","text":"@trixi_timeit timer() \"some label\" expression\n\nBasically the same as a special case of @timeit_debug from TimerOutputs.jl, but without try ... finally ... end block. Thus, it's not exception-safe, but it also avoids some related performance problems. Since we do not use exception handling in Trixi.jl, that's not really an issue.\n\nAll @trixi_timeit timings can be disabled with disable_debug_timings. The timings should then be optimized away, allowing for truly zero-overhead.\n\nSee also disable_debug_timings, enable_debug_timings.\n\n\n\n\n\n","category":"macro"},{"location":"code_of_conduct/","page":"Code of Conduct","title":"Code of Conduct","text":"EditURL = \"https://github.com/JoshuaLampert/DispersiveShallowWater.jl/blob/main/CODE_OF_CONDUCT.md\"","category":"page"},{"location":"code_of_conduct/#code-of-conduct","page":"Code of Conduct","title":"Code of Conduct","text":"","category":"section"},{"location":"code_of_conduct/","page":"Code of Conduct","title":"Code of Conduct","text":"Contributor Covenant Code of ConductOur PledgeWe as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.Our StandardsExamples of behavior that contributes to a positive environment for our community include:Demonstrating empathy and kindness toward other people\nBeing respectful of differing opinions, viewpoints, and experiences\nGiving and gracefully accepting constructive feedback\nAccepting responsibility and apologizing to those affected by our mistakes, and learning from the experience\nFocusing on what is best not just for us as individuals, but for the overall communityExamples of unacceptable behavior include:The use of sexualized language or imagery, and sexual attention or advances of any kind\nTrolling, insulting or derogatory comments, and personal or political attacks\nPublic or private harassment\nPublishing others' private information, such as a physical or email address, without their explicit permission\nOther conduct which could reasonably be considered inappropriate in a professional settingEnforcement ResponsibilitiesCommunity leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.ScopeThis Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.EnforcementInstances of abusive, harassing, or otherwise unacceptable behavior may be reported to Joshua Lampert or Hendrik Ranocha. All complaints will be reviewed and investigated promptly and fairly.All community leaders are obligated to respect the privacy and security of the reporter of any incident.Enforcement GuidelinesCommunity leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:1. CorrectionCommunity Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.Consequence: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.2. WarningCommunity Impact: A violation through a single incident or series of actions.Consequence: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.3. Temporary BanCommunity Impact: A serious violation of community standards, including sustained inappropriate behavior.Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.4. Permanent BanCommunity Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.Consequence: A permanent ban from any sort of public interaction within the community.AttributionThis Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0.Community Impact Guidelines were inspired by Mozilla's code of conduct enforcement ladder.[homepage]: https://www.contributor-covenant.orgFor answers to common questions about this code of conduct, see the FAQ. Translations are also available there.","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 and contributors","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":"contributing/","page":"Contributing","title":"Contributing","text":"EditURL = \"https://github.com/JoshuaLampert/DispersiveShallowWater.jl/blob/main/CONTRIBUTING.md\"","category":"page"},{"location":"contributing/#Contributing","page":"Contributing","title":"Contributing","text":"","category":"section"},{"location":"contributing/","page":"Contributing","title":"Contributing","text":"DispersiveShallowWater.jl is an open-source project and we are very happy to accept contributions from the community. Please feel free to open issues or submit patches (preferably as pull requests) any time.","category":"page"},{"location":"contributing/","page":"Contributing","title":"Contributing","text":"DispersiveShallowWater.jl and its contributions are licensed under the MIT license (see License). As a contributor, you certify that all your contributions are in conformance with the Developer Certificate of Origin (Version 1.1), which is reproduced below.","category":"page"},{"location":"contributing/#Developer-Certificate-of-Origin-(Version-1.1)","page":"Contributing","title":"Developer Certificate of Origin (Version 1.1)","text":"","category":"section"},{"location":"contributing/","page":"Contributing","title":"Contributing","text":"The following text was taken from https://developercertificate.org:","category":"page"},{"location":"contributing/","page":"Contributing","title":"Contributing","text":"Developer Certificate of Origin\nVersion 1.1\n\nCopyright (C) 2004, 2006 The Linux Foundation and its contributors.\n1 Letterman Drive\nSuite D4700\nSan Francisco, CA, 94129\n\nEveryone is permitted to copy and distribute verbatim copies of this\nlicense document, but changing it is not allowed.\n\n\nDeveloper's Certificate of Origin 1.1\n\nBy making a contribution to this project, I certify that:\n\n(a) The contribution was created in whole or in part by me and I\n have the right to submit it under the open source license\n indicated in the file; or\n\n(b) The contribution is based upon previous work that, to the best\n of my knowledge, is covered under an appropriate open source\n license and I have the right under that license to submit that\n work with modifications, whether created in whole or in part\n by me, under the same open source license (unless I am\n permitted to submit under a different license), as indicated\n in the file; or\n\n(c) The contribution was provided directly to me by some other\n person who certified (a), (b) or (c) and I have not modified\n it.\n\n(d) I understand and agree that this project and the contribution\n are public and that a record of the contribution (including all\n personal information I submit with it, including my sign-off) is\n maintained indefinitely and may be redistributed consistent with\n this project or the open source license(s) involved.","category":"page"},{"location":"development/#Development","page":"Development","title":"Development","text":"","category":"section"},{"location":"development/","page":"Development","title":"Development","text":"If you have any suggestions or ideas for improvements or new features, we are pleased to accept and discuss issues or if you are willing to contribute, feel free to open a pull request, even if it is only fixing a typo or improving the docs.","category":"page"},{"location":"development/#Changing-DispersiveShallowWater.jl-and-running-it-locally","page":"Development","title":"Changing DispersiveShallowWater.jl and running it locally","text":"","category":"section"},{"location":"development/","page":"Development","title":"Development","text":"If you plan to edit DispersiveShallowWater.jl, you first need to clone a local copy of the repository, which can be done by using git. It is recommended that you create a project, e.g. call it run, inside the repository, where you can add packages that you use during executing and testing DispersiveShallowWater.jl, but are not needed by DispersiveShallowWater.jl. This way you can keep the Project.toml of the main repository clean. To do so, you can execute the following lines in a terminal:","category":"page"},{"location":"development/","page":"Development","title":"Development","text":"git clone https://github.com/JoshuaLampert/DispersiveShallowWater.jl.git\ncd DispersiveShallowWater\nmkdir run\ncd run\njulia --project=. -e 'using Pkg; Pkg.develop(PackageSpec(path=\"..\"))' # Install local DispersiveShallowWater.jl clone\njulia --project=. -e 'using Pkg; Pkg.add([\"OrdinaryDiffEq\", \"Plots\", \"SummationByPartsOperators\"])' # Install additional packages","category":"page"},{"location":"development/","page":"Development","title":"Development","text":"If you use other packages for executing DispersiveShallowWater.jl, you can add them to the project in the run directory in an analogous way as above. To use the Julia project within run, be sure to start the Julia REPL by","category":"page"},{"location":"development/","page":"Development","title":"Development","text":"julia --project=.","category":"page"},{"location":"development/","page":"Development","title":"Development","text":"if already inside the the run directory or julia --project=run if in the main directory of the repo.","category":"page"},{"location":"development/#Preview-of-the-documentation","page":"Development","title":"Preview of the documentation","text":"","category":"section"},{"location":"development/","page":"Development","title":"Development","text":"If you want to build the documentation locally, you can run","category":"page"},{"location":"development/","page":"Development","title":"Development","text":"julia --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'","category":"page"},{"location":"development/","page":"Development","title":"Development","text":"once from the DispersiveShallowWater.jl main directory to tell Documenter.jl to build the documentation of your local clone. To build the documentation, run","category":"page"},{"location":"development/","page":"Development","title":"Development","text":"julia --project=docs --color=yes docs/make.jl","category":"page"},{"location":"development/","page":"Development","title":"Development","text":"The resulting .html files can then be found in docs/build/ and you can look at them by opening them in a browser. For pull requests from the main repository (i.e. not from a fork), the documentation is automatically built and can be previewed under https://joshualampert.github.io/DispersiveShallowWater.jl/previews/PRXXX/ where XXX is the number of the pull request.","category":"page"},{"location":"changelog/","page":"Changelog","title":"Changelog","text":"EditURL = \"https://github.com/JoshuaLampert/DispersiveShallowWater.jl/blob/main/NEWS.md\"","category":"page"},{"location":"changelog/#Changelog","page":"Changelog","title":"Changelog","text":"","category":"section"},{"location":"changelog/","page":"Changelog","title":"Changelog","text":"DispersiveShallowWater.jl follows the interpretation of semantic versioning (semver) used in the Julia ecosystem. Notable changes will be documented in this file for human readability.","category":"page"},{"location":"changelog/#Changes-in-the-v0.4-lifecycle","page":"Changelog","title":"Changes in the v0.4 lifecycle","text":"","category":"section"},{"location":"changelog/#Added","page":"Changelog","title":"Added","text":"","category":"section"},{"location":"changelog/","page":"Changelog","title":"Changelog","text":"Add BBMEquation1D (#150).","category":"page"},{"location":"changelog/#Changes-when-updating-to-v0.5-from-v0.4.x","page":"Changelog","title":"Changes when updating to v0.5 from v0.4.x","text":"","category":"section"},{"location":"changelog/#Changed","page":"Changelog","title":"Changed","text":"","category":"section"},{"location":"changelog/","page":"Changelog","title":"Changelog","text":"The BBMBBMVariableEquations1D were removed and BBMBBMEquations1D now supports a bathymetry_type to choose between a flat and a variable bathymetry (#147).\nThe default of bathymetry_type for the SerreGreenNaghdiEquations1D changed from bathymetry_flat to bathymetry_variable (#147).\nbathymetry_type is now a keyword argument for all equations instead of a positional argument (#147).\nThe initial_condition_dingemans for the SerreGreenNaghdiEquations1D and HyperbolicSerreGreenNaghdiEquations1D was changed a bit to be more consistent with the other equations (#147).","category":"page"},{"location":"changelog/#Changes-in-the-v0.4-lifecycle-2","page":"Changelog","title":"Changes in the v0.4 lifecycle","text":"","category":"section"},{"location":"changelog/#Added-2","page":"Changelog","title":"Added","text":"","category":"section"},{"location":"changelog/","page":"Changelog","title":"Changelog","text":"The SerreGreenNaghdiEquations1D were added for different types of bathymetry (#127, #135).\nThe HyperbolicSerreGreenNaghdiEquations1D were added for different types of bathymetry (#139).\nThe abstract interface AbstractShallowWaterEquations was added to unify several systems such as the SerreGreenNaghdiEquations1D, the BBMBBMEquations1D, and the SvärdKalischEquations1D (#127).\nA new conversion function prim2phys was introduced, defaulting to prim2prim. prim2phys is the default conversion function for plotting.","category":"page"},{"location":"changelog/#Changes-when-updating-to-v0.4-from-v0.3.x","page":"Changelog","title":"Changes when updating to v0.4 from v0.3.x","text":"","category":"section"},{"location":"changelog/#Changed-2","page":"Changelog","title":"Changed","text":"","category":"section"},{"location":"changelog/","page":"Changelog","title":"Changelog","text":"Use ArrayPartition from RecursiveArrayTools.jl to store the solution of the ODEProblem (#118).","category":"page"},{"location":"changelog/#Changes-in-the-v0.3-lifecycle","page":"Changelog","title":"Changes in the v0.3 lifecycle","text":"","category":"section"},{"location":"changelog/#Added-3","page":"Changelog","title":"Added","text":"","category":"section"},{"location":"changelog/","page":"Changelog","title":"Changelog","text":"Add possibility to pass vector of Ns to convergence_test (#113).\nPerformance improvements by using factorized matrices for linear systems solves (#108, #112, #114).\nReflecting boundary conditions are added for the BBM-BBM equations (#104, #109).\nFix for the BBMBBMVariableEquations1D, where the still water surface was neglected leading to a bug in the Dingemans setup (#91).","category":"page"},{"location":"changelog/#Changes-when-updating-to-v0.3-from-v0.2.x","page":"Changelog","title":"Changes when updating to v0.3 from v0.2.x","text":"","category":"section"},{"location":"changelog/#Changed-3","page":"Changelog","title":"Changed","text":"","category":"section"},{"location":"changelog/","page":"Changelog","title":"Changelog","text":"Add keyword argument start_from when plotting AnalysisCallback (#87).\nManufactured solution for Svärd-Kalisch equations uses a variable bathymetry (#84).","category":"page"},{"location":"changelog/#Changes-in-the-v0.2-lifecycle","page":"Changelog","title":"Changes in the v0.2 lifecycle","text":"","category":"section"},{"location":"changelog/#Added-4","page":"Changelog","title":"Added","text":"","category":"section"},{"location":"changelog/","page":"Changelog","title":"Changelog","text":"Add SummaryCallback (#75).","category":"page"},{"location":"changelog/#Changes-when-updating-to-v0.2-from-v0.1.x","page":"Changelog","title":"Changes when updating to v0.2 from v0.1.x","text":"","category":"section"},{"location":"changelog/#Changed-4","page":"Changelog","title":"Changed","text":"","category":"section"},{"location":"changelog/","page":"Changelog","title":"Changelog","text":"The code from the master thesis of Joshua Lampert was separated (#69).\nAdd support for source terms (#65).\nA higher order interpolation is used when plotting the solution at a value x outside the grid (#64).","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 = eta_0 - D the bathymetry and v the velocity in horizontal direction. Here, eta_0 is a reference water height also called still water height. In the case of the BBM-BBM equations, eta_0 is usually taken to be 0. 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: water height and bathymetry)","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 traveling wave that moves towards a beach, which is modeled by a linearly increasing bathymetry.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"equations = BBMBBMEquations1D(bathymetry_type = bathymetry_variable, gravity_constant = 9.81)\n\nfunction initial_condition_shoaling(x, t, equations::BBMBBMEquations1D, 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. DispersiveShallowWater.jl also supports reflecting boundary conditions for the BBMBBMEquations1D, see boundary_condition_reflecting. 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-traveling 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 (SBP) 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. Note that for non-periodic boundary conditions, the solver also needs to be created with non-periodic operators, see, e.g. examples/bbm_bbm_1d/bbm_bbm_1d_basic_reflecting.jl.","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 water height eta waterheight_total, the velocity and the entropy are computed and saved for each time step. The total water height 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\") # hide\nnothing # hide","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"(Image: shoaling solution)","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 water height. The resulting plot will have one subplot for each of the returned variables of the conversion variable. By default, the conversion function is just prim2phys, which computes the physical variables from the primitive ones, i.e., the identity for most equations.","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)\nnothing # hide","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"(Image: shoaling solution)","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 from the reproducibility repository of the master thesis of Joshua Lampert 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\") # hide\nnothing # hide","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"This creates the following figure:","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"(Image: analysis callback)","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, ylims = (-5e-16, 5e-16))\nsavefig(\"analysis_callback_relaxation.png\") # hide\nnothing # hide","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"(Image: analysis callback relaxation)","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)\nnothing # hide","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"(Image: shoaling solution DG)","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 from the reproducibility repository of the master thesis of Joshua Lampert.","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":"DispersiveShallowWater","title":"DispersiveShallowWater.jl API","text":"","category":"section"},{"location":"ref/","page":"DispersiveShallowWater","title":"DispersiveShallowWater","text":"CurrentModule = DispersiveShallowWater","category":"page"},{"location":"ref/","page":"DispersiveShallowWater","title":"DispersiveShallowWater","text":"Modules = [DispersiveShallowWater]\nPages = [\"DispersiveShallowWater.jl\"]","category":"page"},{"location":"ref/#DispersiveShallowWater.DispersiveShallowWater","page":"DispersiveShallowWater","title":"DispersiveShallowWater.DispersiveShallowWater","text":"DispersiveShallowWater\n\nDispersiveShallowWater.jl is a Julia package that implements structure-preserving numerical methods for dispersive shallow water models. It provides provably conservative, entropy-conserving, and well-balanced numerical schemes for some dispersive shallow water models.\n\nThe semidiscretizations are based on summation-by-parts (SBP) operators, which are implemented in SummationByPartsOperators.jl. To obtain fully discrete schemes, the time integration methods from OrdinaryDiffEq.jl are used to solve the resulting ordinary differential equations. Fully discrete entropy-conservative methods can be obtained by using the relaxation method provided by DispersiveShallowWater.jl.\n\nSee also: DispersiveShallowWater.jl\n\n\n\n\n\n","category":"module"},{"location":"ref/#Equations","page":"DispersiveShallowWater","title":"Equations","text":"","category":"section"},{"location":"ref/","page":"DispersiveShallowWater","title":"DispersiveShallowWater","text":"Modules = [DispersiveShallowWater]\nPages = Main.EQUATIONS_FILES","category":"page"},{"location":"ref/#DispersiveShallowWater.BBMEquation1D","page":"DispersiveShallowWater","title":"DispersiveShallowWater.BBMEquation1D","text":"BBMEquation1D(; bathymetry_type = bathymetry_flat, eta0 = 0.0)\n\nBBM (Benjamin–Bona–Mahony) equation in one spatial dimension. The equations are given by\n\nbeginaligned\n eta_t + etaeta_x + eta_x - eta_xxt = 0\nendaligned\n\nThe unknown quantity of the BBM equation is the total water height eta. The water height is given by h = eta - eta_0, where eta_0 is the constant still-water surface.\n\nCurrently, the equations only support a flat bathymetry b = 0, see bathymetry_flat.\n\nThe BBM equation is first described in Benjamin, Bona, and Mahony (1972). The semidiscretization implemented here is developed in Ranocha, Mitsotakis, and Ketcheson (2020). It conserves\n\nthe total water mass (integral of h) as a linear invariant\nthe total modified energy\n\nfor periodic boundary conditions.\n\nThomas B. Benjamin, Jerry L. Bona and John J. Mahony (1972) Model equations for long waves in nonlinear dispersive systems DOI: 10.1098/rsta.1972.0032\nHendrik Ranocha, Dimitrios Mitsotakis and David I. Ketcheson (2020) A Broad Class of Conservative Numerical Methods for Dispersive Wave Equations DOI: 10.4208/cicp.OA-2020-0119\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.energy_total_modified!-Tuple{Any, Any, BBMEquation1D, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.energy_total_modified!","text":"energy_total_modified!(e, q, equations::BBMEquation1D, cache)\n\nReturn the modified total energy e of the primitive variables q_global for the BBMEquation1D. The energy_total_modified is a conserved quantity (for periodic boundary conditions).\n\nIt is given by\n\nfrac12 eta^2 + frac12 eta_x^2\n\nq_global is a vector of the primitive variables at ALL nodes. cache needs to hold the SBP operators used by the solver.\n\nSee also energy_total_modified.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_convergence_test-Tuple{Any, Any, BBMEquation1D, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.initial_condition_convergence_test","text":"initial_condition_convergence_test(x, t, equations::BBMEquation1D, mesh)\n\nA travelling-wave solution used for convergence tests in a periodic domain.\n\nSee section 4.1.3 in (there is an error in paper: it should be sech^2 instead of cosh):\n\nHendrik Ranocha, Dimitrios Mitsotakis and David I. Ketcheson (2020) A Broad Class of Conservative Numerical Methods for Dispersive Wave Equations DOI: 10.4208/cicp.OA-2020-0119\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_manufactured-Tuple{Any, Any, BBMEquation1D, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.initial_condition_manufactured","text":"initial_condition_manufactured(x, t, equations::BBMEquation1D, mesh)\n\nA smooth manufactured solution in combination with source_terms_manufactured.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.invariant_cubic-Tuple{Any, BBMEquation1D}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.invariant_cubic","text":"invariant_cubic(q, equations::BBMEquation1D)\n\nReturn the cubic invariant of the primitive variables q for the BBMEquation1D. The cubic invariant is given by\n\n(eta + 1)^3\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.source_terms_manufactured-Tuple{Any, Any, Any, BBMEquation1D}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.source_terms_manufactured","text":"source_terms_manufactured(q, x, t, equations::BBMEquation1D, mesh)\n\nA smooth manufactured solution in combination with initial_condition_manufactured.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.BBMBBMEquations1D","page":"DispersiveShallowWater","title":"DispersiveShallowWater.BBMBBMEquations1D","text":"BBMBBMEquations1D(; bathymetry_type = bathymetry_variable,\n gravity_constant, eta0 = 0.0)\n\nBBM-BBM (Benjamin–Bona–Mahony) system in one spatial dimension. The equations for flat bathymetry 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 = eta_0 - D. The water height above the bathymetry is therefore given by h = eta - eta_0 + D. The BBM-BBM equations are only implemented for eta_0 = 0.\n\nTwo types of bathymetry_type are supported:\n\nbathymetry_flat: flat bathymetry (typically b = 0 everywhere)\nbathymetry_variable: general variable bathymetry\n\nFor the general case of variable vathymetry the BBM-BBM equations are\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\nOne reference for the BBM-BBM system can be found in Bona et al. (1998). The semidiscretization implemented here was developed for flat bathymetry in Ranocha et al. (2020) and generalized for a variable bathymetry in Lampert and Ranocha (2024). It conserves\n\nthe total water mass (integral of h) as a linear invariant\nthe total velocity (integral of v) as a linear invariant for flat bathymetry\nthe total energy\n\nfor periodic boundary conditions (see Lampert, Ranocha). For reflecting boundary conditions, the semidiscretization conserves\n\nthe total water (integral of h) as a linear invariant\nthe total energy.\n\nAdditionally, it is well-balanced for the lake-at-rest stationary solution, see Lampert and Ranocha (2024).\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\nHendrik Ranocha, Dimitrios Mitsotakis, David I. Ketcheson (2020) A Broad Class of Conservative Numerical Methods for Dispersive Wave Equations DOI: 10.4208/cicp.OA-2020-0119\nJoshua Lampert, Hendrik Ranocha (2024) Structure-Preserving Numerical Methods for Two Nonlinear Systems of Dispersive Wave Equations DOI: 10.48550/arXiv.2402.16669\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.initial_condition_convergence_test-Tuple{Any, Any, BBMBBMEquations1D, Any}","page":"DispersiveShallowWater","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. 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, BBMBBMEquations1D, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.initial_condition_dingemans","text":"initial_condition_dingemans(x, t, equations::BBMBBMEquations1D, 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\nwarning: Translation of water height\nThe initial condition for the water height is translated to be around 0, which is needed for the simulation because the BBMBBMEquations1D are only implemented for eta_0 = 0.\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":"DispersiveShallowWater","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_reflecting-Tuple{Any, Any, BBMBBMEquations1D, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.initial_condition_manufactured_reflecting","text":"initial_condition_manufactured_reflecting(x, t, equations::BBMBBMEquations1D, mesh)\n\nA smooth manufactured solution for reflecting boundary conditions in combination with source_terms_manufactured_reflecting.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.source_terms_manufactured-Tuple{Any, Any, Any, BBMBBMEquations1D}","page":"DispersiveShallowWater","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_reflecting-Tuple{Any, Any, Any, BBMBBMEquations1D}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.source_terms_manufactured_reflecting","text":"source_terms_manufactured_reflecting(q, x, t, equations::BBMBBMEquations1D, mesh)\n\nA smooth manufactured solution for reflecting boundary conditions in combination with initial_condition_manufactured_reflecting.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.bathymetry_flat","page":"DispersiveShallowWater","title":"DispersiveShallowWater.bathymetry_flat","text":"bathymetry_flat = DispersiveShallowWater.BathymetryFlat()\n\nA singleton struct indicating a flat bathymetry.\n\nSee also bathymetry_mild_slope and bathymetry_variable.\n\n\n\n\n\n","category":"constant"},{"location":"ref/#DispersiveShallowWater.bathymetry_mild_slope","page":"DispersiveShallowWater","title":"DispersiveShallowWater.bathymetry_mild_slope","text":"bathymetry_mild_slope = DispersiveShallowWater.BathymetryMildSlope()\n\nA singleton struct indicating a variable bathymetry with mild-slope approximation. Typically, this means that some terms like b_x^2 are neglected.\n\nSee also bathymetry_flat and bathymetry_variable.\n\n\n\n\n\n","category":"constant"},{"location":"ref/#DispersiveShallowWater.bathymetry_variable","page":"DispersiveShallowWater","title":"DispersiveShallowWater.bathymetry_variable","text":"bathymetry_variable = DispersiveShallowWater.BathymetryVariable()\n\nA singleton struct indicating a variable bathymetry (without mild-slope approximation).\n\nSee also bathymetry_flat and bathymetry_mild_slope.\n\n\n\n\n\n","category":"constant"},{"location":"ref/#DispersiveShallowWater.AbstractEquations","page":"DispersiveShallowWater","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\nSee also AbstractShallowWaterEquations.\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.AbstractShallowWaterEquations","page":"DispersiveShallowWater","title":"DispersiveShallowWater.AbstractShallowWaterEquations","text":"AbstractShallowWaterEquations{NDIMS, NVARS}\n\nAn abstract supertype of all equation system that contain the classical shallow water equations as a subsystem, e.g., the BBMBBMEquations1D, the SvaerdKalischEquations1D, and the SerreGreenNaghdiEquations1D. In 1D, the shallow water equations with flat bathymetry are given by\n\nbeginaligned\n h_t + (h v)_x = 0\n h v_t + frac12 g (h^2)_x + frac12 h (v^2)_x = 0\nendaligned\n\nwhere h is the waterheight, v the velocity, and g the gravity_constant.\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.bathymetry-Tuple{Any, DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.bathymetry","text":"bathymetry(q, equations)\n\nReturn the bathymetry 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":"method"},{"location":"ref/#DispersiveShallowWater.cons2prim-Tuple{Any, AbstractShallowWaterEquations}","page":"DispersiveShallowWater","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":"method"},{"location":"ref/#DispersiveShallowWater.default_analysis_errors-Tuple{DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","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":"DispersiveShallowWater","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.discharge-Tuple{Any, DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","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":"DispersiveShallowWater","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-Tuple{Any, AbstractShallowWaterEquations}","page":"DispersiveShallowWater","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. For all AbstractShallowWaterEquations, the total energy is given by the sum of the kinetic and potential energy of the shallow water subsystem, i.e.,\n\nfrac12 h v^2 + frac12 g eta^2\n\nin 1D, where h is the waterheight, eta = h + b the waterheight_total, v the velocity, and g the gravity_constant.\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.energy_total_modified!-Tuple{Any, Any, DispersiveShallowWater.AbstractEquations, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.energy_total_modified!","text":"energy_total_modified!(e, q_global, equations, cache)\n\nIn-place version of energy_total_modified.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.energy_total_modified-Tuple{Any, DispersiveShallowWater.AbstractEquations, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.energy_total_modified","text":"energy_total_modified(q_global, equations, cache)\n\nReturn the modified total energy of the primitive variables q_global for the equations. This modified total energy is a conserved quantity and can contain additional terms compared to the usual energy_total. For example, for the SvaerdKalischEquations1D and the SerreGreenNaghdiEquations1D, it contains additional terms depending on the derivative of the velocity v_x modeling non-hydrostatic contributions.\n\nq_global is a vector of the primitive variables at ALL nodes. cache needs to hold the SBP operators used by the solver if non-hydrostatic terms are present.\n\nInternally, this function allocates a vector for the output and calls DispersiveShallowWater.energy_total_modified!.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.entropy-Tuple{Any, AbstractShallowWaterEquations}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.entropy","text":"entropy(q, equations)\n\nReturn the entropy of the primitive variables q for a given set of equations. For all AbstractShallowWaterEquations, the entropy is just the energy_total.\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.entropy_modified!-NTuple{4, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.entropy_modified!","text":"entropy_modified!(e, q_global, equations, cache)\n\nIn-place version of entropy_modified.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.entropy_modified-Tuple{Any, AbstractShallowWaterEquations, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.entropy_modified","text":"entropy_modified(q_global, equations, cache)\n\nAlias for energy_total_modified.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.get_name-Tuple{DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","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-BathymetryVariable\"\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.gravity_constant-Tuple{AbstractShallowWaterEquations}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.gravity_constant","text":"gravity_constant(equations)\n\nReturn the gravity constant g for a given set of equations. See also AbstractShallowWaterEquations.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.hyperbolic_approximation_limit-Tuple{DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.hyperbolic_approximation_limit","text":"DispersiveShallowWater.hyperbolic_approximation_limit(equations)\n\nIf the equations are a hyperbolic approximation of another set of equations, return the equations of the limit system. Otherwise, return the input equations.\n\nSee also is_hyperbolic_appproximation and prim2phys.\n\nnote: Implementation details\nThis function is mostly used for some internal dispatch. For example, it allows to return a reduced set of variables from initial conditions for hyperbolic approximations.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_dingemans-Tuple{Any, Any, AbstractShallowWaterEquations, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.initial_condition_dingemans","text":"initial_condition_dingemans(x, t, equations::AbstractShallowWaterEquations, 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_discontinuous_well_balancedness-Tuple{Any, Any, AbstractShallowWaterEquations, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.initial_condition_discontinuous_well_balancedness","text":"initial_condition_discontinuous_well_balancedness(x, t, equations::AbstractShallowWaterEquations, mesh)\n\nSetup a truly discontinuous bottom topography function for this academic lake-at-rest test case of well-balancedness, i.e. eta is constant and v is zero everywhere. The error for this lake-at-rest test case ∫|η-η₀| should be around machine roundoff.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.is_hyperbolic_appproximation-Tuple{DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.is_hyperbolic_appproximation","text":"DispersiveShallowWater.is_hyperbolic_appproximation(equations)\n\nReturns Val{true}() if the equations are a hyperbolic approximation of another set of equations and Val{false}() otherwise (default). For example, the HyperbolicSerreGreenNaghdiEquations1D are a hyperbolic approximation of the SerreGreenNaghdiEquations1D.\n\nSee also hyperbolic_approximation_limit and prim2phys.\n\nnote: Implementation details\nThis function is mostly used for some internal dispatch. For example, it allows to return a reduced set of variables from initial conditions for hyperbolic approximations.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.lake_at_rest_error-Tuple{Any, DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.lake_at_rest_error","text":"lake_at_rest_error(q, equations)\n\nCalculate the error for the \"lake-at-rest\" test case where the waterheight_total eta = h + b should be a constant value over time (given by the value eta_0 passed to the equations when constructing them).\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.momentum-Tuple{Any, DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.momentum","text":"momentum(q, equations)\n\nReturn the momentum/discharge 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.prim2cons-Tuple{Any, AbstractShallowWaterEquations}","page":"DispersiveShallowWater","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":"method"},{"location":"ref/#DispersiveShallowWater.prim2phys-Tuple{Any, DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.prim2phys","text":"prim2phys(q, equations)\n\nConvert the primitive variables q to the physically meaningful variables for a given set of equations. By default, this is the same as prim2prim for most equations. However, some equations like the HyperbolicSerreGreenNaghdiEquations1D return a reduced set of variables since they are a hyperbolic approximation of another set of equations (in this case the SerreGreenNaghdiEquations1D).\n\nSee also is_hyperbolic_appproximation and hyperbolic_approximation_limit.\n\nq 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.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.prim2prim-Tuple{Any, DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","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.still_water_surface-Tuple{Any, DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.still_water_surface","text":"still_water_surface(q, equations)\n\nReturn the still water surface eta_0 (lake at rest) for a given set of equations.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.varnames","page":"DispersiveShallowWater","title":"DispersiveShallowWater.varnames","text":"varnames(conversion_function, equations)\n\nReturn the list of variable names when applying conversion_function to the primitive variables associated to equations. Common choices of the conversion_function are prim2prim, prim2cons, and prim2phys.\n\n\n\n\n\n","category":"function"},{"location":"ref/#DispersiveShallowWater.velocity-Tuple{Any, AbstractShallowWaterEquations}","page":"DispersiveShallowWater","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":"method"},{"location":"ref/#DispersiveShallowWater.waterheight-Tuple{Any, DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","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 h above the bathymetry b.\n\nq is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations).\n\nSee also waterheight_total, bathymetry.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.waterheight_total-Tuple{Any, DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","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 h plus the bathymetry b.\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.HyperbolicSerreGreenNaghdiEquations1D","page":"DispersiveShallowWater","title":"DispersiveShallowWater.HyperbolicSerreGreenNaghdiEquations1D","text":"HyperbolicSerreGreenNaghdiEquations1D(; bathymetry_type = bathymetry_mild_slope,\n gravity_constant,\n eta0 = 0.0,\n lambda)\n\nHyperbolic approximation of the Serre-Green-Naghdi system in one spatial dimension. The equations for flat bathymetry are given by\n\nbeginaligned\n h_t + (h v)_x = 0\n h v_t + frac12 g (h^2)_x + frac12 h (v^2)_x\n + biggl( fraclambda3 H (1 - H h) biggr)_x = 0\n h w_t + h v w_x = lambda (1 - H h)\n H_t + H_x u = w\nendaligned\n\nThe unknown quantities of the hyperbolized Serre-Green-Naghdi equations are the total water height eta = h + b and the velocity v. The gravitational constant is denoted by g and the bottom topography (bathymetry) b = eta_0 - D. The water height above the bathymetry is therefore given by h = eta - eta_0 + D. The total water height is therefore given by eta = h + b.\n\nThere are two additional variables w approx -h v_x and H approx h compared to the SerreGreenNaghdiEquations1D. In the original papers of Gavrilyuk et al., the variable H is called eta. Here, we use eta for the total water height and H for auxiliary variable introduced in the hyperbolic approximation.\n\nnote: Initial conditions\nThe HyperbolicSerreGreenNaghdiEquations1D allow two options for specifying initial conditions:Returning the full set of variables q = (η, v, D, w, H)\nReturning a reduced set of variables q = (η, v, D) as required for the limit system SerreGreenNaghdiEquations1D of the hyperbolic approximation. The remaining variables w and H are initialized using the default initialization w approx -h v_x and H approx h using the derivative operator of the solver.\n\nThe relaxation parameter lambda (lambda) introduced to obtain this hyperbolic approximation of the SerreGreenNaghdiEquations1D influences the stiffness of the system. For lambda to infty, the hyperbolic Serre-Green-Naghdi equations converge (at least formally) to the original SerreGreenNaghdiEquations1D. However, the wave speeds of the hyperbolic system increase with increasing lambda, so that explicit time integration methods become more expensive.\n\nTwo types of bathymetry_type are supported:\n\nbathymetry_flat: flat bathymetry (typically b = 0 everywhere)\nbathymetry_mild_slope: variable bathymetry with mild-slope approximation\n\nFor the mild-slope approximation, the Serre-Green-Naghdi equations are\n\nbeginaligned\n h_t + (h v)_x = 0\n h v_t + frac12 g (h^2)_x + frac12 h (v^2)_x\n + biggl( fraclambda3 H (1 - H h) biggr)_x\n + biggl( g h + fraclambda2 (1 - H h) biggr) b_x = 0\n h w_t + h v w_x = lambda (1 - H h)\n H_t + H_x u + frac32 b_x v = w\nendaligned\n\nReferences for the hyperbolized Serre-Green-Naghdi system can be found in\n\nFavrie and Gavrilyuk. A rapid numerical method for solving Serre-Green-Naghdi equations describing long free surface gravity waves DOI: 10.1088/1361-6544/aa712d\nBusto, Dumbser, Escalante, Favrie, and Gavrilyuk. On High Order ADER Discontinuous Galerkin Schemes for First Order Hyperbolic Reformulations of Nonlinear Dispersive Systems DOI: 10.1007/s10915-021-01429-8\n\nThe semidiscretization implemented here conserves\n\nthe total water mass (integral of h) as a linear invariant\nthe total modified energy\n\nfor periodic boundary conditions (see Ranocha and Ricchiuto (2024)). Additionally, it is well-balanced for the lake-at-rest stationary solution, see\n\nHendrik Ranocha and Mario Ricchiuto (2024) Structure-preserving approximations of the Serre-Green-Naghdi equations in standard and hyperbolic form arXiv: 2408.02665\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.energy_total_modified!-Tuple{Any, Any, HyperbolicSerreGreenNaghdiEquations1D, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.energy_total_modified!","text":"DispersiveShallowWater.energy_total_modified!(e, q_global, equations::HyperbolicSerreGreenNaghdiEquations1D, cache)\n\nReturn the modified total energy e of the primitive variables q_global for the HyperbolicSerreGreenNaghdiEquations1D. It contains additional terms compared to the usual energy_total modeling non-hydrostatic contributions. The energy_total_modified is a conserved quantity (for periodic boundary conditions).\n\nFor a bathymetry_mild_slope (and a bathymetry_flat), the total modified energy is given by\n\nfrac12 g eta^2 + frac12 h v^2 +\nfrac16 h w^2 + fraclambda6 h (1 - eta h)^2\n\nq_global is a vector of the primitive variables at ALL nodes.\n\nSee also energy_total_modified.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_manufactured-Tuple{Any, Any, HyperbolicSerreGreenNaghdiEquations1D, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.initial_condition_manufactured","text":"initial_condition_manufactured(x, t, equations::HyperbolicSerreGreenNaghdiEquations1D, mesh)\n\nA smooth manufactured solution in combination with source_terms_manufactured, see\n\nHendrik Ranocha and Mario Ricchiuto (2024) Structure-preserving approximations of the Serre-Green-Naghdi equations in standard and hyperbolic form arXiv: 2408.02665\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_soliton-Tuple{Any, Any, HyperbolicSerreGreenNaghdiEquations1D, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.initial_condition_soliton","text":"initial_condition_soliton(x, t, equations::HyperbolicSerreGreenNaghdiEquations1D, mesh)\n\nA soliton solution of the SerreGreenNaghdiEquations1D used for convergence tests in a periodic domain. This is physically the same as initial_condition_convergence_test for the SerreGreenNaghdiEquations1D. Please note that this is not an exact solution of the HyperbolicSerreGreenNaghdiEquations1D (only in the limit of the relaxation parameter lambda to infty).\n\nSee also initial_condition_convergence_test.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.prim2phys-Tuple{Any, HyperbolicSerreGreenNaghdiEquations1D}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.prim2phys","text":"prim2phys(q, equations::HyperbolicSerreGreenNaghdiEquations1D)\n\nReturn the physical variables eta v D used also by the SerreGreenNaghdiEquations1D from the main variables q for the HyperbolicSerreGreenNaghdiEquations1D.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.source_terms_manufactured-Tuple{Any, Any, Any, HyperbolicSerreGreenNaghdiEquations1D}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.source_terms_manufactured","text":"source_terms_manufactured(q, x, t, equations::HyperbolicSerreGreenNaghdiEquations1D, mesh)\n\nA smooth manufactured solution in combination with initial_condition_manufactured.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.SerreGreenNaghdiEquations1D","page":"DispersiveShallowWater","title":"DispersiveShallowWater.SerreGreenNaghdiEquations1D","text":"SerreGreenNaghdiEquations1D(; bathymetry_type = bathymetry_variable,\n gravity_constant, eta0 = 0.0)\n\nSerre-Green-Naghdi system in one spatial dimension. The equations for flat bathymetry are given by\n\nbeginaligned\n h_t + (h v)_x = 0\n h v_t - frac13 (h^3 v_tx)_x + frac12 g (h^2)_x + frac12 h (v^2)_x + p_x = 0\n p = frac13 h^3 v_x^2 - frac13 h^3 v v_xx\nendaligned\n\nThe unknown quantities of the Serre-Green-Naghdi equations are the total water height eta = h + b and the velocity v. The gravitational constant is denoted by g and the bottom topography (bathymetry) b = eta_0 - D. The water height above the bathymetry is therefore given by h = eta - eta_0 + D. The total water height is therefore given by eta = h + b.\n\nThree types of bathymetry_type are supported:\n\nbathymetry_flat: flat bathymetry (typically b = 0 everywhere)\nbathymetry_mild_slope: variable bathymetry with mild-slope approximation\nbathymetry_variable: general variable bathymetry\n\nFor the mild-slope approximation, the Serre-Green-Naghdi equations are\n\nbeginaligned\n h_t + (h v)_x = 0\n h v_t - frac13 (h^3 v_tx)_x + frac12 (h^2 b_x u_t)_x - frac12 h^2 b_x u_tx + frac34 h b_x^2 u_t\n + frac12 g (h^2)_x + g h b_x + frac12 h (v^2)_x\n + p_x + frac32 fracph b_x = 0\n p = frac13 h^3 v_x^2 - frac13 h^3 v v_xx\n + frac12 h^2 v (b_x v)_x\nendaligned\n\nFor the general case of variable vathymetry without mild-slope approximation, the Serre-Green-Naghdi equations are\n\nbeginaligned\n h_t + (h v)_x = 0\n h v_t - frac13 (h^3 v_tx)_x + frac12 (h^2 b_x u_t)_x - frac12 h^2 b_x u_tx + h b_x^2 u_t\n + frac12 g (h^2)_x + g h b_x + frac12 h (v^2)_x\n + p_x + frac32 fracph b_x + psi b_x = 0\n p = frac13 h^3 v_x^2 - frac13 h^3 v v_xx\n + frac12 h^2 v (b_x v)_x\n psi = frac14 h v (b_x v)_x\nendaligned\n\nReferences for the Serre-Green-Naghdi system can be found in\n\nSerre (1953) Contribution â l'étude des écoulements permanents et variables dans les canaux DOI: 10.1051/lhb/1953034\nGreen and Naghdi (1976) A derivation of equations for wave propagation in water of variable depth DOI: 10.1017/S0022112076002425\n\nThe semidiscretization implemented here conserves\n\nthe total water mass (integral of h) as a linear invariant\nthe total momentum (integral of h v) as a nonlinear invariant if the bathymetry is constant\nthe total modified energy\n\nfor periodic boundary conditions (see Ranocha and Ricchiuto (2024)). Additionally, it is well-balanced for the lake-at-rest stationary solution, see\n\nHendrik Ranocha and Mario Ricchiuto (2024) Structure-preserving approximations of the Serre-Green-Naghdi equations in standard and hyperbolic form arXiv: 2408.02665\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.energy_total_modified!-Tuple{Any, Any, SerreGreenNaghdiEquations1D, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.energy_total_modified!","text":"DispersiveShallowWater.energy_total_modified!(e, q_global, equations::SerreGreenNaghdiEquations1D, cache)\n\nReturn the modified total energy e of the primitive variables q_global for the SerreGreenNaghdiEquations1D. It contains an additional term containing a derivative compared to the usual energy_total modeling non-hydrostatic contributions. The energy_total_modified is a conserved quantity (for periodic boundary conditions).\n\nFor a bathymetry_flat the total modified energy is given by\n\nfrac12 g eta^2 + frac12 h v^2 + frac16 h^3 v_x^2\n\nFor a bathymetry_mild_slope the total modified energy is given by\n\nfrac12 g eta^2 + frac12 h v^2 + frac16 h (-h v_x + 15 v b_x)^2\n\nFor a bathymetry_variable the total modified energy has the additional term\n\n+ frac18 h (v b_x)^2\n\nq_global is a vector of the primitive variables at ALL nodes. cache needs to hold the SBP operators used by the solver.\n\nSee also energy_total_modified.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_convergence_test-Tuple{Any, Any, SerreGreenNaghdiEquations1D, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.initial_condition_convergence_test","text":"initial_condition_convergence_test(x, t, equations::SerreGreenNaghdiEquations1D, mesh)\n\nA soliton solution used for convergence tests in a periodic domain.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.SvaerdKalischEquations1D","page":"DispersiveShallowWater","title":"DispersiveShallowWater.SvaerdKalischEquations1D","text":"SvaerdKalischEquations1D(; bathymetry_type = bathymetry_variable,\n gravity_constant, eta0 = 0.0, alpha = 0.0,\n beta = 0.2308939393939394, gamma = 0.04034343434343434)\n\nDispersive system by Svärd and Kalisch (2023) in one spatial dimension. The equations for variable bathymetry 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 = eta_0 - D. The water height above the bathymetry is therefore given by h = eta - eta_0 + D.\n\nCurrently, the equations only support a general variable bathymetry, see bathymetry_variable.\n\nSvärdKalischEquations1D is an alias for SvaerdKalischEquations1D.\n\nThe equations by Svärd and Kalisch are presented and analyzed in Svärd and Kalisch (2023). The semidiscretization implemented here conserves\n\nthe total water mass (integral of h) as a linear invariant\nthe total momentum (integral of h v) as a nonlinear invariant for flat bathymetry\nthe total modified energy\n\nfor periodic boundary conditions (see Lampert, Ranocha). Additionally, it is well-balanced for the lake-at-rest stationary solution, see Lampert and Ranocha (2024).\n\nMagnus Svärd, Henrik Kalisch (2023) A novel energy-bounded Boussinesq model and a well-balanced and stable numerical discretization arXiv: 2302.09924\nJoshua Lampert, Hendrik Ranocha (2024) Structure-Preserving Numerical Methods for Two Nonlinear Systems of Dispersive Wave Equations DOI: 10.48550/arXiv.2402.16669\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.energy_total_modified!-Tuple{Any, Any, SvaerdKalischEquations1D, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.energy_total_modified!","text":"DispersiveShallowWater.energy_total_modified!(e, q_global, equations::SvaerdKalischEquations1D, cache)\n\nReturn the modified total energy e of the primitive variables q_global for the SvaerdKalischEquations1D. It contains an additional term containing a derivative compared to the usual energy_total modeling non-hydrostatic contributions. The energy_total_modified is a conserved quantity (for periodic boundary conditions).\n\nIt is given by\n\nfrac12 g eta^2 + frac12 h v^2 + frac12 hatbeta v_x^2\n\nq_global is a vector of the primitive variables at ALL nodes. cache needs to hold the SBP operators used by the solver.\n\nSee also energy_total_modified.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_manufactured-Tuple{Any, Any, SvaerdKalischEquations1D, Any}","page":"DispersiveShallowWater","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.source_terms_manufactured-Tuple{Any, Any, Any, SvaerdKalischEquations1D}","page":"DispersiveShallowWater","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/#Mesh","page":"DispersiveShallowWater","title":"Mesh","text":"","category":"section"},{"location":"ref/","page":"DispersiveShallowWater","title":"DispersiveShallowWater","text":"Modules = [DispersiveShallowWater]\nPages = [\"mesh.jl\"]","category":"page"},{"location":"ref/#DispersiveShallowWater.Mesh1D","page":"DispersiveShallowWater","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":"DispersiveShallowWater","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/#Boundary-conditions","page":"DispersiveShallowWater","title":"Boundary conditions","text":"","category":"section"},{"location":"ref/","page":"DispersiveShallowWater","title":"DispersiveShallowWater","text":"Modules = [DispersiveShallowWater]\nPages = [\"boundary_conditions.jl\"]","category":"page"},{"location":"ref/#DispersiveShallowWater.boundary_condition_periodic","page":"DispersiveShallowWater","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.boundary_condition_reflecting","page":"DispersiveShallowWater","title":"DispersiveShallowWater.boundary_condition_reflecting","text":"boundary_condition_reflecting = DispersiveShallowWater.BoundaryConditionReflecting()\n\nA singleton struct indicating reflecting boundary conditions.\n\n\n\n\n\n","category":"constant"},{"location":"ref/#Solver","page":"DispersiveShallowWater","title":"Solver","text":"","category":"section"},{"location":"ref/","page":"DispersiveShallowWater","title":"DispersiveShallowWater","text":"Modules = [DispersiveShallowWater]\nPages = [\"solver.jl\"]","category":"page"},{"location":"ref/#DispersiveShallowWater.AbstractSolver","page":"DispersiveShallowWater","title":"DispersiveShallowWater.AbstractSolver","text":"AbstractSolver\n\nAn abstract supertype of specific solvers.\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.Solver","page":"DispersiveShallowWater","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":"DispersiveShallowWater","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{Nothing, AbstractMatrix{RealT}, SummationByPartsOperators.AbstractDerivativeOperator{RealT}}}} where RealT","page":"DispersiveShallowWater","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. It can also be nothing if no second derivative is used by the discretization. Both summation-by-parts operators should be associated with the same grid.\n\n\n\n\n\n","category":"method"},{"location":"ref/#Semidiscretization","page":"DispersiveShallowWater","title":"Semidiscretization","text":"","category":"section"},{"location":"ref/","page":"DispersiveShallowWater","title":"DispersiveShallowWater","text":"Modules = [DispersiveShallowWater]\nPages = [\"semidiscretization.jl\"]","category":"page"},{"location":"ref/#DispersiveShallowWater.Semidiscretization","page":"DispersiveShallowWater","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":"DispersiveShallowWater","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=(tmp1 = Array{RealT}(undef, nnodes(mesh)),))\n\nConstruct a semidiscretization of a PDE.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.semidiscretize-Tuple{Semidiscretization, Any}","page":"DispersiveShallowWater","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/#SummationByPartsOperators.grid-Tuple{Semidiscretization}","page":"DispersiveShallowWater","title":"SummationByPartsOperators.grid","text":"grid(semi)\n\nGet the grid of a semidiscretization.\n\n\n\n\n\n","category":"method"},{"location":"ref/#Callbacks","page":"DispersiveShallowWater","title":"Callbacks","text":"","category":"section"},{"location":"ref/","page":"DispersiveShallowWater","title":"DispersiveShallowWater","text":"Modules = [DispersiveShallowWater]\nPages = Main.CALLBACKS_STEP_FILES","category":"page"},{"location":"ref/#DispersiveShallowWater.AnalysisCallback","page":"DispersiveShallowWater","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.errors-Union{Tuple{SciMLBase.DiscreteCallback{Condition, Affect!}}, Tuple{Affect!}, Tuple{Condition}} where {Condition, Affect!<:AnalysisCallback}","page":"DispersiveShallowWater","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.integrals-Union{Tuple{SciMLBase.DiscreteCallback{Condition, Affect!}}, Tuple{Affect!}, Tuple{Condition}} where {Condition, Affect!<:AnalysisCallback}","page":"DispersiveShallowWater","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.tstops-Union{Tuple{SciMLBase.DiscreteCallback{Condition, Affect!}}, Tuple{Affect!}, Tuple{Condition}} where {Condition, Affect!<:AnalysisCallback}","page":"DispersiveShallowWater","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.RelaxationCallback","page":"DispersiveShallowWater","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.SummaryCallback","page":"DispersiveShallowWater","title":"DispersiveShallowWater.SummaryCallback","text":"SummaryCallback(io::IO = stdout)\n\nCreate and return a callback that resets the timer at the beginning of a simulation and prints the timer values at the end of the simulation.\n\n\n\n\n\n","category":"type"},{"location":"ref/#Utilities","page":"DispersiveShallowWater","title":"Utilities","text":"","category":"section"},{"location":"ref/","page":"DispersiveShallowWater","title":"DispersiveShallowWater","text":"Modules = [DispersiveShallowWater]\nPages = [\"util.jl\"]","category":"page"},{"location":"ref/#DispersiveShallowWater.convergence_test-Tuple{Module, AbstractString, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.convergence_test","text":"convergence_test([mod::Module=Main,] example::AbstractString, iterations; io::IO = stdout, kwargs...)\nconvergence_test([mod::Module=Main,] example::AbstractString, Ns::AbstractVector; io::IO = stdout, kwargs...)\n\nRun multiple simulations using the setup given in example and compute the experimental order of convergence (EOC) in the L^2 and L^infty norm. If iterations is passed as integer, in each iteration, the resolution of the respective mesh will be doubled. If Ns is passed as vector, the simulations will be run for each value of Ns. Additional keyword arguments kwargs... and the optional module mod are passed directly to trixi_include.\n\nAdjusted from Trixi.jl.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.default_example-Tuple{}","page":"DispersiveShallowWater","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.examples_dir-Tuple{}","page":"DispersiveShallowWater","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":"DispersiveShallowWater","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.@autoinfiltrate","page":"DispersiveShallowWater","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: codecov) (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 some dispersive shallow water models:","category":"page"},{"location":"","page":"Home","title":"Home","text":"the Benjamin-Bona-Mahony (BBM) equation, also known as regularized long-wave equation,\nthe BBM-BBM equations with varying bottom topography,\nthe dispersive shallow water model proposed by Magnus Svärd and Henrik Kalisch,\nthe Serre-Green-Naghdi equations.","category":"page"},{"location":"","page":"Home","title":"Home","text":"The semidiscretizations are based on summation-by-parts (SBP) operators, which are implemented in SummationByPartsOperators.jl. To obtain fully discrete schemes, the time integration methods from OrdinaryDiffEq.jl are used to solve the resulting ordinary differential equations. Fully discrete entropy-conservative methods can be obtained by using the relaxation method provided by DispersiveShallowWater.jl.","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.9 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":"#Referencing","page":"Home","title":"Referencing","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"You can directly refer to DispersiveShallowWater.jl as","category":"page"},{"location":"","page":"Home","title":"Home","text":"@misc{lampert2023dispersive,\n title={{D}ispersive{S}hallow{W}ater.jl: {S}tructure-preserving numerical\n methods for dispersive shallow water models},\n author={Lampert, Joshua and Ranocha, Hendrik},\n year={2023},\n month={10},\n howpublished={\\url{https://github.com/JoshuaLampert/DispersiveShallowWater.jl}},\n doi={10.5281/zenodo.10034636}\n}","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 (University of Hamburg) with contributions from Hendrik Ranocha (Johannes Gutenberg University Mainz). Some parts of this repository are based on parts of Dispersive-wave-schemes-notebooks. A Broad Class of Conservative Numerical Methods for Dispersive Wave Equations by Hendrik Ranocha, Dimitrios Mitsotakis and David Ketcheson. The code structure is inspired by Trixi.jl.","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":"changelog_tmp/","page":"Changelog","title":"Changelog","text":"EditURL = \"https://github.com/JoshuaLampert/DispersiveShallowWater.jl/blob/main/CHANGELOG.md\"","category":"page"},{"location":"changelog_tmp/#Changelog","page":"Changelog","title":"Changelog","text":"","category":"section"},{"location":"changelog_tmp/","page":"Changelog","title":"Changelog","text":"DispersiveShallowWater.jl follows the interpretation of semantic versioning (semver) used in the Julia ecosystem. Notable changes will be documented in this file for human readability.","category":"page"},{"location":"changelog_tmp/#Changes-in-the-v0.4-lifecycle","page":"Changelog","title":"Changes in the v0.4 lifecycle","text":"","category":"section"},{"location":"changelog_tmp/#Added","page":"Changelog","title":"Added","text":"","category":"section"},{"location":"changelog_tmp/","page":"Changelog","title":"Changelog","text":"Add BBMEquation1D (#150).","category":"page"},{"location":"changelog_tmp/#Changes-when-updating-to-v0.5-from-v0.4.x","page":"Changelog","title":"Changes when updating to v0.5 from v0.4.x","text":"","category":"section"},{"location":"changelog_tmp/#Changed","page":"Changelog","title":"Changed","text":"","category":"section"},{"location":"changelog_tmp/","page":"Changelog","title":"Changelog","text":"The BBMBBMVariableEquations1D were removed and BBMBBMEquations1D now supports a bathymetry_type to choose between a flat and a variable bathymetry (#147).\nThe default of bathymetry_type for the SerreGreenNaghdiEquations1D changed from bathymetry_flat to bathymetry_variable (#147).\nbathymetry_type is now a keyword argument for all equations instead of a positional argument (#147).\nThe initial_condition_dingemans for the SerreGreenNaghdiEquations1D and HyperbolicSerreGreenNaghdiEquations1D was changed a bit to be more consistent with the other equations (#147).","category":"page"},{"location":"changelog_tmp/#Changes-in-the-v0.4-lifecycle-2","page":"Changelog","title":"Changes in the v0.4 lifecycle","text":"","category":"section"},{"location":"changelog_tmp/#Added-2","page":"Changelog","title":"Added","text":"","category":"section"},{"location":"changelog_tmp/","page":"Changelog","title":"Changelog","text":"The SerreGreenNaghdiEquations1D were added for different types of bathymetry (#127, #135).\nThe HyperbolicSerreGreenNaghdiEquations1D were added for different types of bathymetry (#139).\nThe abstract interface AbstractShallowWaterEquations was added to unify several systems such as the SerreGreenNaghdiEquations1D, the BBMBBMEquations1D, and the SvärdKalischEquations1D (#127).\nA new conversion function prim2phys was introduced, defaulting to prim2prim. prim2phys is the default conversion function for plotting.","category":"page"},{"location":"changelog_tmp/#Changes-when-updating-to-v0.4-from-v0.3.x","page":"Changelog","title":"Changes when updating to v0.4 from v0.3.x","text":"","category":"section"},{"location":"changelog_tmp/#Changed-2","page":"Changelog","title":"Changed","text":"","category":"section"},{"location":"changelog_tmp/","page":"Changelog","title":"Changelog","text":"Use ArrayPartition from RecursiveArrayTools.jl to store the solution of the ODEProblem (#118).","category":"page"},{"location":"changelog_tmp/#Changes-in-the-v0.3-lifecycle","page":"Changelog","title":"Changes in the v0.3 lifecycle","text":"","category":"section"},{"location":"changelog_tmp/#Added-3","page":"Changelog","title":"Added","text":"","category":"section"},{"location":"changelog_tmp/","page":"Changelog","title":"Changelog","text":"Add possibility to pass vector of Ns to convergence_test (#113).\nPerformance improvements by using factorized matrices for linear systems solves (#108, #112, #114).\nReflecting boundary conditions are added for the BBM-BBM equations (#104, #109).\nFix for the BBMBBMVariableEquations1D, where the still water surface was neglected leading to a bug in the Dingemans setup (#91).","category":"page"},{"location":"changelog_tmp/#Changes-when-updating-to-v0.3-from-v0.2.x","page":"Changelog","title":"Changes when updating to v0.3 from v0.2.x","text":"","category":"section"},{"location":"changelog_tmp/#Changed-3","page":"Changelog","title":"Changed","text":"","category":"section"},{"location":"changelog_tmp/","page":"Changelog","title":"Changelog","text":"Add keyword argument start_from when plotting AnalysisCallback (#87).\nManufactured solution for Svärd-Kalisch equations uses a variable bathymetry (#84).","category":"page"},{"location":"changelog_tmp/#Changes-in-the-v0.2-lifecycle","page":"Changelog","title":"Changes in the v0.2 lifecycle","text":"","category":"section"},{"location":"changelog_tmp/#Added-4","page":"Changelog","title":"Added","text":"","category":"section"},{"location":"changelog_tmp/","page":"Changelog","title":"Changelog","text":"Add SummaryCallback (#75).","category":"page"},{"location":"changelog_tmp/#Changes-when-updating-to-v0.2-from-v0.1.x","page":"Changelog","title":"Changes when updating to v0.2 from v0.1.x","text":"","category":"section"},{"location":"changelog_tmp/#Changed-4","page":"Changelog","title":"Changed","text":"","category":"section"},{"location":"changelog_tmp/","page":"Changelog","title":"Changelog","text":"The code from the master thesis of Joshua Lampert was separated (#69).\nAdd support for source terms (#65).\nA higher order interpolation is used when plotting the solution at a value x outside the grid (#64).","category":"page"},{"location":"ref-trixibase/#TrixiBase.jl-API","page":"TrixiBase","title":"TrixiBase.jl API","text":"","category":"section"},{"location":"ref-trixibase/","page":"TrixiBase","title":"TrixiBase","text":"CurrentModule = TrixiBase","category":"page"},{"location":"ref-trixibase/","page":"TrixiBase","title":"TrixiBase","text":"Modules = [TrixiBase]","category":"page"},{"location":"ref-trixibase/#TrixiBase.disable_debug_timings-Tuple{}","page":"TrixiBase","title":"TrixiBase.disable_debug_timings","text":"disable_debug_timings()\n\nDisable all @trixi_timeit timings. The timings should be optimized away, allowing for truly zero-overhead. Enable timings again with enable_debug_timings.\n\nSee also enable_debug_timings, @trixi_timeit.\n\n\n\n\n\n","category":"method"},{"location":"ref-trixibase/#TrixiBase.enable_debug_timings-Tuple{}","page":"TrixiBase","title":"TrixiBase.enable_debug_timings","text":"enable_debug_timings()\n\nEnable all @trixi_timeit timings (default behavior).\n\nSee also disable_debug_timings, @trixi_timeit.\n\n\n\n\n\n","category":"method"},{"location":"ref-trixibase/#TrixiBase.timer-Tuple{}","page":"TrixiBase","title":"TrixiBase.timer","text":"timer()\n\nMain timer for global timing, e.g., to be used with @trixi_timeit.\n\n\n\n\n\n","category":"method"},{"location":"ref-trixibase/#TrixiBase.trixi_include-Tuple{Module, AbstractString}","page":"TrixiBase","title":"TrixiBase.trixi_include","text":"trixi_include([mod::Module=Main,] elixir::AbstractString; kwargs...)\n\ninclude the file elixir and evaluate its content in the global scope of module mod. You can override specific assignments in elixir by supplying keyword arguments. Its basic purpose is to make it easier to modify some parameters while running simulations 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 elixir, the keyword argument maxiters is inserted into calls to solve with it's default value used in the SciML ecosystem for ODEs, see the \"Miscellaneous\" section of the documentation.\n\nExamples\n\njulia> using TrixiBase, Trixi\n\njulia> redirect_stdout(devnull) do\n trixi_include(@__MODULE__, joinpath(examples_dir(), \"tree_1d_dgsem\", \"elixir_advection_extended.jl\"),\n tspan=(0.0, 0.1))\n sol.t[end]\n end\n[ Info: You just called `trixi_include`. Julia may now compile the code, please be patient.\n0.1\n\n\n\n\n\n","category":"method"},{"location":"ref-trixibase/#TrixiBase.@trixi_timeit-Tuple{Any, Any, Any}","page":"TrixiBase","title":"TrixiBase.@trixi_timeit","text":"@trixi_timeit timer() \"some label\" expression\n\nBasically the same as a special case of @timeit_debug from TimerOutputs.jl, but without try ... finally ... end block. Thus, it's not exception-safe, but it also avoids some related performance problems. Since we do not use exception handling in Trixi.jl, that's not really an issue.\n\nAll @trixi_timeit timings can be disabled with disable_debug_timings. The timings should then be optimized away, allowing for truly zero-overhead.\n\nSee also disable_debug_timings, enable_debug_timings.\n\n\n\n\n\n","category":"macro"},{"location":"code_of_conduct/","page":"Code of Conduct","title":"Code of Conduct","text":"EditURL = \"https://github.com/JoshuaLampert/DispersiveShallowWater.jl/blob/main/CODE_OF_CONDUCT.md\"","category":"page"},{"location":"code_of_conduct/#code-of-conduct","page":"Code of Conduct","title":"Code of Conduct","text":"","category":"section"},{"location":"code_of_conduct/","page":"Code of Conduct","title":"Code of Conduct","text":"Contributor Covenant Code of ConductOur PledgeWe as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.Our StandardsExamples of behavior that contributes to a positive environment for our community include:Demonstrating empathy and kindness toward other people\nBeing respectful of differing opinions, viewpoints, and experiences\nGiving and gracefully accepting constructive feedback\nAccepting responsibility and apologizing to those affected by our mistakes, and learning from the experience\nFocusing on what is best not just for us as individuals, but for the overall communityExamples of unacceptable behavior include:The use of sexualized language or imagery, and sexual attention or advances of any kind\nTrolling, insulting or derogatory comments, and personal or political attacks\nPublic or private harassment\nPublishing others' private information, such as a physical or email address, without their explicit permission\nOther conduct which could reasonably be considered inappropriate in a professional settingEnforcement ResponsibilitiesCommunity leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.ScopeThis Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.EnforcementInstances of abusive, harassing, or otherwise unacceptable behavior may be reported to Joshua Lampert or Hendrik Ranocha. All complaints will be reviewed and investigated promptly and fairly.All community leaders are obligated to respect the privacy and security of the reporter of any incident.Enforcement GuidelinesCommunity leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:1. CorrectionCommunity Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.Consequence: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.2. WarningCommunity Impact: A violation through a single incident or series of actions.Consequence: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.3. Temporary BanCommunity Impact: A serious violation of community standards, including sustained inappropriate behavior.Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.4. Permanent BanCommunity Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.Consequence: A permanent ban from any sort of public interaction within the community.AttributionThis Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0.Community Impact Guidelines were inspired by Mozilla's code of conduct enforcement ladder.[homepage]: https://www.contributor-covenant.orgFor answers to common questions about this code of conduct, see the FAQ. Translations are also available there.","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 and contributors","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":"contributing/","page":"Contributing","title":"Contributing","text":"EditURL = \"https://github.com/JoshuaLampert/DispersiveShallowWater.jl/blob/main/CONTRIBUTING.md\"","category":"page"},{"location":"contributing/#Contributing","page":"Contributing","title":"Contributing","text":"","category":"section"},{"location":"contributing/","page":"Contributing","title":"Contributing","text":"DispersiveShallowWater.jl is an open-source project and we are very happy to accept contributions from the community. Please feel free to open issues or submit patches (preferably as pull requests) any time.","category":"page"},{"location":"contributing/","page":"Contributing","title":"Contributing","text":"DispersiveShallowWater.jl and its contributions are licensed under the MIT license (see License). As a contributor, you certify that all your contributions are in conformance with the Developer Certificate of Origin (Version 1.1), which is reproduced below.","category":"page"},{"location":"contributing/#Developer-Certificate-of-Origin-(Version-1.1)","page":"Contributing","title":"Developer Certificate of Origin (Version 1.1)","text":"","category":"section"},{"location":"contributing/","page":"Contributing","title":"Contributing","text":"The following text was taken from https://developercertificate.org:","category":"page"},{"location":"contributing/","page":"Contributing","title":"Contributing","text":"Developer Certificate of Origin\nVersion 1.1\n\nCopyright (C) 2004, 2006 The Linux Foundation and its contributors.\n1 Letterman Drive\nSuite D4700\nSan Francisco, CA, 94129\n\nEveryone is permitted to copy and distribute verbatim copies of this\nlicense document, but changing it is not allowed.\n\n\nDeveloper's Certificate of Origin 1.1\n\nBy making a contribution to this project, I certify that:\n\n(a) The contribution was created in whole or in part by me and I\n have the right to submit it under the open source license\n indicated in the file; or\n\n(b) The contribution is based upon previous work that, to the best\n of my knowledge, is covered under an appropriate open source\n license and I have the right under that license to submit that\n work with modifications, whether created in whole or in part\n by me, under the same open source license (unless I am\n permitted to submit under a different license), as indicated\n in the file; or\n\n(c) The contribution was provided directly to me by some other\n person who certified (a), (b) or (c) and I have not modified\n it.\n\n(d) I understand and agree that this project and the contribution\n are public and that a record of the contribution (including all\n personal information I submit with it, including my sign-off) is\n maintained indefinitely and may be redistributed consistent with\n this project or the open source license(s) involved.","category":"page"},{"location":"development/#Development","page":"Development","title":"Development","text":"","category":"section"},{"location":"development/","page":"Development","title":"Development","text":"If you have any suggestions or ideas for improvements or new features, we are pleased to accept and discuss issues or if you are willing to contribute, feel free to open a pull request, even if it is only fixing a typo or improving the docs.","category":"page"},{"location":"development/#Changing-DispersiveShallowWater.jl-and-running-it-locally","page":"Development","title":"Changing DispersiveShallowWater.jl and running it locally","text":"","category":"section"},{"location":"development/","page":"Development","title":"Development","text":"If you plan to edit DispersiveShallowWater.jl, you first need to clone a local copy of the repository, which can be done by using git. It is recommended that you create a project, e.g. call it run, inside the repository, where you can add packages that you use during executing and testing DispersiveShallowWater.jl, but are not needed by DispersiveShallowWater.jl. This way you can keep the Project.toml of the main repository clean. To do so, you can execute the following lines in a terminal:","category":"page"},{"location":"development/","page":"Development","title":"Development","text":"git clone https://github.com/JoshuaLampert/DispersiveShallowWater.jl.git\ncd DispersiveShallowWater\nmkdir run\ncd run\njulia --project=. -e 'using Pkg; Pkg.develop(PackageSpec(path=\"..\"))' # Install local DispersiveShallowWater.jl clone\njulia --project=. -e 'using Pkg; Pkg.add([\"OrdinaryDiffEq\", \"Plots\", \"SummationByPartsOperators\"])' # Install additional packages","category":"page"},{"location":"development/","page":"Development","title":"Development","text":"If you use other packages for executing DispersiveShallowWater.jl, you can add them to the project in the run directory in an analogous way as above. To use the Julia project within run, be sure to start the Julia REPL by","category":"page"},{"location":"development/","page":"Development","title":"Development","text":"julia --project=.","category":"page"},{"location":"development/","page":"Development","title":"Development","text":"if already inside the the run directory or julia --project=run if in the main directory of the repo.","category":"page"},{"location":"development/#Preview-of-the-documentation","page":"Development","title":"Preview of the documentation","text":"","category":"section"},{"location":"development/","page":"Development","title":"Development","text":"If you want to build the documentation locally, you can run","category":"page"},{"location":"development/","page":"Development","title":"Development","text":"julia --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'","category":"page"},{"location":"development/","page":"Development","title":"Development","text":"once from the DispersiveShallowWater.jl main directory to tell Documenter.jl to build the documentation of your local clone. To build the documentation, run","category":"page"},{"location":"development/","page":"Development","title":"Development","text":"julia --project=docs --color=yes docs/make.jl","category":"page"},{"location":"development/","page":"Development","title":"Development","text":"The resulting .html files can then be found in docs/build/ and you can look at them by opening them in a browser. For pull requests from the main repository (i.e. not from a fork), the documentation is automatically built and can be previewed under https://joshualampert.github.io/DispersiveShallowWater.jl/previews/PRXXX/ where XXX is the number of the pull request.","category":"page"},{"location":"changelog/","page":"Changelog","title":"Changelog","text":"EditURL = \"https://github.com/JoshuaLampert/DispersiveShallowWater.jl/blob/main/NEWS.md\"","category":"page"},{"location":"changelog/#Changelog","page":"Changelog","title":"Changelog","text":"","category":"section"},{"location":"changelog/","page":"Changelog","title":"Changelog","text":"DispersiveShallowWater.jl follows the interpretation of semantic versioning (semver) used in the Julia ecosystem. Notable changes will be documented in this file for human readability.","category":"page"},{"location":"changelog/#Changes-in-the-v0.4-lifecycle","page":"Changelog","title":"Changes in the v0.4 lifecycle","text":"","category":"section"},{"location":"changelog/#Added","page":"Changelog","title":"Added","text":"","category":"section"},{"location":"changelog/","page":"Changelog","title":"Changelog","text":"Add BBMEquation1D (#150).","category":"page"},{"location":"changelog/#Changes-when-updating-to-v0.5-from-v0.4.x","page":"Changelog","title":"Changes when updating to v0.5 from v0.4.x","text":"","category":"section"},{"location":"changelog/#Changed","page":"Changelog","title":"Changed","text":"","category":"section"},{"location":"changelog/","page":"Changelog","title":"Changelog","text":"The BBMBBMVariableEquations1D were removed and BBMBBMEquations1D now supports a bathymetry_type to choose between a flat and a variable bathymetry (#147).\nThe default of bathymetry_type for the SerreGreenNaghdiEquations1D changed from bathymetry_flat to bathymetry_variable (#147).\nbathymetry_type is now a keyword argument for all equations instead of a positional argument (#147).\nThe initial_condition_dingemans for the SerreGreenNaghdiEquations1D and HyperbolicSerreGreenNaghdiEquations1D was changed a bit to be more consistent with the other equations (#147).","category":"page"},{"location":"changelog/#Changes-in-the-v0.4-lifecycle-2","page":"Changelog","title":"Changes in the v0.4 lifecycle","text":"","category":"section"},{"location":"changelog/#Added-2","page":"Changelog","title":"Added","text":"","category":"section"},{"location":"changelog/","page":"Changelog","title":"Changelog","text":"The SerreGreenNaghdiEquations1D were added for different types of bathymetry (#127, #135).\nThe HyperbolicSerreGreenNaghdiEquations1D were added for different types of bathymetry (#139).\nThe abstract interface AbstractShallowWaterEquations was added to unify several systems such as the SerreGreenNaghdiEquations1D, the BBMBBMEquations1D, and the SvärdKalischEquations1D (#127).\nA new conversion function prim2phys was introduced, defaulting to prim2prim. prim2phys is the default conversion function for plotting.","category":"page"},{"location":"changelog/#Changes-when-updating-to-v0.4-from-v0.3.x","page":"Changelog","title":"Changes when updating to v0.4 from v0.3.x","text":"","category":"section"},{"location":"changelog/#Changed-2","page":"Changelog","title":"Changed","text":"","category":"section"},{"location":"changelog/","page":"Changelog","title":"Changelog","text":"Use ArrayPartition from RecursiveArrayTools.jl to store the solution of the ODEProblem (#118).","category":"page"},{"location":"changelog/#Changes-in-the-v0.3-lifecycle","page":"Changelog","title":"Changes in the v0.3 lifecycle","text":"","category":"section"},{"location":"changelog/#Added-3","page":"Changelog","title":"Added","text":"","category":"section"},{"location":"changelog/","page":"Changelog","title":"Changelog","text":"Add possibility to pass vector of Ns to convergence_test (#113).\nPerformance improvements by using factorized matrices for linear systems solves (#108, #112, #114).\nReflecting boundary conditions are added for the BBM-BBM equations (#104, #109).\nFix for the BBMBBMVariableEquations1D, where the still water surface was neglected leading to a bug in the Dingemans setup (#91).","category":"page"},{"location":"changelog/#Changes-when-updating-to-v0.3-from-v0.2.x","page":"Changelog","title":"Changes when updating to v0.3 from v0.2.x","text":"","category":"section"},{"location":"changelog/#Changed-3","page":"Changelog","title":"Changed","text":"","category":"section"},{"location":"changelog/","page":"Changelog","title":"Changelog","text":"Add keyword argument start_from when plotting AnalysisCallback (#87).\nManufactured solution for Svärd-Kalisch equations uses a variable bathymetry (#84).","category":"page"},{"location":"changelog/#Changes-in-the-v0.2-lifecycle","page":"Changelog","title":"Changes in the v0.2 lifecycle","text":"","category":"section"},{"location":"changelog/#Added-4","page":"Changelog","title":"Added","text":"","category":"section"},{"location":"changelog/","page":"Changelog","title":"Changelog","text":"Add SummaryCallback (#75).","category":"page"},{"location":"changelog/#Changes-when-updating-to-v0.2-from-v0.1.x","page":"Changelog","title":"Changes when updating to v0.2 from v0.1.x","text":"","category":"section"},{"location":"changelog/#Changed-4","page":"Changelog","title":"Changed","text":"","category":"section"},{"location":"changelog/","page":"Changelog","title":"Changelog","text":"The code from the master thesis of Joshua Lampert was separated (#69).\nAdd support for source terms (#65).\nA higher order interpolation is used when plotting the solution at a value x outside the grid (#64).","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 = eta_0 - D the bathymetry and v the velocity in horizontal direction. Here, eta_0 is a reference water height also called still water height. In the case of the BBM-BBM equations, eta_0 is usually taken to be 0. 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: water height and bathymetry)","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 traveling wave that moves towards a beach, which is modeled by a linearly increasing bathymetry.","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"equations = BBMBBMEquations1D(bathymetry_type = bathymetry_variable, gravity_constant = 9.81)\n\nfunction initial_condition_shoaling(x, t, equations::BBMBBMEquations1D, 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. DispersiveShallowWater.jl also supports reflecting boundary conditions for the BBMBBMEquations1D, see boundary_condition_reflecting. 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-traveling 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 (SBP) 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. Note that for non-periodic boundary conditions, the solver also needs to be created with non-periodic operators, see, e.g. examples/bbm_bbm_1d/bbm_bbm_1d_basic_reflecting.jl.","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 water height eta waterheight_total, the velocity and the entropy are computed and saved for each time step. The total water height 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\") # hide\nnothing # hide","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"(Image: shoaling solution)","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 water height. The resulting plot will have one subplot for each of the returned variables of the conversion variable. By default, the conversion function is just prim2phys, which computes the physical variables from the primitive ones, i.e., the identity for most equations.","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)\nnothing # hide","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"(Image: shoaling solution)","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 from the reproducibility repository of the master thesis of Joshua Lampert 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\") # hide\nnothing # hide","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"This creates the following figure:","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"(Image: analysis callback)","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, ylims = (-5e-16, 5e-16))\nsavefig(\"analysis_callback_relaxation.png\") # hide\nnothing # hide","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"(Image: analysis callback relaxation)","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)\nnothing # hide","category":"page"},{"location":"overview/","page":"Overview","title":"Overview","text":"(Image: shoaling solution DG)","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 from the reproducibility repository of the master thesis of Joshua Lampert.","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":"DispersiveShallowWater","title":"DispersiveShallowWater.jl API","text":"","category":"section"},{"location":"ref/","page":"DispersiveShallowWater","title":"DispersiveShallowWater","text":"CurrentModule = DispersiveShallowWater","category":"page"},{"location":"ref/","page":"DispersiveShallowWater","title":"DispersiveShallowWater","text":"Modules = [DispersiveShallowWater]\nPages = [\"DispersiveShallowWater.jl\"]","category":"page"},{"location":"ref/#DispersiveShallowWater.DispersiveShallowWater","page":"DispersiveShallowWater","title":"DispersiveShallowWater.DispersiveShallowWater","text":"DispersiveShallowWater\n\nDispersiveShallowWater.jl is a Julia package that implements structure-preserving numerical methods for dispersive shallow water models. It provides provably conservative, entropy-conserving, and well-balanced numerical schemes for some dispersive shallow water models.\n\nThe semidiscretizations are based on summation-by-parts (SBP) operators, which are implemented in SummationByPartsOperators.jl. To obtain fully discrete schemes, the time integration methods from OrdinaryDiffEq.jl are used to solve the resulting ordinary differential equations. Fully discrete entropy-conservative methods can be obtained by using the relaxation method provided by DispersiveShallowWater.jl.\n\nSee also: DispersiveShallowWater.jl\n\n\n\n\n\n","category":"module"},{"location":"ref/#Equations","page":"DispersiveShallowWater","title":"Equations","text":"","category":"section"},{"location":"ref/","page":"DispersiveShallowWater","title":"DispersiveShallowWater","text":"Modules = [DispersiveShallowWater]\nPages = Main.EQUATIONS_FILES","category":"page"},{"location":"ref/#DispersiveShallowWater.BBMEquation1D","page":"DispersiveShallowWater","title":"DispersiveShallowWater.BBMEquation1D","text":"BBMEquation1D(; bathymetry_type = bathymetry_flat, eta0 = 0.0)\n\nBBM (Benjamin–Bona–Mahony) equation in one spatial dimension. The equations are given by\n\nbeginaligned\n eta_t + etaeta_x + eta_x - eta_xxt = 0\nendaligned\n\nThe unknown quantity of the BBM equation is the total water height eta. The water height is given by h = eta - eta_0, where eta_0 is the constant still-water surface.\n\nCurrently, the equations only support a flat bathymetry b = 0, see bathymetry_flat.\n\nThe BBM equation is first described in Benjamin, Bona, and Mahony (1972). The semidiscretization implemented here is developed in Ranocha, Mitsotakis, and Ketcheson (2020). It conserves\n\nthe total water mass (integral of h) as a linear invariant\na quadratic invariant (integral of eta^2 + eta_x^2), which is called here energy_total_modified (and entropy_modified) because it contains derivatives of the solution\n\nfor periodic boundary conditions.\n\nThomas B. Benjamin, Jerry L. Bona and John J. Mahony (1972) Model equations for long waves in nonlinear dispersive systems DOI: 10.1098/rsta.1972.0032\nHendrik Ranocha, Dimitrios Mitsotakis and David I. Ketcheson (2020) A Broad Class of Conservative Numerical Methods for Dispersive Wave Equations DOI: 10.4208/cicp.OA-2020-0119\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.energy_total_modified!-Tuple{Any, Any, BBMEquation1D, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.energy_total_modified!","text":"energy_total_modified!(e, q, equations::BBMEquation1D, cache)\n\nReturn the modified total energy e of the primitive variables q_global for the BBMEquation1D. The energy_total_modified is a conserved quantity (for periodic boundary conditions).\n\nIt is given by\n\nfrac12 eta^2 + frac12 eta_x^2\n\nq_global is a vector of the primitive variables at ALL nodes. cache needs to hold the SBP operators used by the solver.\n\nSee also energy_total_modified.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_convergence_test-Tuple{Any, Any, BBMEquation1D, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.initial_condition_convergence_test","text":"initial_condition_convergence_test(x, t, equations::BBMEquation1D, mesh)\n\nA travelling-wave solution used for convergence tests in a periodic domain.\n\nSee section 4.1.3 in (there is an error in paper: it should be sech^2 instead of cosh):\n\nHendrik Ranocha, Dimitrios Mitsotakis and David I. Ketcheson (2020) A Broad Class of Conservative Numerical Methods for Dispersive Wave Equations DOI: 10.4208/cicp.OA-2020-0119\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_manufactured-Tuple{Any, Any, BBMEquation1D, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.initial_condition_manufactured","text":"initial_condition_manufactured(x, t, equations::BBMEquation1D, mesh)\n\nA smooth manufactured solution in combination with source_terms_manufactured.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.invariant_cubic-Tuple{Any, BBMEquation1D}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.invariant_cubic","text":"invariant_cubic(q, equations::BBMEquation1D)\n\nReturn the cubic invariant of the primitive variables q for the BBMEquation1D. The cubic invariant is given by\n\n(eta + 1)^3\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.source_terms_manufactured-Tuple{Any, Any, Any, BBMEquation1D}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.source_terms_manufactured","text":"source_terms_manufactured(q, x, t, equations::BBMEquation1D, mesh)\n\nA smooth manufactured solution in combination with initial_condition_manufactured.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.BBMBBMEquations1D","page":"DispersiveShallowWater","title":"DispersiveShallowWater.BBMBBMEquations1D","text":"BBMBBMEquations1D(; bathymetry_type = bathymetry_variable,\n gravity_constant, eta0 = 0.0)\n\nBBM-BBM (Benjamin–Bona–Mahony) system in one spatial dimension. The equations for flat bathymetry 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 = eta_0 - D. The water height above the bathymetry is therefore given by h = eta - eta_0 + D. The BBM-BBM equations are only implemented for eta_0 = 0.\n\nTwo types of bathymetry_type are supported:\n\nbathymetry_flat: flat bathymetry (typically b = 0 everywhere)\nbathymetry_variable: general variable bathymetry\n\nFor the general case of variable vathymetry the BBM-BBM equations are\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\nOne reference for the BBM-BBM system can be found in Bona et al. (1998). The semidiscretization implemented here was developed for flat bathymetry in Ranocha et al. (2020) and generalized for a variable bathymetry in Lampert and Ranocha (2024). It conserves\n\nthe total water mass (integral of h) as a linear invariant\nthe total velocity (integral of v) as a linear invariant for flat bathymetry\nthe total energy\n\nfor periodic boundary conditions (see Lampert, Ranocha). For reflecting boundary conditions, the semidiscretization conserves\n\nthe total water (integral of h) as a linear invariant\nthe total energy.\n\nAdditionally, it is well-balanced for the lake-at-rest stationary solution, see Lampert and Ranocha (2024).\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\nHendrik Ranocha, Dimitrios Mitsotakis, David I. Ketcheson (2020) A Broad Class of Conservative Numerical Methods for Dispersive Wave Equations DOI: 10.4208/cicp.OA-2020-0119\nJoshua Lampert, Hendrik Ranocha (2024) Structure-Preserving Numerical Methods for Two Nonlinear Systems of Dispersive Wave Equations DOI: 10.48550/arXiv.2402.16669\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.initial_condition_convergence_test-Tuple{Any, Any, BBMBBMEquations1D, Any}","page":"DispersiveShallowWater","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. 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, BBMBBMEquations1D, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.initial_condition_dingemans","text":"initial_condition_dingemans(x, t, equations::BBMBBMEquations1D, 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\nwarning: Translation of water height\nThe initial condition for the water height is translated to be around 0, which is needed for the simulation because the BBMBBMEquations1D are only implemented for eta_0 = 0.\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":"DispersiveShallowWater","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_reflecting-Tuple{Any, Any, BBMBBMEquations1D, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.initial_condition_manufactured_reflecting","text":"initial_condition_manufactured_reflecting(x, t, equations::BBMBBMEquations1D, mesh)\n\nA smooth manufactured solution for reflecting boundary conditions in combination with source_terms_manufactured_reflecting.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.source_terms_manufactured-Tuple{Any, Any, Any, BBMBBMEquations1D}","page":"DispersiveShallowWater","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_reflecting-Tuple{Any, Any, Any, BBMBBMEquations1D}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.source_terms_manufactured_reflecting","text":"source_terms_manufactured_reflecting(q, x, t, equations::BBMBBMEquations1D, mesh)\n\nA smooth manufactured solution for reflecting boundary conditions in combination with initial_condition_manufactured_reflecting.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.bathymetry_flat","page":"DispersiveShallowWater","title":"DispersiveShallowWater.bathymetry_flat","text":"bathymetry_flat = DispersiveShallowWater.BathymetryFlat()\n\nA singleton struct indicating a flat bathymetry.\n\nSee also bathymetry_mild_slope and bathymetry_variable.\n\n\n\n\n\n","category":"constant"},{"location":"ref/#DispersiveShallowWater.bathymetry_mild_slope","page":"DispersiveShallowWater","title":"DispersiveShallowWater.bathymetry_mild_slope","text":"bathymetry_mild_slope = DispersiveShallowWater.BathymetryMildSlope()\n\nA singleton struct indicating a variable bathymetry with mild-slope approximation. Typically, this means that some terms like b_x^2 are neglected.\n\nSee also bathymetry_flat and bathymetry_variable.\n\n\n\n\n\n","category":"constant"},{"location":"ref/#DispersiveShallowWater.bathymetry_variable","page":"DispersiveShallowWater","title":"DispersiveShallowWater.bathymetry_variable","text":"bathymetry_variable = DispersiveShallowWater.BathymetryVariable()\n\nA singleton struct indicating a variable bathymetry (without mild-slope approximation).\n\nSee also bathymetry_flat and bathymetry_mild_slope.\n\n\n\n\n\n","category":"constant"},{"location":"ref/#DispersiveShallowWater.AbstractEquations","page":"DispersiveShallowWater","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\nSee also AbstractShallowWaterEquations.\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.AbstractShallowWaterEquations","page":"DispersiveShallowWater","title":"DispersiveShallowWater.AbstractShallowWaterEquations","text":"AbstractShallowWaterEquations{NDIMS, NVARS}\n\nAn abstract supertype of all equation system that contain the classical shallow water equations as a subsystem, e.g., the BBMBBMEquations1D, the SvaerdKalischEquations1D, and the SerreGreenNaghdiEquations1D. In 1D, the shallow water equations with flat bathymetry are given by\n\nbeginaligned\n h_t + (h v)_x = 0\n h v_t + frac12 g (h^2)_x + frac12 h (v^2)_x = 0\nendaligned\n\nwhere h is the waterheight, v the velocity, and g the gravity_constant.\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.bathymetry-Tuple{Any, DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.bathymetry","text":"bathymetry(q, equations)\n\nReturn the bathymetry 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":"method"},{"location":"ref/#DispersiveShallowWater.cons2prim-Tuple{Any, AbstractShallowWaterEquations}","page":"DispersiveShallowWater","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":"method"},{"location":"ref/#DispersiveShallowWater.default_analysis_errors-Tuple{DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","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":"DispersiveShallowWater","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.discharge-Tuple{Any, DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","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":"DispersiveShallowWater","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-Tuple{Any, AbstractShallowWaterEquations}","page":"DispersiveShallowWater","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. For all AbstractShallowWaterEquations, the total energy is given by the sum of the kinetic and potential energy of the shallow water subsystem, i.e.,\n\nfrac12 h v^2 + frac12 g eta^2\n\nin 1D, where h is the waterheight, eta = h + b the waterheight_total, v the velocity, and g the gravity_constant.\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.energy_total_modified!-Tuple{Any, Any, DispersiveShallowWater.AbstractEquations, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.energy_total_modified!","text":"energy_total_modified!(e, q_global, equations, cache)\n\nIn-place version of energy_total_modified.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.energy_total_modified-Tuple{Any, DispersiveShallowWater.AbstractEquations, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.energy_total_modified","text":"energy_total_modified(q_global, equations, cache)\n\nReturn the modified total energy of the primitive variables q_global for the equations. This modified total energy is a conserved quantity and can contain additional terms compared to the usual energy_total. For example, for the SvaerdKalischEquations1D and the SerreGreenNaghdiEquations1D, it contains additional terms depending on the derivative of the velocity v_x modeling non-hydrostatic contributions. For equations, which are not AbstractShallowWaterEquations, the modified total energy does not have to be an extension of the usual energy_total and does not have to be related to a physical energy. However, it is still a conserved quantity and contains derivatives of the solution.\n\nq_global is a vector of the primitive variables at ALL nodes. cache needs to hold the SBP operators used by the solver if non-hydrostatic terms are present.\n\nInternally, this function allocates a vector for the output and calls DispersiveShallowWater.energy_total_modified!.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.entropy-Tuple{Any, AbstractShallowWaterEquations}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.entropy","text":"entropy(q, equations)\n\nReturn the entropy of the primitive variables q for a given set of equations. For all AbstractShallowWaterEquations, the entropy is just the energy_total.\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.entropy_modified!-NTuple{4, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.entropy_modified!","text":"entropy_modified!(e, q_global, equations, cache)\n\nIn-place version of entropy_modified.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.entropy_modified-Tuple{Any, AbstractShallowWaterEquations, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.entropy_modified","text":"entropy_modified(q_global, equations, cache)\n\nAlias for energy_total_modified.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.get_name-Tuple{DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","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-BathymetryVariable\"\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.gravity_constant-Tuple{AbstractShallowWaterEquations}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.gravity_constant","text":"gravity_constant(equations)\n\nReturn the gravity constant g for a given set of equations. See also AbstractShallowWaterEquations.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.hyperbolic_approximation_limit-Tuple{DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.hyperbolic_approximation_limit","text":"DispersiveShallowWater.hyperbolic_approximation_limit(equations)\n\nIf the equations are a hyperbolic approximation of another set of equations, return the equations of the limit system. Otherwise, return the input equations.\n\nSee also is_hyperbolic_appproximation and prim2phys.\n\nnote: Implementation details\nThis function is mostly used for some internal dispatch. For example, it allows to return a reduced set of variables from initial conditions for hyperbolic approximations.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_dingemans-Tuple{Any, Any, AbstractShallowWaterEquations, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.initial_condition_dingemans","text":"initial_condition_dingemans(x, t, equations::AbstractShallowWaterEquations, 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_discontinuous_well_balancedness-Tuple{Any, Any, AbstractShallowWaterEquations, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.initial_condition_discontinuous_well_balancedness","text":"initial_condition_discontinuous_well_balancedness(x, t, equations::AbstractShallowWaterEquations, mesh)\n\nSetup a truly discontinuous bottom topography function for this academic lake-at-rest test case of well-balancedness, i.e. eta is constant and v is zero everywhere. The error for this lake-at-rest test case ∫|η-η₀| should be around machine roundoff.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.is_hyperbolic_appproximation-Tuple{DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.is_hyperbolic_appproximation","text":"DispersiveShallowWater.is_hyperbolic_appproximation(equations)\n\nReturns Val{true}() if the equations are a hyperbolic approximation of another set of equations and Val{false}() otherwise (default). For example, the HyperbolicSerreGreenNaghdiEquations1D are a hyperbolic approximation of the SerreGreenNaghdiEquations1D.\n\nSee also hyperbolic_approximation_limit and prim2phys.\n\nnote: Implementation details\nThis function is mostly used for some internal dispatch. For example, it allows to return a reduced set of variables from initial conditions for hyperbolic approximations.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.lake_at_rest_error-Tuple{Any, DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.lake_at_rest_error","text":"lake_at_rest_error(q, equations)\n\nCalculate the error for the \"lake-at-rest\" test case where the waterheight_total eta = h + b should be a constant value over time (given by the value eta_0 passed to the equations when constructing them).\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.momentum-Tuple{Any, DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.momentum","text":"momentum(q, equations)\n\nReturn the momentum/discharge 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.prim2cons-Tuple{Any, AbstractShallowWaterEquations}","page":"DispersiveShallowWater","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":"method"},{"location":"ref/#DispersiveShallowWater.prim2phys-Tuple{Any, DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.prim2phys","text":"prim2phys(q, equations)\n\nConvert the primitive variables q to the physically meaningful variables for a given set of equations. By default, this is the same as prim2prim for most equations. However, some equations like the HyperbolicSerreGreenNaghdiEquations1D return a reduced set of variables since they are a hyperbolic approximation of another set of equations (in this case the SerreGreenNaghdiEquations1D).\n\nSee also is_hyperbolic_appproximation and hyperbolic_approximation_limit.\n\nq 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.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.prim2prim-Tuple{Any, DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","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.still_water_surface-Tuple{Any, DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.still_water_surface","text":"still_water_surface(q, equations)\n\nReturn the still water surface eta_0 (lake at rest) for a given set of equations.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.varnames","page":"DispersiveShallowWater","title":"DispersiveShallowWater.varnames","text":"varnames(conversion_function, equations)\n\nReturn the list of variable names when applying conversion_function to the primitive variables associated to equations. Common choices of the conversion_function are prim2prim, prim2cons, and prim2phys.\n\n\n\n\n\n","category":"function"},{"location":"ref/#DispersiveShallowWater.velocity-Tuple{Any, AbstractShallowWaterEquations}","page":"DispersiveShallowWater","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":"method"},{"location":"ref/#DispersiveShallowWater.waterheight-Tuple{Any, DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","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 h above the bathymetry b.\n\nq is a vector of the primitive variables at a single node, i.e., a vector of the correct length nvariables(equations).\n\nSee also waterheight_total, bathymetry.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.waterheight_total-Tuple{Any, DispersiveShallowWater.AbstractEquations}","page":"DispersiveShallowWater","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 h plus the bathymetry b.\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.HyperbolicSerreGreenNaghdiEquations1D","page":"DispersiveShallowWater","title":"DispersiveShallowWater.HyperbolicSerreGreenNaghdiEquations1D","text":"HyperbolicSerreGreenNaghdiEquations1D(; bathymetry_type = bathymetry_mild_slope,\n gravity_constant,\n eta0 = 0.0,\n lambda)\n\nHyperbolic approximation of the Serre-Green-Naghdi system in one spatial dimension. The equations for flat bathymetry are given by\n\nbeginaligned\n h_t + (h v)_x = 0\n h v_t + frac12 g (h^2)_x + frac12 h (v^2)_x\n + biggl( fraclambda3 H (1 - H h) biggr)_x = 0\n h w_t + h v w_x = lambda (1 - H h)\n H_t + H_x u = w\nendaligned\n\nThe unknown quantities of the hyperbolized Serre-Green-Naghdi equations are the total water height eta = h + b and the velocity v. The gravitational constant is denoted by g and the bottom topography (bathymetry) b = eta_0 - D. The water height above the bathymetry is therefore given by h = eta - eta_0 + D. The total water height is therefore given by eta = h + b.\n\nThere are two additional variables w approx -h v_x and H approx h compared to the SerreGreenNaghdiEquations1D. In the original papers of Gavrilyuk et al., the variable H is called eta. Here, we use eta for the total water height and H for auxiliary variable introduced in the hyperbolic approximation.\n\nnote: Initial conditions\nThe HyperbolicSerreGreenNaghdiEquations1D allow two options for specifying initial conditions:Returning the full set of variables q = (η, v, D, w, H)\nReturning a reduced set of variables q = (η, v, D) as required for the limit system SerreGreenNaghdiEquations1D of the hyperbolic approximation. The remaining variables w and H are initialized using the default initialization w approx -h v_x and H approx h using the derivative operator of the solver.\n\nThe relaxation parameter lambda (lambda) introduced to obtain this hyperbolic approximation of the SerreGreenNaghdiEquations1D influences the stiffness of the system. For lambda to infty, the hyperbolic Serre-Green-Naghdi equations converge (at least formally) to the original SerreGreenNaghdiEquations1D. However, the wave speeds of the hyperbolic system increase with increasing lambda, so that explicit time integration methods become more expensive.\n\nTwo types of bathymetry_type are supported:\n\nbathymetry_flat: flat bathymetry (typically b = 0 everywhere)\nbathymetry_mild_slope: variable bathymetry with mild-slope approximation\n\nFor the mild-slope approximation, the Serre-Green-Naghdi equations are\n\nbeginaligned\n h_t + (h v)_x = 0\n h v_t + frac12 g (h^2)_x + frac12 h (v^2)_x\n + biggl( fraclambda3 H (1 - H h) biggr)_x\n + biggl( g h + fraclambda2 (1 - H h) biggr) b_x = 0\n h w_t + h v w_x = lambda (1 - H h)\n H_t + H_x u + frac32 b_x v = w\nendaligned\n\nReferences for the hyperbolized Serre-Green-Naghdi system can be found in\n\nFavrie and Gavrilyuk. A rapid numerical method for solving Serre-Green-Naghdi equations describing long free surface gravity waves DOI: 10.1088/1361-6544/aa712d\nBusto, Dumbser, Escalante, Favrie, and Gavrilyuk. On High Order ADER Discontinuous Galerkin Schemes for First Order Hyperbolic Reformulations of Nonlinear Dispersive Systems DOI: 10.1007/s10915-021-01429-8\n\nThe semidiscretization implemented here conserves\n\nthe total water mass (integral of h) as a linear invariant\nthe total modified energy\n\nfor periodic boundary conditions (see Ranocha and Ricchiuto (2024)). Additionally, it is well-balanced for the lake-at-rest stationary solution, see\n\nHendrik Ranocha and Mario Ricchiuto (2024) Structure-preserving approximations of the Serre-Green-Naghdi equations in standard and hyperbolic form arXiv: 2408.02665\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.energy_total_modified!-Tuple{Any, Any, HyperbolicSerreGreenNaghdiEquations1D, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.energy_total_modified!","text":"DispersiveShallowWater.energy_total_modified!(e, q_global, equations::HyperbolicSerreGreenNaghdiEquations1D, cache)\n\nReturn the modified total energy e of the primitive variables q_global for the HyperbolicSerreGreenNaghdiEquations1D. It contains additional terms compared to the usual energy_total modeling non-hydrostatic contributions. The energy_total_modified is a conserved quantity (for periodic boundary conditions).\n\nFor a bathymetry_mild_slope (and a bathymetry_flat), the total modified energy is given by\n\nfrac12 g eta^2 + frac12 h v^2 +\nfrac16 h w^2 + fraclambda6 h (1 - eta h)^2\n\nq_global is a vector of the primitive variables at ALL nodes.\n\nSee also energy_total_modified.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_manufactured-Tuple{Any, Any, HyperbolicSerreGreenNaghdiEquations1D, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.initial_condition_manufactured","text":"initial_condition_manufactured(x, t, equations::HyperbolicSerreGreenNaghdiEquations1D, mesh)\n\nA smooth manufactured solution in combination with source_terms_manufactured, see\n\nHendrik Ranocha and Mario Ricchiuto (2024) Structure-preserving approximations of the Serre-Green-Naghdi equations in standard and hyperbolic form arXiv: 2408.02665\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_soliton-Tuple{Any, Any, HyperbolicSerreGreenNaghdiEquations1D, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.initial_condition_soliton","text":"initial_condition_soliton(x, t, equations::HyperbolicSerreGreenNaghdiEquations1D, mesh)\n\nA soliton solution of the SerreGreenNaghdiEquations1D used for convergence tests in a periodic domain. This is physically the same as initial_condition_convergence_test for the SerreGreenNaghdiEquations1D. Please note that this is not an exact solution of the HyperbolicSerreGreenNaghdiEquations1D (only in the limit of the relaxation parameter lambda to infty).\n\nSee also initial_condition_convergence_test.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.prim2phys-Tuple{Any, HyperbolicSerreGreenNaghdiEquations1D}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.prim2phys","text":"prim2phys(q, equations::HyperbolicSerreGreenNaghdiEquations1D)\n\nReturn the physical variables eta v D used also by the SerreGreenNaghdiEquations1D from the main variables q for the HyperbolicSerreGreenNaghdiEquations1D.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.source_terms_manufactured-Tuple{Any, Any, Any, HyperbolicSerreGreenNaghdiEquations1D}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.source_terms_manufactured","text":"source_terms_manufactured(q, x, t, equations::HyperbolicSerreGreenNaghdiEquations1D, mesh)\n\nA smooth manufactured solution in combination with initial_condition_manufactured.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.SerreGreenNaghdiEquations1D","page":"DispersiveShallowWater","title":"DispersiveShallowWater.SerreGreenNaghdiEquations1D","text":"SerreGreenNaghdiEquations1D(; bathymetry_type = bathymetry_variable,\n gravity_constant, eta0 = 0.0)\n\nSerre-Green-Naghdi system in one spatial dimension. The equations for flat bathymetry are given by\n\nbeginaligned\n h_t + (h v)_x = 0\n h v_t - frac13 (h^3 v_tx)_x + frac12 g (h^2)_x + frac12 h (v^2)_x + p_x = 0\n p = frac13 h^3 v_x^2 - frac13 h^3 v v_xx\nendaligned\n\nThe unknown quantities of the Serre-Green-Naghdi equations are the total water height eta = h + b and the velocity v. The gravitational constant is denoted by g and the bottom topography (bathymetry) b = eta_0 - D. The water height above the bathymetry is therefore given by h = eta - eta_0 + D. The total water height is therefore given by eta = h + b.\n\nThree types of bathymetry_type are supported:\n\nbathymetry_flat: flat bathymetry (typically b = 0 everywhere)\nbathymetry_mild_slope: variable bathymetry with mild-slope approximation\nbathymetry_variable: general variable bathymetry\n\nFor the mild-slope approximation, the Serre-Green-Naghdi equations are\n\nbeginaligned\n h_t + (h v)_x = 0\n h v_t - frac13 (h^3 v_tx)_x + frac12 (h^2 b_x u_t)_x - frac12 h^2 b_x u_tx + frac34 h b_x^2 u_t\n + frac12 g (h^2)_x + g h b_x + frac12 h (v^2)_x\n + p_x + frac32 fracph b_x = 0\n p = frac13 h^3 v_x^2 - frac13 h^3 v v_xx\n + frac12 h^2 v (b_x v)_x\nendaligned\n\nFor the general case of variable vathymetry without mild-slope approximation, the Serre-Green-Naghdi equations are\n\nbeginaligned\n h_t + (h v)_x = 0\n h v_t - frac13 (h^3 v_tx)_x + frac12 (h^2 b_x u_t)_x - frac12 h^2 b_x u_tx + h b_x^2 u_t\n + frac12 g (h^2)_x + g h b_x + frac12 h (v^2)_x\n + p_x + frac32 fracph b_x + psi b_x = 0\n p = frac13 h^3 v_x^2 - frac13 h^3 v v_xx\n + frac12 h^2 v (b_x v)_x\n psi = frac14 h v (b_x v)_x\nendaligned\n\nReferences for the Serre-Green-Naghdi system can be found in\n\nSerre (1953) Contribution â l'étude des écoulements permanents et variables dans les canaux DOI: 10.1051/lhb/1953034\nGreen and Naghdi (1976) A derivation of equations for wave propagation in water of variable depth DOI: 10.1017/S0022112076002425\n\nThe semidiscretization implemented here conserves\n\nthe total water mass (integral of h) as a linear invariant\nthe total momentum (integral of h v) as a nonlinear invariant if the bathymetry is constant\nthe total modified energy\n\nfor periodic boundary conditions (see Ranocha and Ricchiuto (2024)). Additionally, it is well-balanced for the lake-at-rest stationary solution, see\n\nHendrik Ranocha and Mario Ricchiuto (2024) Structure-preserving approximations of the Serre-Green-Naghdi equations in standard and hyperbolic form arXiv: 2408.02665\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.energy_total_modified!-Tuple{Any, Any, SerreGreenNaghdiEquations1D, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.energy_total_modified!","text":"DispersiveShallowWater.energy_total_modified!(e, q_global, equations::SerreGreenNaghdiEquations1D, cache)\n\nReturn the modified total energy e of the primitive variables q_global for the SerreGreenNaghdiEquations1D. It contains an additional term containing a derivative compared to the usual energy_total modeling non-hydrostatic contributions. The energy_total_modified is a conserved quantity (for periodic boundary conditions).\n\nFor a bathymetry_flat the total modified energy is given by\n\nfrac12 g eta^2 + frac12 h v^2 + frac16 h^3 v_x^2\n\nFor a bathymetry_mild_slope the total modified energy is given by\n\nfrac12 g eta^2 + frac12 h v^2 + frac16 h (-h v_x + 15 v b_x)^2\n\nFor a bathymetry_variable the total modified energy has the additional term\n\n+ frac18 h (v b_x)^2\n\nq_global is a vector of the primitive variables at ALL nodes. cache needs to hold the SBP operators used by the solver.\n\nSee also energy_total_modified.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_convergence_test-Tuple{Any, Any, SerreGreenNaghdiEquations1D, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.initial_condition_convergence_test","text":"initial_condition_convergence_test(x, t, equations::SerreGreenNaghdiEquations1D, mesh)\n\nA soliton solution used for convergence tests in a periodic domain.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.SvaerdKalischEquations1D","page":"DispersiveShallowWater","title":"DispersiveShallowWater.SvaerdKalischEquations1D","text":"SvaerdKalischEquations1D(; bathymetry_type = bathymetry_variable,\n gravity_constant, eta0 = 0.0, alpha = 0.0,\n beta = 0.2308939393939394, gamma = 0.04034343434343434)\n\nDispersive system by Svärd and Kalisch (2023) in one spatial dimension. The equations for variable bathymetry 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 = eta_0 - D. The water height above the bathymetry is therefore given by h = eta - eta_0 + D.\n\nCurrently, the equations only support a general variable bathymetry, see bathymetry_variable.\n\nSvärdKalischEquations1D is an alias for SvaerdKalischEquations1D.\n\nThe equations by Svärd and Kalisch are presented and analyzed in Svärd and Kalisch (2023). The semidiscretization implemented here conserves\n\nthe total water mass (integral of h) as a linear invariant\nthe total momentum (integral of h v) as a nonlinear invariant for flat bathymetry\nthe total modified energy\n\nfor periodic boundary conditions (see Lampert, Ranocha). Additionally, it is well-balanced for the lake-at-rest stationary solution, see Lampert and Ranocha (2024).\n\nMagnus Svärd, Henrik Kalisch (2023) A novel energy-bounded Boussinesq model and a well-balanced and stable numerical discretization arXiv: 2302.09924\nJoshua Lampert, Hendrik Ranocha (2024) Structure-Preserving Numerical Methods for Two Nonlinear Systems of Dispersive Wave Equations DOI: 10.48550/arXiv.2402.16669\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.energy_total_modified!-Tuple{Any, Any, SvaerdKalischEquations1D, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.energy_total_modified!","text":"DispersiveShallowWater.energy_total_modified!(e, q_global, equations::SvaerdKalischEquations1D, cache)\n\nReturn the modified total energy e of the primitive variables q_global for the SvaerdKalischEquations1D. It contains an additional term containing a derivative compared to the usual energy_total modeling non-hydrostatic contributions. The energy_total_modified is a conserved quantity (for periodic boundary conditions).\n\nIt is given by\n\nfrac12 g eta^2 + frac12 h v^2 + frac12 hatbeta v_x^2\n\nq_global is a vector of the primitive variables at ALL nodes. cache needs to hold the SBP operators used by the solver.\n\nSee also energy_total_modified.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.initial_condition_manufactured-Tuple{Any, Any, SvaerdKalischEquations1D, Any}","page":"DispersiveShallowWater","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.source_terms_manufactured-Tuple{Any, Any, Any, SvaerdKalischEquations1D}","page":"DispersiveShallowWater","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/#Mesh","page":"DispersiveShallowWater","title":"Mesh","text":"","category":"section"},{"location":"ref/","page":"DispersiveShallowWater","title":"DispersiveShallowWater","text":"Modules = [DispersiveShallowWater]\nPages = [\"mesh.jl\"]","category":"page"},{"location":"ref/#DispersiveShallowWater.Mesh1D","page":"DispersiveShallowWater","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":"DispersiveShallowWater","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/#Boundary-conditions","page":"DispersiveShallowWater","title":"Boundary conditions","text":"","category":"section"},{"location":"ref/","page":"DispersiveShallowWater","title":"DispersiveShallowWater","text":"Modules = [DispersiveShallowWater]\nPages = [\"boundary_conditions.jl\"]","category":"page"},{"location":"ref/#DispersiveShallowWater.boundary_condition_periodic","page":"DispersiveShallowWater","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.boundary_condition_reflecting","page":"DispersiveShallowWater","title":"DispersiveShallowWater.boundary_condition_reflecting","text":"boundary_condition_reflecting = DispersiveShallowWater.BoundaryConditionReflecting()\n\nA singleton struct indicating reflecting boundary conditions.\n\n\n\n\n\n","category":"constant"},{"location":"ref/#Solver","page":"DispersiveShallowWater","title":"Solver","text":"","category":"section"},{"location":"ref/","page":"DispersiveShallowWater","title":"DispersiveShallowWater","text":"Modules = [DispersiveShallowWater]\nPages = [\"solver.jl\"]","category":"page"},{"location":"ref/#DispersiveShallowWater.AbstractSolver","page":"DispersiveShallowWater","title":"DispersiveShallowWater.AbstractSolver","text":"AbstractSolver\n\nAn abstract supertype of specific solvers.\n\n\n\n\n\n","category":"type"},{"location":"ref/#DispersiveShallowWater.Solver","page":"DispersiveShallowWater","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":"DispersiveShallowWater","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{Nothing, AbstractMatrix{RealT}, SummationByPartsOperators.AbstractDerivativeOperator{RealT}}}} where RealT","page":"DispersiveShallowWater","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. It can also be nothing if no second derivative is used by the discretization. Both summation-by-parts operators should be associated with the same grid.\n\n\n\n\n\n","category":"method"},{"location":"ref/#Semidiscretization","page":"DispersiveShallowWater","title":"Semidiscretization","text":"","category":"section"},{"location":"ref/","page":"DispersiveShallowWater","title":"DispersiveShallowWater","text":"Modules = [DispersiveShallowWater]\nPages = [\"semidiscretization.jl\"]","category":"page"},{"location":"ref/#DispersiveShallowWater.Semidiscretization","page":"DispersiveShallowWater","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":"DispersiveShallowWater","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=(tmp1 = Array{RealT}(undef, nnodes(mesh)),))\n\nConstruct a semidiscretization of a PDE.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.semidiscretize-Tuple{Semidiscretization, Any}","page":"DispersiveShallowWater","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/#SummationByPartsOperators.grid-Tuple{Semidiscretization}","page":"DispersiveShallowWater","title":"SummationByPartsOperators.grid","text":"grid(semi)\n\nGet the grid of a semidiscretization.\n\n\n\n\n\n","category":"method"},{"location":"ref/#Callbacks","page":"DispersiveShallowWater","title":"Callbacks","text":"","category":"section"},{"location":"ref/","page":"DispersiveShallowWater","title":"DispersiveShallowWater","text":"Modules = [DispersiveShallowWater]\nPages = Main.CALLBACKS_STEP_FILES","category":"page"},{"location":"ref/#DispersiveShallowWater.AnalysisCallback","page":"DispersiveShallowWater","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.errors-Union{Tuple{SciMLBase.DiscreteCallback{Condition, Affect!}}, Tuple{Affect!}, Tuple{Condition}} where {Condition, Affect!<:AnalysisCallback}","page":"DispersiveShallowWater","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.integrals-Union{Tuple{SciMLBase.DiscreteCallback{Condition, Affect!}}, Tuple{Affect!}, Tuple{Condition}} where {Condition, Affect!<:AnalysisCallback}","page":"DispersiveShallowWater","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.tstops-Union{Tuple{SciMLBase.DiscreteCallback{Condition, Affect!}}, Tuple{Affect!}, Tuple{Condition}} where {Condition, Affect!<:AnalysisCallback}","page":"DispersiveShallowWater","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.RelaxationCallback","page":"DispersiveShallowWater","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.SummaryCallback","page":"DispersiveShallowWater","title":"DispersiveShallowWater.SummaryCallback","text":"SummaryCallback(io::IO = stdout)\n\nCreate and return a callback that resets the timer at the beginning of a simulation and prints the timer values at the end of the simulation.\n\n\n\n\n\n","category":"type"},{"location":"ref/#Utilities","page":"DispersiveShallowWater","title":"Utilities","text":"","category":"section"},{"location":"ref/","page":"DispersiveShallowWater","title":"DispersiveShallowWater","text":"Modules = [DispersiveShallowWater]\nPages = [\"util.jl\"]","category":"page"},{"location":"ref/#DispersiveShallowWater.convergence_test-Tuple{Module, AbstractString, Any}","page":"DispersiveShallowWater","title":"DispersiveShallowWater.convergence_test","text":"convergence_test([mod::Module=Main,] example::AbstractString, iterations; io::IO = stdout, kwargs...)\nconvergence_test([mod::Module=Main,] example::AbstractString, Ns::AbstractVector; io::IO = stdout, kwargs...)\n\nRun multiple simulations using the setup given in example and compute the experimental order of convergence (EOC) in the L^2 and L^infty norm. If iterations is passed as integer, in each iteration, the resolution of the respective mesh will be doubled. If Ns is passed as vector, the simulations will be run for each value of Ns. Additional keyword arguments kwargs... and the optional module mod are passed directly to trixi_include.\n\nAdjusted from Trixi.jl.\n\n\n\n\n\n","category":"method"},{"location":"ref/#DispersiveShallowWater.default_example-Tuple{}","page":"DispersiveShallowWater","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.examples_dir-Tuple{}","page":"DispersiveShallowWater","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":"DispersiveShallowWater","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.@autoinfiltrate","page":"DispersiveShallowWater","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: codecov) (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 some dispersive shallow water models:","category":"page"},{"location":"","page":"Home","title":"Home","text":"the Benjamin-Bona-Mahony (BBM) equation, also known as regularized long-wave equation,\nthe BBM-BBM equations with varying bottom topography,\nthe dispersive shallow water model proposed by Magnus Svärd and Henrik Kalisch,\nthe Serre-Green-Naghdi equations.","category":"page"},{"location":"","page":"Home","title":"Home","text":"The semidiscretizations are based on summation-by-parts (SBP) operators, which are implemented in SummationByPartsOperators.jl. To obtain fully discrete schemes, the time integration methods from OrdinaryDiffEq.jl are used to solve the resulting ordinary differential equations. Fully discrete entropy-conservative methods can be obtained by using the relaxation method provided by DispersiveShallowWater.jl.","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.9 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":"#Referencing","page":"Home","title":"Referencing","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"You can directly refer to DispersiveShallowWater.jl as","category":"page"},{"location":"","page":"Home","title":"Home","text":"@misc{lampert2023dispersive,\n title={{D}ispersive{S}hallow{W}ater.jl: {S}tructure-preserving numerical\n methods for dispersive shallow water models},\n author={Lampert, Joshua and Ranocha, Hendrik},\n year={2023},\n month={10},\n howpublished={\\url{https://github.com/JoshuaLampert/DispersiveShallowWater.jl}},\n doi={10.5281/zenodo.10034636}\n}","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 (University of Hamburg) with contributions from Hendrik Ranocha (Johannes Gutenberg University Mainz). Some parts of this repository are based on parts of Dispersive-wave-schemes-notebooks. A Broad Class of Conservative Numerical Methods for Dispersive Wave Equations by Hendrik Ranocha, Dimitrios Mitsotakis and David Ketcheson. The code structure is inspired by Trixi.jl.","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"}] }