Update docs and example files (#64)

* update docs, filenames, and README

* cleanup Project.toml for testing. Should make things faster

* Apply suggestions from code review

Co-authored-by: Patrick Ersing <[email protected]>

---------

Co-authored-by: Patrick Ersing <[email protected]>

Author: andrewwinters5000

README.md

@@ -6,7 +6,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-success.svg)](https://opensource.org/licenses/MIT)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15122147.svg)](https://doi.org/10.5281/zenodo.15122147)
 
-**TrixiBottomTopography.jl** is a supplementary package to the numerical solvers [Trixi.jl](https://github.com/trixi-framework/Trixi.jl) and [TrixiShallowWater.jl](https://github.com/trixi-framework/TrixiShallowWater.jl), which enables use of real world geographical data for the bottom topography function of the shallow water equations.
+**TrixiBottomTopography.jl** is a supplementary package to the numerical solver [TrixiShallowWater.jl](https://github.com/trixi-framework/TrixiShallowWater.jl), which enables use of real world geographical data for the bottom topography function of the shallow water equations.
 
 The shallow water equations in one dimension
 ```math
@@ -59,17 +59,18 @@ be installed in addition to TrixiBottomTopography
 julia> using Pkg; Pkg.add("GLMakie")
 ```
 
-To use TrixiBottomTopography.jl together with the numerical solver framework [Trixi.jl](https://github.com/trixi-framework/Trixi.jl),
-you need both Trixi.jl and a relevant time integration sub-package of
+To use TrixiBottomTopography.jl together with the numerical solver framework [TrixiShallowWater.jl](https://github.com/trixi-framework/TrixiShallowWater.jl),
+you additionally need both [Trixi.jl](https://github.com/trixi-framework/Trixi.jl)
+and a relevant time integration sub-package of
 [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl), e.g.,
 for high-order low-storage Runge-Kutta schemes. These can be added
 by executing
 ```julia
-julia> using Pkg; Pkg.add(["Trixi", "OrdinaryDiffEqLowStorageRK"])
+julia> using Pkg; Pkg.add(["Trixi", "TrixiShallowWater", "OrdinaryDiffEqLowStorageRK"])
 ```
-TrixiBottomTopography.jl can also be used together with
-[TrixiShallowWater.jl](https://github.com/trixi-framework/TrixiShallowWater.jl), a solver suite specifically designed for shallow water flow applications.
-An example that combines TrixiBottomTopography.jl with wet/dry transitions and
+Two examples that combine TrixiBottomTopography.jl together with TrixiShallowWater.jl
+are available in the `examples` folder.
+An additional example that combines TrixiBottomTopography.jl with wet/dry transitions and
 shock capturing to model a tsunami runup is available as a
 [tutorial](https://trixi-framework.github.io/TrixiShallowWater.jl/stable/tutorials/elixir_shallowwater_monai_tsunami/)
 in TrixiShallowWater.jl.
@@ -83,7 +84,7 @@ cd TrixiBottomTopography.jl
 mkdir run
 cd run
 julia --project=. -e 'using Pkg; Pkg.develop(PackageSpec(path=".."))' # Install local TrixiBottomTopography.jl clone
-julia --project=. -e 'using Pkg; Pkg.add(["GLMakie", "Trixi", "OrdinaryDiffEqLowStorageRK"])' # Install additional packages
+julia --project=. -e 'using Pkg; Pkg.add(["GLMakie", "Trixi", "TrixiShallowWater", "OrdinaryDiffEqLowStorageRK"])' # Install additional packages
 ```
 Note that the additional packages are optional and can be omitted.
 

docs/Project.toml

@@ -5,10 +5,12 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 OrdinaryDiffEqLowStorageRK = "b0944070-b475-4768-8dec-fb6eb410534d"
 Trixi = "a7f1ee26-1774-49b1-8366-f1abc58fbfcb"
 TrixiBottomTopography = "86af9953-43df-404b-8eaa-d20d82623a82"
+TrixiShallowWater = "804cb1fc-5b08-4398-a671-a789bfe091b3"
 
 [compat]
 CairoMakie = "0.13"
 Changelog = "1.1"
 Documenter = "1.3"
 OrdinaryDiffEqLowStorageRK = "1.3"
-Trixi = "0.11.12"
+Trixi = "0.12"
+TrixiShallowWater = "0.2"

docs/make.jl

@@ -106,7 +106,7 @@ makedocs(;
                  "B-spline structure" => "structure.md",
                  "B-spline function" => "function.md"
              ],
-             "Trixi.jl examples" => "trixi_jl_examples.md",
+             "TrixiShallowWater.jl examples" => "trixishallowwater_jl_examples.md",
              "Advanced topics & developers" => ["Development" => "development.md",
                  "Style guide" => "styleguide.md",
                  "Testing" => "testing.md"],

docs/src/trixi_jl_examples.md renamed to docs/src/trixishallowwater_jl_examples.md

@@ -1,13 +1,14 @@
-# Examples with Trixi.jl
+# Examples with TrixiShallowWater.jl
 
 As mentioned in the [Home](https://trixi-framework.github.io/TrixiBottomTopography.jl/stable/)
-section of this documentation, TrixiBottomTopography.jl was initially developed as a
-supplementary package for the numerical solver [Trixi.jl](https://github.com/trixi-framework/Trixi.jl)
+section of this documentation, TrixiBottomTopography.jl was developed as a
+supplementary package for the numerical solver suite
+[TrixiShallowWater.jl](https://github.com/trixi-framework/TrixiShallowWater.jl)
 to enable the user to use real world geographical data for the bottom topography
 function of the shallow water equations.
-TrixiBottomTopography.jl can also be used together with
-[TrixiShallowWater.jl](https://github.com/trixi-framework/TrixiShallowWater.jl)
-a solver suite specifically designed for shallow water flow applications.
+TrixiShallowWater.jl itself is a spinoff of
+[Trixi.jl](https://github.com/trixi-framework/Trixi.jl)
+that is specifically designed for shallow water flow applications.
 An example that combines TrixiBottomTopography.jl with wet/dry transitions and
 shock capturing to model a tsunami runup is available as a
 [tutorial](https://trixi-framework.github.io/TrixiShallowWater.jl/stable/tutorials/elixir_shallowwater_monai_tsunami/)
@@ -16,10 +17,10 @@ in TrixiShallowWater.jl.
 ## One dimensional dam break
 
 In this section, a one dimensional example is presented which uses the functionalities of
-TrixiBottomTopography.jl with [Trixi.jl](https://github.com/trixi-framework/Trixi.jl)
+TrixiBottomTopography.jl with [TrixiShallowWater.jl](https://github.com/trixi-framework/TrixiShallowWater.jl)
 to simulate a dam break problem.
 
-The underlying example file can be found [here](https://github.com/trixi-framework/TrixiBottomTopography.jl/blob/main/examples/trixi_dam_break_1D.jl).
+The underlying example file can be found [here](https://github.com/trixi-framework/TrixiBottomTopography.jl/blob/main/examples/trixishallowwater_dam_break_1D.jl).
 
 First, all the necessary packages must be included at the beginning of the file.
 
@@ -29,6 +30,7 @@ using TrixiBottomTopography
 using CairoMakie
 using OrdinaryDiffEqLowStorageRK
 using Trixi
+using TrixiShallowWater
 ```
 
 - [CairoMakie.jl](https://github.com/JuliaPlots/CairoMakie.jl)
@@ -58,14 +60,14 @@ const spline_struct = CubicBSpline(Rhine_data)
 spline_func(x::Float64) = spline_interpolation(spline_struct, x)
 ```
 
-Now that the B-spline interpolation function is determined, the one dimensional shallow water equations implemented in Trixi.jl can be defined by calling:
+Now that the B-spline interpolation function is determined, the one dimensional shallow water equations implemented in TrixiShallowWater.jl can be defined by calling:
 
 ```@example trixi1d
 # Defining one dimensional shallow water equations
-equations = ShallowWaterEquations1D(gravity_constant = 1.0, H0 = 55.0)
+equations = ShallowWaterEquations1D(gravity = 1.0, H0 = 55.0)
 ```
 
-Here the gravity constant has been chosen to be $1.0$, and the background
+Here the constant gravititational acceleration has been chosen to be $1.0$, and the background
 total water height $H_0$ has been set to $55.0$.
 
 Next, the initial condition for the dam break problem can be defined.
@@ -93,7 +95,7 @@ end
 
 After the initial condition, we can set the boundary conditions.
 In this case, a reflective wall condition is chosen, which is already implemented
-in Trixi.jl for the one dimensional shallow water equations.
+in TrixiShallowWater.jl for the one dimensional shallow water equations.
 
 ```@example trixi1d
 # Setting initial condition
@@ -105,7 +107,8 @@ boundary_condition = boundary_condition_slip_wall
 
 The upcoming code parts will **not** be covered in full detail.
 To get a more profound understanding of the routines, please see the
-[Trixi.jl documentation](https://trixi-framework.github.io/TrixiDocumentation/stable/).
+[Trixi.jl documentation](https://trixi-framework.github.io/TrixiDocumentation/stable/)
+as well as the [TrixiShallowWater documentation](https://trixi-framework.github.io/TrixiShallowWater.jl/stable/).
 
 The following code snippet sets up the discontinuous Galerkin spectral element method (DGSEM).
 In this solver type, we can specify which flux functions for the surface and volume fluxes
@@ -223,7 +226,7 @@ nothing #hide
 
 ## Two dimensional dam break
 
-The underlying example file can be found [here](https://github.com/trixi-framework/TrixiBottomTopography.jl/blob/main/examples/trixi_dam_break_2D.jl).
+The underlying example file can be found [here](https://github.com/trixi-framework/TrixiBottomTopography.jl/blob/main/examples/trixishallowwater_dam_break_2D.jl).
 
 The two dimensional example is similar to the one dimensional case.
 
@@ -235,6 +238,7 @@ using TrixiBottomTopography
 using CairoMakie
 using OrdinaryDiffEqLowStorageRK
 using Trixi
+using TrixiShallowWater
 
 Rhine_data = download("https://gist.githubusercontent.com/maxbertrand1996/a30db4dc9f5427c78160321d75a08166/raw/fa53ceb39ac82a6966cbb14e1220656cf7f97c1b/Rhine_data_2D_40.txt")
 nothing #hide
@@ -249,10 +253,14 @@ const spline_struct = BicubicBSpline(Rhine_data)
 spline_func(x::Float64, y::Float64) = spline_interpolation(spline_struct, x, y)
 ```
 
-Then the two dimensional shallow water equations are defined, where the gravitational constant has been chosen to be `3.0` and the initial water height `55.0`. Afterwards, the initial condition is defined. Similar to the one dimensional case, in the center of the domain, a circular part with a diameter of `100.0` is chosen where the initial water height is chosen to be `10.0` units higher.
+Then the two dimensional shallow water equations are defined, where the gravitational acceleration
+has been chosen to be `9.81` and the initial water height `55.0`.
+Afterwards, the initial condition is defined. Similar to the one dimensional case,
+in the center of the domain, a circular part with a diameter of `100.0` is chosen
+where the initial water height is chosen to be `10.0` units higher.
 
 ```@example trixi2d
-equations = ShallowWaterEquations2D(gravity_constant = 9.81, H0 = 55.0)
+equations = ShallowWaterEquations2D(gravity = 9.81, H0 = 55.0)
 
 function initial_condition_wave(x, t, equations::ShallowWaterEquations2D)
 

examples/trixi_dam_break_1D.jl renamed to examples/trixishallowwater_dam_break_1D.jl

@@ -7,6 +7,7 @@
 using TrixiBottomTopography
 using OrdinaryDiffEqLowStorageRK
 using Trixi
+using TrixiShallowWater
 
 # Download one dimensional Rhine bottom data from gist
 root_dir = pkgdir(TrixiBottomTopography)
@@ -18,7 +19,7 @@ spline_struct = CubicBSpline(Rhine_data)
 spline_func(x) = spline_interpolation(spline_struct, x)
 
 # Defining one dimensional shallow water equations
-equations = ShallowWaterEquations1D(gravity_constant = 1.0, H0 = 55.0)
+equations = ShallowWaterEquations1D(gravity = 1.0, H0 = 55.0)
 
 # Defining initial condition for the dam break problem
 function initial_condition_dam_break(x, t, equations::ShallowWaterEquations1D)

examples/trixi_dam_break_2D.jl renamed to examples/trixishallowwater_dam_break_2D.jl

@@ -7,6 +7,7 @@
 using TrixiBottomTopography
 using OrdinaryDiffEqLowStorageRK
 using Trixi
+using TrixiShallowWater
 
 # Download two dimensional Rhine bottom data from gist
 root_dir = pkgdir(TrixiBottomTopography)
@@ -17,7 +18,7 @@ Rhine_data = Trixi.download("https://gist.githubusercontent.com/maxbertrand1996/
 spline_struct = BicubicBSpline(Rhine_data)
 spline_func(x, y) = spline_interpolation(spline_struct, x, y)
 
-equations = ShallowWaterEquations2D(gravity_constant = 9.81, H0 = 55.0)
+equations = ShallowWaterEquations2D(gravity = 9.81, H0 = 55.0)
 
 function initial_condition_wave(x, t, equations::ShallowWaterEquations2D)
     inicenter = SVector(357490.0, 5646519.0)

test/Project.toml

@@ -1,13 +1,7 @@
 [deps]
-CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 Downloads = "f43a241f-c20a-4ad4-852c-f6b1247861c6"
-OrdinaryDiffEqLowStorageRK = "b0944070-b475-4768-8dec-fb6eb410534d"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
-Trixi = "a7f1ee26-1774-49b1-8366-f1abc58fbfcb"
 
 [compat]
-CairoMakie = "0.12, 0.13"
 Downloads = "1.6"
-OrdinaryDiffEqLowStorageRK = "1.2"
 Test = "1"
-Trixi = "0.11"