add warning on entropy vs. energy

[ranocha]

@Alexander-Barth I tried to address your question on entropy vs. energy in #264

As a physicist, I am familiar with the term entropy from thermodynamics and statistical mechanics (which are closely related). In physics, entropy is quite a different concept from energy. In your documentation, however, the term appears to be used interchangeably with what I would describe as the total mechanical energy (the sum of potential and kinetic energy). I understand that your use of the word “entropy” follows the conventions of the hyperbolic PDE literature.
Given that FOSS is an interdisciplinary journal, it may be beneficial to clarify that the term “entropy” is used differently here than in thermodynamics and statistics (if my interpretation is correct).

Yes, you are right. I added a warning to the documentation to mention this explicitly.

Can you also enlightenment me with an example in which entropy as you define it not the same as total energy in the context of fluid dynamics? Or outside the context of fluid dynamics?

For classical gas dynamics like the Euler equations of an ideal compressible gas (see https://trixi-framework.github.io/TrixiDocumentation/stable/reference-trixi/#Trixi.CompressibleEulerEquations1D), the mathematical entropy is just the physical entropy up to a sign since mathematicians like convex functionals whereas the physical entropy is concave.

[JoshuaLampert]

Yes, that's a good clarification. Thanks @ranocha and thanks for the suggestion, @Alexander-Barth!

[JoshuaLampert]

Maybe it would also be helpful to add the term "mathematical" in front of "entropy" in the relevant docstrings, e.g., here:

DispersiveShallowWater.jl/src/equations/equations.jl

Line 297 in ebbdfea

Return the entropy ``U`` of the primitive variables `q` for a given set of

[Alexander-Barth]

Thanks a lot for the clarification!

[ranocha]

Maybe it would also be helpful to add the term "mathematical" in front of "entropy" in the relevant docstrings, e.g., here:

DispersiveShallowWater.jl/src/equations/equations.jl

Line 297 in ebbdfea

Return the entropy ``U`` of the primitive variables `q` for a given set of

Done in the latest commit

[JoshuaLampert]

Thanks!

[github-actions]

Benchmark Results (Julia v1.10)

Time benchmarks

	main	6c55410...	main / 6c55410...
bbm_1d/bbm_1d_basic.jl - rhs!:	12.8 ± 0.38 μs	12.6 ± 0.9 μs	1.01 ± 0.078
bbm_1d/bbm_1d_fourier.jl - rhs!:	0.246 ± 0.0083 ms	0.246 ± 0.0076 ms	1 ± 0.046
bbm_bbm_1d/bbm_bbm_1d_basic_reflecting.jl - rhs!:	0.0847 ± 0.0051 ms	0.0833 ± 0.0055 ms	1.02 ± 0.091
bbm_bbm_1d/bbm_bbm_1d_dg.jl - rhs!:	0.0324 ± 0.00057 ms	0.0323 ± 0.0014 ms	1 ± 0.047
bbm_bbm_1d/bbm_bbm_1d_relaxation.jl - rhs!:	25 ± 0.7 μs	22.7 ± 1.1 μs	1.1 ± 0.06
bbm_bbm_1d/bbm_bbm_1d_upwind_relaxation.jl - rhs!:	0.0319 ± 0.0011 ms	30.8 ± 2.5 μs	1.03 ± 0.091
hyperbolic_serre_green_naghdi_1d/hyperbolic_serre_green_naghdi_dingemans.jl - rhs!:	5.48 ± 0.39 μs	5.45 ± 0.36 μs	1.01 ± 0.098
kdv_1d/kdv_1d_basic.jl - rhs!:	1.72 ± 0.017 μs	2.21 ± 0.15 μs	0.778 ± 0.053
kdv_1d/kdv_1d_implicit.jl - rhs!:	1.87 ± 0.023 μs	1.87 ± 0.03 μs	1 ± 0.02
serre_green_naghdi_1d/serre_green_naghdi_well_balanced.jl - rhs!:	0.215 ± 0.015 ms	0.205 ± 0.015 ms	1.05 ± 0.11
svaerd_kalisch_1d/svaerd_kalisch_1d_dingemans_relaxation.jl - rhs!:	0.159 ± 0.0095 ms	0.153 ± 0.01 ms	1.03 ± 0.092
time_to_load	1.96 ± 0.02 s	1.96 ± 0.015 s	0.999 ± 0.013

Memory benchmarks

	main	6c55410...	main / 6c55410...
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!