[DO NOT MERGE] JOSS paper draft

[JoshuaLampert]

DO NOT MERGE THIS PR

We can use this PR to check and discuss the paper draft. The PR can be closed when the JOSS paper is finished. The branch paper-2025-joss must be kept around forever.

You can download the PDF of the paper draft from the GitHub action Build JOSS paper draft PDF / JOSS Paper Draft (pull_request) below.

• Click on it
• Go to Summary on the left
• Download the artifact

[github-actions]

Benchmark Results (Julia v1.10)

Time benchmarks

	main	d7b8b40...	main / d7b8b40...
bbm_1d/bbm_1d_basic.jl - rhs!:	13.6 ± 0.25 μs	13.8 ± 0.32 μs	0.991 ± 0.029
bbm_1d/bbm_1d_fourier.jl - rhs!:	0.53 ± 0.0095 ms	0.535 ± 0.0093 ms	0.992 ± 0.025
bbm_bbm_1d/bbm_bbm_1d_basic_reflecting.jl - rhs!:	0.0821 ± 0.00027 ms	0.0804 ± 0.00026 ms	1.02 ± 0.0047
bbm_bbm_1d/bbm_bbm_1d_dg.jl - rhs!:	0.0343 ± 0.00056 ms	0.0345 ± 0.00047 ms	0.994 ± 0.021
bbm_bbm_1d/bbm_bbm_1d_relaxation.jl - rhs!:	27.4 ± 0.95 μs	27.2 ± 0.43 μs	1.01 ± 0.038
bbm_bbm_1d/bbm_bbm_1d_upwind_relaxation.jl - rhs!:	0.0485 ± 0.00067 ms	0.0481 ± 0.00057 ms	1.01 ± 0.018
hyperbolic_serre_green_naghdi_1d/hyperbolic_serre_green_naghdi_dingemans.jl - rhs!:	4.23 ± 0.03 μs	4.26 ± 0.05 μs	0.993 ± 0.014
kdv_1d/kdv_1d_basic.jl - rhs!:	1.42 ± 0.02 μs	1.42 ± 0.019 μs	1 ± 0.019
kdv_1d/kdv_1d_implicit.jl - rhs!:	1.41 ± 0.019 μs	1.4 ± 0.011 μs	1.01 ± 0.016
serre_green_naghdi_1d/serre_green_naghdi_well_balanced.jl - rhs!:	0.197 ± 0.009 ms	0.198 ± 0.0079 ms	0.993 ± 0.06
svaerd_kalisch_1d/svaerd_kalisch_1d_dingemans_relaxation.jl - rhs!:	0.145 ± 0.0035 ms	0.147 ± 0.0043 ms	0.988 ± 0.037
time_to_load	1.96 ± 0.0027 s	1.96 ± 0.0011 s	0.998 ± 0.0015

Memory benchmarks

	main	d7b8b40...	main / d7b8b40...
bbm_1d/bbm_1d_basic.jl - rhs!:	1 allocs: 4.12 kB	1 allocs: 4.12 kB	1
bbm_1d/bbm_1d_fourier.jl - rhs!:	1 allocs: 4.12 kB	1 allocs: 4.12 kB	1
bbm_bbm_1d/bbm_bbm_1d_basic_reflecting.jl - rhs!:	5 allocs: 1.17 kB	5 allocs: 1.17 kB	1
bbm_bbm_1d/bbm_bbm_1d_dg.jl - rhs!:	10 allocs: 8.62 kB	10 allocs: 8.62 kB	1
bbm_bbm_1d/bbm_bbm_1d_relaxation.jl - rhs!:	2 allocs: 8.25 kB	2 allocs: 8.25 kB	1
bbm_bbm_1d/bbm_bbm_1d_upwind_relaxation.jl - rhs!:	2 allocs: 8.25 kB	2 allocs: 8.25 kB	1
hyperbolic_serre_green_naghdi_1d/hyperbolic_serre_green_naghdi_dingemans.jl - rhs!:	0 allocs: 0 B	0 allocs: 0 B
kdv_1d/kdv_1d_basic.jl - rhs!:	0 allocs: 0 B	0 allocs: 0 B
kdv_1d/kdv_1d_implicit.jl - rhs!:	0 allocs: 0 B	0 allocs: 0 B
serre_green_naghdi_1d/serre_green_naghdi_well_balanced.jl - rhs!:	0.075 k allocs: 0.66 MB	0.075 k allocs: 0.66 MB	1
svaerd_kalisch_1d/svaerd_kalisch_1d_dingemans_relaxation.jl - rhs!:	0.042 k allocs: 0.315 MB	0.042 k allocs: 0.315 MB	1
time_to_load	0.153 k allocs: 14.5 kB	0.153 k allocs: 14.5 kB	1

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[coveralls]

Pull Request Test Coverage Report for Build 19634429005

Details

• 0 of 0 changed or added relevant lines in 0 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 98.467%

---

Totals
Change from base Build 19480307140:	0.0%
Covered Lines:	2313
Relevant Lines:	2349

---

💛 - Coveralls

[JoshuaLampert]

I made a first draft for the paper. I'm happy to hear your suggestions and feedback, @ranocha and @cwittens.

[cwittens]

I feel like I should click "start review" and not "add single comment" all the time 🙈

[ranocha]

@JoshuaLampert I added some additional references to other software. Please check them.

[ranocha]

I guess we should also cite https://github.com/CliMA/Oceananigans.jl

[JoshuaLampert]

What about also citing TrixiShallowWater.jl? It also has multilayer SWE, which are non-hydrostatic/dispersive, right?

[ranocha]

Right, good idea 👍

[JoshuaLampert]

I added a sentence mentioning Oceananigans.jl and TrixiShallowWater.jl. I am not sure how much/what we should write about how they relate to DispersiveShallowWater.jl. For example for TrixiShallowWater.jl I would say probably the main difference is that TrixiShallowWater.jl relies on models that can be written as balance law only including first-order derivatives while the focus of DispersiveShallowWater.jl lies more on equations with higher-order derivatives (which also was the main reason why I didn't try to integrate the methods directly into Trixi.jl), but this becomes a bit technical.

[ranocha]

The current sentence should be fine, I think. Thanks!