Merge branch 'main' into subcell-limiting-entropies

Project.toml

@@ -1,7 +1,7 @@
 name = "Trixi"
 uuid = "a7f1ee26-1774-49b1-8366-f1abc58fbfcb"
 authors = ["Michael Schlottke-Lakemper <[email protected]>", "Gregor Gassner <[email protected]>", "Hendrik Ranocha <[email protected]>", "Andrew R. Winters <[email protected]>", "Jesse Chan <[email protected]>"]
-version = "0.7.8-pre"
+version = "0.7.9-pre"
 
 [deps]
 CodeTracking = "da1fd8a2-8d9e-5ec2-8556-3022fb5608a2"

docs/literate/make.jl

@@ -75,7 +75,17 @@ function create_tutorials(files)
     end
 
     # Generate markdown file for introduction page
-    Literate.markdown(joinpath(repo_src, "index.jl"), pages_dir; name="introduction")
+    # Preprocessing introduction file: Generate consecutive tutorial numbers by replacing
+    # each occurrence of `{index}` with an integer incremented by 1, starting at 1.
+    function preprocess_introduction(content)
+        counter = 1
+        while occursin("{index}", content)
+            content = replace(content, "{index}" => "$counter", count = 1)
+            counter += 1
+        end
+        return content
+    end
+    Literate.markdown(joinpath(repo_src, "index.jl"), pages_dir; name="introduction", preprocess=preprocess_introduction)
     # Navigation system for makedocs
     pages = Any["Introduction" => "tutorials/introduction.md",]
 

docs/literate/src/files/index.jl

@@ -14,14 +14,16 @@
 
 # There are tutorials for the following topics:
 
-# ### [1 First steps in Trixi.jl](@ref getting_started)
+#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
+# ### [{index} First steps in Trixi.jl](@ref getting_started)
 #-
 # This tutorial provides guidance for getting started with Trixi.jl, and Julia as well. It outlines
 # the installation procedures for both Julia and Trixi.jl, the execution of Trixi.jl elixirs, the
 # fundamental structure of a Trixi.jl setup, the visualization of results, and the development
 # process for Trixi.jl.
 
-# ### [2 Behind the scenes of a simulation setup](@ref behind_the_scenes_simulation_setup)
+#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
+# ### [{index} Behind the scenes of a simulation setup](@ref behind_the_scenes_simulation_setup)
 #-
 # This tutorial will guide you through a simple Trixi.jl setup ("elixir"), giving an overview of
 # what happens in the background during the initialization of a simulation. While the setup
@@ -30,92 +32,106 @@
 # the more fundamental, *technical* concepts that are applicable to a variety of
 # (also more complex) configurations.s
 
-# ### [3 Introduction to DG methods](@ref scalar_linear_advection_1d)
+#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
+# ### [{index} Introduction to DG methods](@ref scalar_linear_advection_1d)
 #-
 # This tutorial gives an introduction to discontinuous Galerkin (DG) methods with the example of the
 # scalar linear advection equation in 1D. Starting with some theoretical explanations, we first implement
 # a raw version of a discontinuous Galerkin spectral element method (DGSEM). Then, we will show how
 # to use features of Trixi.jl to achieve the same result.
 
-# ### [4 DGSEM with flux differencing](@ref DGSEM_FluxDiff)
+#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
+# ### [{index} DGSEM with flux differencing](@ref DGSEM_FluxDiff)
 #-
 # To improve stability often the flux differencing formulation of the DGSEM (split form) is used.
 # We want to present the idea and formulation on a basic 1D level. Then, we show how this formulation
 # can be implemented in Trixi.jl and analyse entropy conservation for two different flux combinations.
 
-# ### [5 Shock capturing with flux differencing and stage limiter](@ref shock_capturing)
+#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
+# ### [{index} Shock capturing with flux differencing and stage limiter](@ref shock_capturing)
 #-
 # Using the flux differencing formulation, a simple procedure to capture shocks is a hybrid blending
 # of a high-order DG method and a low-order subcell finite volume (FV) method. We present the idea on a
 # very basic level and show the implementation in Trixi.jl. Then, a positivity preserving limiter is
 # explained and added to an exemplary simulation of the Sedov blast wave with the 2D compressible Euler
 # equations.
 
-# ### [6 Non-periodic boundary conditions](@ref non_periodic_boundaries)
+#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
+# ### [{index} Non-periodic boundary conditions](@ref non_periodic_boundaries)
 #-
 # Thus far, all examples used periodic boundaries. In Trixi.jl, you can also set up a simulation with
 # non-periodic boundaries. This tutorial presents the implementation of the classical Dirichlet
 # boundary condition with a following example. Then, other non-periodic boundaries are mentioned.
 
-# ### [7 DG schemes via `DGMulti` solver](@ref DGMulti_1)
+#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
+# ### [{index} DG schemes via `DGMulti` solver](@ref DGMulti_1)
 #-
 # This tutorial is about the more general DG solver [`DGMulti`](@ref), introduced [here](@ref DGMulti).
 # We are showing some examples for this solver, for instance with discretization nodes by Gauss or
 # triangular elements. Moreover, we present a simple way to include pre-defined triangulate meshes for
 # non-Cartesian domains using the package [StartUpDG.jl](https://github.com/jlchan/StartUpDG.jl).
 
-# ### [8 Other SBP schemes (FD, CGSEM) via `DGMulti` solver](@ref DGMulti_2)
+#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
+# ### [{index} Other SBP schemes (FD, CGSEM) via `DGMulti` solver](@ref DGMulti_2)
 #-
 # Supplementary to the previous tutorial about DG schemes via the `DGMulti` solver we now present
 # the possibility for `DGMulti` to use other SBP schemes via the package
 # [SummationByPartsOperators.jl](https://github.com/ranocha/SummationByPartsOperators.jl).
 # For instance, we show how to set up a finite differences (FD) scheme and a continuous Galerkin
 # (CGSEM) method.
 
-# ### [9 Upwind FD SBP schemes](@ref upwind_fdsbp)
+#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
+# ### [{index} Upwind FD SBP schemes](@ref upwind_fdsbp)
 #-
 # General SBP schemes can not only be used via the [`DGMulti`](@ref) solver but
 # also with a general `DG` solver. In particular, upwind finite difference SBP
 # methods can be used together with the `TreeMesh`. Similar to general SBP
 # schemes in the `DGMulti` framework, the interface is based on the package
 # [SummationByPartsOperators.jl](https://github.com/ranocha/SummationByPartsOperators.jl).
 
-# ### [10 Adding a new scalar conservation law](@ref adding_new_scalar_equations)
+#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
+# ### [{index} Adding a new scalar conservation law](@ref adding_new_scalar_equations)
 #-
 # This tutorial explains how to add a new physics model using the example of the cubic conservation
 # law. First, we define the equation using a `struct` `CubicEquation` and the physical flux. Then,
 # the corresponding standard setup in Trixi.jl (`mesh`, `solver`, `semi` and `ode`) is implemented
 # and the ODE problem is solved by OrdinaryDiffEq's `solve` method.
 
-# ### [11 Adding a non-conservative equation](@ref adding_nonconservative_equation)
+#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
+# ### [{index} Adding a non-conservative equation](@ref adding_nonconservative_equation)
 #-
 # In this part, another physics model is implemented, the nonconservative linear advection equation.
 # We run two different simulations with different levels of refinement and compare the resulting errors.
 
-# ### [12 Parabolic terms](@ref parabolic_terms)
+#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
+# ### [{index} Parabolic terms](@ref parabolic_terms)
 #-
 # This tutorial describes how parabolic terms are implemented in Trixi.jl, e.g.,
 # to solve the advection-diffusion equation.
 
-# ### [13 Adding new parabolic terms](@ref adding_new_parabolic_terms)
+#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
+# ### [{index} Adding new parabolic terms](@ref adding_new_parabolic_terms)
 #-
 # This tutorial describes how new parabolic terms can be implemented using Trixi.jl.
 
-# ### [14 Adaptive mesh refinement](@ref adaptive_mesh_refinement)
+#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
+# ### [{index} Adaptive mesh refinement](@ref adaptive_mesh_refinement)
 #-
 # Adaptive mesh refinement (AMR) helps to increase the accuracy in sensitive or turbolent regions while
 # not wasting resources for less interesting parts of the domain. This leads to much more efficient
 # simulations. This tutorial presents the implementation strategy of AMR in Trixi.jl, including the use of
 # different indicators and controllers.
 
-# ### [15 Structured mesh with curvilinear mapping](@ref structured_mesh_mapping)
+#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
+# ### [{index} Structured mesh with curvilinear mapping](@ref structured_mesh_mapping)
 #-
 # In this tutorial, the use of Trixi.jl's structured curved mesh type [`StructuredMesh`](@ref) is explained.
 # We present the two basic option to initialize such a mesh. First, the curved domain boundaries
 # of a circular cylinder are set by explicit boundary functions. Then, a fully curved mesh is
 # defined by passing the transformation mapping.
 
-# ### [16 Unstructured meshes with HOHQMesh.jl](@ref hohqmesh_tutorial)
+#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
+# ### [{index} Unstructured meshes with HOHQMesh.jl](@ref hohqmesh_tutorial)
 #-
 # The purpose of this tutorial is to demonstrate how to use the [`UnstructuredMesh2D`](@ref)
 # functionality of Trixi.jl. This begins by running and visualizing an available unstructured
@@ -124,26 +140,30 @@
 # software in the Trixi.jl ecosystem, and then run a simulation using Trixi.jl on said mesh.
 # In the end, the tutorial briefly explains how to simulate an example using AMR via `P4estMesh`.
 
-# ### [17 P4est mesh from gmsh](@ref p4est_from_gmsh)
+#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
+# ### [{index} P4est mesh from gmsh](@ref p4est_from_gmsh)
 #-
 # This tutorial describes how to obtain a [`P4estMesh`](@ref) from an existing mesh generated
 # by [`gmsh`](https://gmsh.info/) or any other meshing software that can export to the Abaqus
 # input `.inp` format. The tutorial demonstrates how edges/faces can be associated with boundary conditions based on the physical nodesets.
 
-# ### [18 Explicit time stepping](@ref time_stepping)
+#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
+# ### [{index} Explicit time stepping](@ref time_stepping)
 #-
 # This tutorial is about time integration using [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl).
 # It explains how to use their algorithms and presents two types of time step choices - with error-based
 # and CFL-based adaptive step size control.
 
-# ### [19 Differentiable programming](@ref differentiable_programming)
+#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
+# ### [{index} Differentiable programming](@ref differentiable_programming)
 #-
 # This part deals with some basic differentiable programming topics. For example, a Jacobian, its
 # eigenvalues and a curve of total energy (through the simulation) are calculated and plotted for
 # a few semidiscretizations. Moreover, we calculate an example for propagating errors with Measurement.jl
 # at the end.
 
-# ### [20 Custom semidiscretization](@ref custom_semidiscretization)
+#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
+# ### [{index} Custom semidiscretization](@ref custom_semidiscretization)
 #-
 # This tutorial describes the [semidiscretiations](@ref overview-semidiscretizations) of Trixi.jl
 # and explains how to extend them for custom tasks.

examples/p4est_3d_dgsem/elixir_linearizedeuler_convergence.jl

@@ -0,0 +1,64 @@
+using OrdinaryDiffEq
+using Trixi
+
+###############################################################################
+# semidiscretization of the linearized Euler equations
+
+equations = LinearizedEulerEquations3D(v_mean_global = (0.0, 0.0, 0.0), c_mean_global = 1.0,
+                                       rho_mean_global = 1.0)
+
+initial_condition = initial_condition_convergence_test
+
+solver = DGSEM(polydeg = 3, surface_flux = flux_hll)
+
+coordinates_min = (-1.0, -1.0, -1.0) # minimum coordinates (min(x), min(y), min(z))
+coordinates_max = (1.0, 1.0, 1.0) # maximum coordinates (max(x), max(y), max(z))
+
+# `initial_refinement_level` is provided here to allow for a 
+# convenient convergence test, see
+# https://trixi-framework.github.io/Trixi.jl/stable/#Performing-a-convergence-analysis
+trees_per_dimension = (4, 4, 4)
+mesh = P4estMesh(trees_per_dimension, polydeg = 3,
+                 coordinates_min = coordinates_min,
+                 coordinates_max = coordinates_max,
+                 initial_refinement_level = 0)
+
+# A semidiscretization collects data structures and functions for the spatial discretization
+semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition, solver)
+
+###############################################################################
+# ODE solvers, callbacks etc.
+
+# Create ODE problem with time span from 0.0 to 0.2
+tspan = (0.0, 0.2)
+ode = semidiscretize(semi, tspan)
+
+# At the beginning of the main loop, the SummaryCallback prints a summary of the simulation setup
+# and resets the timers
+summary_callback = SummaryCallback()
+
+analysis_interval = 100
+
+# The AnalysisCallback allows to analyse the solution in regular intervals and prints the results
+analysis_callback = AnalysisCallback(semi, interval = analysis_interval)
+
+# The AliveCallback prints short status information in regular intervals
+alive_callback = AliveCallback(analysis_interval = analysis_interval)
+
+# The StepsizeCallback handles the re-calculation of the maximum Δt after each time step
+stepsize_callback = StepsizeCallback(cfl = 0.8)
+
+# Create a CallbackSet to collect all callbacks such that they can be passed to the ODE solver
+callbacks = CallbackSet(summary_callback, analysis_callback, alive_callback,
+                        stepsize_callback)
+
+###############################################################################
+# run the simulation
+
+# OrdinaryDiffEq's `solve` method evolves the solution in time and executes the passed callbacks
+sol = solve(ode, CarpenterKennedy2N54(williamson_condition = false),
+            dt = 1.0, # solve needs some value here but it will be overwritten by the stepsize_callback
+            save_everystep = false, callback = callbacks);
+
+# print the timer summary
+summary_callback() # print the timer summary

examples/tree_3d_dgsem/elixir_linearizedeuler_gauss_wall.jl

@@ -0,0 +1,65 @@
+using OrdinaryDiffEq
+using Trixi
+
+###############################################################################
+# semidiscretization of the linearized Euler equations
+
+equations = LinearizedEulerEquations3D(v_mean_global = (0.5, 0.5, 0.5), c_mean_global = 1.0,
+                                       rho_mean_global = 1.0)
+
+solver = DGSEM(polydeg = 5, surface_flux = flux_lax_friedrichs)
+
+coordinates_min = (0.0, 0.0, 0.0)
+coordinates_max = (90.0, 90.0, 90.0)
+
+mesh = TreeMesh(coordinates_min, coordinates_max,
+                initial_refinement_level = 4,
+                n_cells_max = 100_000,
+                periodicity = false)
+
+# Initialize density and pressure perturbation with a Gaussian bump
+# that splits into radial waves which are advected with v - c and v + c.
+function initial_condition_gauss_wall(x, t, equations::LinearizedEulerEquations3D)
+    v1_prime = 0.0
+    v2_prime = 0.0
+    v3_prime = 0.0
+    rho_prime = p_prime = 2 * exp(-((x[1] - 45)^2 + (x[2] - 45)^2) / 25)
+    return SVector(rho_prime, v1_prime, v2_prime, v3_prime, p_prime)
+end
+initial_condition = initial_condition_gauss_wall
+
+# A semidiscretization collects data structures and functions for the spatial discretization
+semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition, solver,
+                                    boundary_conditions = boundary_condition_wall)
+
+###############################################################################
+# ODE solvers, callbacks etc.
+
+# At t = 30, the wave moving with v + c crashes into the wall
+tspan = (0.0, 30.0)
+ode = semidiscretize(semi, tspan)
+
+# At the beginning of the main loop, the SummaryCallback prints a summary of the simulation setup
+# and resets the timers
+summary_callback = SummaryCallback()
+
+# The AnalysisCallback allows to analyse the solution in regular intervals and prints the results
+analysis_callback = AnalysisCallback(semi, interval = 100)
+
+# The StepsizeCallback handles the re-calculation of the maximum Δt after each time step
+stepsize_callback = StepsizeCallback(cfl = 0.9)
+
+# Create a CallbackSet to collect all callbacks such that they can be passed to the ODE solver
+callbacks = CallbackSet(summary_callback, analysis_callback,
+                        stepsize_callback)
+
+###############################################################################
+# run the simulation
+
+# OrdinaryDiffEq's `solve` method evolves the solution in time and executes the passed callbacks
+sol = solve(ode, CarpenterKennedy2N54(williamson_condition = false),
+            dt = 1.0, # solve needs some value here but it will be overwritten by the stepsize_callback
+            save_everystep = false, callback = callbacks)
+
+# Print the timer summary
+summary_callback()

src/Trixi.jl

@@ -160,7 +160,7 @@ export AcousticPerturbationEquations2D,
        LatticeBoltzmannEquations2D, LatticeBoltzmannEquations3D,
        ShallowWaterEquations1D, ShallowWaterEquations2D,
        ShallowWaterEquationsQuasi1D,
-       LinearizedEulerEquations1D, LinearizedEulerEquations2D,
+       LinearizedEulerEquations1D, LinearizedEulerEquations2D, LinearizedEulerEquations3D,
        PolytropicEulerEquations2D,
        TrafficFlowLWREquations1D