Implement hyperbolized Sainte-Marie equations developed by Escalante et al.

[ranocha]

I will add a few additional modifications here soon; I just opened this PR now to get the PR number for the NEWS.md entry.

I have implemented the hyperbolization of the Sainte-Marie equations proposed by Escalante, Dumbser, and Castro (2019). The energy-conserving semidiscretization is adapted from the conservative version derived in https://arxiv.org/abs/2603.18978.

Convergence test with manufactured solution:

julia> convergence_test("examples/hyperbolic_sainte_marie_1d/hyperbolic_sainte_marie_manufactured.jl", 4);
[...]
####################################################################################################
l2
η                        v                        D                        w                        p                        
N    error     EOC       N    error     EOC       N    error     EOC       N    error     EOC       N    error     EOC       
50   8.79e-03  -         50   5.67e-03  -         50   0.00e+00  -         50   6.08e-02  -         50   2.17e-01  -         
100  5.43e-04  4.02      100  3.44e-04  4.04      100  0.00e+00  NaN       100  3.71e-03  4.04      100  1.37e-02  3.99      
200  3.32e-05  4.03      200  2.15e-05  4.00      200  0.00e+00  NaN       200  2.32e-04  4.00      200  8.54e-04  4.00      
400  2.07e-06  4.01      400  1.38e-06  3.97      400  0.00e+00  NaN       400  1.45e-05  4.00      400  5.34e-05  4.00      

mean           4.02      mean           4.00      mean           NaN       mean           4.01      mean           4.00      
----------------------------------------------------------------------------------------------------
linf
η                        v                        D                        w                        p                        
N    error     EOC       N    error     EOC       N    error     EOC       N    error     EOC       N    error     EOC       
50   2.49e-02  -         50   1.02e-02  -         50   0.00e+00  -         50   1.32e-01  -         50   3.97e-01  -         
100  1.80e-03  3.79      100  6.42e-04  4.00      100  0.00e+00  NaN       100  7.60e-03  4.12      100  2.24e-02  4.15      
200  1.19e-04  3.92      200  4.06e-05  3.99      200  0.00e+00  NaN       200  4.55e-04  4.06      200  1.49e-03  3.92      
400  7.72e-06  3.94      400  2.55e-06  3.99      400  0.00e+00  NaN       400  2.83e-05  4.01      400  9.30e-05  4.00      

mean           3.88      mean           3.99      mean           NaN       mean           4.06      mean           4.02      
----------------------------------------------------------------------------------------------------

CC @MarcoArtiano

[github-actions]

Benchmark Results (Julia v1.10)

Time benchmarks

	main	bfee7c9...	main / bfee7c9...
bbm_1d/bbm_1d_basic.jl - rhs!:	13.7 ± 0.28 μs	13.7 ± 0.33 μs	0.999 ± 0.032
bbm_1d/bbm_1d_fourier.jl - rhs!:	0.536 ± 0.01 ms	0.527 ± 0.32 ms	1.02 ± 0.62
bbm_bbm_1d/bbm_bbm_1d_basic_reflecting.jl - rhs!:	0.081 ± 0.00021 ms	0.0811 ± 0.00025 ms	0.999 ± 0.004
bbm_bbm_1d/bbm_bbm_1d_dg.jl - rhs!:	0.0343 ± 0.00077 ms	0.0347 ± 0.00066 ms	0.988 ± 0.029
bbm_bbm_1d/bbm_bbm_1d_relaxation.jl - rhs!:	28.1 ± 0.85 μs	27.8 ± 0.96 μs	1.01 ± 0.047
bbm_bbm_1d/bbm_bbm_1d_upwind_relaxation.jl - rhs!:	0.0483 ± 0.00067 ms	0.0486 ± 0.0008 ms	0.993 ± 0.021
hyperbolic_serre_green_naghdi_1d/hyperbolic_serre_green_naghdi_dingemans.jl - rhs!:	4.24 ± 0.03 μs	4.28 ± 0.031 μs	0.991 ± 0.01
kdv_1d/kdv_1d_basic.jl - rhs!:	1.42 ± 0.01 μs	1.42 ± 0.019 μs	1 ± 0.015
kdv_1d/kdv_1d_implicit.jl - rhs!:	1.41 ± 0.019 μs	1.41 ± 0.02 μs	1 ± 0.02
serre_green_naghdi_1d/serre_green_naghdi_well_balanced.jl - rhs!:	0.198 ± 0.01 ms	0.199 ± 0.0095 ms	0.995 ± 0.069
svaerd_kalisch_1d/svaerd_kalisch_1d_dingemans_relaxation.jl - rhs!:	0.145 ± 0.0037 ms	0.15 ± 0.0042 ms	0.971 ± 0.037
time_to_load	2.32 ± 0.0057 s	2.32 ± 0.0087 s	0.997 ± 0.0045

Memory benchmarks

	main	bfee7c9...	main / bfee7c9...
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

❌ Patch coverage is 98.03922% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/equations/hyperbolic_sainte_marie_1d.jl	97.81%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!

[coveralls]

Pull Request Test Coverage Report for Build 23600542836

Details

• 200 of 203 (98.52%) changed or added relevant lines in 4 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage increased (+0.003%) to 98.483%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
src/equations/hyperbolic_sainte_marie_1d.jl	179	182	98.35%

Totals
Change from base Build 22594813032:	0.003%
Covered Lines:	2532
Relevant Lines:	2571

---

💛 - Coveralls

[JoshuaLampert]

Thanks a lot!
Before I take a closer review, could you please add the new equation system to the README, the landing page of the docs, the table in https://numericalmathematics.github.io/DispersiveShallowWater.jl/previews/PR288/overview/#eq_overview, and the docstring in the overview page https://numericalmathematics.github.io/DispersiveShallowWater.jl/previews/PR288/overview/#Detailed-Documentation?
Could you also please add some unit tests here similar to the other equations and increase coverage?
I also have two questions:

• Is there a known linear dispersion relation for the (hyperbolic) Saint-Marie equations? If yes, could you please add it to https://github.com/NumericalMathematics/DispersiveShallowWater.jl/blob/679edf86f933313a9a65bb97130417c1baf047d9/src/dispersion_relation.jl and if no, could you track that in #131, please?
• Out of interest: Did you do any comparison with your implementation in https://github.com/MarcoArtiano/2026_nonconservative_sbp using Trixi.jl? Would it maybe even be possible to create a simple setup, where both implementations should compute the same (e.g., central flux in the Trixi.jl version vs discontinuosly coupled SBP operators here or using FDSBP with one element and a global FD SBP operator in the Trixi.jl version vs the same global SBP operator here)? If not or if it is too much work, that's also fine. I'm just curious.

[ranocha]

Thanks for the initial review! I updated the docs and added unit tests.

• I added the new equations to Include linear dispersion relation for all equations #131, tracking missing dispersion relations.
• I added the new equations to Support other models #95, tracking missing functionality (reflecting BCs).

[MarcoArtiano]

Thanks! I've left a few comments,

[ranocha]

I added the dispersion relations.

[ranocha]

Out of interest: Did you do any comparison with your implementation in https://github.com/MarcoArtiano/2026_nonconservative_sbp using Trixi.jl? Would it maybe even be possible to create a simple setup, where both implementations should compute the same (e.g., central flux in the Trixi.jl version vs discontinuosly coupled SBP operators here or using FDSBP with one element and a global FD SBP operator in the Trixi.jl version vs the same global SBP operator here)? If not or if it is too much work, that's also fine. I'm just curious.

No, I didn't. I just derived the corresponding numerical method by hand. However, I would like to have the equations in TrixiShallowWater.jl. Maybe that's something @MarcoArtiano could do based on his implementation in the reproducibility repository? I spoke with Andrew: it would be totally fine to have a first version without all the wetting and drying treatment (which would also require additional wave breaking models for real applications).

[JoshuaLampert]

Thanks! This looks already quite good. I left some comments below.

[JoshuaLampert]

Looking at the zoomed plot for t = 14.0 at https://numericalmathematics.github.io/DispersiveShallowWater.jl/previews/PR288/dingemans/, it looks like there is some phase shift, which might be reduced by tweaking this calibration parameter. How did you come up with 1.0 so far?

[ranocha]

I tried setting the value so that the time series at the first few gauges look reasonable. Note that in the zoomed plots, the phase shifts at t = 14 and t = 70 are in opposite directions. Thus, we cannot fix both of them together.

If you have another suggestion for a good calibration parameter (based on how you estimated it for other models), please let me know.

[JoshuaLampert]

Hm, true, do you have an explanation of why the hyperbolic Sainte-Marie equations have such a big difference in the phase velocity compared to the other equations? It seems like the waves are too fast. The linear dispersion relation of them does not seem so bad. We could try a setup similar to the lower one in https://numericalmathematics.github.io/DispersiveShallowWater.jl/previews/PR288/dispersion/ to see if the numerical solution matches the velocity predicted by the linear dispersion relation.

[JoshuaLampert]

Ok, just quickly tried that in 1f06885 and it looks as expected. It's just slightly slower.

[ranocha]

Yes, that seems to be the reason. Note that the dispersion relation for $$\alpha = 3$$ is also quite a bit different from the limiting Sainte-Marie system.

[ranocha]

If you cannot find a bug in my code, it looks like this is just how the hyperbolized Sainte-Marie system behaves 🤷

[JoshuaLampert]

Note that the dispersion relation for α = 3 is also quite a bit different from the limiting Sainte-Marie system.

Yes, but for the Dingemans experiment we are talking about a wave number of around 0.85 (that probably becomes bigger when the waves become steeper, but it should not become too high) and for small wave numbers both linear dispersion relations look very similar and even better than most of the other models we have implemented. So I'm wondering where this shift comes from 🤔
But yes, if we don't find any bug, we can just go on and live with it.

[ranocha]

I would be happy to find such a bug - but I haven't been able to do so so far...

[JoshuaLampert]

Thanks! If @MarcoArtiano agrees, this can be merged once my final small comment below is resolved.

[MarcoArtiano]

LGTM! I'm just wondering whether we should somewhere write that \alpha should indeed be greater than 1.

I will open a PR in TrixiShallowWater.jl for the conservative form implementation.

[JoshuaLampert]

Thanks a lot for adding the new equation system, @ranocha and thanks @MarcoArtiano for your review! From my side, this can be merged.

[MarcoArtiano]

Thanks a lot for adding the new equation system, @ranocha and thanks @MarcoArtiano for you review! From my side, this can be merged.

Thank you too!