Merge branch 'main' into docs

docs/literate/src/files/subcell_shock_capturing.jl

@@ -96,7 +96,8 @@ positivity_variables_nonlinear = [pressure]
 
 # ### Local bounds
 # Second, Trixi.jl supports the limiting with local bounds for conservative variables using a
-# two-sided Zalesak-type limiter ([Zalesak, 1979](https://doi.org/10.1016/0021-9991(79)90051-2)).
+# two-sided Zalesak-type limiter ([Zalesak, 1979](https://doi.org/10.1016/0021-9991(79)90051-2))
+# and for general non-linear variables using a one-sided Newton-bisection algorithm.
 # They allow to avoid spurious oscillations within the global bounds and to improve the
 # shock-capturing capabilities of the method. The corresponding numerical admissibility conditions
 # are frequently formulated as local maximum or minimum principles. The local bounds are computed
@@ -108,6 +109,11 @@ positivity_variables_nonlinear = [pressure]
 # the following.
 local_twosided_variables_cons = ["rho"]
 
+# To limit non-linear variables locally, pass the variable function combined with the requested
+# bound (`min` or `max`) as a tuple. For instance, to impose a lower local bound on the modified
+# specific entropy [`Trixi.entropy_guermond_etal`](@ref), use
+local_onesided_variables_nonlinear = [(Trixi.entropy_guermond_etal, min)]
+
 # ## Exemplary simulation
 # How to set up a simulation using the IDP limiting becomes clearer when looking at an exemplary
 # setup. This will be a simplified version of `tree_2d_dgsem/elixir_euler_blast_wave_sc_subcell.jl`.

src/equations/compressible_euler_2d.jl

@@ -2018,8 +2018,18 @@ end
     return cons2entropy(u, equations)
 end
 
-# Calculate the modified specific entropy of Guermond et al. (2019): s_0 = p * rho^(-gamma) / (gamma-1).
-# Note: This is *not* the "conventional" specific entropy s = ln(p / rho^(gamma)).
+@doc raw"""
+    entropy_guermond_etal(u, equations::CompressibleEulerEquations2D)
+
+Calculate the modified specific entropy of Guermond et al. (2019):
+```math
+s_0 = p * \rho^{-\gamma} / (\gamma-1).
+```
+Note: This is *not* the "conventional" specific entropy ``s = ln(p / \rho^\gamma)``.
+- Guermond at al. (2019)
+  Invariant domain preserving discretization-independent schemes and convex limiting for hyperbolic systems.
+  [DOI: 10.1016/j.cma.2018.11.036](https://doi.org/10.1016/j.cma.2018.11.036)
+"""
 @inline function entropy_guermond_etal(u, equations::CompressibleEulerEquations2D)
     rho, rho_v1, rho_v2, rho_e = u