Add Hyperbolic Sainte-Marie Equations 1D by MarcoArtiano · Pull Request #135 · trixi-framework/TrixiShallowWater.jl

MarcoArtiano · 2026-03-29T10:15:38Z

The entropy conserving and well-balanced scheme is derived in https://arxiv.org/abs/2603.18978.

github-actions

Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit

JuliaFormatter

[JuliaFormatter] _{reported by reviewdog 🐶}

TrixiShallowWater.jl/src/equations/hyperbolic_sainte_marie_1d.jl

Lines 221 to 222 in 470f555

    
           f2_fluxdiff = alpha_1 * equations.gravity * h_avg * b_jump + alpha_2 * 2 * p_avg * b_jump 
        
           f2_pointwise = (1 - alpha_1) * equations.gravity * h_ll * b_jump + (1 - alpha_2) * 2 * p_ll * b_jump

[JuliaFormatter] _{reported by reviewdog 🐶}

TrixiShallowWater.jl/src/equations/hyperbolic_sainte_marie_1d.jl

Lines 226 to 227 in 470f555

    
           f4_fluxdiff = alpha_3 * equations.celerity^2 * h_avg * v_jump - 2 * alpha_2 * equations.celerity^2 * v_avg * b_jump 
        
           f4_pointwise = (1 - alpha_3) * equations.celerity^2 * h_ll * v_jump - 2 * (1 - alpha_2) * equations.celerity^2 * v_ll * b_jump

[JuliaFormatter] _{reported by reviewdog 🐶}

TrixiShallowWater.jl/src/equations/hyperbolic_sainte_marie_1d.jl

Lines 231 to 234 in 470f555

    
           f2, 
        
           f3, 
        
           f4, 
        
           zero(eltype(u_ll)))

[JuliaFormatter] _{reported by reviewdog 🐶}

TrixiShallowWater.jl/src/equations/hyperbolic_sainte_marie_1d.jl

Line 239 in 470f555

equations::HyperbolicSainteMarieEquations1D)

[JuliaFormatter] _{reported by reviewdog 🐶}

TrixiShallowWater.jl/src/equations/hyperbolic_sainte_marie_1d.jl

Line 255 in 470f555

[JuliaFormatter] _{reported by reviewdog 🐶}

TrixiShallowWater.jl/src/equations/hyperbolic_sainte_marie_1d.jl

Line 322 in 470f555

    
           e = (h_v^2 + h_w^2) / (2 * h) + h_p^2 / (2 * equations.celerity^2 * h) + 0.5f0 * equations.gravity * h^2 + equations.gravity * h * b

[JuliaFormatter] _{reported by reviewdog 🐶}

TrixiShallowWater.jl/src/equations/hyperbolic_sainte_marie_1d.jl

Line 326 in 470f555

    
           @inline function Trixi.lake_at_rest_error(u, equations::HyperbolicSainteMarieEquations1D)

[JuliaFormatter] _{reported by reviewdog 🐶}

TrixiShallowWater.jl/src/equations/hyperbolic_sainte_marie_1d.jl

Line 332 in 470f555

end # @muladd

codecov · 2026-03-29T10:20:01Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.16%. Comparing base (b2f176a) to head (00072d6).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #135      +/-   ##
==========================================
+ Coverage   99.14%   99.16%   +0.03%     
==========================================
  Files         105      107       +2     
  Lines        5565     5746     +181     
==========================================
+ Hits         5517     5698     +181     
  Misses         48       48

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

ranocha

Thanks a lot!

ranocha · 2026-03-29T14:19:52Z

+function HyperbolicSainteMarieEquations1D(; gravity, H0 = zero(gravity),
+                                          b0 = one(gravity), alpha = 3,
+                                          threshold_limiter = nothing)
+    T = promote_type(typeof(gravity), typeof(H0), typeof(b0), typeof(alpha))
+    if threshold_limiter === nothing
+        threshold_limiter = 500 * eps(T)
+    end
+    celerity = alpha * sqrt(gravity * b0)


I think we should not use b0 to determine the hyperbolization parameter, since Escalante et al. use a reference water height h_0 (and the exact value of the bathymetry b can be changed arbitrarily by moving everything in the vertical direction).

H0 should also not be used since it is a reference for the surface elevation h + b, correct? Maybe we need to introduce another argument, h0, although this can be confusing...

Would it make sense to use H0 - b0 for the reference water height?

Yes - but b0 is not used otherwise. Thus, it would be more straightforward to use another parameter name for it, wouldn't it?

Ah, yes if b0 is not used otherwise I agree it makes more sense to use another parameter name.

What about using something like h_ref or eta0?

I am fine with h_ref and h_0. The docstring is talking about h_0. So why not that?

I am in favor of h_ref because with h_0 I would expect the relation H_0 = b + h_0 to hold.

ranocha · 2026-03-29T14:24:01Z

+"""
+	flux_conservative_ec(u_ll, u_rr, normal_direction::AbstractVector, equations::HyperbolicSainteMarieEquations1D)
+
+Total energy conserving and well-balanced two-point flux by
+-  Marco Artiano, Hendrik Ranocha (2026)
+   On Affordable High-Order Entropy-Conservative/Stable and 
+   Well-Balanced Methods for Nonconservative Hyperbolic Systems
+   [DOI: 10.48550/arXiv.2603.18978](https://arxiv.org/abs/2603.18978)
+"""
+struct flux_conservative_ec{RealT <: Real}


Structs should have capital names like FluxConservativeEC. Please also adapt the docstring to describe what the parameters alpha1, alpha2, alpha3 mean, and how the flux can be applied.
It would also be possible to just pick one set of parameters that performs well and stick with it instead of implementing the whole family. I don't have a strong opinion on this. Since performance is not critical right now, it is definitely nice to have the flexibility - but we may recommend some reasonable default value.

I've fixed the structs' name and adapted the docstrings. We may recommend alpha_1 = 1.0, alpha_2 = 0, alpha_3 = 0, which corresponds to the split form of the shallow water terms and strong form of the remaining terms. Eventually also alpha_1 = 1.0, alpha_2 = 1.0, alpha_3 = 1.0 works (as informative example), which results in a split form for all the terms.

Co-authored-by: Hendrik Ranocha <ranocha@users.noreply.github.com>

…work/TrixiShallowWater.jl into ma/hyperbolized_sainte_marie

JoshuaLampert

Looks mostly good to me. It might make sense to also implement a flux function computing the analytical flux because it enables using, e.g., LLF.

JoshuaLampert · 2026-03-30T17:23:09Z

+    if threshold_limiter === nothing
+        threshold_limiter = 500 * eps(T)
+    end
+    celerity = alpha * sqrt(gravity * b0)


Since we only need the squared celerity it probably makes sense to also just store the square.

JoshuaLampert · 2026-03-30T19:55:42Z

+function HyperbolicSainteMarieEquations1D(; gravity, H0 = zero(gravity),
+                                          b0 = one(gravity), alpha = 3,
+                                          threshold_limiter = nothing)
+    T = promote_type(typeof(gravity), typeof(H0), typeof(b0), typeof(alpha))
+    if threshold_limiter === nothing
+        threshold_limiter = 500 * eps(T)
+    end
+    celerity = alpha * sqrt(gravity * b0)


I am fine with h_ref and h_0. The docstring is talking about h_0. So why not that?

patrickersing

Thanks for adding this new system! That is a really nice addition to the package.
The implementation looks quite good already, I mainly had suggestions about naming conventions and comments.

Could you please also:

Add a convergence test and document convergence result in the PR.
Add equation specific unit tests such as https://github.com/trixi-framework/TrixiShallowWater.jl/blob/main/test/test_unit.jl#L26.
Create an entry to NEWS.md about the addition.

patrickersing · 2026-03-31T08:05:51Z

+function HyperbolicSainteMarieEquations1D(; gravity, H0 = zero(gravity),
+                                          b0 = one(gravity), alpha = 3,
+                                          threshold_limiter = nothing)
+    T = promote_type(typeof(gravity), typeof(H0), typeof(b0), typeof(alpha))
+    if threshold_limiter === nothing
+        threshold_limiter = 500 * eps(T)
+    end
+    celerity = alpha * sqrt(gravity * b0)


I am in favor of h_ref because with h_0 I would expect the relation H_0 = b + h_0 to hold.

Co-authored-by: Patrick Ersing <114223904+patrickersing@users.noreply.github.com>

MarcoArtiano · 2026-06-03T13:03:52Z

Thanks for adding this new system! That is a really nice addition to the package. The implementation looks quite good already, I mainly had suggestions about naming conventions and comments.

Could you please also:
* [x]  Add a convergence test and document convergence result in the PR.

* [ ]  Add equation specific unit tests such as https://github.com/trixi-framework/TrixiShallowWater.jl/blob/main/test/test_unit.jl#L26.

* [ ]  Create an entry to `NEWS.md` about the addition.

l2
h                   h_v                 h_w                 h_p                 b
error     EOC       error     EOC       error     EOC       error     EOC       error     EOC
4.69e-01  -         3.52e-01  -         1.00e+01  -         3.10e+00  -         1.77e-04  -
1.06e-02  5.47      6.47e-03  5.77      3.11e-01  5.01      7.49e-02  5.37      1.11e-05  3.99
4.22e-04  4.65      3.19e-04  4.34      2.09e-02  3.89      3.23e-03  4.54      6.98e-07  4.00
2.42e-05  4.12      1.74e-05  4.19      1.54e-03  3.76      2.17e-04  3.89      4.36e-08  4.00
1.73e-06  3.81      1.31e-06  3.73      1.07e-04  3.85      1.44e-05  3.91      2.73e-09  4.00
1.16e-07  3.90      9.21e-08  3.84      6.21e-06  4.11      9.22e-07  3.96      1.70e-10  4.00
6.93e-09  4.06      5.74e-09  4.00      2.70e-07  4.52      5.12e-08  4.17      1.06e-11  4.00

mean      4.34      mean      4.31      mean      4.19      mean      4.31      mean      4.00
----------------------------------------------------------------------------------------------------
linf
h                   h_v                 h_w                 h_p                 b
error     EOC       error     EOC       error     EOC       error     EOC       error     EOC
1.29e+00  -         1.03e+00  -         3.42e+01  -         6.28e+00  -         3.64e-04  -
3.25e-02  5.31      1.90e-02  5.77      1.26e+00  4.76      1.76e-01  5.16      2.43e-05  3.91
1.43e-03  4.51      9.13e-04  4.38      1.04e-01  3.60      1.38e-02  3.68      1.54e-06  3.98
1.13e-04  3.66      5.84e-05  3.97      1.15e-02  3.18      1.02e-03  3.75      9.66e-08  3.99
8.40e-06  3.75      4.46e-06  3.71      9.61e-04  3.58      8.19e-05  3.64      6.05e-09  4.00
4.76e-07  4.14      3.17e-07  3.82      6.25e-05  3.94      4.43e-06  4.21      3.78e-10  4.00
2.05e-08  4.54      1.94e-08  4.03      2.84e-06  4.46      1.88e-07  4.56      2.36e-11  4.00

mean      4.32      mean      4.28      mean      3.92      mean      4.17      mean      3.98
----------------------------------------------------------------------------------------------------

patrickersing

The comment mentioned in #135 (comment) still needs to be addressed and I have added a couple of questions regarding the tolerances in the EC elixir.

Co-authored-by: Marco Artiano <57838732+MarcoArtiano@users.noreply.github.com>

Co-authored-by: Hendrik Ranocha <ranocha@users.noreply.github.com>

…work/TrixiShallowWater.jl into ma/hyperbolized_sainte_marie

patrickersing

Please add a comment regarding the tolerances as mentioned in #135 (comment).
Other than that the PR looks good!

MarcoArtiano · 2026-06-23T10:44:40Z

Please add a comment regarding the tolerances as mentioned in #135 (comment). Other than that the PR looks good!

Done, should I add also a comment in the elixirs? Usually this is not done in the main repo Trixi.jl. Adaptive time-stepper methods often allow to run maximum stable CFL number at loose tolerances, therefore it is often suggested, unless restricted by temporal accuracy, to use loose tolerances.

patrickersing

Thanks, to me it's sufficient to document it in the test file.
LGTM!

add hypsm

470f555

github-actions Bot reviewed Mar 29, 2026

View reviewed changes

fmt

fd849ec

MarcoArtiano added 8 commits March 29, 2026 12:46

add tests

ab09b24

add docs for the fluxes

78326d9

fixup

c780f8e

fix type tests

1512512

fix type tests

d18e1e0

fix

02adfd7

fix

9943b3e

fis

8dd05fc

MarcoArtiano marked this pull request as ready for review March 29, 2026 12:40

MarcoArtiano requested a review from patrickersing March 29, 2026 12:41

MarcoArtiano added 2 commits March 29, 2026 15:44

change name of flux

6d2249c

fix exports

63c6de4

ranocha requested changes Mar 29, 2026

View reviewed changes

MarcoArtiano and others added 6 commits March 29, 2026 18:11

Apply suggestions from code review

ffe33c2

Co-authored-by: Hendrik Ranocha <ranocha@users.noreply.github.com>

fix docs

a9fb37b

Merge branch 'ma/hyperbolized_sainte_marie' of github.com:trixi-frame…

3d0520b

…work/TrixiShallowWater.jl into ma/hyperbolized_sainte_marie

change name convenction for the struct

a835f87

fix tests

ac4c35d

fix docs

1b9ceff

JoshuaLampert requested changes Mar 30, 2026

View reviewed changes

patrickersing requested changes Mar 31, 2026

View reviewed changes

MarcoArtiano and others added 4 commits June 3, 2026 10:17

Update src/equations/hyperbolic_sainte_marie_1d.jl

5330437

Co-authored-by: Patrick Ersing <114223904+patrickersing@users.noreply.github.com>

Merge branch 'main' into ma/hyperbolized_sainte_marie

57bcf9a

Update examples/tree_1d_dgsem/elixir_hyperbolic_sainte_marie_ec.jl

32dd63e

Co-authored-by: Patrick Ersing <114223904+patrickersing@users.noreply.github.com>

add docs, fix naming conventions, small fixes

b2284ed

MarcoArtiano and others added 11 commits June 3, 2026 16:08

fmt

246b14d

fix tests value

a8c83e1

increase tolerance

f56ff55

Merge branch 'main' into ma/hyperbolized_sainte_marie

1a9b002

update test values

2b3f501

change alpha to beta for the fluxes

7c61af9

revert beta renaming

683fd8e

rename fluxes

b2b3e93

fix type tests

2da0f15

fix export

12b2bbf

fix typo

213bae5

MarcoArtiano requested a review from patrickersing June 15, 2026 08:29

patrickersing requested changes Jun 15, 2026

View reviewed changes

Comment thread examples/tree_1d_dgsem/elixir_hyperbolic_sainte_marie_manufactured.jl Outdated

Comment thread test/test_tree_1d.jl Outdated

MarcoArtiano commented Jun 15, 2026

View reviewed changes

Comment thread src/equations/hyperbolic_sainte_marie_1d.jl Outdated

Apply suggestions from code review

abc7e99

Co-authored-by: Marco Artiano <57838732+MarcoArtiano@users.noreply.github.com>

ranocha reviewed Jun 18, 2026

View reviewed changes

Comment thread examples/tree_1d_dgsem/elixir_hyperbolic_sainte_marie_ec.jl Outdated

Comment thread examples/tree_1d_dgsem/elixir_hyperbolic_sainte_marie_ec.jl Outdated

Comment thread examples/tree_1d_dgsem/elixir_hyperbolic_sainte_marie_ec.jl Outdated

MarcoArtiano and others added 3 commits June 18, 2026 13:07

Apply suggestions from code review

7d773e5

Co-authored-by: Hendrik Ranocha <ranocha@users.noreply.github.com>

update tests

413e337

Merge branch 'main' into ma/hyperbolized_sainte_marie

2893521

github-actions Bot reviewed Jun 18, 2026

View reviewed changes

Comment thread test/test_tree_1d.jl Outdated

Comment thread test/test_tree_1d.jl Outdated

MarcoArtiano added 5 commits June 18, 2026 13:15

fmt

d618a55

Merge branch 'ma/hyperbolized_sainte_marie' of github.com:trixi-frame…

847357c

…work/TrixiShallowWater.jl into ma/hyperbolized_sainte_marie

fix test values

d8ece3c

change tspan

a6359d9

fix test values

8a3c5f9

MarcoArtiano requested a review from patrickersing June 18, 2026 12:30

patrickersing requested changes Jun 23, 2026

View reviewed changes

add comment regarding stricter tolerances

00072d6

patrickersing approved these changes Jun 23, 2026

View reviewed changes

	f2_fluxdiff = alpha_1 * equations.gravity * h_avg * b_jump + alpha_2 * 2 * p_avg * b_jump
	f2_pointwise = (1 - alpha_1) * equations.gravity * h_ll * b_jump + (1 - alpha_2) * 2 * p_ll * b_jump

	f4_fluxdiff = alpha_3 * equations.celerity^2 * h_avg * v_jump - 2 * alpha_2 * equations.celerity^2 * v_avg * b_jump
	f4_pointwise = (1 - alpha_3) * equations.celerity^2 * h_ll * v_jump - 2 * (1 - alpha_2) * equations.celerity^2 * v_ll * b_jump

Uh oh!

Conversation

MarcoArtiano commented Mar 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

codecov Bot commented Mar 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

ranocha left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MarcoArtiano Mar 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MarcoArtiano Mar 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

JoshuaLampert left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

patrickersing left a comment • edited by MarcoArtiano Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MarcoArtiano commented Jun 3, 2026

Uh oh!

patrickersing left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

patrickersing left a comment

Choose a reason for hiding this comment

Uh oh!

MarcoArtiano commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

MarcoArtiano commented Mar 29, 2026 •

edited

Loading

codecov Bot commented Mar 29, 2026 •

edited

Loading

MarcoArtiano Mar 29, 2026 •

edited

Loading

MarcoArtiano Mar 29, 2026 •

edited

Loading

patrickersing left a comment •

edited by MarcoArtiano

Loading

MarcoArtiano commented Jun 23, 2026 •

edited

Loading