Skip to content

add warning on entropy vs. energy #267

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JoshuaLampert merged 3 commits into from
Nov 24, 2025
Merged

add warning on entropy vs. energy #267

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b8e4211
add warning on entropy vs. energy
ranocha Nov 24, 2025
6c55410
update docstring of entropy
ranocha Nov 24, 2025
b6f1bbc
Merge branch 'main' into hr/entropy
ranocha Nov 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions docs/src/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,18 @@ Several equation systems in [DispersiveShallowWater.jl](https://github.com/Numer

The common interface provides shared functionality like [`waterheight`](@ref), [`velocity`](@ref), [`energy_total`](@ref), and [`entropy`](@ref). This enables consistent analysis and visualization across different dispersive models while maintaining the underlying shallow water physics.

!!! warning "Entropy vs. Energy"
[DispersiveShallowWater.jl](https://github.com/NumericalMathematics/DispersiveShallowWater.jl)
is written by mathematicians with a background in numerical methods for
hyperbolic balance laws. Therefore, the term *entropy* is often used
in the sense of a mathematical entropy function, i.e., typically a
convex function that is conserved by smooth solutions and whose dissipation
provides useful bounds and estimates. For the classical shallow water
equations, the mathematical entropy is the same as the physical energy
(see [`energy_total`](@ref) and [`entropy`](@ref)). However, some dispersive
models like the [`SerreGreenNaghdiEquations1D`](@ref) do not conserve
the [`energy_total`](@ref) but a modified form [`energy_total_modified`](@ref).

## Hyperbolic Approximations

Some equations are hyperbolic approximations of other systems (e.g., [`HyperbolicSerreGreenNaghdiEquations1D`](@ref) approximates [`SerreGreenNaghdiEquations1D`](@ref)). These systems support two approaches for initial conditions:
Expand Down