From 240a5e9478df348edbadc31e8fc2d3081f21251e Mon Sep 17 00:00:00 2001 From: patrickersing Date: Wed, 21 Aug 2024 09:43:41 +0200 Subject: [PATCH 01/16] update Readme, create page links --- README.md | 27 +++++++++++++++++++++++++++ docs/make.jl | 4 ++++ 2 files changed, 31 insertions(+) diff --git a/README.md b/README.md index ab3a2e7..6db86ce 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,33 @@ [![Coverage](https://codecov.io/gh/trixi-framework/TrixiShallowWater.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/trixi-framework/TrixiShallowWater.jl) [![Coverage](https://coveralls.io/repos/github/trixi-framework/TrixiShallowWater.jl/badge.svg?branch=main)](https://coveralls.io/github/trixi-framework/TrixiShallowWater.jl?branch=main) +**TrixiShallowWater.jl** is a numerical simulation package focused on solving shallow water equations +with the discontinuous Galerkin method and written in Julia. The package builds on the numerical solver [Trixi.jl](https://github.com/trixi-framework/Trixi.jl) +and provides several specialized models and features specific for shallow water applications. + +## Examples + +## Installation +TrixiShallowWater.jl is **not** a registered Julia package, and therefore needs to be downloaded manually and then run from with the cloned directory: +```bash +git clone https://github.com/trixi-framework/TrixiShallowWater.jl.git +julia --project=@. +``` +In addition TrixiShallowWater.jl requires the numerical solver framework [Trixi.jl](https://github.com/trixi-framework/Trixi.jl), [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) for time integration, and [Plots.jl](https://github.com/JuliaPlots/Plots.jl) for visualization, which can be installed by executing the following in the Julia REPL: +```julia +julia> using Pkg + +julia> Pkg.add(["Trixi", "Trixi2Vtk", "OrdinaryDiffEq", "Plots"]) +``` + +## License and contributing +TrixiShallowWater.jl is licensed under the MIT license (see [LICENSE.md](LICENSE.md)). Since Trixi.jl is +an open-source project, we are very happy to accept contributions from the +community. To get in touch with the developers, +[join us on Slack](https://join.slack.com/t/trixi-framework/shared_invite/zt-sgkc6ppw-6OXJqZAD5SPjBYqLd8MU~g) +or [create an issue](https://github.com/trixi-framework/TrixiShallowWater.jl/issues/new). + + **Note: This repository is still in its alpha stage and anything might change at any time and without warning, including the deletion of this repository itself.** diff --git a/docs/make.jl b/docs/make.jl index d285e8d..1c39f72 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -21,6 +21,10 @@ makedocs(; assets = String[],), pages = [ "Home" => "index.md", + "Installation" => "installation.md", + "Tutorials" => "tutorial.md", + "Authors" => "authors.md", + "License" => "license.md", ], plugins = [links],) From d185618c3530cd56f282869a8fd3790b3746586d Mon Sep 17 00:00:00 2001 From: patrickersing Date: Wed, 21 Aug 2024 14:37:05 +0200 Subject: [PATCH 02/16] add authors list, update license --- AUTHORS.md | 22 ++++++++++++++++++++++ LICENSE.md | 2 +- 2 files changed, 23 insertions(+), 1 deletion(-) create mode 100644 AUTHORS.md diff --git a/AUTHORS.md b/AUTHORS.md new file mode 100644 index 0000000..4819252 --- /dev/null +++ b/AUTHORS.md @@ -0,0 +1,22 @@ +# Authors + +TrixiShallowWater.jl's development is coordinated by a group of *principal developers*, +who are also its main contributors and who can be contacted in case of +questions about TrixiShallowWater.jl. In addition, there are *contributors* who have +provided substantial additions or modifications. Together, these two groups form +"The TrixiShallowWater.jl Authors" as mentioned in the [LICENSE.md](LICENSE.md) file. + +## Principal Developers +* [Andrew Winters](https://liu.se/en/employee/andwi94), + Linköping University, Sweden +* [Patrick Ersing](https://liu.se/en/employee/pater53), + Linköping University, Sweden + +## Contributors +The following people contributed major additions or modifications to TrixiShallowWater.jl and +are listed in alphabetical order: + +* Patrick Ersing +* Hendrik Ranocha +* Michael Schlottke-Lakemper +* Andrew Winters \ No newline at end of file diff --git a/LICENSE.md b/LICENSE.md index 220a3e3..098011d 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2023-present The Trixi.jl Authors (see [trixi-framework/Trixi.jl/AUTHORS.md](https://github.com/trixi-framework/Trixi.jl/blob/main/AUTHORS.md)) +Copyright (c) 2023-present The TrixiShallowWater.jl Authors (see [trixi-framework/TrixiShallowWater.jl/AUTHORS.md](https://github.com/trixi-framework/TrixiShallowWater.jl/blob/main/AUTHORS.md)) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal From 7a7850e67c6f5ca5b016fb586e30df7dc82bc403 Mon Sep 17 00:00:00 2001 From: patrickersing Date: Wed, 21 Aug 2024 14:40:13 +0200 Subject: [PATCH 03/16] add code of conduct --- CODE_OF_CONDUCT.md | 128 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 CODE_OF_CONDUCT.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..b4dc837 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,128 @@ +# 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 the principal developers responsible for enforcement listed in +[AUTHORS.md](AUTHORS.md). +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, available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. \ No newline at end of file From cd20833981e4513b3b257cd8e1970648b9f92cc5 Mon Sep 17 00:00:00 2001 From: patrickersing Date: Wed, 21 Aug 2024 14:42:46 +0200 Subject: [PATCH 04/16] add contributing --- CONTRIBUTING.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..8ee0417 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,57 @@ +# Contributing + +TrixiShallowWater.jl is an open-source project and we are very happy to accept contributions +from the community. Please feel free to +[open issues](https://github.com/trixi-framework/TrixiShallowWater.jl/issues/new/choose) +or submit patches (preferably as +[pull requests](https://github.com/trixi-framework/TrixiShallowWater.jl/pulls)) +any time. For planned larger contributions, it is often beneficial to get +in contact with one of the principal developers first (see +[AUTHORS.md](AUTHORS.md)). + +TrixiShallowWater.jl and its contributions are licensed under the MIT license (see +[LICENSE.md](LICENSE.md)). 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. + +## Developer Certificate of Origin (Version 1.1) +The following text was taken from +[https://developercertificate.org](https://developercertificate.org): + + Developer Certificate of Origin + Version 1.1 + + Copyright (C) 2004, 2006 The Linux Foundation and its contributors. + 1 Letterman Drive + Suite D4700 + San Francisco, CA, 94129 + + Everyone is permitted to copy and distribute verbatim copies of this + license document, but changing it is not allowed. + + + Developer's Certificate of Origin 1.1 + + By making a contribution to this project, I certify that: + + (a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + + (b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + + (c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + + (d) I understand and agree that this project and the contribution + 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. \ No newline at end of file From a16d6b545535e3766495119699589376bb055fca Mon Sep 17 00:00:00 2001 From: patrickersing Date: Wed, 21 Aug 2024 14:44:57 +0200 Subject: [PATCH 05/16] add pages for Contributing, CodeOfConduct --- docs/make.jl | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/make.jl b/docs/make.jl index 1c39f72..cd94fb6 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -24,6 +24,8 @@ makedocs(; "Installation" => "installation.md", "Tutorials" => "tutorial.md", "Authors" => "authors.md", + "Contributing" => "contributing.md", + "Code of Conduct" => "code_of_conduct.md", "License" => "license.md", ], plugins = [links],) From caba44612789e469d5fee21a5da30fdf34409e26 Mon Sep 17 00:00:00 2001 From: patrickersing Date: Wed, 21 Aug 2024 15:03:16 +0200 Subject: [PATCH 06/16] update make to create pages --- docs/make.jl | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/docs/make.jl b/docs/make.jl index cd94fb6..092ca4a 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -6,9 +6,53 @@ using DocumenterInterLinks links = InterLinks("Trixi" => ("https://trixi-framework.github.io/Trixi.jl/stable/", "https://trixi-framework.github.io/Trixi.jl/stable/objects.inv")) + +# Copy list of authors to not need to synchronize it manually +authors_text = read(joinpath(dirname(@__DIR__), "AUTHORS.md"), String) +authors_text = replace(authors_text, "in the [LICENSE.md](LICENSE.md) file" => "under [License](@ref)") +write(joinpath(@__DIR__, "src", "authors.md"), authors_text) + + DocMeta.setdocmeta!(TrixiShallowWater, :DocTestSetup, :(using TrixiShallowWater); recursive = true) +# Copy some files from the repository root directory to the docs and modify them +# as necessary +# Based on: https://github.com/ranocha/SummationByPartsOperators.jl/blob/0206a74140d5c6eb9921ca5021cb7bf2da1a306d/docs/make.jl#L27-L41 +open(joinpath(@__DIR__, "src", "code_of_conduct.md"), "w") do io + # Point to source license file + println(io, + """ + ```@meta + EditURL = "https://github.com/trixi-framework/TrixiShallowWater.jl/blob/main/CODE_OF_CONDUCT.md" + ``` + """) + # Write the modified contents + println(io, "# [Code of Conduct](@id code-of-conduct)") + println(io, "") + for line in eachline(joinpath(dirname(@__DIR__), "CODE_OF_CONDUCT.md")) + line = replace(line, "[AUTHORS.md](AUTHORS.md)" => "[Authors](@ref)") + println(io, "> ", line) + end +end + +open(joinpath(@__DIR__, "src", "contributing.md"), "w") do io + # Point to source license file + println(io, + """ + ```@meta + EditURL = "https://github.com/trixi-framework/TrixiTrixiShallowWater.jl/blob/main/CONTRIBUTING.md" + ``` + """) + # Write the modified contents + for line in eachline(joinpath(dirname(@__DIR__), "CONTRIBUTING.md")) + line = replace(line, "[LICENSE.md](LICENSE.md)" => "[License](@ref)") + line = replace(line, "[AUTHORS.md](AUTHORS.md)" => "[Authors](@ref)") + println(io, line) + end +end + + makedocs(; modules = [TrixiShallowWater], authors = "Andrew R. Winters , Michael Schlottke-Lakemper ", From 5dc82b4776f44029c766063918541ac3a9218c53 Mon Sep 17 00:00:00 2001 From: patrickersing Date: Wed, 21 Aug 2024 15:03:46 +0200 Subject: [PATCH 07/16] create placeholder for missing pages --- docs/src/installation.md | 1 + docs/src/license.md | 23 +++++++++++++++++++++++ docs/src/tutorial.md | 1 + 3 files changed, 25 insertions(+) create mode 100644 docs/src/installation.md create mode 100644 docs/src/license.md create mode 100644 docs/src/tutorial.md diff --git a/docs/src/installation.md b/docs/src/installation.md new file mode 100644 index 0000000..f34d65b --- /dev/null +++ b/docs/src/installation.md @@ -0,0 +1 @@ +# Installation \ No newline at end of file diff --git a/docs/src/license.md b/docs/src/license.md new file mode 100644 index 0000000..f3aa3db --- /dev/null +++ b/docs/src/license.md @@ -0,0 +1,23 @@ +# License + +> MIT License +> +> Copyright (c) 2020-present The TrixiShallowWater.jl Authors (see [Authors](@ref)) +> +> 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/docs/src/tutorial.md b/docs/src/tutorial.md new file mode 100644 index 0000000..203501d --- /dev/null +++ b/docs/src/tutorial.md @@ -0,0 +1 @@ +# Tutorial \ No newline at end of file From 26604097d0123e8e7740cba3ef197a1b8e0dfa68 Mon Sep 17 00:00:00 2001 From: patrickersing Date: Wed, 21 Aug 2024 15:05:47 +0200 Subject: [PATCH 08/16] update .gitignore --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index 70e0ee5..11361eb 100644 --- a/.gitignore +++ b/.gitignore @@ -13,6 +13,9 @@ **/Manifest.toml out*/ docs/build +docs/src/authors.md +docs/src/code_of_conduct.md +docs/src/contributing.md public/ coverage/ coverage_report/ From 916be0a4625ae08df45e021ca95286259c980f55 Mon Sep 17 00:00:00 2001 From: patrickersing Date: Wed, 21 Aug 2024 15:08:46 +0200 Subject: [PATCH 09/16] fix external links in docstrings --- src/equations/shallow_water_multilayer_2d.jl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/equations/shallow_water_multilayer_2d.jl b/src/equations/shallow_water_multilayer_2d.jl index 555f18b..7ef5d55 100644 --- a/src/equations/shallow_water_multilayer_2d.jl +++ b/src/equations/shallow_water_multilayer_2d.jl @@ -52,7 +52,7 @@ This affects the implementation and use of these equations in various ways: * The flux values corresponding to the bottom topography must be zero. * The bottom topography values must be included when defining initial conditions, boundary conditions or source terms. -* [`AnalysisCallback`](@ref) analyzes this variable. +* [`Trixi.AnalysisCallback`](@extref) analyzes this variable. * Trixi's visualization tools will visualize the bottom topography by default. A good introduction for the MLSWE is available in Chapter 12 of the book: @@ -360,7 +360,7 @@ end boundary_condition_slip_wall(u_inner, orientation, direction, x, t, surface_flux_function, equations::ShallowWaterMultiLayerEquations2D) -Should be used together with [`TreeMesh`](@ref). +Should be used together with [`Trixi.TreeMesh`](@extref). """ @inline function Trixi.boundary_condition_slip_wall(u_inner, orientation, direction, x, t, From 24ba9db35d0d2abcf3d15bb4f62f0bf611fc9242 Mon Sep 17 00:00:00 2001 From: patrickersing Date: Wed, 21 Aug 2024 16:11:44 +0200 Subject: [PATCH 10/16] add pages for development and testing --- docs/make.jl | 8 ++--- docs/src/development.md | 47 ++++++++++++++++++++++++ docs/src/testing.md | 80 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 131 insertions(+), 4 deletions(-) create mode 100644 docs/src/development.md create mode 100644 docs/src/testing.md diff --git a/docs/make.jl b/docs/make.jl index 092ca4a..5489017 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -6,13 +6,12 @@ using DocumenterInterLinks links = InterLinks("Trixi" => ("https://trixi-framework.github.io/Trixi.jl/stable/", "https://trixi-framework.github.io/Trixi.jl/stable/objects.inv")) - # Copy list of authors to not need to synchronize it manually authors_text = read(joinpath(dirname(@__DIR__), "AUTHORS.md"), String) -authors_text = replace(authors_text, "in the [LICENSE.md](LICENSE.md) file" => "under [License](@ref)") +authors_text = replace(authors_text, + "in the [LICENSE.md](LICENSE.md) file" => "under [License](@ref)") write(joinpath(@__DIR__, "src", "authors.md"), authors_text) - DocMeta.setdocmeta!(TrixiShallowWater, :DocTestSetup, :(using TrixiShallowWater); recursive = true) @@ -51,7 +50,6 @@ open(joinpath(@__DIR__, "src", "contributing.md"), "w") do io println(io, line) end end - makedocs(; modules = [TrixiShallowWater], @@ -67,6 +65,8 @@ makedocs(; "Home" => "index.md", "Installation" => "installation.md", "Tutorials" => "tutorial.md", + "Advanced topics & developers" => ["Development" => "development.md" + "Testing" => "testing.md"], "Authors" => "authors.md", "Contributing" => "contributing.md", "Code of Conduct" => "code_of_conduct.md", diff --git a/docs/src/development.md b/docs/src/development.md new file mode 100644 index 0000000..edaee30 --- /dev/null +++ b/docs/src/development.md @@ -0,0 +1,47 @@ +# Development + +This page contains some helpful information for the development of TrixiShallowWater.jl. Further +information about helpful tools for package development in Julia can be found on the +[development page](https://trixi-framework.github.io/Trixi.jl/stable/development/) of the Trixi.jl docs + +## Releasing a new version of TrixiShallowWater + +- Check whether everything is okay, tests pass etc. +- Set the new version number in `Project.toml` according to the Julian version of semver. + Commit and push. +- Comment `@JuliaRegistrator register` on the commit setting the version number. +- `JuliaRegistrator` will create a PR with the new version in the General registry. + Wait for it to be merged. +- Increment the version number in `Project.toml` again with suffix `-pre`. For example, + if you have released version `v0.2.0`, use `v0.2.1-pre` as new version number. + + + +## Preview the documentation + +You can build the documentation of TrixiShallowWater.jl locally by running +```bash +julia --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()' +julia --project=docs --color=yes docs/make.jl +``` +from the TrixiShallowWater.jl main directory. Then, you can look at the html files generated in +`docs/build`. + + + +## Developing with a local Trixi.jl version + +TrixiShallowWater.jl has Trixi.jl as a dependency and uses Trixi.jl's implementation. +When developing TrixiShallowWater.jl, one may want to change functions in Trixi.jl to allow them to be reused +in TrixiShallowWater.jl. +To use a locally modified Trixi.jl clone instead of a Trixi.jl release, one can tell Pkg +to use the local source code of Trixi.jl instead of a registered version by running +```julia-repl +using Pkg +Pkg.develop(PackageSpec(path="path/to/Trixi.jl")) +``` + +To switch back from a local version to a Trixi.jl release run +```julia-repl +Pkg.free("Trixi") +``` diff --git a/docs/src/testing.md b/docs/src/testing.md new file mode 100644 index 0000000..4de5568 --- /dev/null +++ b/docs/src/testing.md @@ -0,0 +1,80 @@ +# Testing + +During the development of TrixiShallowWater.jl, we rely on +[continuous testing](https://en.wikipedia.org/wiki/Continuous_testing) to ensure +that modifications or new features do not break existing +functionality or add other errors. In the main +[TrixiShallowWater](https://github.com/trixi-framework/TrixiShallowWater.jl) repository, this is facilitated by +[GitHub Actions](https://docs.github.com/en/free-pro-team@latest/actions), +which allows to run tests automatically upon certain events. When, how, and what +is tested by GitHub Actions is controlled by the workflow file +[`.github/workflows/ci.yml`](https://github.com/trixi-framework/TrixiShallowWater.jl/blob/main/.github/workflows/ci.yml). +In TrixiShallowWater.jl tests are triggered by +* each `git push` to `main` and +* each `git push` to any pull request. +Besides checking functionality, we also analyze the [Test coverage](@ref) to +ensure that we do not miss important parts during testing. + +!!! note "Test and coverage requirements" + Before merging a pull request (PR) to `main`, we require that + * the code passes all functional tests + * code coverage does not decrease. + + +## Testing setup +The entry point for all testing is the file +[`test/runtests.jl`](https://github.com/trixi-framework/TrixiShallowWater.jl/blob/main/test/runtests.jl), +which is run by the automated tests and which can be triggered manually by +executing +```julia +julia> using Pkg; Pkg.test("TrixiShallowWater") +``` +in the REPL. Since there already exist many tests, we have split them up into +multiple files in the `test` directory to allow for faster testing of individual +parts of the code. +Thus in addition to performing all tests, you can also just `include` one of the +files named `test_xxx.jl` to run only a specific subset, e.g., +```julia +julia> # Run all test for the TreeMesh1D + include(joinpath("test", "test_tree_1d.jl")) +``` + + +## Adding new tests +We use Julia's built-in [unit testing capabilities](https://docs.julialang.org/en/v1/stdlib/Test/) +to configure tests. In general, newly added code must be covered by at least one +test, and all new scripts added to the `examples/` directory must be used at +least once during testing. New tests should be added to the corresponding +`test/test_xxx.jl` file. +Please study one of the existing tests and stay consistent to the current style +when creating new tests. + +Since we want to test as much as possible, we have a lot of tests and +frequently create new ones. Therefore, new tests should be as +short as reasonably possible, i.e., without being too insensitive to pick up +changes or errors in the code. + +When you add new tests, please check whether all CI jobs still take approximately +the same time. If the job where you added new tests takes much longer than +everything else, please consider moving some tests from one job to another +(or report this incident and ask the main developers for help). + +!!! note "Test duration" + As a general rule, tests should last **no more than 10 seconds** when run + with a single thread and after compilation (i.e., excluding the first run). + + +## Test coverage +In addition to ensuring that the code produces the expected results, the +automated tests also record the +[code coverage](https://en.wikipedia.org/wiki/Code_coverage). The resulting +coverage reports, i.e., which lines of code were executed by at least one test +and are thus considered "covered" by testing, are automatically uploaded to +[Coveralls](https://coveralls.io) for easy analysis. Typically, you see a number +of Coveralls results at the bottom of each pull request: One for each parallel +job (see [Testing setup](@ref)), which can usually be ignored since they only +cover parts of the code by definition, and a cumulative coverage result named +`coverage/coveralls`. The "Details" link takes you to a detailed report on +which lines of code are covered by tests, which ones are missed, and especially +which *new* lines the pull requests adds to TrixiShallowWater.jl's code base that are not yet +covered by testing. \ No newline at end of file From 94a8c6e0e3c387e607aed0af3b6e3a612729f29d Mon Sep 17 00:00:00 2001 From: Andrew Winters Date: Thu, 22 Aug 2024 10:04:13 +0200 Subject: [PATCH 11/16] add extra badges --- README.md | 6 ++- src/equations/shallow_water_exner_1d.jl | 56 ++++++++++++------------- 2 files changed, 32 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 6db86ce..923eb8a 100644 --- a/README.md +++ b/README.md @@ -2,12 +2,14 @@ [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://trixi-framework.github.io/TrixiShallowWater.jl/stable/) [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://trixi-framework.github.io/TrixiShallowWater.jl/dev/) +[![Slack](https://img.shields.io/badge/chat-slack-e01e5a)](https://join.slack.com/t/trixi-framework/shared_invite/zt-sgkc6ppw-6OXJqZAD5SPjBYqLd8MU~g) [![Build Status](https://github.com/trixi-framework/TrixiShallowWater.jl/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/trixi-framework/TrixiShallowWater.jl/actions/workflows/ci.yml?query=branch%3Amain) [![Coverage](https://codecov.io/gh/trixi-framework/TrixiShallowWater.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/trixi-framework/TrixiShallowWater.jl) [![Coverage](https://coveralls.io/repos/github/trixi-framework/TrixiShallowWater.jl/badge.svg?branch=main)](https://coveralls.io/github/trixi-framework/TrixiShallowWater.jl?branch=main) +[![License: MIT](https://img.shields.io/badge/License-MIT-success.svg)](https://opensource.org/licenses/MIT) -**TrixiShallowWater.jl** is a numerical simulation package focused on solving shallow water equations -with the discontinuous Galerkin method and written in Julia. The package builds on the numerical solver [Trixi.jl](https://github.com/trixi-framework/Trixi.jl) +**TrixiShallowWater.jl** is a numerical simulation package focused on solving shallow water equations +with the discontinuous Galerkin method and written in Julia. The package builds on the numerical solver [Trixi.jl](https://github.com/trixi-framework/Trixi.jl) and provides several specialized models and features specific for shallow water applications. ## Examples diff --git a/src/equations/shallow_water_exner_1d.jl b/src/equations/shallow_water_exner_1d.jl index cf77759..af33151 100644 --- a/src/equations/shallow_water_exner_1d.jl +++ b/src/equations/shallow_water_exner_1d.jl @@ -29,7 +29,7 @@ abstract type SedimentModel{RealT} end @doc raw""" ShieldsStressModel(; m_1, m_2, m_3, k_1, k_2, k_3, theta_c, d_s) -Create a Shields stress model to compute the sediment discharge `q_s` based on the generalized +Create a Shields stress model to compute the sediment discharge `q_s` based on the generalized formulation from equation (1.2) in the given reference. The choice of the real constants `m_1`, `m_2`, `m_3`, `k_1`, `k_2`, and `k_3` creates @@ -40,7 +40,7 @@ The Shields stress represents the ratio of agitating and stabilizing forces in t the sediment grain size. - E.D. Fernández-Nieto, T.M. de Luna, G. Narbona-Reina and J. de Dieu Zabsonré (2017)\ - Formal deduction of the Saint-Venant–Exner model including arbitrarily sloping sediment beds and + Formal deduction of the Saint-Venant–Exner model including arbitrarily sloping sediment beds and associated energy\ [DOI: 10.1051/m2an/2016018](https://doi.org/10.1051/m2an/2016018) """ @@ -63,15 +63,15 @@ Creates a Grass model to compute the sediment discharge `q_s` as q_s = A_g v^{m_g} ``` with the coefficients `A_g` and `m_g`. The constant `A_g` lies in the interval ``[0,1]`` -and is a dimensional calibration constant that is usually measured experimental. It expresses -the kind of interaction between the fluid and the sediment, the strength of which -increases as `A_g` approaches to 1. The factor `m_g` lies in the interval ``[1, 4]``. +and is a dimensional calibration constant that is usually measured experimentally. +It expresses the kind of interaction between the fluid and the sediment, the strength +of which increases as `A_g` approaches to 1. The factor `m_g` lies in the interval ``[1, 4]``. Typically, one considers an odd integer value for `m_g` such that the sediment discharge `q_s` can be differentiated and the model remains valid for all values of the velocity `v`. An overview of different formulations to compute the sediment discharge can be found in: - M.J. Castro Díaz, E.D. Fernández-Nieto, A.M. Ferreiro (2008)\ - Sediment transport models in Shallow Water equations and numerical approach by high order + Sediment transport models in Shallow Water equations and numerical approach by high order finite volume methods\ [DOI:10.1016/j.compfluid.2007.07.017](https://doi.org/10.1016/j.compfluid.2007.07.017) """ @@ -87,12 +87,12 @@ end @doc raw""" MeyerPeterMueller(; theta_c, d_s) -Creates a Meyer-Peter-Mueller model to compute the sediment discharge +Creates a Meyer-Peter-Mueller model to compute the sediment discharge `q_s` with the critical Shields stress `theta_c` and the grain diameter `d_s`. An overview of different formulations to compute the sediment discharge can be found in: - M.J. Castro Díaz, E.D. Fernández-Nieto, A.M. Ferreiro (2008)\ - Sediment transport models in Shallow Water equations and numerical approach by high order + Sediment transport models in Shallow Water equations and numerical approach by high order finite volume methods\ [DOI:10.1016/j.compfluid.2007.07.017](https://doi.org/10.1016/j.compfluid.2007.07.017) """ @@ -116,10 +116,10 @@ entropy inequality. The equations are given by \end{cases} ``` The unknown quantities are the water and sediment height ``h``, ``h_b`` and the velocity ``v``. -The sediment discharge ``q_s(h, hv)`` is determined by the `sediment_model` and is used to determine -the active sediment height ``h_s = q_s / v``. -Furthermore ``\tau`` denotes the shear stress at the water-sediment interface and is determined by -the `friction` model. +The sediment discharge ``q_s(h, hv)`` is determined by the `sediment_model` and is used to determine +the active sediment height ``h_s = q_s / v``. +Furthermore ``\tau`` denotes the shear stress at the water-sediment interface and is determined by +the `friction` model. The gravitational constant is denoted by ``g``, and ``\rho_f`` and ``\rho_s`` are the fluid and sediment densities, respectively. The density ratio is given by ``r = \rho_f / \rho_s``, where ``r`` lies between ``0 < r < 1`` as the fluid density ``\rho_f`` should be smaller than the sediment density ``\rho_s``. @@ -127,12 +127,12 @@ densities, respectively. The density ratio is given by ``r = \rho_f / \rho_s``, The conservative variable water height ``h`` is measured from the sediment height ``h_b``, therefore one also defines the total water height as ``H = h + h_b``. -The additional quantity ``H_0`` is also available to store a reference value for the total water +The additional quantity ``H_0`` is also available to store a reference value for the total water height that is useful to set initial conditions or test the "lake-at-rest" well-balancedness. The entropy conservative formulation has been derived in the paper: - E.D. Fernández-Nieto, T.M. de Luna, G. Narbona-Reina and J. de Dieu Zabsonré (2017)\ - Formal deduction of the Saint-Venant–Exner model including arbitrarily sloping sediment beds and + Formal deduction of the Saint-Venant–Exner model including arbitrarily sloping sediment beds and associated energy\ [DOI: 10.1051/m2an/2016018](https://doi.org/10.1051/m2an/2016018) """ @@ -140,7 +140,7 @@ struct ShallowWaterExnerEquations1D{RealT <: Real, FrictionT <: Friction{RealT}, SedimentT <: SedimentModel{RealT}} <: Trixi.AbstractShallowWaterEquations{1, 3} - # This structure ensures that friction and sediment models are concrete types + # This structure ensures that friction and sediment models are concrete types # to prevent allocations gravity::RealT # gravitational constant H0::RealT # constant "lake-at-rest" total water height @@ -229,8 +229,8 @@ end """ source_terms_convergence_test(u, x, t, equations::ShallowWaterExnerEquations1D{T, S, GrassModel{T}}) where {T, S} - -Source terms used for convergence tests in combination with [`Trixi.initial_condition_convergence_test`](@ref) + +Source terms used for convergence tests in combination with [`Trixi.initial_condition_convergence_test`](@ref) when using the the [`GrassModel`](@ref) model. To use this source term the equations must be set to: @@ -264,7 +264,7 @@ end """ source_terms_convergence_test(u, x, t, equations::ShallowWaterExnerEquations1D{T, S, ShieldsStressModel{T}}) where {T, S} -Source terms used for convergence tests in combination with [`Trixi.initial_condition_convergence_test`](@ref) +Source terms used for convergence tests in combination with [`Trixi.initial_condition_convergence_test`](@ref) when using the [`MeyerPeterMueller`](@ref) model. To use this source term the equations must be set to: @@ -312,7 +312,7 @@ end """ source_term_bottom_friction(u, x, t, equations::ShallowWaterExnerEquations1D) -Source term that accounts for the bottom friction in the [ShallowWaterExnerEquations1D](@ref). +Source term that accounts for the bottom friction in the [ShallowWaterExnerEquations1D](@ref). The actual friction law is determined through the friction model in `equations.friction`. """ @inline function source_term_bottom_friction(u, x, t, @@ -341,7 +341,7 @@ end Non-symmetric path-conservative two-point flux discretizing the nonconservative terms of the [`ShallowWaterExnerEquations1D`](@ref) which consists of the hydrostatic pressure of the fluid -layer and an additional pressure contribution from the sediment layer to obtain an entropy +layer and an additional pressure contribution from the sediment layer to obtain an entropy inequality. This non-conservative flux should be used together with [`flux_ersing_etal`](@ref) to create a @@ -379,8 +379,8 @@ end flux_ersing_etal(u_ll, u_rr, orientation::Integer, equations::ShallowWaterMultiLayerEquations1D) -Entropy conservative split form, without the hydrostatic pressure. This flux should be used -together with the nonconservative [`flux_nonconservative_ersing_etal`](@ref) to create a scheme +Entropy conservative split form, without the hydrostatic pressure. This flux should be used +together with the nonconservative [`flux_nonconservative_ersing_etal`](@ref) to create a scheme that is entropy conservative and well-balanced. To obtain an entropy stable formulation the `surface_flux` can be set as @@ -410,7 +410,7 @@ end """ dissipation_roe(u_ll, u_rr, orientation_or_normal_direction, equations::ShallowWaterExnerEquations1D) -Roe-type dissipation term for the [`ShallowWaterExnerEquations1D`](@ref) with an approximate Roe average +Roe-type dissipation term for the [`ShallowWaterExnerEquations1D`](@ref) with an approximate Roe average for the sediment discharge `q_s`. """ @inline function dissipation_roe(u_ll, u_rr, orientation_or_normal_direction, @@ -424,8 +424,8 @@ for the sediment discharge `q_s`. v_rr = velocity(u_rr, equations) # Compute approximate Roe averages. - # The actual Roe average for the sediment discharge `q_s` would depend on the sediment and - # friction model and can be difficult to compute analytically. + # The actual Roe average for the sediment discharge `q_s` would depend on the sediment and + # friction model and can be difficult to compute analytically. # Therefore we only use an approximation here. h_avg = 0.5 * (u_ll[1] + u_rr[1]) v_avg = (sqrt(u_ll[1]) * v_ll + sqrt(u_rr[1]) * v_rr) / @@ -505,7 +505,7 @@ end (max(sqrt(theta) - k_3 * sqrt(theta_c), 0.0))^m_3) end -# Compute the sediment discharge for the Grass model +# Compute the sediment discharge for the Grass model @inline function q_s(u, equations::ShallowWaterExnerEquations1D{T, S, GrassModel{T}}) where { T, @@ -581,7 +581,7 @@ end end # Calculate the error for the "lake-at-rest" test case where H = h + h_b should -# be a constant value over time. +# be a constant value over time. @inline function Trixi.lake_at_rest_error(u, equations::ShallowWaterExnerEquations1D) h, _, h_b = u return abs(equations.H0 - (h + h_b)) @@ -600,7 +600,7 @@ end if v > eps() h_s = q_s(u, equations) / v # Compute gradients of q_s using automatic differentiation. - # Introduces a closure to make q_s a function of u only. This is necessary since the + # Introduces a closure to make q_s a function of u only. This is necessary since the # gradient function only accepts functions of one variable. dq_s_dh, dq_s_dhv, _ = Trixi.ForwardDiff.gradient(u -> q_s(u, equations), u) else From 49d23623697ed25d3c12ea98732538f8b24f6458 Mon Sep 17 00:00:00 2001 From: Andrew Winters Date: Thu, 22 Aug 2024 10:18:24 +0200 Subject: [PATCH 12/16] add feature list --- README.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 923eb8a..7582d0b 100644 --- a/README.md +++ b/README.md @@ -9,8 +9,25 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-success.svg)](https://opensource.org/licenses/MIT) **TrixiShallowWater.jl** is a numerical simulation package focused on solving shallow water equations -with the discontinuous Galerkin method and written in Julia. The package builds on the numerical solver [Trixi.jl](https://github.com/trixi-framework/Trixi.jl) +with the discontinuous Galerkin method and written in Julia. The package builds on the numerical +simulation framework for conservation laws [Trixi.jl](https://github.com/trixi-framework/Trixi.jl) and provides several specialized models and features specific for shallow water applications. +Below is a short summary of the available features: + +* 1D and 2D simulations on [line/quad meshes](https://trixi-framework.github.io/Trixi.jl/stable/overview/#Semidiscretizations) + * Cartesian and curvilinear meshes + * Conforming and non-conforming meshes + * Hierarchical quadtree meshes with adaptive mesh refinement +* High-order accuracy in space and time + * Entropy-stable discontinuous Galerkin methods based on flux differencing + * Entropy-stable shock capturing + * Positivity-preserving limiting + * Compatible with the [SciML ecosystem for ordinary differential equations](https://diffeq.sciml.ai/latest/) + * CFL-based and error-based time step control +* Shallow water capabilities + * Wetting and drying + * Multi-layer flows + * Sediment transport via an Exner model ## Examples From a010a9149e80bd560b19bb5bf797aa95105eb050 Mon Sep 17 00:00:00 2001 From: Andrew Winters Date: Thu, 22 Aug 2024 11:04:28 +0200 Subject: [PATCH 13/16] add acknowledgement --- README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/README.md b/README.md index 7582d0b..0cc453a 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,12 @@ Below is a short summary of the available features: ## Examples ## Installation +If you have not yet installed Julia, please [follow the instructions for your +operating system](https://julialang.org/downloads/platform/). TrixiShallowWater.jl works +with Julia v1.8 and newer. We recommend using the latest stable release of Julia. + +[comment]: <> (We can update this with a "for users" and "for developers" section once the package is registered) + TrixiShallowWater.jl is **not** a registered Julia package, and therefore needs to be downloaded manually and then run from with the cloned directory: ```bash git clone https://github.com/trixi-framework/TrixiShallowWater.jl.git @@ -51,6 +57,16 @@ community. To get in touch with the developers, [join us on Slack](https://join.slack.com/t/trixi-framework/shared_invite/zt-sgkc6ppw-6OXJqZAD5SPjBYqLd8MU~g) or [create an issue](https://github.com/trixi-framework/TrixiShallowWater.jl/issues/new). +## Acknowledgments +

+

+ +This project has benefited from funding from [Vetenskapsrådet](https://www.vr.se) +(VR, Swedish Research Council), Sweden +through the VR Starting Grant "Shallow water flows including sediment transport and morphodynamics", +VR grant agreement 2020-03642 VR. **Note: This repository is still in its alpha stage and anything might change at any time and without warning, including the deletion of this repository From 95e71d419b2f87fbc29fb7a56e081dbdabdefc8c Mon Sep 17 00:00:00 2001 From: Andrew Winters Date: Thu, 22 Aug 2024 11:11:19 +0200 Subject: [PATCH 14/16] add authors to readme --- README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/README.md b/README.md index 0cc453a..2bf0984 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,15 @@ julia> using Pkg julia> Pkg.add(["Trixi", "Trixi2Vtk", "OrdinaryDiffEq", "Plots"]) ``` +## Authors +TrixiShallowWater.jl is maintained by the +[Trixi authors](https://github.com/trixi-framework/Trixi.jl/blob/main/AUTHORS.md). +Its principal developers are [Andrew Winters](https://liu.se/en/employee/andwi94) +(Linköping University, Sweden) +and [Patrick Ersing](https://liu.se/en/employee/pater53) +(Linköping University, Sweden). The principle developers are +The full list of contributors can be found in [AUTHORS.md](AUTHORS.md). + ## License and contributing TrixiShallowWater.jl is licensed under the MIT license (see [LICENSE.md](LICENSE.md)). Since Trixi.jl is an open-source project, we are very happy to accept contributions from the From f224af4288071637c399b31f324ee2157b4dc688 Mon Sep 17 00:00:00 2001 From: Andrew Winters Date: Thu, 22 Aug 2024 14:11:33 +0200 Subject: [PATCH 15/16] add new logo --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 2bf0984..1e0f1f7 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,10 @@ [![Coverage](https://coveralls.io/repos/github/trixi-framework/TrixiShallowWater.jl/badge.svg?branch=main)](https://coveralls.io/github/trixi-framework/TrixiShallowWater.jl?branch=main) [![License: MIT](https://img.shields.io/badge/License-MIT-success.svg)](https://opensource.org/licenses/MIT) +

+ +

+ **TrixiShallowWater.jl** is a numerical simulation package focused on solving shallow water equations with the discontinuous Galerkin method and written in Julia. The package builds on the numerical simulation framework for conservation laws [Trixi.jl](https://github.com/trixi-framework/Trixi.jl) From 8eac4ec316c7923ec23179aa4dcab95c2f424af5 Mon Sep 17 00:00:00 2001 From: patrickersing Date: Thu, 22 Aug 2024 14:52:34 +0200 Subject: [PATCH 16/16] update readme --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 1e0f1f7..de57814 100644 --- a/README.md +++ b/README.md @@ -60,12 +60,12 @@ TrixiShallowWater.jl is maintained by the Its principal developers are [Andrew Winters](https://liu.se/en/employee/andwi94) (Linköping University, Sweden) and [Patrick Ersing](https://liu.se/en/employee/pater53) -(Linköping University, Sweden). The principle developers are +(Linköping University, Sweden). The full list of contributors can be found in [AUTHORS.md](AUTHORS.md). ## License and contributing -TrixiShallowWater.jl is licensed under the MIT license (see [LICENSE.md](LICENSE.md)). Since Trixi.jl is -an open-source project, we are very happy to accept contributions from the +TrixiShallowWater.jl is licensed under the MIT license (see [LICENSE.md](LICENSE.md)). +Since TrixiShallowWater.jl is an open-source project, we are very happy to accept contributions from the community. To get in touch with the developers, [join us on Slack](https://join.slack.com/t/trixi-framework/shared_invite/zt-sgkc6ppw-6OXJqZAD5SPjBYqLd8MU~g) or [create an issue](https://github.com/trixi-framework/TrixiShallowWater.jl/issues/new).