From 3a3a58d6a330bc1dfc42d0494daa7219af0b3334 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Wed, 1 Nov 2023 12:14:48 +0200
Subject: [PATCH 01/74] Doc: Core aspects of the basic setup

---
 .../src/files/innards_of_the_basic_setup.jl   | 244 ++++++++++++++++++
 docs/make.jl                                  |   3 +-
 2 files changed, 246 insertions(+), 1 deletion(-)
 create mode 100644 docs/literate/src/files/innards_of_the_basic_setup.jl

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
new file mode 100644
index 0000000000..5193b8800d
--- /dev/null
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -0,0 +1,244 @@
+#src # Core aspects of the basic setup
+
+# This tutorial aims to provide insights into the Trixi.jl framework, with a focus on commonly
+# used complex functions. These functions may lack clarity in their names and brief documentation
+# descriptions.
+
+# We will guide you through a simplified setup, emphasizing functionalities that may not be evident
+# to an average user. This setup is based on stable parts of Trixi.jl that are unlikely to undergo
+# significant changes in the near future. Nevertheless, it will clarify fundamental concepts that
+# continue to be applied in more recent and flexible configurations.
+
+
+# ## Basic setup
+
+# Import essential libraries and specify an equation.
+
+using Trixi, OrdinaryDiffEq
+equations=LinearScalarAdvectionEquation2D((-0.2,0.7))
+
+# Generate a geometrical instruction for spatial discretization using [`TreeMesh`](@ref) with
+# pre-coarsened cell.
+
+coordinates_min = (-2.0, -2.0)
+coordinates_max = (2.0, 2.0)
+
+coarsening_patches = ( # Coarsen cell in the lower-right quarter
+  (type="box", coordinates_min=[0.0, -2.0], coordinates_max=[2.0, 0.0]), 
+)
+
+ mesh = TreeMesh(coordinates_min, coordinates_max, initial_refinement_level=2, 
+                 n_cells_max=30_000,
+                 coarsening_patches=coarsening_patches)
+
+# Created `TreeMesh` looks like:
+
+# ![TreeMesh_example](https://github.com/ArseniyKholod/Test/assets/119304909/df675af6-9eba-4e18-9e68-454a401b1292)
+
+# Instantiate a [`DGSEM`](@ref) solver with a user-specified polynomial degree. The solver's
+# objective is to define the `polydeg + 1` Gauss-Lobatto nodes, and their associated weights within
+# the reference interval [-1, 1]. These nodes will be subsequently used to approximate solutions
+# on each leaf cell of the `TreeMesh`.
+
+solver = DGSEM(polydeg=3)
+
+# Gauss-Lobatto nodes with `N=4`:
+
+# ![Gauss-Lobatto_nodes_example](https://github.com/ArseniyKholod/Test/assets/119304909/ce7ecdc8-23b6-47b6-9f3d-3ff58b4e5677)
+
+
+# ## Overview of the [`SemidiscretizationHyperbolic`](@ref) function
+
+# At this stage, all the necessary components for configuring domain discretization are in place.
+# The remaining task is to combine these components into a single structure that will be used
+# throughout the entire solving process. This is where [`SemidiscretizationHyperbolic`](@ref) comes
+# into play.
+
+semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergence_test, solver)
+
+# The `SemidiscretizationHyperbolic` function calls numerous sub-functions to perform the necessary
+# steps. A brief description of the key sub-functions is provided below.
+
+# - `init_elements(leaf_cell_ids, mesh, equations, dg.basis, RealT, uEltype)`
+ 
+#   As was already mentioned, the fundamental elements for approximating a solution are the leaf
+#   cells. This implies that on each leaf cell, the solution is treated as a polynomial of the
+#   degree specified in the `DGSEM` solver and evaluated at the Gauss-Lobatto nodes, which were
+#   previously illustrated. To provide this, the `init_elements` function extracts these leaf cells
+#   from the `TreeMesh`, assigns them the label "elements", records their coordinates, and maps the
+#   Gauss-Lobatto nodes from the 1D interval [-1, 1] onto each axis of every element.
+
+#   ![elements_example](https://github.com/ArseniyKholod/Test/assets/119304909/637a6efb-9e04-47bd-9dd0-dc4b8ee48dd1)
+
+#   The visualization of elements with nodes includes spaces between elements, which do not exist
+#   in  reality. This spacing is included only for illustrative purposes to underscore the
+#   separation of elements and the independent projection of nodes onto each element.
+
+# - `init_interfaces(leaf_cell_ids, mesh, elements)`
+
+#   At this point, the elements with nodes have been defined; however, they lack the necessary
+#   communication functionality. This is crucial because the solutions on the elements are not
+#   independent of each other. Furthermore, nodes on the boundary of adjacent elements share
+#   the same spatial location, requiring a method to combine their solutions.
+
+#   As demonstrated earlier, the elements can have varying sizes. Let us initially consider
+#   neighbors with equal size. For these elements, the `init_interfaces` function generates
+#   interfaces that store information about adjacent elements, their relative positions, and
+#   allocate containers for sharing solutions between neighbors during the solving process. 
+
+#   In our visualization, these interfaces would conceptually resemble tubes connecting the
+#   corresponding elements.
+
+#   ![interfaces_example](https://github.com/ArseniyKholod/Test/assets/119304909/4f6c7835-c98e-4e46-a025-2df81b28883b)
+
+# - `init_mortars(leaf_cell_ids, mesh, elements, dg.mortar)`
+
+#   Returning to the consideration of different sizes among adjacent elements, within the
+#   `TreeMesh`, adjacent leaf cells can vary in size by a maximum factor of two. This implies
+#   that a coarsened element on each side, excluding the domain boundaries, has one neighbor of
+#   equal size with a connection through an interface, or two neighbors with sizes two times
+#   smaller, requiring a connection through so called "mortars".
+
+#   Mortars store information about the connected elements, their relative positions, and allocate
+#   containers for sharing solutions between these elements along their boundaries.
+
+#   In our visualization, mortars are represented as branched tubes.
+
+#   ![mortars_example](https://github.com/ArseniyKholod/Test/assets/119304909/1c603899-c02c-4923-85b9-75d0e9e0426e)
+
+# - `init_boundaries(leaf_cell_ids, mesh, elements)`
+
+#   In order to apply boundary conditions, it is necessary to identify the locations of the
+#   boundaries. Therefore, we initialize a "boundaries" object, which records the elements that
+#   contain boundaries, specifies which side of an element is a boundary, stores the coordinates
+#   of boundary nodes, and allocates containers for managing solutions at these boundaries.
+
+#   In our visualization, boundaries and their corresponding nodes are highlighted with green,
+#   semi-transparent lines.
+
+#   ![boundaries_example](https://github.com/ArseniyKholod/Test/assets/119304909/db0c6d62-e520-49a1-925f-049e3a378841)
+
+# All the structures mentioned earlier are packed as a cache of type `Tuple`. Subsequently, an
+# object of type `SemidiscretizationHyperbolic` is initialized using this cache, initial and
+# boundary conditions, equations, mesh and solver.
+
+# In conclusion, `Semidiscretization`'s primary function is to collect equations, the geometric
+# representation of the domain, and approximation instructions, creating specialized structures to
+# interconnect these components in a manner that enables their utilization for the numerical
+# solution of partial differential equations (PDEs).
+
+# As evident from the earlier description of `SemidiscretizationHyperbolic`, it comprises numerous
+# functions called recursively. Without delving into details, the structure of the primary calls
+# can be illustrated as follows:
+
+# ![SemidiscretizationHyperbolic_structure](https://github.com/ArseniyKholod/Test/assets/119304909/ac95eb2e-d963-4b16-be1c-65dd731368bd)
+
+
+# ## Overview of the [`semidiscretize`](@ref) function
+
+# At this stage, we have defined the equations and configured the domain's discretization. The
+# final step before solving is to select a suitable time span and apply the corresponding initial
+# conditions, which are already stored in the initialized `SemidiscretizationHyperbolic` object.
+
+# The purpose of the `semidiscretize` function is to wrap the semi-discretization as an
+# `ODEProblem` within the specified time interval, while also applying the initial conditions at
+# the left boundary of this interval. This `ODEProblem` can be subsequently passed to the `solve`
+# function from the OrdinaryDiffEq.jl package.
+
+ode = semidiscretize(semi, (0.0, 1.0));
+ 
+# The `semidiscretize` function involves a deep tree of recursive calls, with the primary ones
+# explained below.
+
+# - `allocate_coefficients(mesh, equations, solver, cache)`
+
+#   To apply initial conditions, a container needs to be generated to store the initial values of
+#   the target variables for each node within each element. The `allocate_coefficients` function
+#   initializes `u_ode` as a 1D zero-vector with a length that depends on the number of variables,
+#   elements, nodes, and dimensions. The use of a 1D vector format is consistent with the
+#   requirements of the `solve` function from OrdinaryDiffEq.jl. Therefore, Trixi.jl follows this
+#   format to be able to utilize the functionalities of OrdinaryDiffEq.jl.
+
+# - `wrap_array(u_ode, semi)`
+
+#   As previously noted, `u_ode` is constructed as a 1D vector to ensure compatibility with
+#   OrdinaryDiffEq.jl. However, for internal use within Trixi.jl, identification which part of the
+#   vector relates to specific variables, elements and nodes can be challenging.
+
+#   This is why the `u_ode` vector is wrapped by the `wrap_array` function to create a
+#   multidimensional array `u`, with each dimension representing variables, nodes and elements.
+#   Consequently, navigation within this multidimensional array becomes noticeably easier.
+
+#   "Wrapping" in this context involves the creation of a reference to the same storage location
+#   but with an alternative structural representation. This approach enables the use of both
+#   instances `u` and `u_ode` as needed, so that changes are simultaneously reflected in both.
+#   This is possible because, from a storage perspective, they share the same stored data, while
+#   access to this data is provided in different ways.
+
+# - `compute_coefficients!(u, initial_conditions, t, mesh::DG, equations, solver, cache)`
+
+#   Now the variable `u`, intended to store solutions, has been allocated and wrapped, it is time
+#   to apply the initial conditions. The `compute_coefficients!` function calculates the initial
+#   conditions for each variable at every node within each element and properly stores them in the
+#   `u` array.
+
+# At this stage, the `semidiscretize` function has all the necessary components to initialize and
+# return an `ODEProblem` object, which will be used by the `solve` function to compute the
+# solution.
+
+# In summary, the internal workings of `semidiscretize` with brief descriptions can be presented
+# as follows.
+
+# ![semidiscretize_structure](https://github.com/ArseniyKholod/Test/assets/119304909/fa775789-7b4e-4909-9a44-e43b5b3a4a75)
+
+
+# ## Functions `solve` and `rhs!`
+
+# Once the `ODEProblem` object is initialized, the `solve` function from the OrdinaryDiffEq.jl
+# package can be utilized to compute an approximate solution using the instructions contained in
+# the `ODEProblem` object.
+
+sol = solve(ode, CarpenterKennedy2N54(williamson_condition=false), dt=0.01, save_everystep=false);
+
+# Since the `solve` function is defined in another package without knowledge of how to handle
+# discretizations performed in Trixi.jl, it is necessary to define the right-hand-side function,
+# `rhs!`, within Trixi.jl.
+
+# Trixi.jl includes a set of `rhs!` functions designed to compute `du` according to the structure
+# of the setup. These `rhs!` functions calculate interface, mortars, and boundary fluxes, in
+# addition to surface and volume integrals, in order to construct the `du` vector. This `du` vector
+# is then used by the time integration method to derive solutions in the subsequent time step.
+# The `rhs!` function is called by time integration methods in each iteration of the solve-loop
+# within OrdinaryDiffEq.jl, with arguments `du`, `u`, `Semidiscretization`, and the time step.
+
+# The problem is that `rhs!` functions within Trixi.jl are specialized for specific solver and mesh
+# types. However, the types of arguments passed to `rhs!` by time integration methods do not
+# explicitly provide this information. Consequently, Trixi.jl uses a two-levels approach for `rhs!`
+# functions. The first level is limited to a single function for each `semidiscretization` type,
+# and its role is to redirect data to the target `rhs!`. It performs this by extracting the
+# necessary data from the integrator and passing them, along with the originally received
+# arguments, to the specialized for solver and mesh types `rhs!` function, which is
+# responsible for calculating `du`.
+
+# Path from the `solve` function call to the appropriate `rhs!` function call:
+
+# ![rhs_structure](https://github.com/ArseniyKholod/Test/assets/119304909/6603223c-8287-41f9-b609-1dcff7a5a8eb)
+
+# Computed solution:
+
+using Plots
+plot(sol)
+pd = PlotData2D(sol)
+plot!(getmesh(pd))
+
+
+# ## Package versions
+
+# These results were obtained using the following versions.
+
+using InteractiveUtils
+versioninfo()
+
+using Pkg
+Pkg.status(["Trixi", "OrdinaryDiffEq", "Plots", "ForwardDiff"],
+           mode=PKGMODE_MANIFEST)
diff --git a/docs/make.jl b/docs/make.jl
index df8ac04be1..3ffce0a166 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -68,7 +68,8 @@ files = [
     # Topic: other stuff
     "Explicit time stepping" => "time_stepping.jl",
     "Differentiable programming" => "differentiable_programming.jl",
-    "Custom semidiscretizations" => "custom_semidiscretization.jl"
+    "Custom semidiscretizations" => "custom_semidiscretization.jl",
+    "Core aspects of the basic setup" => "innards_of_the_basic_setup.jl",
     ]
 tutorials = create_tutorials(files)
 

From a3422229e549532c182fdbe608a65835270a802c Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Wed, 1 Nov 2023 12:39:50 +0200
Subject: [PATCH 02/74] update pictures

---
 .../src/files/innards_of_the_basic_setup.jl   | 20 +++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
index 5193b8800d..d6411993e0 100644
--- a/docs/literate/src/files/innards_of_the_basic_setup.jl
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -33,7 +33,7 @@ coarsening_patches = ( # Coarsen cell in the lower-right quarter
 
 # Created `TreeMesh` looks like:
 
-# ![TreeMesh_example](https://github.com/ArseniyKholod/Test/assets/119304909/df675af6-9eba-4e18-9e68-454a401b1292)
+# ![TreeMesh_example](https://github.com/trixi-framework/Trixi.jl/assets/119304909/d5ef76ee-8246-4730-a692-b472c06063a3)
 
 # Instantiate a [`DGSEM`](@ref) solver with a user-specified polynomial degree. The solver's
 # objective is to define the `polydeg + 1` Gauss-Lobatto nodes, and their associated weights within
@@ -44,7 +44,7 @@ solver = DGSEM(polydeg=3)
 
 # Gauss-Lobatto nodes with `N=4`:
 
-# ![Gauss-Lobatto_nodes_example](https://github.com/ArseniyKholod/Test/assets/119304909/ce7ecdc8-23b6-47b6-9f3d-3ff58b4e5677)
+# ![Gauss-Lobatto_nodes_example](https://github.com/trixi-framework/Trixi.jl/assets/119304909/401e5e85-026e-48b6-8a1f-dca0306f3bb0)
 
 
 # ## Overview of the [`SemidiscretizationHyperbolic`](@ref) function
@@ -68,7 +68,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 #   from the `TreeMesh`, assigns them the label "elements", records their coordinates, and maps the
 #   Gauss-Lobatto nodes from the 1D interval [-1, 1] onto each axis of every element.
 
-#   ![elements_example](https://github.com/ArseniyKholod/Test/assets/119304909/637a6efb-9e04-47bd-9dd0-dc4b8ee48dd1)
+#   ![elements_example](https://github.com/trixi-framework/Trixi.jl/assets/119304909/534131bd-e85b-43d5-860d-2db6e60ce921)
 
 #   The visualization of elements with nodes includes spaces between elements, which do not exist
 #   in  reality. This spacing is included only for illustrative purposes to underscore the
@@ -89,7 +89,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 #   In our visualization, these interfaces would conceptually resemble tubes connecting the
 #   corresponding elements.
 
-#   ![interfaces_example](https://github.com/ArseniyKholod/Test/assets/119304909/4f6c7835-c98e-4e46-a025-2df81b28883b)
+#   ![interfaces_example](https://github.com/trixi-framework/Trixi.jl/assets/119304909/bc3b6b02-afbc-4371-aaf7-c7bdc5a6c540)
 
 # - `init_mortars(leaf_cell_ids, mesh, elements, dg.mortar)`
 
@@ -104,7 +104,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 
 #   In our visualization, mortars are represented as branched tubes.
 
-#   ![mortars_example](https://github.com/ArseniyKholod/Test/assets/119304909/1c603899-c02c-4923-85b9-75d0e9e0426e)
+#   ![mortars_example](https://github.com/trixi-framework/Trixi.jl/assets/119304909/43a95a60-3a31-4b1f-8724-14049e7a0481)
 
 # - `init_boundaries(leaf_cell_ids, mesh, elements)`
 
@@ -116,7 +116,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 #   In our visualization, boundaries and their corresponding nodes are highlighted with green,
 #   semi-transparent lines.
 
-#   ![boundaries_example](https://github.com/ArseniyKholod/Test/assets/119304909/db0c6d62-e520-49a1-925f-049e3a378841)
+#   ![boundaries_example](https://github.com/trixi-framework/Trixi.jl/assets/119304909/21996b20-4a22-4dfb-b16a-e2c22c2f29fe)
 
 # All the structures mentioned earlier are packed as a cache of type `Tuple`. Subsequently, an
 # object of type `SemidiscretizationHyperbolic` is initialized using this cache, initial and
@@ -131,7 +131,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 # functions called recursively. Without delving into details, the structure of the primary calls
 # can be illustrated as follows:
 
-# ![SemidiscretizationHyperbolic_structure](https://github.com/ArseniyKholod/Test/assets/119304909/ac95eb2e-d963-4b16-be1c-65dd731368bd)
+# ![SemidiscretizationHyperbolic_structure](https://github.com/trixi-framework/Trixi.jl/assets/119304909/2cdfe3d1-f88a-4028-b83c-908d34d400cd)
 
 
 # ## Overview of the [`semidiscretize`](@ref) function
@@ -140,7 +140,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 # final step before solving is to select a suitable time span and apply the corresponding initial
 # conditions, which are already stored in the initialized `SemidiscretizationHyperbolic` object.
 
-# The purpose of the `semidiscretize` function is to wrap the semi-discretization as an
+# The purpose of the [`semidiscretize`](@ref) function is to wrap the semi-discretization as an
 # `ODEProblem` within the specified time interval, while also applying the initial conditions at
 # the left boundary of this interval. This `ODEProblem` can be subsequently passed to the `solve`
 # function from the OrdinaryDiffEq.jl package.
@@ -189,7 +189,7 @@ ode = semidiscretize(semi, (0.0, 1.0));
 # In summary, the internal workings of `semidiscretize` with brief descriptions can be presented
 # as follows.
 
-# ![semidiscretize_structure](https://github.com/ArseniyKholod/Test/assets/119304909/fa775789-7b4e-4909-9a44-e43b5b3a4a75)
+# ![semidiscretize_structure](https://github.com/trixi-framework/Trixi.jl/assets/119304909/491eddc4-aadb-4e29-8c76-a7c821d0674e)
 
 
 # ## Functions `solve` and `rhs!`
@@ -222,7 +222,7 @@ sol = solve(ode, CarpenterKennedy2N54(williamson_condition=false), dt=0.01, save
 
 # Path from the `solve` function call to the appropriate `rhs!` function call:
 
-# ![rhs_structure](https://github.com/ArseniyKholod/Test/assets/119304909/6603223c-8287-41f9-b609-1dcff7a5a8eb)
+# ![rhs_structure](https://github.com/trixi-framework/Trixi.jl/assets/119304909/dbea9a0e-25a4-4afa-855e-01f1ad619982)
 
 # Computed solution:
 

From 6c62bc82b4865dc5ee4233d26b7f6d8c7dd98781 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Wed, 1 Nov 2023 13:33:51 +0200
Subject: [PATCH 03/74] Update innards_of_the_basic_setup.jl

---
 docs/literate/src/files/innards_of_the_basic_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
index d6411993e0..cba25a0797 100644
--- a/docs/literate/src/files/innards_of_the_basic_setup.jl
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -195,7 +195,7 @@ ode = semidiscretize(semi, (0.0, 1.0));
 # ## Functions `solve` and `rhs!`
 
 # Once the `ODEProblem` object is initialized, the `solve` function from the OrdinaryDiffEq.jl
-# package can be utilized to compute an approximate solution using the instructions contained in
+# package can be utilized to compute an approximated solution using the instructions contained in
 # the `ODEProblem` object.
 
 sol = solve(ode, CarpenterKennedy2N54(williamson_condition=false), dt=0.01, save_everystep=false);

From bb518f50053cef054220fd35542f52a47214a997 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Thu, 2 Nov 2023 10:22:51 +0200
Subject: [PATCH 04/74] mention ODE-Solvers

---
 .../src/files/innards_of_the_basic_setup.jl        | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
index cba25a0797..9d9d5fb90b 100644
--- a/docs/literate/src/files/innards_of_the_basic_setup.jl
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -156,7 +156,7 @@ ode = semidiscretize(semi, (0.0, 1.0));
 #   the target variables for each node within each element. The `allocate_coefficients` function
 #   initializes `u_ode` as a 1D zero-vector with a length that depends on the number of variables,
 #   elements, nodes, and dimensions. The use of a 1D vector format is consistent with the
-#   requirements of the `solve` function from OrdinaryDiffEq.jl. Therefore, Trixi.jl follows this
+#   requirements of the ODE-solvers from OrdinaryDiffEq.jl. Therefore, Trixi.jl follows this
 #   format to be able to utilize the functionalities of OrdinaryDiffEq.jl.
 
 # - `wrap_array(u_ode, semi)`
@@ -194,15 +194,15 @@ ode = semidiscretize(semi, (0.0, 1.0));
 
 # ## Functions `solve` and `rhs!`
 
-# Once the `ODEProblem` object is initialized, the `solve` function from the OrdinaryDiffEq.jl
-# package can be utilized to compute an approximated solution using the instructions contained in
-# the `ODEProblem` object.
+# Once the `ODEProblem` object is initialized, the `solve` function and one of the ODE-solvers from
+# the OrdinaryDiffEq.jl package can be utilized to compute an approximated solution using the
+# instructions contained in the `ODEProblem` object.
 
 sol = solve(ode, CarpenterKennedy2N54(williamson_condition=false), dt=0.01, save_everystep=false);
 
-# Since the `solve` function is defined in another package without knowledge of how to handle
-# discretizations performed in Trixi.jl, it is necessary to define the right-hand-side function,
-# `rhs!`, within Trixi.jl.
+# Since the `solve` function and the ODE-solver are defined in another package without knowledge
+# of how to handle discretizations performed in Trixi.jl, it is necessary to define the
+# right-hand-side function, `rhs!`, within Trixi.jl.
 
 # Trixi.jl includes a set of `rhs!` functions designed to compute `du` according to the structure
 # of the setup. These `rhs!` functions calculate interface, mortars, and boundary fluxes, in

From 85d6e8b50261885ad198ae4036e8599189912e56 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Thu, 2 Nov 2023 11:05:35 +0200
Subject: [PATCH 05/74] Revert "Merge branch 'main' into
 semidiscretization-doc"

This reverts commit b8f8b0bc167a476b3dead39f6aadf4fe43601e7d, reversing
changes made to bb518f50053cef054220fd35542f52a47214a997.
---
 .github/workflows/SpellCheck.yml       |   2 +-
 src/equations/compressible_euler_1d.jl |  36 +++-
 src/equations/compressible_euler_2d.jl |  92 +++------
 src/equations/compressible_euler_3d.jl | 100 ++++------
 src/equations/numerical_fluxes.jl      |   8 -
 test/test_dgmulti_2d.jl                | 265 +------------------------
 test/test_p4est_2d.jl                  |  26 ---
 test/test_p4est_3d.jl                  |  28 ---
 test/test_tree_1d_euler.jl             |  16 --
 test/test_tree_2d_euler.jl             |  26 ---
 test/test_tree_3d_euler.jl             |  28 ---
 test/test_unit.jl                      |  18 +-
 12 files changed, 115 insertions(+), 530 deletions(-)

diff --git a/.github/workflows/SpellCheck.yml b/.github/workflows/SpellCheck.yml
index fb71fe45af..eae6d8e0be 100644
--- a/.github/workflows/SpellCheck.yml
+++ b/.github/workflows/SpellCheck.yml
@@ -10,4 +10,4 @@ jobs:
       - name: Checkout Actions Repository
         uses: actions/checkout@v4
       - name: Check spelling
-        uses: crate-ci/typos@v1.16.21
+        uses: crate-ci/typos@v1.16.15
diff --git a/src/equations/compressible_euler_1d.jl b/src/equations/compressible_euler_1d.jl
index 05c38ce791..9204989e8b 100644
--- a/src/equations/compressible_euler_1d.jl
+++ b/src/equations/compressible_euler_1d.jl
@@ -808,7 +808,7 @@ function flux_hllc(u_ll, u_rr, orientation::Integer,
 end
 
 """
-    min_max_speed_einfeldt(u_ll, u_rr, orientation, equations::CompressibleEulerEquations1D)
+    flux_hlle(u_ll, u_rr, orientation, equations::CompressibleEulerEquations1D)
 
 Computes the HLLE (Harten-Lax-van Leer-Einfeldt) flux for the compressible Euler equations.
 Special estimates of the signal velocites and linearization of the Riemann problem developed
@@ -825,8 +825,8 @@ Compactly summarized:
   Numerical methods for conservation laws and related equations.
   [Link](https://metaphor.ethz.ch/x/2019/hs/401-4671-00L/literature/mishra_hyperbolic_pdes.pdf)
 """
-@inline function min_max_speed_einfeldt(u_ll, u_rr, orientation::Integer,
-                                        equations::CompressibleEulerEquations1D)
+function flux_hlle(u_ll, u_rr, orientation::Integer,
+                   equations::CompressibleEulerEquations1D)
     # Calculate primitive variables, enthalpy and speed of sound
     rho_ll, v_ll, p_ll = cons2prim(u_ll, equations)
     rho_rr, v_rr, p_rr = cons2prim(u_rr, equations)
@@ -858,7 +858,35 @@ Compactly summarized:
     SsL = min(v_roe - c_roe, v_ll - beta * c_ll, zero(v_roe))
     SsR = max(v_roe + c_roe, v_rr + beta * c_rr, zero(v_roe))
 
-    return SsL, SsR
+    if SsL >= 0.0 && SsR > 0.0
+        # Positive supersonic speed
+        f_ll = flux(u_ll, orientation, equations)
+
+        f1 = f_ll[1]
+        f2 = f_ll[2]
+        f3 = f_ll[3]
+    elseif SsR <= 0.0 && SsL < 0.0
+        # Negative supersonic speed
+        f_rr = flux(u_rr, orientation, equations)
+
+        f1 = f_rr[1]
+        f2 = f_rr[2]
+        f3 = f_rr[3]
+    else
+        # Subsonic case
+        # Compute left and right fluxes
+        f_ll = flux(u_ll, orientation, equations)
+        f_rr = flux(u_rr, orientation, equations)
+
+        f1 = (SsR * f_ll[1] - SsL * f_rr[1] + SsL * SsR * (u_rr[1] - u_ll[1])) /
+             (SsR - SsL)
+        f2 = (SsR * f_ll[2] - SsL * f_rr[2] + SsL * SsR * (u_rr[2] - u_ll[2])) /
+             (SsR - SsL)
+        f3 = (SsR * f_ll[3] - SsL * f_rr[3] + SsL * SsR * (u_rr[3] - u_ll[3])) /
+             (SsR - SsL)
+    end
+
+    return SVector(f1, f2, f3)
 end
 
 @inline function max_abs_speeds(u, equations::CompressibleEulerEquations1D)
diff --git a/src/equations/compressible_euler_2d.jl b/src/equations/compressible_euler_2d.jl
index 6c8f2e1e84..27b92f4195 100644
--- a/src/equations/compressible_euler_2d.jl
+++ b/src/equations/compressible_euler_2d.jl
@@ -1253,7 +1253,7 @@ function flux_hllc(u_ll, u_rr, orientation::Integer,
 end
 
 """
-    min_max_speed_einfeldt(u_ll, u_rr, orientation, equations::CompressibleEulerEquations2D)
+    flux_hlle(u_ll, u_rr, orientation, equations::CompressibleEulerEquations2D)
 
 Computes the HLLE (Harten-Lax-van Leer-Einfeldt) flux for the compressible Euler equations.
 Special estimates of the signal velocites and linearization of the Riemann problem developed
@@ -1267,8 +1267,8 @@ of the numerical flux.
   On Godunov-type methods near low densities.
   [DOI: 10.1016/0021-9991(91)90211-3](https://doi.org/10.1016/0021-9991(91)90211-3)
 """
-@inline function min_max_speed_einfeldt(u_ll, u_rr, orientation::Integer,
-                                        equations::CompressibleEulerEquations2D)
+function flux_hlle(u_ll, u_rr, orientation::Integer,
+                   equations::CompressibleEulerEquations2D)
     # Calculate primitive variables, enthalpy and speed of sound
     rho_ll, v1_ll, v2_ll, p_ll = cons2prim(u_ll, equations)
     rho_rr, v1_rr, v2_rr, p_rr = cons2prim(u_rr, equations)
@@ -1306,65 +1306,39 @@ of the numerical flux.
         SsR = max(v2_roe + c_roe, v2_rr + beta * c_rr, zero(v2_roe))
     end
 
-    return SsL, SsR
-end
-
-"""
-    min_max_speed_einfeldt(u_ll, u_rr, normal_direction, equations::CompressibleEulerEquations2D)
-
-Computes the HLLE (Harten-Lax-van Leer-Einfeldt) flux for the compressible Euler equations.
-Special estimates of the signal velocites and linearization of the Riemann problem developed
-by Einfeldt to ensure that the internal energy and density remain positive during the computation
-of the numerical flux.
-
-- Bernd Einfeldt (1988)
-  On Godunov-type methods for gas dynamics.
-  [DOI: 10.1137/0725021](https://doi.org/10.1137/0725021)
-- Bernd Einfeldt, Claus-Dieter Munz, Philip L. Roe and Björn Sjögreen (1991)
-  On Godunov-type methods near low densities.
-  [DOI: 10.1016/0021-9991(91)90211-3](https://doi.org/10.1016/0021-9991(91)90211-3)
-"""
-@inline function min_max_speed_einfeldt(u_ll, u_rr, normal_direction::AbstractVector,
-                                        equations::CompressibleEulerEquations2D)
-    # Calculate primitive variables, enthalpy and speed of sound
-    rho_ll, v1_ll, v2_ll, p_ll = cons2prim(u_ll, equations)
-    rho_rr, v1_rr, v2_rr, p_rr = cons2prim(u_rr, equations)
-
-    v_dot_n_ll = v1_ll * normal_direction[1] + v2_ll * normal_direction[2]
-    v_dot_n_rr = v1_rr * normal_direction[1] + v2_rr * normal_direction[2]
-
-    norm_ = norm(normal_direction)
-
-    # `u_ll[4]` is total energy `rho_e_ll` on the left
-    H_ll = (u_ll[4] + p_ll) / rho_ll
-    c_ll = sqrt(equations.gamma * p_ll / rho_ll) * norm_
-
-    # `u_rr[4]` is total energy `rho_e_rr` on the right
-    H_rr = (u_rr[4] + p_rr) / rho_rr
-    c_rr = sqrt(equations.gamma * p_rr / rho_rr) * norm_
+    if SsL >= 0.0 && SsR > 0.0
+        # Positive supersonic speed
+        f_ll = flux(u_ll, orientation, equations)
 
-    # Compute Roe averages
-    sqrt_rho_ll = sqrt(rho_ll)
-    sqrt_rho_rr = sqrt(rho_rr)
-    inv_sum_sqrt_rho = inv(sqrt_rho_ll + sqrt_rho_rr)
-
-    v1_roe = (sqrt_rho_ll * v1_ll + sqrt_rho_rr * v1_rr) * inv_sum_sqrt_rho
-    v2_roe = (sqrt_rho_ll * v2_ll + sqrt_rho_rr * v2_rr) * inv_sum_sqrt_rho
-    v_roe = v1_roe * normal_direction[1] + v2_roe * normal_direction[2]
-    v_roe_mag = (v1_roe * normal_direction[1])^2 + (v2_roe * normal_direction[2])^2
-
-    H_roe = (sqrt_rho_ll * H_ll + sqrt_rho_rr * H_rr) * inv_sum_sqrt_rho
-    c_roe = sqrt((equations.gamma - 1) * (H_roe - 0.5 * v_roe_mag)) * norm_
-
-    # Compute convenience constant for positivity preservation, see
-    # https://doi.org/10.1016/0021-9991(91)90211-3
-    beta = sqrt(0.5 * (equations.gamma - 1) / equations.gamma)
+        f1 = f_ll[1]
+        f2 = f_ll[2]
+        f3 = f_ll[3]
+        f4 = f_ll[4]
+    elseif SsR <= 0.0 && SsL < 0.0
+        # Negative supersonic speed
+        f_rr = flux(u_rr, orientation, equations)
 
-    # Estimate the edges of the Riemann fan (with positivity conservation)
-    SsL = min(v_roe - c_roe, v_dot_n_ll - beta * c_ll, zero(v_roe))
-    SsR = max(v_roe + c_roe, v_dot_n_rr + beta * c_rr, zero(v_roe))
+        f1 = f_rr[1]
+        f2 = f_rr[2]
+        f3 = f_rr[3]
+        f4 = f_rr[4]
+    else
+        # Subsonic case
+        # Compute left and right fluxes
+        f_ll = flux(u_ll, orientation, equations)
+        f_rr = flux(u_rr, orientation, equations)
+
+        f1 = (SsR * f_ll[1] - SsL * f_rr[1] + SsL * SsR * (u_rr[1] - u_ll[1])) /
+             (SsR - SsL)
+        f2 = (SsR * f_ll[2] - SsL * f_rr[2] + SsL * SsR * (u_rr[2] - u_ll[2])) /
+             (SsR - SsL)
+        f3 = (SsR * f_ll[3] - SsL * f_rr[3] + SsL * SsR * (u_rr[3] - u_ll[3])) /
+             (SsR - SsL)
+        f4 = (SsR * f_ll[4] - SsL * f_rr[4] + SsL * SsR * (u_rr[4] - u_ll[4])) /
+             (SsR - SsL)
+    end
 
-    return SsL, SsR
+    return SVector(f1, f2, f3, f4)
 end
 
 @inline function max_abs_speeds(u, equations::CompressibleEulerEquations2D)
diff --git a/src/equations/compressible_euler_3d.jl b/src/equations/compressible_euler_3d.jl
index fc56f58025..7f25bde31f 100644
--- a/src/equations/compressible_euler_3d.jl
+++ b/src/equations/compressible_euler_3d.jl
@@ -1322,7 +1322,7 @@ function flux_hllc(u_ll, u_rr, orientation::Integer,
 end
 
 """
-    min_max_speed_einfeldt(u_ll, u_rr, orientation, equations::CompressibleEulerEquations3D)
+    flux_hlle(u_ll, u_rr, orientation, equations::CompressibleEulerEquations3D)
 
 Computes the HLLE (Harten-Lax-van Leer-Einfeldt) flux for the compressible Euler equations.
 Special estimates of the signal velocites and linearization of the Riemann problem developed
@@ -1336,8 +1336,8 @@ of the numerical flux.
   On Godunov-type methods near low densities.
   [DOI: 10.1016/0021-9991(91)90211-3](https://doi.org/10.1016/0021-9991(91)90211-3)
 """
-@inline function min_max_speed_einfeldt(u_ll, u_rr, orientation::Integer,
-                                        equations::CompressibleEulerEquations3D)
+function flux_hlle(u_ll, u_rr, orientation::Integer,
+                   equations::CompressibleEulerEquations3D)
     # Calculate primitive variables, enthalpy and speed of sound
     rho_ll, v1_ll, v2_ll, v3_ll, p_ll = cons2prim(u_ll, equations)
     rho_rr, v1_rr, v2_rr, v3_rr, p_rr = cons2prim(u_rr, equations)
@@ -1379,69 +1379,43 @@ of the numerical flux.
         SsR = max(v3_roe + c_roe, v3_rr + beta * c_rr, zero(v3_roe))
     end
 
-    return SsL, SsR
-end
-
-"""
-    min_max_speed_einfeldt(u_ll, u_rr, normal_direction, equations::CompressibleEulerEquations3D)
-
-Computes the HLLE (Harten-Lax-van Leer-Einfeldt) flux for the compressible Euler equations.
-Special estimates of the signal velocites and linearization of the Riemann problem developed
-by Einfeldt to ensure that the internal energy and density remain positive during the computation
-of the numerical flux.
-
-- Bernd Einfeldt (1988)
-  On Godunov-type methods for gas dynamics.
-  [DOI: 10.1137/0725021](https://doi.org/10.1137/0725021)
-- Bernd Einfeldt, Claus-Dieter Munz, Philip L. Roe and Björn Sjögreen (1991)
-  On Godunov-type methods near low densities.
-  [DOI: 10.1016/0021-9991(91)90211-3](https://doi.org/10.1016/0021-9991(91)90211-3)
-"""
-@inline function min_max_speed_einfeldt(u_ll, u_rr, normal_direction::AbstractVector,
-                                        equations::CompressibleEulerEquations3D)
-    # Calculate primitive variables, enthalpy and speed of sound
-    rho_ll, v1_ll, v2_ll, v3_ll, p_ll = cons2prim(u_ll, equations)
-    rho_rr, v1_rr, v2_rr, v3_rr, p_rr = cons2prim(u_rr, equations)
-
-    v_dot_n_ll = v1_ll * normal_direction[1] + v2_ll * normal_direction[2] +
-                 v3_ll * normal_direction[3]
-    v_dot_n_rr = v1_rr * normal_direction[1] + v2_rr * normal_direction[2] +
-                 v3_rr * normal_direction[3]
-
-    norm_ = norm(normal_direction)
-
-    # `u_ll[5]` is total energy `rho_e_ll` on the left
-    H_ll = (u_ll[5] + p_ll) / rho_ll
-    c_ll = sqrt(equations.gamma * p_ll / rho_ll) * norm_
-
-    # `u_rr[5]` is total energy `rho_e_rr` on the right
-    H_rr = (u_rr[5] + p_rr) / rho_rr
-    c_rr = sqrt(equations.gamma * p_rr / rho_rr) * norm_
-
-    # Compute Roe averages
-    sqrt_rho_ll = sqrt(rho_ll)
-    sqrt_rho_rr = sqrt(rho_rr)
-    inv_sum_sqrt_rho = inv(sqrt_rho_ll + sqrt_rho_rr)
+    if SsL >= 0.0 && SsR > 0.0
+        # Positive supersonic speed
+        f_ll = flux(u_ll, orientation, equations)
 
-    v1_roe = (sqrt_rho_ll * v1_ll + sqrt_rho_rr * v1_rr) * inv_sum_sqrt_rho
-    v2_roe = (sqrt_rho_ll * v2_ll + sqrt_rho_rr * v2_rr) * inv_sum_sqrt_rho
-    v3_roe = (sqrt_rho_ll * v3_ll + sqrt_rho_rr * v3_rr) * inv_sum_sqrt_rho
-    v_roe = v1_roe * normal_direction[1] + v2_roe * normal_direction[2] +
-            v3_roe * normal_direction[3]
-    v_roe_mag = v1_roe^2 + v2_roe^2 + v3_roe^2
-
-    H_roe = (sqrt_rho_ll * H_ll + sqrt_rho_rr * H_rr) * inv_sum_sqrt_rho
-    c_roe = sqrt((equations.gamma - 1) * (H_roe - 0.5 * v_roe_mag)) * norm_
-
-    # Compute convenience constant for positivity preservation, see
-    # https://doi.org/10.1016/0021-9991(91)90211-3
-    beta = sqrt(0.5 * (equations.gamma - 1) / equations.gamma)
+        f1 = f_ll[1]
+        f2 = f_ll[2]
+        f3 = f_ll[3]
+        f4 = f_ll[4]
+        f5 = f_ll[5]
+    elseif SsR <= 0.0 && SsL < 0.0
+        # Negative supersonic speed
+        f_rr = flux(u_rr, orientation, equations)
 
-    # Estimate the edges of the Riemann fan (with positivity conservation)
-    SsL = min(v_roe - c_roe, v_dot_n_ll - beta * c_ll, zero(v_roe))
-    SsR = max(v_roe + c_roe, v_dot_n_rr + beta * c_rr, zero(v_roe))
+        f1 = f_rr[1]
+        f2 = f_rr[2]
+        f3 = f_rr[3]
+        f4 = f_rr[4]
+        f5 = f_rr[5]
+    else
+        # Subsonic case
+        # Compute left and right fluxes
+        f_ll = flux(u_ll, orientation, equations)
+        f_rr = flux(u_rr, orientation, equations)
+
+        f1 = (SsR * f_ll[1] - SsL * f_rr[1] + SsL * SsR * (u_rr[1] - u_ll[1])) /
+             (SsR - SsL)
+        f2 = (SsR * f_ll[2] - SsL * f_rr[2] + SsL * SsR * (u_rr[2] - u_ll[2])) /
+             (SsR - SsL)
+        f3 = (SsR * f_ll[3] - SsL * f_rr[3] + SsL * SsR * (u_rr[3] - u_ll[3])) /
+             (SsR - SsL)
+        f4 = (SsR * f_ll[4] - SsL * f_rr[4] + SsL * SsR * (u_rr[4] - u_ll[4])) /
+             (SsR - SsL)
+        f5 = (SsR * f_ll[5] - SsL * f_rr[5] + SsL * SsR * (u_rr[5] - u_ll[5])) /
+             (SsR - SsL)
+    end
 
-    return SsL, SsR
+    return SVector(f1, f2, f3, f4, f5)
 end
 
 @inline function max_abs_speeds(u, equations::CompressibleEulerEquations3D)
diff --git a/src/equations/numerical_fluxes.jl b/src/equations/numerical_fluxes.jl
index 71782644b1..87010275f2 100644
--- a/src/equations/numerical_fluxes.jl
+++ b/src/equations/numerical_fluxes.jl
@@ -304,14 +304,6 @@ See [`FluxHLL`](@ref).
 """
 const flux_hll = FluxHLL()
 
-"""
-    flux_hlle
-
-See [`min_max_speed_einfeldt`](@ref).
-This is a [`FluxHLL`](@ref)-type two-wave solver with special estimates of the wave speeds.
-"""
-const flux_hlle = FluxHLL(min_max_speed_einfeldt)
-
 # TODO: TrixiShallowWater: move the chen_noelle flux structure to the new package
 
 # An empty version of the `min_max_speed_chen_noelle` function is declared here
diff --git a/test/test_dgmulti_2d.jl b/test/test_dgmulti_2d.jl
index 892c8ed37f..8fd00df72e 100644
--- a/test/test_dgmulti_2d.jl
+++ b/test/test_dgmulti_2d.jl
@@ -30,14 +30,6 @@ isdir(outdir) && rm(outdir, recursive = true)
                             0.002062399194485476,
                             0.004897700392503701,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_weakform.jl (SBP)" begin
@@ -57,14 +49,6 @@ end
                             0.013593978324845324,
                             0.03270995869587523,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_weakform.jl (Quadrilateral elements)" begin
@@ -84,14 +68,6 @@ end
                             0.0013568139808290969,
                             0.0032249020004324613,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_weakform.jl (EC) " begin
@@ -112,14 +88,6 @@ end
                             0.01396529873508534,
                             0.04227683691807904,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_weakform.jl (SBP, EC)" begin
@@ -141,14 +109,6 @@ end
                             0.05321027922608157,
                             0.13392025411844033,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_weakform.jl (Quadrilateral elements, SBP, EC)" begin
@@ -171,14 +131,6 @@ end
                             0.012674028479251254,
                             0.02210545278615017,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_bilinear.jl (Bilinear quadrilateral elements, SBP, flux differencing)" begin
@@ -195,14 +147,6 @@ end
                             6.874188052830021e-5,
                             0.0001912435192696904,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_curved.jl (Quadrilateral elements, SBP, flux differencing)" begin
@@ -219,14 +163,6 @@ end
                             0.00010003778085621029,
                             0.00036426282101720275,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_curved.jl (Quadrilateral elements, GaussSBP, flux differencing)" begin
@@ -245,14 +181,6 @@ end
                             3.679582619220412e-5,
                         ],
                         rtol=2 * sqrt(eps()))
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_curved.jl (Triangular elements, Polynomial, weak formulation)" begin
@@ -271,14 +199,6 @@ end
                             4.032272526011127e-5,
                             0.00012013725458537294,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_hohqmesh.jl (Quadrilateral elements, SBP, flux differencing)" begin
@@ -295,14 +215,6 @@ end
                             0.0028721569841545502,
                             0.011125365074589944,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_weakform.jl (convergence)" begin
@@ -316,14 +228,6 @@ end
                        4.128314378397532,
                        4.081366752807379,
                    ], rtol = 0.05)
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_weakform_periodic.jl" begin
@@ -341,14 +245,6 @@ end
                             0.0019373508504538783,
                             0.004742686826709086,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_triangulate_pkg_mesh.jl" begin
@@ -365,14 +261,6 @@ end
                             2.6180448559287584e-5,
                             5.5752932611508044e-5,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_kelvin_helmholtz_instability.jl" begin
@@ -392,14 +280,6 @@ end
                             0.1235468309508845,
                             0.26911424973147735,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_kelvin_helmholtz_instability.jl (Quadrilateral elements, GaussSBP)" begin
@@ -420,14 +300,6 @@ end
                             0.12344140473946856,
                             0.26978428189564774,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_rayleigh_taylor_instability.jl" begin
@@ -446,14 +318,6 @@ end
                             0.040307056293369226,
                             0.0852365428206836,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_brown_minion_vortex.jl" begin
@@ -471,14 +335,6 @@ end
                             0.021957154972646383,
                             0.33773439650806303,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_shockcapturing.jl" begin
@@ -496,14 +352,6 @@ end
                             0.1668441768697189,
                             0.8572572782118661,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_shockcapturing_curved.jl" begin
@@ -521,14 +369,6 @@ end
                             0.16930148707515688,
                             0.8587706761131937,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_weakform.jl (FD SBP)" begin
@@ -555,14 +395,6 @@ end
                             0.0016243096040242655,
                             0.004447503691245913,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_weakform.jl (FD SBP, EC)" begin
@@ -591,14 +423,6 @@ end
                             0.003452046522624652,
                             0.007677153211004928,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_fdsbp_periodic.jl" begin
@@ -615,14 +439,6 @@ end
                             3.9885950273710336e-6,
                             8.848583042286862e-6,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_fdsbp_periodic.jl (arbitrary reference domain)" begin
@@ -640,14 +456,6 @@ end
                             3.988595024928543e-6,
                             8.84858303740188e-6,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_fdsbp_periodic.jl (arbitrary reference and physical domains)" begin
@@ -671,14 +479,6 @@ end
                             0.5244468027020814,
                             1.2210130256735705,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_euler_fdsbp_periodic.jl (CGSEM)" begin
@@ -703,14 +503,6 @@ end
                             5.067812786885284e-5,
                             9.887976803746312e-5,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_mhd_weak_blast_wave.jl (Quad)" begin
@@ -726,14 +518,6 @@ end
                             0.7450328339751362, 0.06357382685763713, 0.0635738268576378,
                             0.1058830287485999,
                             0.005740591170062146])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_mhd_weak_blast_wave.jl (Tri)" begin
@@ -749,14 +533,6 @@ end
                             0.6906308908961734, 0.05349939593012487,
                             0.05349939593013042, 0.08830587480616725,
                             0.0029551359803035027])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_mhd_weak_blast_wave_SBP.jl (Quad)" begin
@@ -825,14 +601,6 @@ end
                             0.0,
                             0.0002992631411931389,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_shallowwater_source_terms.jl (Quad, SBP)" begin
@@ -851,14 +619,6 @@ end
                             0.12088392994348407,
                             9.325873406851315e-15,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_shallowwater_source_terms.jl (Tri, SBP)" begin
@@ -877,14 +637,6 @@ end
                             0.5674183379872275,
                             1.1546319456101628e-14,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_shallowwater_source_terms.jl (Tri, Polynomial)" begin
@@ -905,14 +657,6 @@ end
                             0.06345885709961152,
                             3.3989933098554914e-5,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 
 @trixi_testset "elixir_shallowwater_source_terms.jl (Quad, Polynomial)" begin
@@ -935,16 +679,9 @@ end
                             0.010364675200833062,
                             1.021405182655144e-14,
                         ])
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
 end
 end
+
 # Clean up afterwards: delete Trixi.jl output directory
 @test_nowarn isdir(outdir) && rm(outdir, recursive = true)
 
diff --git a/test/test_p4est_2d.jl b/test/test_p4est_2d.jl
index 546e5bff8a..cf7250b246 100644
--- a/test/test_p4est_2d.jl
+++ b/test/test_p4est_2d.jl
@@ -200,32 +200,6 @@ end
     end
 end
 
-@trixi_testset "elixir_euler_sedov.jl (HLLE)" begin
-    @test_trixi_include(joinpath(EXAMPLES_DIR, "elixir_euler_sedov.jl"),
-                        l2=[
-                            0.411541263324004,
-                            0.2558929632770186,
-                            0.2558929632770193,
-                            1.298715766843915,
-                        ],
-                        linf=[
-                            1.3457201726152221,
-                            1.3138961427140758,
-                            1.313896142714079,
-                            6.293305112638921,
-                        ],
-                        surface_flux=flux_hlle,
-                        tspan=(0.0, 0.3))
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
-end
-
 @trixi_testset "elixir_euler_blast_wave_amr.jl" begin
     @test_trixi_include(joinpath(EXAMPLES_DIR, "elixir_euler_blast_wave_amr.jl"),
                         l2=[
diff --git a/test/test_p4est_3d.jl b/test/test_p4est_3d.jl
index 346c61c744..63077deb43 100644
--- a/test/test_p4est_3d.jl
+++ b/test/test_p4est_3d.jl
@@ -287,34 +287,6 @@ end
     end
 end
 
-@trixi_testset "elixir_euler_sedov.jl (HLLE)" begin
-    @test_trixi_include(joinpath(EXAMPLES_DIR, "elixir_euler_sedov.jl"),
-                        l2=[
-                            0.09946224487902565,
-                            0.04863386374672001,
-                            0.048633863746720116,
-                            0.04863386374672032,
-                            0.3751015774232693,
-                        ],
-                        linf=[
-                            0.789241521871487,
-                            0.42046970270100276,
-                            0.42046970270100276,
-                            0.4204697027010028,
-                            4.730877375538398,
-                        ],
-                        tspan=(0.0, 0.3),
-                        surface_flux=flux_hlle)
-    # Ensure that we do not have excessive memory allocations 
-    # (e.g., from type instabilities) 
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
-end
-
 @trixi_testset "elixir_euler_source_terms_nonconforming_earth.jl" begin
     @test_trixi_include(joinpath(EXAMPLES_DIR,
                                  "elixir_euler_source_terms_nonconforming_earth.jl"),
diff --git a/test/test_tree_1d_euler.jl b/test/test_tree_1d_euler.jl
index 62afc5baee..f01124509c 100644
--- a/test/test_tree_1d_euler.jl
+++ b/test/test_tree_1d_euler.jl
@@ -281,22 +281,6 @@ end
     end
 end
 
-@trixi_testset "elixir_euler_sedov_blast_wave.jl (HLLE)" begin
-    @test_trixi_include(joinpath(EXAMPLES_DIR, "elixir_euler_sedov_blast_wave.jl"),
-                        l2=[0.6442208390304879, 0.508817280068289, 0.9482809853033687],
-                        linf=[3.007059066482486, 2.4678899558345506, 2.3952311739389787],
-                        tspan=(0.0, 0.5),
-                        surface_flux=flux_hlle)
-    # Ensure that we do not have excessive memory allocations
-    # (e.g., from type instabilities)
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
-end
-
 @trixi_testset "elixir_euler_sedov_blast_wave_pure_fv.jl" begin
     @test_trixi_include(joinpath(EXAMPLES_DIR,
                                  "elixir_euler_sedov_blast_wave_pure_fv.jl"),
diff --git a/test/test_tree_2d_euler.jl b/test/test_tree_2d_euler.jl
index db36cb7d79..af7c5d8324 100644
--- a/test/test_tree_2d_euler.jl
+++ b/test/test_tree_2d_euler.jl
@@ -422,32 +422,6 @@ end
     end
 end
 
-@trixi_testset "elixir_euler_sedov_blast_wave.jl (HLLE)" begin
-    @test_trixi_include(joinpath(EXAMPLES_DIR, "elixir_euler_sedov_blast_wave.jl"),
-                        l2=[
-                            0.35267161504176747,
-                            0.17218309138797958,
-                            0.17218307467125854,
-                            0.6236143054619037,
-                        ],
-                        linf=[
-                            2.77484045816607,
-                            1.8281111268370718,
-                            1.8281110470490887,
-                            6.24263735888126,
-                        ],
-                        tspan=(0.0, 0.5),
-                        surface_flux=flux_hlle)
-    # Ensure that we do not have excessive memory allocations
-    # (e.g., from type instabilities)
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
-end
-
 @trixi_testset "elixir_euler_sedov_blast_wave_neuralnetwork_perssonperaire.jl" begin
     @test_trixi_include(joinpath(EXAMPLES_DIR,
                                  "elixir_euler_sedov_blast_wave_neuralnetwork_perssonperaire.jl"),
diff --git a/test/test_tree_3d_euler.jl b/test/test_tree_3d_euler.jl
index 02e657e001..d96dcff397 100644
--- a/test/test_tree_3d_euler.jl
+++ b/test/test_tree_3d_euler.jl
@@ -473,34 +473,6 @@ end
         @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
     end
 end
-
-@trixi_testset "elixir_euler_sedov_blast_wave.jl (HLLE)" begin
-    @test_trixi_include(joinpath(EXAMPLES_DIR, "elixir_euler_sedov_blast_wave.jl"),
-                        l2=[
-                            0.0007871241159752619,
-                            0.0037168004033428146,
-                            0.0037168004033428094,
-                            0.0037168004033428514,
-                            0.011119869089205635,
-                        ],
-                        linf=[
-                            0.13982864363612468,
-                            0.786004687738243,
-                            0.786004687738243,
-                            0.7860046877382431,
-                            1.7082524045150382,
-                        ],
-                        tspan=(0.0, 0.01),
-                        surface_flux=flux_hlle)
-    # Ensure that we do not have excessive memory allocations
-    # (e.g., from type instabilities)
-    let
-        t = sol.t[end]
-        u_ode = sol.u[end]
-        du_ode = similar(u_ode)
-        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
-    end
-end
 end
 
 end # module
diff --git a/test/test_unit.jl b/test/test_unit.jl
index a73dfab550..5422db7a66 100644
--- a/test/test_unit.jl
+++ b/test/test_unit.jl
@@ -911,7 +911,7 @@ end
         SVector(-1.2, 0.3)]
 
     for normal_direction in normal_directions
-        @test flux_hlle(u, u, normal_direction, equations) ≈
+        @test flux_hll(u, u, normal_direction, equations) ≈
               flux(u, normal_direction, equations)
     end
 
@@ -930,15 +930,18 @@ end
         SVector(-1.2, 0.3, 1.4)]
 
     for normal_direction in normal_directions
-        @test flux_hlle(u, u, normal_direction, equations) ≈
+        @test flux_hll(u, u, normal_direction, equations) ≈
               flux(u, normal_direction, equations)
     end
 end
 
 @timed_testset "Consistency check for HLLE flux: SWE" begin
+    # Test HLL flux with min_max_speed_einfeldt
+    flux_hll = FluxHLL(min_max_speed_einfeldt)
+
     equations = ShallowWaterEquations1D(gravity_constant = 9.81)
     u = SVector(1, 0.5, 0.0)
-    @test flux_hlle(u, u, 1, equations) ≈ flux(u, 1, equations)
+    @test flux_hll(u, u, 1, equations) ≈ flux(u, 1, equations)
 
     equations = ShallowWaterEquations2D(gravity_constant = 9.81)
     normal_directions = [SVector(1.0, 0.0),
@@ -950,17 +953,18 @@ end
     u = SVector(1, 0.5, 0.5, 0.0)
 
     for orientation in orientations
-        @test flux_hlle(u, u, orientation, equations) ≈ flux(u, orientation, equations)
+        @test flux_hll(u, u, orientation, equations) ≈ flux(u, orientation, equations)
     end
 
     for normal_direction in normal_directions
-        @test flux_hlle(u, u, normal_direction, equations) ≈
+        @test flux_hll(u, u, normal_direction, equations) ≈
               flux(u, normal_direction, equations)
     end
 end
 
 @timed_testset "Consistency check for HLLE flux: MHD" begin
-    # Note: min_max_speed_naive for MHD is essentially min_max_speed_einfeldt
+    # Test HLL flux with min_max_speed_einfeldt
+    flux_hll = FluxHLL(min_max_speed_naive)
 
     equations = IdealGlmMhdEquations1D(1.4)
     u_values = [SVector(1.0, 0.4, -0.5, 0.1, 1.0, 0.1, -0.2, 0.1),
@@ -1238,7 +1242,7 @@ end
         u = SVector(1, 0.5, 0.5, 0.0)
 
         fluxes = [flux_central, flux_fjordholm_etal, flux_wintermeyer_etal,
-            flux_hll, FluxHLL(min_max_speed_davis), flux_hlle]
+            flux_hll, FluxHLL(min_max_speed_davis), FluxHLL(min_max_speed_einfeldt)]
     end
 
     @timed_testset "IdealGlmMhdEquations2D" begin

From c5b8b2851722bf8ff36bb987b4a262d589ace027 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Thu, 2 Nov 2023 11:10:55 +0200
Subject: [PATCH 06/74] Revert "Revert "Merge branch 'main' into
 semidiscretization-doc""

This reverts commit 85d6e8b50261885ad198ae4036e8599189912e56.
---
 .github/workflows/SpellCheck.yml       |   2 +-
 src/equations/compressible_euler_1d.jl |  36 +---
 src/equations/compressible_euler_2d.jl |  92 ++++++---
 src/equations/compressible_euler_3d.jl | 100 ++++++----
 src/equations/numerical_fluxes.jl      |   8 +
 test/test_dgmulti_2d.jl                | 265 ++++++++++++++++++++++++-
 test/test_p4est_2d.jl                  |  26 +++
 test/test_p4est_3d.jl                  |  28 +++
 test/test_tree_1d_euler.jl             |  16 ++
 test/test_tree_2d_euler.jl             |  26 +++
 test/test_tree_3d_euler.jl             |  28 +++
 test/test_unit.jl                      |  18 +-
 12 files changed, 530 insertions(+), 115 deletions(-)

diff --git a/.github/workflows/SpellCheck.yml b/.github/workflows/SpellCheck.yml
index eae6d8e0be..fb71fe45af 100644
--- a/.github/workflows/SpellCheck.yml
+++ b/.github/workflows/SpellCheck.yml
@@ -10,4 +10,4 @@ jobs:
       - name: Checkout Actions Repository
         uses: actions/checkout@v4
       - name: Check spelling
-        uses: crate-ci/typos@v1.16.15
+        uses: crate-ci/typos@v1.16.21
diff --git a/src/equations/compressible_euler_1d.jl b/src/equations/compressible_euler_1d.jl
index 9204989e8b..05c38ce791 100644
--- a/src/equations/compressible_euler_1d.jl
+++ b/src/equations/compressible_euler_1d.jl
@@ -808,7 +808,7 @@ function flux_hllc(u_ll, u_rr, orientation::Integer,
 end
 
 """
-    flux_hlle(u_ll, u_rr, orientation, equations::CompressibleEulerEquations1D)
+    min_max_speed_einfeldt(u_ll, u_rr, orientation, equations::CompressibleEulerEquations1D)
 
 Computes the HLLE (Harten-Lax-van Leer-Einfeldt) flux for the compressible Euler equations.
 Special estimates of the signal velocites and linearization of the Riemann problem developed
@@ -825,8 +825,8 @@ Compactly summarized:
   Numerical methods for conservation laws and related equations.
   [Link](https://metaphor.ethz.ch/x/2019/hs/401-4671-00L/literature/mishra_hyperbolic_pdes.pdf)
 """
-function flux_hlle(u_ll, u_rr, orientation::Integer,
-                   equations::CompressibleEulerEquations1D)
+@inline function min_max_speed_einfeldt(u_ll, u_rr, orientation::Integer,
+                                        equations::CompressibleEulerEquations1D)
     # Calculate primitive variables, enthalpy and speed of sound
     rho_ll, v_ll, p_ll = cons2prim(u_ll, equations)
     rho_rr, v_rr, p_rr = cons2prim(u_rr, equations)
@@ -858,35 +858,7 @@ function flux_hlle(u_ll, u_rr, orientation::Integer,
     SsL = min(v_roe - c_roe, v_ll - beta * c_ll, zero(v_roe))
     SsR = max(v_roe + c_roe, v_rr + beta * c_rr, zero(v_roe))
 
-    if SsL >= 0.0 && SsR > 0.0
-        # Positive supersonic speed
-        f_ll = flux(u_ll, orientation, equations)
-
-        f1 = f_ll[1]
-        f2 = f_ll[2]
-        f3 = f_ll[3]
-    elseif SsR <= 0.0 && SsL < 0.0
-        # Negative supersonic speed
-        f_rr = flux(u_rr, orientation, equations)
-
-        f1 = f_rr[1]
-        f2 = f_rr[2]
-        f3 = f_rr[3]
-    else
-        # Subsonic case
-        # Compute left and right fluxes
-        f_ll = flux(u_ll, orientation, equations)
-        f_rr = flux(u_rr, orientation, equations)
-
-        f1 = (SsR * f_ll[1] - SsL * f_rr[1] + SsL * SsR * (u_rr[1] - u_ll[1])) /
-             (SsR - SsL)
-        f2 = (SsR * f_ll[2] - SsL * f_rr[2] + SsL * SsR * (u_rr[2] - u_ll[2])) /
-             (SsR - SsL)
-        f3 = (SsR * f_ll[3] - SsL * f_rr[3] + SsL * SsR * (u_rr[3] - u_ll[3])) /
-             (SsR - SsL)
-    end
-
-    return SVector(f1, f2, f3)
+    return SsL, SsR
 end
 
 @inline function max_abs_speeds(u, equations::CompressibleEulerEquations1D)
diff --git a/src/equations/compressible_euler_2d.jl b/src/equations/compressible_euler_2d.jl
index 27b92f4195..6c8f2e1e84 100644
--- a/src/equations/compressible_euler_2d.jl
+++ b/src/equations/compressible_euler_2d.jl
@@ -1253,7 +1253,7 @@ function flux_hllc(u_ll, u_rr, orientation::Integer,
 end
 
 """
-    flux_hlle(u_ll, u_rr, orientation, equations::CompressibleEulerEquations2D)
+    min_max_speed_einfeldt(u_ll, u_rr, orientation, equations::CompressibleEulerEquations2D)
 
 Computes the HLLE (Harten-Lax-van Leer-Einfeldt) flux for the compressible Euler equations.
 Special estimates of the signal velocites and linearization of the Riemann problem developed
@@ -1267,8 +1267,8 @@ of the numerical flux.
   On Godunov-type methods near low densities.
   [DOI: 10.1016/0021-9991(91)90211-3](https://doi.org/10.1016/0021-9991(91)90211-3)
 """
-function flux_hlle(u_ll, u_rr, orientation::Integer,
-                   equations::CompressibleEulerEquations2D)
+@inline function min_max_speed_einfeldt(u_ll, u_rr, orientation::Integer,
+                                        equations::CompressibleEulerEquations2D)
     # Calculate primitive variables, enthalpy and speed of sound
     rho_ll, v1_ll, v2_ll, p_ll = cons2prim(u_ll, equations)
     rho_rr, v1_rr, v2_rr, p_rr = cons2prim(u_rr, equations)
@@ -1306,39 +1306,65 @@ function flux_hlle(u_ll, u_rr, orientation::Integer,
         SsR = max(v2_roe + c_roe, v2_rr + beta * c_rr, zero(v2_roe))
     end
 
-    if SsL >= 0.0 && SsR > 0.0
-        # Positive supersonic speed
-        f_ll = flux(u_ll, orientation, equations)
+    return SsL, SsR
+end
 
-        f1 = f_ll[1]
-        f2 = f_ll[2]
-        f3 = f_ll[3]
-        f4 = f_ll[4]
-    elseif SsR <= 0.0 && SsL < 0.0
-        # Negative supersonic speed
-        f_rr = flux(u_rr, orientation, equations)
+"""
+    min_max_speed_einfeldt(u_ll, u_rr, normal_direction, equations::CompressibleEulerEquations2D)
 
-        f1 = f_rr[1]
-        f2 = f_rr[2]
-        f3 = f_rr[3]
-        f4 = f_rr[4]
-    else
-        # Subsonic case
-        # Compute left and right fluxes
-        f_ll = flux(u_ll, orientation, equations)
-        f_rr = flux(u_rr, orientation, equations)
-
-        f1 = (SsR * f_ll[1] - SsL * f_rr[1] + SsL * SsR * (u_rr[1] - u_ll[1])) /
-             (SsR - SsL)
-        f2 = (SsR * f_ll[2] - SsL * f_rr[2] + SsL * SsR * (u_rr[2] - u_ll[2])) /
-             (SsR - SsL)
-        f3 = (SsR * f_ll[3] - SsL * f_rr[3] + SsL * SsR * (u_rr[3] - u_ll[3])) /
-             (SsR - SsL)
-        f4 = (SsR * f_ll[4] - SsL * f_rr[4] + SsL * SsR * (u_rr[4] - u_ll[4])) /
-             (SsR - SsL)
-    end
+Computes the HLLE (Harten-Lax-van Leer-Einfeldt) flux for the compressible Euler equations.
+Special estimates of the signal velocites and linearization of the Riemann problem developed
+by Einfeldt to ensure that the internal energy and density remain positive during the computation
+of the numerical flux.
 
-    return SVector(f1, f2, f3, f4)
+- Bernd Einfeldt (1988)
+  On Godunov-type methods for gas dynamics.
+  [DOI: 10.1137/0725021](https://doi.org/10.1137/0725021)
+- Bernd Einfeldt, Claus-Dieter Munz, Philip L. Roe and Björn Sjögreen (1991)
+  On Godunov-type methods near low densities.
+  [DOI: 10.1016/0021-9991(91)90211-3](https://doi.org/10.1016/0021-9991(91)90211-3)
+"""
+@inline function min_max_speed_einfeldt(u_ll, u_rr, normal_direction::AbstractVector,
+                                        equations::CompressibleEulerEquations2D)
+    # Calculate primitive variables, enthalpy and speed of sound
+    rho_ll, v1_ll, v2_ll, p_ll = cons2prim(u_ll, equations)
+    rho_rr, v1_rr, v2_rr, p_rr = cons2prim(u_rr, equations)
+
+    v_dot_n_ll = v1_ll * normal_direction[1] + v2_ll * normal_direction[2]
+    v_dot_n_rr = v1_rr * normal_direction[1] + v2_rr * normal_direction[2]
+
+    norm_ = norm(normal_direction)
+
+    # `u_ll[4]` is total energy `rho_e_ll` on the left
+    H_ll = (u_ll[4] + p_ll) / rho_ll
+    c_ll = sqrt(equations.gamma * p_ll / rho_ll) * norm_
+
+    # `u_rr[4]` is total energy `rho_e_rr` on the right
+    H_rr = (u_rr[4] + p_rr) / rho_rr
+    c_rr = sqrt(equations.gamma * p_rr / rho_rr) * norm_
+
+    # Compute Roe averages
+    sqrt_rho_ll = sqrt(rho_ll)
+    sqrt_rho_rr = sqrt(rho_rr)
+    inv_sum_sqrt_rho = inv(sqrt_rho_ll + sqrt_rho_rr)
+
+    v1_roe = (sqrt_rho_ll * v1_ll + sqrt_rho_rr * v1_rr) * inv_sum_sqrt_rho
+    v2_roe = (sqrt_rho_ll * v2_ll + sqrt_rho_rr * v2_rr) * inv_sum_sqrt_rho
+    v_roe = v1_roe * normal_direction[1] + v2_roe * normal_direction[2]
+    v_roe_mag = (v1_roe * normal_direction[1])^2 + (v2_roe * normal_direction[2])^2
+
+    H_roe = (sqrt_rho_ll * H_ll + sqrt_rho_rr * H_rr) * inv_sum_sqrt_rho
+    c_roe = sqrt((equations.gamma - 1) * (H_roe - 0.5 * v_roe_mag)) * norm_
+
+    # Compute convenience constant for positivity preservation, see
+    # https://doi.org/10.1016/0021-9991(91)90211-3
+    beta = sqrt(0.5 * (equations.gamma - 1) / equations.gamma)
+
+    # Estimate the edges of the Riemann fan (with positivity conservation)
+    SsL = min(v_roe - c_roe, v_dot_n_ll - beta * c_ll, zero(v_roe))
+    SsR = max(v_roe + c_roe, v_dot_n_rr + beta * c_rr, zero(v_roe))
+
+    return SsL, SsR
 end
 
 @inline function max_abs_speeds(u, equations::CompressibleEulerEquations2D)
diff --git a/src/equations/compressible_euler_3d.jl b/src/equations/compressible_euler_3d.jl
index 7f25bde31f..fc56f58025 100644
--- a/src/equations/compressible_euler_3d.jl
+++ b/src/equations/compressible_euler_3d.jl
@@ -1322,7 +1322,7 @@ function flux_hllc(u_ll, u_rr, orientation::Integer,
 end
 
 """
-    flux_hlle(u_ll, u_rr, orientation, equations::CompressibleEulerEquations3D)
+    min_max_speed_einfeldt(u_ll, u_rr, orientation, equations::CompressibleEulerEquations3D)
 
 Computes the HLLE (Harten-Lax-van Leer-Einfeldt) flux for the compressible Euler equations.
 Special estimates of the signal velocites and linearization of the Riemann problem developed
@@ -1336,8 +1336,8 @@ of the numerical flux.
   On Godunov-type methods near low densities.
   [DOI: 10.1016/0021-9991(91)90211-3](https://doi.org/10.1016/0021-9991(91)90211-3)
 """
-function flux_hlle(u_ll, u_rr, orientation::Integer,
-                   equations::CompressibleEulerEquations3D)
+@inline function min_max_speed_einfeldt(u_ll, u_rr, orientation::Integer,
+                                        equations::CompressibleEulerEquations3D)
     # Calculate primitive variables, enthalpy and speed of sound
     rho_ll, v1_ll, v2_ll, v3_ll, p_ll = cons2prim(u_ll, equations)
     rho_rr, v1_rr, v2_rr, v3_rr, p_rr = cons2prim(u_rr, equations)
@@ -1379,43 +1379,69 @@ function flux_hlle(u_ll, u_rr, orientation::Integer,
         SsR = max(v3_roe + c_roe, v3_rr + beta * c_rr, zero(v3_roe))
     end
 
-    if SsL >= 0.0 && SsR > 0.0
-        # Positive supersonic speed
-        f_ll = flux(u_ll, orientation, equations)
+    return SsL, SsR
+end
 
-        f1 = f_ll[1]
-        f2 = f_ll[2]
-        f3 = f_ll[3]
-        f4 = f_ll[4]
-        f5 = f_ll[5]
-    elseif SsR <= 0.0 && SsL < 0.0
-        # Negative supersonic speed
-        f_rr = flux(u_rr, orientation, equations)
+"""
+    min_max_speed_einfeldt(u_ll, u_rr, normal_direction, equations::CompressibleEulerEquations3D)
 
-        f1 = f_rr[1]
-        f2 = f_rr[2]
-        f3 = f_rr[3]
-        f4 = f_rr[4]
-        f5 = f_rr[5]
-    else
-        # Subsonic case
-        # Compute left and right fluxes
-        f_ll = flux(u_ll, orientation, equations)
-        f_rr = flux(u_rr, orientation, equations)
-
-        f1 = (SsR * f_ll[1] - SsL * f_rr[1] + SsL * SsR * (u_rr[1] - u_ll[1])) /
-             (SsR - SsL)
-        f2 = (SsR * f_ll[2] - SsL * f_rr[2] + SsL * SsR * (u_rr[2] - u_ll[2])) /
-             (SsR - SsL)
-        f3 = (SsR * f_ll[3] - SsL * f_rr[3] + SsL * SsR * (u_rr[3] - u_ll[3])) /
-             (SsR - SsL)
-        f4 = (SsR * f_ll[4] - SsL * f_rr[4] + SsL * SsR * (u_rr[4] - u_ll[4])) /
-             (SsR - SsL)
-        f5 = (SsR * f_ll[5] - SsL * f_rr[5] + SsL * SsR * (u_rr[5] - u_ll[5])) /
-             (SsR - SsL)
-    end
+Computes the HLLE (Harten-Lax-van Leer-Einfeldt) flux for the compressible Euler equations.
+Special estimates of the signal velocites and linearization of the Riemann problem developed
+by Einfeldt to ensure that the internal energy and density remain positive during the computation
+of the numerical flux.
 
-    return SVector(f1, f2, f3, f4, f5)
+- Bernd Einfeldt (1988)
+  On Godunov-type methods for gas dynamics.
+  [DOI: 10.1137/0725021](https://doi.org/10.1137/0725021)
+- Bernd Einfeldt, Claus-Dieter Munz, Philip L. Roe and Björn Sjögreen (1991)
+  On Godunov-type methods near low densities.
+  [DOI: 10.1016/0021-9991(91)90211-3](https://doi.org/10.1016/0021-9991(91)90211-3)
+"""
+@inline function min_max_speed_einfeldt(u_ll, u_rr, normal_direction::AbstractVector,
+                                        equations::CompressibleEulerEquations3D)
+    # Calculate primitive variables, enthalpy and speed of sound
+    rho_ll, v1_ll, v2_ll, v3_ll, p_ll = cons2prim(u_ll, equations)
+    rho_rr, v1_rr, v2_rr, v3_rr, p_rr = cons2prim(u_rr, equations)
+
+    v_dot_n_ll = v1_ll * normal_direction[1] + v2_ll * normal_direction[2] +
+                 v3_ll * normal_direction[3]
+    v_dot_n_rr = v1_rr * normal_direction[1] + v2_rr * normal_direction[2] +
+                 v3_rr * normal_direction[3]
+
+    norm_ = norm(normal_direction)
+
+    # `u_ll[5]` is total energy `rho_e_ll` on the left
+    H_ll = (u_ll[5] + p_ll) / rho_ll
+    c_ll = sqrt(equations.gamma * p_ll / rho_ll) * norm_
+
+    # `u_rr[5]` is total energy `rho_e_rr` on the right
+    H_rr = (u_rr[5] + p_rr) / rho_rr
+    c_rr = sqrt(equations.gamma * p_rr / rho_rr) * norm_
+
+    # Compute Roe averages
+    sqrt_rho_ll = sqrt(rho_ll)
+    sqrt_rho_rr = sqrt(rho_rr)
+    inv_sum_sqrt_rho = inv(sqrt_rho_ll + sqrt_rho_rr)
+
+    v1_roe = (sqrt_rho_ll * v1_ll + sqrt_rho_rr * v1_rr) * inv_sum_sqrt_rho
+    v2_roe = (sqrt_rho_ll * v2_ll + sqrt_rho_rr * v2_rr) * inv_sum_sqrt_rho
+    v3_roe = (sqrt_rho_ll * v3_ll + sqrt_rho_rr * v3_rr) * inv_sum_sqrt_rho
+    v_roe = v1_roe * normal_direction[1] + v2_roe * normal_direction[2] +
+            v3_roe * normal_direction[3]
+    v_roe_mag = v1_roe^2 + v2_roe^2 + v3_roe^2
+
+    H_roe = (sqrt_rho_ll * H_ll + sqrt_rho_rr * H_rr) * inv_sum_sqrt_rho
+    c_roe = sqrt((equations.gamma - 1) * (H_roe - 0.5 * v_roe_mag)) * norm_
+
+    # Compute convenience constant for positivity preservation, see
+    # https://doi.org/10.1016/0021-9991(91)90211-3
+    beta = sqrt(0.5 * (equations.gamma - 1) / equations.gamma)
+
+    # Estimate the edges of the Riemann fan (with positivity conservation)
+    SsL = min(v_roe - c_roe, v_dot_n_ll - beta * c_ll, zero(v_roe))
+    SsR = max(v_roe + c_roe, v_dot_n_rr + beta * c_rr, zero(v_roe))
+
+    return SsL, SsR
 end
 
 @inline function max_abs_speeds(u, equations::CompressibleEulerEquations3D)
diff --git a/src/equations/numerical_fluxes.jl b/src/equations/numerical_fluxes.jl
index 87010275f2..71782644b1 100644
--- a/src/equations/numerical_fluxes.jl
+++ b/src/equations/numerical_fluxes.jl
@@ -304,6 +304,14 @@ See [`FluxHLL`](@ref).
 """
 const flux_hll = FluxHLL()
 
+"""
+    flux_hlle
+
+See [`min_max_speed_einfeldt`](@ref).
+This is a [`FluxHLL`](@ref)-type two-wave solver with special estimates of the wave speeds.
+"""
+const flux_hlle = FluxHLL(min_max_speed_einfeldt)
+
 # TODO: TrixiShallowWater: move the chen_noelle flux structure to the new package
 
 # An empty version of the `min_max_speed_chen_noelle` function is declared here
diff --git a/test/test_dgmulti_2d.jl b/test/test_dgmulti_2d.jl
index 8fd00df72e..892c8ed37f 100644
--- a/test/test_dgmulti_2d.jl
+++ b/test/test_dgmulti_2d.jl
@@ -30,6 +30,14 @@ isdir(outdir) && rm(outdir, recursive = true)
                             0.002062399194485476,
                             0.004897700392503701,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_weakform.jl (SBP)" begin
@@ -49,6 +57,14 @@ end
                             0.013593978324845324,
                             0.03270995869587523,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_weakform.jl (Quadrilateral elements)" begin
@@ -68,6 +84,14 @@ end
                             0.0013568139808290969,
                             0.0032249020004324613,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_weakform.jl (EC) " begin
@@ -88,6 +112,14 @@ end
                             0.01396529873508534,
                             0.04227683691807904,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_weakform.jl (SBP, EC)" begin
@@ -109,6 +141,14 @@ end
                             0.05321027922608157,
                             0.13392025411844033,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_weakform.jl (Quadrilateral elements, SBP, EC)" begin
@@ -131,6 +171,14 @@ end
                             0.012674028479251254,
                             0.02210545278615017,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_bilinear.jl (Bilinear quadrilateral elements, SBP, flux differencing)" begin
@@ -147,6 +195,14 @@ end
                             6.874188052830021e-5,
                             0.0001912435192696904,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_curved.jl (Quadrilateral elements, SBP, flux differencing)" begin
@@ -163,6 +219,14 @@ end
                             0.00010003778085621029,
                             0.00036426282101720275,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_curved.jl (Quadrilateral elements, GaussSBP, flux differencing)" begin
@@ -181,6 +245,14 @@ end
                             3.679582619220412e-5,
                         ],
                         rtol=2 * sqrt(eps()))
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_curved.jl (Triangular elements, Polynomial, weak formulation)" begin
@@ -199,6 +271,14 @@ end
                             4.032272526011127e-5,
                             0.00012013725458537294,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_hohqmesh.jl (Quadrilateral elements, SBP, flux differencing)" begin
@@ -215,6 +295,14 @@ end
                             0.0028721569841545502,
                             0.011125365074589944,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_weakform.jl (convergence)" begin
@@ -228,6 +316,14 @@ end
                        4.128314378397532,
                        4.081366752807379,
                    ], rtol = 0.05)
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_weakform_periodic.jl" begin
@@ -245,6 +341,14 @@ end
                             0.0019373508504538783,
                             0.004742686826709086,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_triangulate_pkg_mesh.jl" begin
@@ -261,6 +365,14 @@ end
                             2.6180448559287584e-5,
                             5.5752932611508044e-5,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_kelvin_helmholtz_instability.jl" begin
@@ -280,6 +392,14 @@ end
                             0.1235468309508845,
                             0.26911424973147735,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_kelvin_helmholtz_instability.jl (Quadrilateral elements, GaussSBP)" begin
@@ -300,6 +420,14 @@ end
                             0.12344140473946856,
                             0.26978428189564774,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_rayleigh_taylor_instability.jl" begin
@@ -318,6 +446,14 @@ end
                             0.040307056293369226,
                             0.0852365428206836,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_brown_minion_vortex.jl" begin
@@ -335,6 +471,14 @@ end
                             0.021957154972646383,
                             0.33773439650806303,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_shockcapturing.jl" begin
@@ -352,6 +496,14 @@ end
                             0.1668441768697189,
                             0.8572572782118661,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_shockcapturing_curved.jl" begin
@@ -369,6 +521,14 @@ end
                             0.16930148707515688,
                             0.8587706761131937,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_weakform.jl (FD SBP)" begin
@@ -395,6 +555,14 @@ end
                             0.0016243096040242655,
                             0.004447503691245913,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_weakform.jl (FD SBP, EC)" begin
@@ -423,6 +591,14 @@ end
                             0.003452046522624652,
                             0.007677153211004928,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_fdsbp_periodic.jl" begin
@@ -439,6 +615,14 @@ end
                             3.9885950273710336e-6,
                             8.848583042286862e-6,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_fdsbp_periodic.jl (arbitrary reference domain)" begin
@@ -456,6 +640,14 @@ end
                             3.988595024928543e-6,
                             8.84858303740188e-6,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_fdsbp_periodic.jl (arbitrary reference and physical domains)" begin
@@ -479,6 +671,14 @@ end
                             0.5244468027020814,
                             1.2210130256735705,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_euler_fdsbp_periodic.jl (CGSEM)" begin
@@ -503,6 +703,14 @@ end
                             5.067812786885284e-5,
                             9.887976803746312e-5,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_mhd_weak_blast_wave.jl (Quad)" begin
@@ -518,6 +726,14 @@ end
                             0.7450328339751362, 0.06357382685763713, 0.0635738268576378,
                             0.1058830287485999,
                             0.005740591170062146])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_mhd_weak_blast_wave.jl (Tri)" begin
@@ -533,6 +749,14 @@ end
                             0.6906308908961734, 0.05349939593012487,
                             0.05349939593013042, 0.08830587480616725,
                             0.0029551359803035027])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_mhd_weak_blast_wave_SBP.jl (Quad)" begin
@@ -601,6 +825,14 @@ end
                             0.0,
                             0.0002992631411931389,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_shallowwater_source_terms.jl (Quad, SBP)" begin
@@ -619,6 +851,14 @@ end
                             0.12088392994348407,
                             9.325873406851315e-15,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_shallowwater_source_terms.jl (Tri, SBP)" begin
@@ -637,6 +877,14 @@ end
                             0.5674183379872275,
                             1.1546319456101628e-14,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_shallowwater_source_terms.jl (Tri, Polynomial)" begin
@@ -657,6 +905,14 @@ end
                             0.06345885709961152,
                             3.3989933098554914e-5,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 
 @trixi_testset "elixir_shallowwater_source_terms.jl (Quad, Polynomial)" begin
@@ -679,9 +935,16 @@ end
                             0.010364675200833062,
                             1.021405182655144e-14,
                         ])
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
 end
 end
-
 # Clean up afterwards: delete Trixi.jl output directory
 @test_nowarn isdir(outdir) && rm(outdir, recursive = true)
 
diff --git a/test/test_p4est_2d.jl b/test/test_p4est_2d.jl
index cf7250b246..546e5bff8a 100644
--- a/test/test_p4est_2d.jl
+++ b/test/test_p4est_2d.jl
@@ -200,6 +200,32 @@ end
     end
 end
 
+@trixi_testset "elixir_euler_sedov.jl (HLLE)" begin
+    @test_trixi_include(joinpath(EXAMPLES_DIR, "elixir_euler_sedov.jl"),
+                        l2=[
+                            0.411541263324004,
+                            0.2558929632770186,
+                            0.2558929632770193,
+                            1.298715766843915,
+                        ],
+                        linf=[
+                            1.3457201726152221,
+                            1.3138961427140758,
+                            1.313896142714079,
+                            6.293305112638921,
+                        ],
+                        surface_flux=flux_hlle,
+                        tspan=(0.0, 0.3))
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
+end
+
 @trixi_testset "elixir_euler_blast_wave_amr.jl" begin
     @test_trixi_include(joinpath(EXAMPLES_DIR, "elixir_euler_blast_wave_amr.jl"),
                         l2=[
diff --git a/test/test_p4est_3d.jl b/test/test_p4est_3d.jl
index 63077deb43..346c61c744 100644
--- a/test/test_p4est_3d.jl
+++ b/test/test_p4est_3d.jl
@@ -287,6 +287,34 @@ end
     end
 end
 
+@trixi_testset "elixir_euler_sedov.jl (HLLE)" begin
+    @test_trixi_include(joinpath(EXAMPLES_DIR, "elixir_euler_sedov.jl"),
+                        l2=[
+                            0.09946224487902565,
+                            0.04863386374672001,
+                            0.048633863746720116,
+                            0.04863386374672032,
+                            0.3751015774232693,
+                        ],
+                        linf=[
+                            0.789241521871487,
+                            0.42046970270100276,
+                            0.42046970270100276,
+                            0.4204697027010028,
+                            4.730877375538398,
+                        ],
+                        tspan=(0.0, 0.3),
+                        surface_flux=flux_hlle)
+    # Ensure that we do not have excessive memory allocations 
+    # (e.g., from type instabilities) 
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
+end
+
 @trixi_testset "elixir_euler_source_terms_nonconforming_earth.jl" begin
     @test_trixi_include(joinpath(EXAMPLES_DIR,
                                  "elixir_euler_source_terms_nonconforming_earth.jl"),
diff --git a/test/test_tree_1d_euler.jl b/test/test_tree_1d_euler.jl
index f01124509c..62afc5baee 100644
--- a/test/test_tree_1d_euler.jl
+++ b/test/test_tree_1d_euler.jl
@@ -281,6 +281,22 @@ end
     end
 end
 
+@trixi_testset "elixir_euler_sedov_blast_wave.jl (HLLE)" begin
+    @test_trixi_include(joinpath(EXAMPLES_DIR, "elixir_euler_sedov_blast_wave.jl"),
+                        l2=[0.6442208390304879, 0.508817280068289, 0.9482809853033687],
+                        linf=[3.007059066482486, 2.4678899558345506, 2.3952311739389787],
+                        tspan=(0.0, 0.5),
+                        surface_flux=flux_hlle)
+    # Ensure that we do not have excessive memory allocations
+    # (e.g., from type instabilities)
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
+end
+
 @trixi_testset "elixir_euler_sedov_blast_wave_pure_fv.jl" begin
     @test_trixi_include(joinpath(EXAMPLES_DIR,
                                  "elixir_euler_sedov_blast_wave_pure_fv.jl"),
diff --git a/test/test_tree_2d_euler.jl b/test/test_tree_2d_euler.jl
index af7c5d8324..db36cb7d79 100644
--- a/test/test_tree_2d_euler.jl
+++ b/test/test_tree_2d_euler.jl
@@ -422,6 +422,32 @@ end
     end
 end
 
+@trixi_testset "elixir_euler_sedov_blast_wave.jl (HLLE)" begin
+    @test_trixi_include(joinpath(EXAMPLES_DIR, "elixir_euler_sedov_blast_wave.jl"),
+                        l2=[
+                            0.35267161504176747,
+                            0.17218309138797958,
+                            0.17218307467125854,
+                            0.6236143054619037,
+                        ],
+                        linf=[
+                            2.77484045816607,
+                            1.8281111268370718,
+                            1.8281110470490887,
+                            6.24263735888126,
+                        ],
+                        tspan=(0.0, 0.5),
+                        surface_flux=flux_hlle)
+    # Ensure that we do not have excessive memory allocations
+    # (e.g., from type instabilities)
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
+end
+
 @trixi_testset "elixir_euler_sedov_blast_wave_neuralnetwork_perssonperaire.jl" begin
     @test_trixi_include(joinpath(EXAMPLES_DIR,
                                  "elixir_euler_sedov_blast_wave_neuralnetwork_perssonperaire.jl"),
diff --git a/test/test_tree_3d_euler.jl b/test/test_tree_3d_euler.jl
index d96dcff397..02e657e001 100644
--- a/test/test_tree_3d_euler.jl
+++ b/test/test_tree_3d_euler.jl
@@ -473,6 +473,34 @@ end
         @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
     end
 end
+
+@trixi_testset "elixir_euler_sedov_blast_wave.jl (HLLE)" begin
+    @test_trixi_include(joinpath(EXAMPLES_DIR, "elixir_euler_sedov_blast_wave.jl"),
+                        l2=[
+                            0.0007871241159752619,
+                            0.0037168004033428146,
+                            0.0037168004033428094,
+                            0.0037168004033428514,
+                            0.011119869089205635,
+                        ],
+                        linf=[
+                            0.13982864363612468,
+                            0.786004687738243,
+                            0.786004687738243,
+                            0.7860046877382431,
+                            1.7082524045150382,
+                        ],
+                        tspan=(0.0, 0.01),
+                        surface_flux=flux_hlle)
+    # Ensure that we do not have excessive memory allocations
+    # (e.g., from type instabilities)
+    let
+        t = sol.t[end]
+        u_ode = sol.u[end]
+        du_ode = similar(u_ode)
+        @test (@allocated Trixi.rhs!(du_ode, u_ode, semi, t)) < 1000
+    end
+end
 end
 
 end # module
diff --git a/test/test_unit.jl b/test/test_unit.jl
index 5422db7a66..a73dfab550 100644
--- a/test/test_unit.jl
+++ b/test/test_unit.jl
@@ -911,7 +911,7 @@ end
         SVector(-1.2, 0.3)]
 
     for normal_direction in normal_directions
-        @test flux_hll(u, u, normal_direction, equations) ≈
+        @test flux_hlle(u, u, normal_direction, equations) ≈
               flux(u, normal_direction, equations)
     end
 
@@ -930,18 +930,15 @@ end
         SVector(-1.2, 0.3, 1.4)]
 
     for normal_direction in normal_directions
-        @test flux_hll(u, u, normal_direction, equations) ≈
+        @test flux_hlle(u, u, normal_direction, equations) ≈
               flux(u, normal_direction, equations)
     end
 end
 
 @timed_testset "Consistency check for HLLE flux: SWE" begin
-    # Test HLL flux with min_max_speed_einfeldt
-    flux_hll = FluxHLL(min_max_speed_einfeldt)
-
     equations = ShallowWaterEquations1D(gravity_constant = 9.81)
     u = SVector(1, 0.5, 0.0)
-    @test flux_hll(u, u, 1, equations) ≈ flux(u, 1, equations)
+    @test flux_hlle(u, u, 1, equations) ≈ flux(u, 1, equations)
 
     equations = ShallowWaterEquations2D(gravity_constant = 9.81)
     normal_directions = [SVector(1.0, 0.0),
@@ -953,18 +950,17 @@ end
     u = SVector(1, 0.5, 0.5, 0.0)
 
     for orientation in orientations
-        @test flux_hll(u, u, orientation, equations) ≈ flux(u, orientation, equations)
+        @test flux_hlle(u, u, orientation, equations) ≈ flux(u, orientation, equations)
     end
 
     for normal_direction in normal_directions
-        @test flux_hll(u, u, normal_direction, equations) ≈
+        @test flux_hlle(u, u, normal_direction, equations) ≈
               flux(u, normal_direction, equations)
     end
 end
 
 @timed_testset "Consistency check for HLLE flux: MHD" begin
-    # Test HLL flux with min_max_speed_einfeldt
-    flux_hll = FluxHLL(min_max_speed_naive)
+    # Note: min_max_speed_naive for MHD is essentially min_max_speed_einfeldt
 
     equations = IdealGlmMhdEquations1D(1.4)
     u_values = [SVector(1.0, 0.4, -0.5, 0.1, 1.0, 0.1, -0.2, 0.1),
@@ -1242,7 +1238,7 @@ end
         u = SVector(1, 0.5, 0.5, 0.0)
 
         fluxes = [flux_central, flux_fjordholm_etal, flux_wintermeyer_etal,
-            flux_hll, FluxHLL(min_max_speed_davis), FluxHLL(min_max_speed_einfeldt)]
+            flux_hll, FluxHLL(min_max_speed_davis), flux_hlle]
     end
 
     @timed_testset "IdealGlmMhdEquations2D" begin

From df646994ac074a02e553b3355bb0cdd0845e7e9c Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:18:01 +0200
Subject: [PATCH 07/74] Update
 docs/literate/src/files/innards_of_the_basic_setup.jl

Co-authored-by: Michael Schlottke-Lakemper <michael@sloede.com>
---
 docs/literate/src/files/innards_of_the_basic_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
index 9d9d5fb90b..16a1bf7cc6 100644
--- a/docs/literate/src/files/innards_of_the_basic_setup.jl
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -15,7 +15,7 @@
 # Import essential libraries and specify an equation.
 
 using Trixi, OrdinaryDiffEq
-equations=LinearScalarAdvectionEquation2D((-0.2,0.7))
+equations = inearScalarAdvectionEquation2D((-0.2, 0.7))
 
 # Generate a geometrical instruction for spatial discretization using [`TreeMesh`](@ref) with
 # pre-coarsened cell.

From 39a9d78fa541104e12de54ce955e95bf01fb7f35 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:18:15 +0200
Subject: [PATCH 08/74] Update
 docs/literate/src/files/innards_of_the_basic_setup.jl

Co-authored-by: Michael Schlottke-Lakemper <michael@sloede.com>
---
 docs/literate/src/files/innards_of_the_basic_setup.jl | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
index 16a1bf7cc6..798b7d9c58 100644
--- a/docs/literate/src/files/innards_of_the_basic_setup.jl
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -17,8 +17,7 @@
 using Trixi, OrdinaryDiffEq
 equations = inearScalarAdvectionEquation2D((-0.2, 0.7))
 
-# Generate a geometrical instruction for spatial discretization using [`TreeMesh`](@ref) with
-# pre-coarsened cell.
+# Generate a spatial discretization using a [`TreeMesh`](@ref) with a pre-coarsened set of cells.
 
 coordinates_min = (-2.0, -2.0)
 coordinates_max = (2.0, 2.0)

From 26153db57f9fd293b532f38af6eba4b043a4272d Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:18:30 +0200
Subject: [PATCH 09/74] Update
 docs/literate/src/files/innards_of_the_basic_setup.jl

Co-authored-by: Michael Schlottke-Lakemper <michael@sloede.com>
---
 docs/literate/src/files/innards_of_the_basic_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
index 798b7d9c58..72863d1f7b 100644
--- a/docs/literate/src/files/innards_of_the_basic_setup.jl
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -23,7 +23,7 @@ coordinates_min = (-2.0, -2.0)
 coordinates_max = (2.0, 2.0)
 
 coarsening_patches = ( # Coarsen cell in the lower-right quarter
-  (type="box", coordinates_min=[0.0, -2.0], coordinates_max=[2.0, 0.0]), 
+  (type = "box", coordinates_min = [0.0, -2.0], coordinates_max = [2.0, 0.0]), 
 )
 
  mesh = TreeMesh(coordinates_min, coordinates_max, initial_refinement_level=2, 

From 35a61d3a1ebc22ff0a33322cbe2858f4b9321f93 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:18:41 +0200
Subject: [PATCH 10/74] Update
 docs/literate/src/files/innards_of_the_basic_setup.jl

Co-authored-by: Michael Schlottke-Lakemper <michael@sloede.com>
---
 docs/literate/src/files/innards_of_the_basic_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
index 72863d1f7b..0a6b8bbd11 100644
--- a/docs/literate/src/files/innards_of_the_basic_setup.jl
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -30,7 +30,7 @@ coarsening_patches = ( # Coarsen cell in the lower-right quarter
                  n_cells_max=30_000,
                  coarsening_patches=coarsening_patches)
 
-# Created `TreeMesh` looks like:
+# The created `TreeMesh` looks like the following:
 
 # ![TreeMesh_example](https://github.com/trixi-framework/Trixi.jl/assets/119304909/d5ef76ee-8246-4730-a692-b472c06063a3)
 

From e6871724603316b84fad0840d6cdbc52e3b40a25 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:19:20 +0200
Subject: [PATCH 11/74] Update
 docs/literate/src/files/innards_of_the_basic_setup.jl

Co-authored-by: Michael Schlottke-Lakemper <michael@sloede.com>
---
 docs/literate/src/files/innards_of_the_basic_setup.jl | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
index 0a6b8bbd11..f9ac493211 100644
--- a/docs/literate/src/files/innards_of_the_basic_setup.jl
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -34,9 +34,9 @@ coarsening_patches = ( # Coarsen cell in the lower-right quarter
 
 # ![TreeMesh_example](https://github.com/trixi-framework/Trixi.jl/assets/119304909/d5ef76ee-8246-4730-a692-b472c06063a3)
 
-# Instantiate a [`DGSEM`](@ref) solver with a user-specified polynomial degree. The solver's
-# objective is to define the `polydeg + 1` Gauss-Lobatto nodes, and their associated weights within
-# the reference interval [-1, 1]. These nodes will be subsequently used to approximate solutions
+# Instantiate a [`DGSEM`](@ref) solver with a user-specified polynomial degree. The solver
+# will define `polydeg + 1` Gauss-Lobatto nodes and their associated weights within
+# the reference interval ``[-1, 1]`` in each spatial direction. These nodes will be subsequently used to approximate solutions
 # on each leaf cell of the `TreeMesh`.
 
 solver = DGSEM(polydeg=3)

From 740fbbbd29ae820b38a0a4742c6066eedf3aa7d1 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:19:38 +0200
Subject: [PATCH 12/74] Update
 docs/literate/src/files/innards_of_the_basic_setup.jl

Co-authored-by: Michael Schlottke-Lakemper <michael@sloede.com>
---
 docs/literate/src/files/innards_of_the_basic_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
index f9ac493211..a40ca6bfe8 100644
--- a/docs/literate/src/files/innards_of_the_basic_setup.jl
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -46,7 +46,7 @@ solver = DGSEM(polydeg=3)
 # ![Gauss-Lobatto_nodes_example](https://github.com/trixi-framework/Trixi.jl/assets/119304909/401e5e85-026e-48b6-8a1f-dca0306f3bb0)
 
 
-# ## Overview of the [`SemidiscretizationHyperbolic`](@ref) function
+# ## Overview of the [`SemidiscretizationHyperbolic`](@ref) type
 
 # At this stage, all the necessary components for configuring domain discretization are in place.
 # The remaining task is to combine these components into a single structure that will be used

From 4594ff8a79c972992b565761760eabfae51d2d4a Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:20:07 +0200
Subject: [PATCH 13/74] Update
 docs/literate/src/files/innards_of_the_basic_setup.jl

Co-authored-by: Michael Schlottke-Lakemper <michael@sloede.com>
---
 docs/literate/src/files/innards_of_the_basic_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
index a40ca6bfe8..8796dbb9c5 100644
--- a/docs/literate/src/files/innards_of_the_basic_setup.jl
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -48,7 +48,7 @@ solver = DGSEM(polydeg=3)
 
 # ## Overview of the [`SemidiscretizationHyperbolic`](@ref) type
 
-# At this stage, all the necessary components for configuring domain discretization are in place.
+# At this stage, all necessary components for configuring the spatial discretization are in place.
 # The remaining task is to combine these components into a single structure that will be used
 # throughout the entire solving process. This is where [`SemidiscretizationHyperbolic`](@ref) comes
 # into play.

From d444631ba060ee770011d8f6960a480b630153ad Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:20:25 +0200
Subject: [PATCH 14/74] Update
 docs/literate/src/files/innards_of_the_basic_setup.jl

Co-authored-by: Michael Schlottke-Lakemper <michael@sloede.com>
---
 docs/literate/src/files/innards_of_the_basic_setup.jl | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
index 8796dbb9c5..1b85138b15 100644
--- a/docs/literate/src/files/innards_of_the_basic_setup.jl
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -55,8 +55,8 @@ solver = DGSEM(polydeg=3)
 
 semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergence_test, solver)
 
-# The `SemidiscretizationHyperbolic` function calls numerous sub-functions to perform the necessary
-# steps. A brief description of the key sub-functions is provided below.
+# The constructor for the `SemidiscretizationHyperbolic` object calls numerous sub-functions to perform the necessary
+# initialization steps. A brief description of the key sub-functions is provided below.
 
 # - `init_elements(leaf_cell_ids, mesh, equations, dg.basis, RealT, uEltype)`
  

From 3d7b59c928c5461558475a04c3eedbfbb6d63ab6 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:21:29 +0200
Subject: [PATCH 15/74] Update
 docs/literate/src/files/innards_of_the_basic_setup.jl

Co-authored-by: Michael Schlottke-Lakemper <michael@sloede.com>
---
 .../literate/src/files/innards_of_the_basic_setup.jl | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
index 1b85138b15..2b5cc49d27 100644
--- a/docs/literate/src/files/innards_of_the_basic_setup.jl
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -60,17 +60,17 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 
 # - `init_elements(leaf_cell_ids, mesh, equations, dg.basis, RealT, uEltype)`
  
-#   As was already mentioned, the fundamental elements for approximating a solution are the leaf
-#   cells. This implies that on each leaf cell, the solution is treated as a polynomial of the
+#   The fundamental elements for approximating a solution are the leaf
+#   cells. This implies that on each leaf cell and in each spatial direction, the solution is treated as a polynomial of the
 #   degree specified in the `DGSEM` solver and evaluated at the Gauss-Lobatto nodes, which were
-#   previously illustrated. To provide this, the `init_elements` function extracts these leaf cells
+#   previously illustrated. The `init_elements` function extracts these leaf cells
 #   from the `TreeMesh`, assigns them the label "elements", records their coordinates, and maps the
-#   Gauss-Lobatto nodes from the 1D interval [-1, 1] onto each axis of every element.
+#   Gauss-Lobatto nodes from the 1D interval ``[-1, 1]`` onto each axis of every element.
 
 #   ![elements_example](https://github.com/trixi-framework/Trixi.jl/assets/119304909/534131bd-e85b-43d5-860d-2db6e60ce921)
 
-#   The visualization of elements with nodes includes spaces between elements, which do not exist
-#   in  reality. This spacing is included only for illustrative purposes to underscore the
+#   The visualization of elements with nodes shown here includes spaces between elements, which do not exist
+#   in reality. This spacing is included only for illustrative purposes to underscore the
 #   separation of elements and the independent projection of nodes onto each element.
 
 # - `init_interfaces(leaf_cell_ids, mesh, elements)`

From 497118b512dfaa0d550a3203b91159a64ef75bcb Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:22:10 +0200
Subject: [PATCH 16/74] Update
 docs/literate/src/files/innards_of_the_basic_setup.jl

Co-authored-by: Michael Schlottke-Lakemper <michael@sloede.com>
---
 docs/literate/src/files/innards_of_the_basic_setup.jl | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
index 2b5cc49d27..bff2cf8c25 100644
--- a/docs/literate/src/files/innards_of_the_basic_setup.jl
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -93,10 +93,11 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 # - `init_mortars(leaf_cell_ids, mesh, elements, dg.mortar)`
 
 #   Returning to the consideration of different sizes among adjacent elements, within the
-#   `TreeMesh`, adjacent leaf cells can vary in size by a maximum factor of two. This implies
-#   that a coarsened element on each side, excluding the domain boundaries, has one neighbor of
-#   equal size with a connection through an interface, or two neighbors with sizes two times
-#   smaller, requiring a connection through so called "mortars".
+#   `TreeMesh`, adjacent leaf cells can vary in side length by a maximum factor of two. This implies
+#   that a large element has one neighbor of
+#   equal size with a connection through an interface, or two neighbors at half the size,
+#   requiring a connection through so called "mortars". In 3D, a large element would have
+#   four small neighbor elements.
 
 #   Mortars store information about the connected elements, their relative positions, and allocate
 #   containers for sharing solutions between these elements along their boundaries.

From dd9ab8582dd7810d1e74a5d96f8a611021ffb1ce Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:22:35 +0200
Subject: [PATCH 17/74] Update
 docs/literate/src/files/innards_of_the_basic_setup.jl

Co-authored-by: Michael Schlottke-Lakemper <michael@sloede.com>
---
 docs/literate/src/files/innards_of_the_basic_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
index bff2cf8c25..562aa197f1 100644
--- a/docs/literate/src/files/innards_of_the_basic_setup.jl
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -100,7 +100,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 #   four small neighbor elements.
 
 #   Mortars store information about the connected elements, their relative positions, and allocate
-#   containers for sharing solutions between these elements along their boundaries.
+#   containers for storing the solutions along the boundaries between these elements.
 
 #   In our visualization, mortars are represented as branched tubes.
 

From 96176b13f702658c50705f4ff5cc12904c6c4ca5 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:23:25 +0200
Subject: [PATCH 18/74] Update
 docs/literate/src/files/innards_of_the_basic_setup.jl

Co-authored-by: Michael Schlottke-Lakemper <michael@sloede.com>
---
 docs/literate/src/files/innards_of_the_basic_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
index 562aa197f1..0ed90ed1aa 100644
--- a/docs/literate/src/files/innards_of_the_basic_setup.jl
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -118,7 +118,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 
 #   ![boundaries_example](https://github.com/trixi-framework/Trixi.jl/assets/119304909/21996b20-4a22-4dfb-b16a-e2c22c2f29fe)
 
-# All the structures mentioned earlier are packed as a cache of type `Tuple`. Subsequently, an
+# All the structures mentioned earlier are collected as a cache of type `NamedTuple`. Subsequently, an
 # object of type `SemidiscretizationHyperbolic` is initialized using this cache, initial and
 # boundary conditions, equations, mesh and solver.
 

From e8747699a20437370bc62870dd97ee20e0d7ac39 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:23:43 +0200
Subject: [PATCH 19/74] Update
 docs/literate/src/files/innards_of_the_basic_setup.jl

Co-authored-by: Michael Schlottke-Lakemper <michael@sloede.com>
---
 docs/literate/src/files/innards_of_the_basic_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
index 0ed90ed1aa..04fa9672bc 100644
--- a/docs/literate/src/files/innards_of_the_basic_setup.jl
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -122,7 +122,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 # object of type `SemidiscretizationHyperbolic` is initialized using this cache, initial and
 # boundary conditions, equations, mesh and solver.
 
-# In conclusion, `Semidiscretization`'s primary function is to collect equations, the geometric
+# In conclusion, a `HyperbolicSemidiscretization`'s primary purpose is to collect equations, the geometric
 # representation of the domain, and approximation instructions, creating specialized structures to
 # interconnect these components in a manner that enables their utilization for the numerical
 # solution of partial differential equations (PDEs).

From 0179cf31c53d61b78981664de32d9b842ef098c4 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:24:13 +0200
Subject: [PATCH 20/74] Update
 docs/literate/src/files/innards_of_the_basic_setup.jl

Co-authored-by: Michael Schlottke-Lakemper <michael@sloede.com>
---
 docs/literate/src/files/innards_of_the_basic_setup.jl | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
index 04fa9672bc..609de41746 100644
--- a/docs/literate/src/files/innards_of_the_basic_setup.jl
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -140,10 +140,10 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 # final step before solving is to select a suitable time span and apply the corresponding initial
 # conditions, which are already stored in the initialized `SemidiscretizationHyperbolic` object.
 
-# The purpose of the [`semidiscretize`](@ref) function is to wrap the semi-discretization as an
+# The purpose of the [`semidiscretize`](@ref) function is to wrap the semidiscretization as an
 # `ODEProblem` within the specified time interval, while also applying the initial conditions at
-# the left boundary of this interval. This `ODEProblem` can be subsequently passed to the `solve`
-# function from the OrdinaryDiffEq.jl package.
+# the initial time. This `ODEProblem` can be subsequently passed to the `solve`
+# function from the [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) package or to [`Trixi.solve`](@ref).
 
 ode = semidiscretize(semi, (0.0, 1.0));
  

From 22b050f48c19ac464aabcf26fb5f0fa51513e2ea Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:24:46 +0200
Subject: [PATCH 21/74] Update
 docs/literate/src/files/innards_of_the_basic_setup.jl

Co-authored-by: Michael Schlottke-Lakemper <michael@sloede.com>
---
 docs/literate/src/files/innards_of_the_basic_setup.jl | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
index 609de41746..6e126ed240 100644
--- a/docs/literate/src/files/innards_of_the_basic_setup.jl
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -152,12 +152,11 @@ ode = semidiscretize(semi, (0.0, 1.0));
 
 # - `allocate_coefficients(mesh, equations, solver, cache)`
 
-#   To apply initial conditions, a container needs to be generated to store the initial values of
+#   To apply initial conditions, a data structure ("container") needs to be generated to store the initial values of
 #   the target variables for each node within each element. The `allocate_coefficients` function
-#   initializes `u_ode` as a 1D zero-vector with a length that depends on the number of variables,
-#   elements, nodes, and dimensions. The use of a 1D vector format is consistent with the
-#   requirements of the ODE-solvers from OrdinaryDiffEq.jl. Therefore, Trixi.jl follows this
-#   format to be able to utilize the functionalities of OrdinaryDiffEq.jl.
+#   initializes `u_ode` as a 1D vector with a length that depends on the number of variables,
+#   elements, nodes, and dimensions. The use of a 1D vector format allows one to resize the mesh (and thus change the number of elements)
+#   while utilizing the functionalities of OrdinaryDiffEq.jl.
 
 # - `wrap_array(u_ode, semi)`
 

From b07e220c6da555fcbd1e2cd7de05c18667e8ed15 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:25:08 +0200
Subject: [PATCH 22/74] Update
 docs/literate/src/files/innards_of_the_basic_setup.jl

Co-authored-by: Michael Schlottke-Lakemper <michael@sloede.com>
---
 docs/literate/src/files/innards_of_the_basic_setup.jl | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
index 6e126ed240..afde34105a 100644
--- a/docs/literate/src/files/innards_of_the_basic_setup.jl
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -161,8 +161,8 @@ ode = semidiscretize(semi, (0.0, 1.0));
 # - `wrap_array(u_ode, semi)`
 
 #   As previously noted, `u_ode` is constructed as a 1D vector to ensure compatibility with
-#   OrdinaryDiffEq.jl. However, for internal use within Trixi.jl, identification which part of the
-#   vector relates to specific variables, elements and nodes can be challenging.
+#   OrdinaryDiffEq.jl. However, for internal use within Trixi.jl, identifying which part of the
+#   vector relates to specific variables, elements, or nodes can be challenging.
 
 #   This is why the `u_ode` vector is wrapped by the `wrap_array` function to create a
 #   multidimensional array `u`, with each dimension representing variables, nodes and elements.

From 11e2687a1ba4f989c8fa122291e56cbc3a26d992 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:25:27 +0200
Subject: [PATCH 23/74] Update
 docs/literate/src/files/innards_of_the_basic_setup.jl

Co-authored-by: Michael Schlottke-Lakemper <michael@sloede.com>
---
 docs/literate/src/files/innards_of_the_basic_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
index afde34105a..57f5f386fc 100644
--- a/docs/literate/src/files/innards_of_the_basic_setup.jl
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -193,7 +193,7 @@ ode = semidiscretize(semi, (0.0, 1.0));
 
 # ## Functions `solve` and `rhs!`
 
-# Once the `ODEProblem` object is initialized, the `solve` function and one of the ODE-solvers from
+# Once the `ODEProblem` object is initialized, the `solve` function and one of the ODE solvers from
 # the OrdinaryDiffEq.jl package can be utilized to compute an approximated solution using the
 # instructions contained in the `ODEProblem` object.
 

From d21db97852f6958f8a8965266a01cb56dcb62f7e Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:25:44 +0200
Subject: [PATCH 24/74] Update
 docs/literate/src/files/innards_of_the_basic_setup.jl

Co-authored-by: Michael Schlottke-Lakemper <michael@sloede.com>
---
 docs/literate/src/files/innards_of_the_basic_setup.jl | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
index 57f5f386fc..5b552ea33d 100644
--- a/docs/literate/src/files/innards_of_the_basic_setup.jl
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -199,9 +199,9 @@ ode = semidiscretize(semi, (0.0, 1.0));
 
 sol = solve(ode, CarpenterKennedy2N54(williamson_condition=false), dt=0.01, save_everystep=false);
 
-# Since the `solve` function and the ODE-solver are defined in another package without knowledge
-# of how to handle discretizations performed in Trixi.jl, it is necessary to define the
-# right-hand-side function, `rhs!`, within Trixi.jl.
+# Since the `solve` function and the ODE solver have no knowledge
+# of a particular spatial discretization, it is necessary to define a
+# "right-hand-side function", `rhs!`, within Trixi.jl.
 
 # Trixi.jl includes a set of `rhs!` functions designed to compute `du` according to the structure
 # of the setup. These `rhs!` functions calculate interface, mortars, and boundary fluxes, in

From 2f207a97a2f567afaf4a55afc7d536f850906405 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:25:59 +0200
Subject: [PATCH 25/74] Update
 docs/literate/src/files/innards_of_the_basic_setup.jl

Co-authored-by: Michael Schlottke-Lakemper <michael@sloede.com>
---
 docs/literate/src/files/innards_of_the_basic_setup.jl | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
index 5b552ea33d..c85bb3a8d4 100644
--- a/docs/literate/src/files/innards_of_the_basic_setup.jl
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -203,12 +203,12 @@ sol = solve(ode, CarpenterKennedy2N54(williamson_condition=false), dt=0.01, save
 # of a particular spatial discretization, it is necessary to define a
 # "right-hand-side function", `rhs!`, within Trixi.jl.
 
-# Trixi.jl includes a set of `rhs!` functions designed to compute `du` according to the structure
+# Trixi.jl includes a set of `rhs!` functions designed to compute `du`, i.e., ``\partial u/\partial t`` according to the structure
 # of the setup. These `rhs!` functions calculate interface, mortars, and boundary fluxes, in
 # addition to surface and volume integrals, in order to construct the `du` vector. This `du` vector
-# is then used by the time integration method to derive solutions in the subsequent time step.
-# The `rhs!` function is called by time integration methods in each iteration of the solve-loop
-# within OrdinaryDiffEq.jl, with arguments `du`, `u`, `Semidiscretization`, and the time step.
+# is then used by the time integration method to obtain the solution at the subsequent time step.
+# The `rhs!` function is called by time integration methods in each iteration of the solve loop
+# within OrdinaryDiffEq.jl, with arguments `du`, `u`, `semidiscretization`, and the current time.
 
 # The problem is that `rhs!` functions within Trixi.jl are specialized for specific solver and mesh
 # types. However, the types of arguments passed to `rhs!` by time integration methods do not

From 4dfef40e8ec592455284e8beeeec3c6df1dd615c Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:26:10 +0200
Subject: [PATCH 26/74] Update
 docs/literate/src/files/innards_of_the_basic_setup.jl

Co-authored-by: Michael Schlottke-Lakemper <michael@sloede.com>
---
 docs/literate/src/files/innards_of_the_basic_setup.jl | 11 -----------
 1 file changed, 11 deletions(-)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
index c85bb3a8d4..50e93f0949 100644
--- a/docs/literate/src/files/innards_of_the_basic_setup.jl
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -230,14 +230,3 @@ plot(sol)
 pd = PlotData2D(sol)
 plot!(getmesh(pd))
 
-
-# ## Package versions
-
-# These results were obtained using the following versions.
-
-using InteractiveUtils
-versioninfo()
-
-using Pkg
-Pkg.status(["Trixi", "OrdinaryDiffEq", "Plots", "ForwardDiff"],
-           mode=PKGMODE_MANIFEST)

From 5a8669c3c532e8ab41c16c996cf6ab1ef05859fd Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:26:39 +0200
Subject: [PATCH 27/74] Update
 docs/literate/src/files/innards_of_the_basic_setup.jl

Co-authored-by: Michael Schlottke-Lakemper <michael@sloede.com>
---
 .../src/files/innards_of_the_basic_setup.jl       | 15 ++++++---------
 1 file changed, 6 insertions(+), 9 deletions(-)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/innards_of_the_basic_setup.jl
index 50e93f0949..762e74eda2 100644
--- a/docs/literate/src/files/innards_of_the_basic_setup.jl
+++ b/docs/literate/src/files/innards_of_the_basic_setup.jl
@@ -1,13 +1,10 @@
-#src # Core aspects of the basic setup
+#src # Behind the scenes of a simulation setup
 
-# This tutorial aims to provide insights into the Trixi.jl framework, with a focus on commonly
-# used complex functions. These functions may lack clarity in their names and brief documentation
-# descriptions.
-
-# We will guide you through a simplified setup, emphasizing functionalities that may not be evident
-# to an average user. This setup is based on stable parts of Trixi.jl that are unlikely to undergo
-# significant changes in the near future. Nevertheless, it will clarify fundamental concepts that
-# continue to be applied in more recent and flexible configurations.
+# 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 this setup
+# does not cover all details, it is based on relatively stable parts of Trixi.jl that are unlikely to undergo
+# significant changes in the near future. The goal is to clarify some of the more fundamental, *technical* concepts that
+# are applicable to a variety of (also more complex) configurations.
 
 
 # ## Basic setup

From a2d71b39ba051bdd07b87fbce2f87b79349d1067 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:26:57 +0200
Subject: [PATCH 28/74] Update docs/make.jl

Co-authored-by: Michael Schlottke-Lakemper <michael@sloede.com>
---
 docs/make.jl | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/make.jl b/docs/make.jl
index 3ffce0a166..e97727f422 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -69,7 +69,8 @@ files = [
     "Explicit time stepping" => "time_stepping.jl",
     "Differentiable programming" => "differentiable_programming.jl",
     "Custom semidiscretizations" => "custom_semidiscretization.jl",
-    "Core aspects of the basic setup" => "innards_of_the_basic_setup.jl",
+    "Behind the scenes of a simulation setup"
+     => "behind_the_scenes_simulation_setup.jl",
     ]
 tutorials = create_tutorials(files)
 

From e0693b94b93a8161c69953e44f5b6495af616df3 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:27:29 +0200
Subject: [PATCH 29/74] Rename innards_of_the_basic_setup.jl to
 behind_the_scenes_simulation_setup.jl

---
 ...f_the_basic_setup.jl => behind_the_scenes_simulation_setup.jl} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename docs/literate/src/files/{innards_of_the_basic_setup.jl => behind_the_scenes_simulation_setup.jl} (100%)

diff --git a/docs/literate/src/files/innards_of_the_basic_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
similarity index 100%
rename from docs/literate/src/files/innards_of_the_basic_setup.jl
rename to docs/literate/src/files/behind_the_scenes_simulation_setup.jl

From 3edd1082bc8661efbbf374ad1ede8099220040ce Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:28:00 +0200
Subject: [PATCH 30/74] add plot scripts

---
 ...scretizationHyperbolic_structure_figure.jl |  64 ++++++
 .../generate_boundary_figure.jl               | 190 ++++++++++++++++++
 .../generate_elements_figure.jl               | 117 +++++++++++
 .../generate_interfaces_figure.jl             | 157 +++++++++++++++
 .../generate_mortars_figure.jl                | 166 +++++++++++++++
 .../generate_nodes_figure.jl                  |   6 +
 .../generate_treemesh_figure.jl               |  26 +++
 .../rhs_structure_figure.jl                   |  43 ++++
 .../semidiscretize_structure_figure.jl        |  51 +++++
 9 files changed, 820 insertions(+)
 create mode 100644 docs/literate/src/files/behind_the_scenes_simulation_setup_plots/SemidiscretizationHyperbolic_structure_figure.jl
 create mode 100644 docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_boundary_figure.jl
 create mode 100644 docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_elements_figure.jl
 create mode 100644 docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_interfaces_figure.jl
 create mode 100644 docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_mortars_figure.jl
 create mode 100644 docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_nodes_figure.jl
 create mode 100644 docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_treemesh_figure.jl
 create mode 100644 docs/literate/src/files/behind_the_scenes_simulation_setup_plots/rhs_structure_figure.jl
 create mode 100644 docs/literate/src/files/behind_the_scenes_simulation_setup_plots/semidiscretize_structure_figure.jl

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/SemidiscretizationHyperbolic_structure_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/SemidiscretizationHyperbolic_structure_figure.jl
new file mode 100644
index 0000000000..64bf3af004
--- /dev/null
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/SemidiscretizationHyperbolic_structure_figure.jl
@@ -0,0 +1,64 @@
+using Plots
+plot(Shape([(-2.3,4.5), (2.35,4.5), (2.35,2.5), (-2.3,2.5)]), linecolor="black", fillcolor="white", label=false,linewidth=2, size=(800,600), showaxis=false, grid=false, xlim=(-2.4,2.8), ylim=(-25,5.5))
+annotate!(2.3, 3.5, ("SemidiscretizationHyperbolic(mesh, equations, initial_conditions, solver; source_terms,
+boundary_conditions, RealT, uEltype, initial_cache)          ", 10, :black, :right))
+annotate!(-2.3, 1.5, ("creates and returns SemidiscretizationHyperbolic object, initialized using a mesh, equations,
+initial_coditions, boundary_conditions, source_terms, solver and cache", 9, :black, :left))
+plot!([-1.2,-1.2],[0.6,-2],arrow=true,color=:black,linewidth=2,label="")
+plot!([-1.2,-1.4],[0.6,-2],arrow=true,color=:black,linewidth=2,label="")
+plot!([-1.2,-1.],[0.6,-2],arrow=true,color=:black,linewidth=2,label="")
+annotate!(-1, -0.7, ("specialized for mesh
+and solver types", 9, :black, :left))
+plot!([1.25,1.25],[0.6,-2],arrow=true,color=:black,linewidth=2,label="")
+plot!([1.25,1.05],[0.6,-2],arrow=true,color=:black,linewidth=2,label="")
+plot!([1.25,1.45],[0.6,-2],arrow=true,color=:black,linewidth=2,label="")
+annotate!(1.48, -0.7, ("specialized for mesh
+and boundary_conditions
+types", 9, :black, :left))
+
+plot!(Shape([(-2.3,-2), (-0.1,-2), (-0.1,-4), (-2.3,-4)]), linecolor="black", fillcolor="white", label=false,linewidth=2)
+annotate!(-1.2, -3, ("create_cache(mesh::TreeMesh, equations,
+                   solver::Dg, RealT, uEltype)", 10, :black, :center))
+plot!([-2.22,-2.22],[-4,-22],arrow=false,color=:black,linewidth=2,label="")
+
+plot!(Shape([(-0.05,-2), (2.6,-2), (2.6,-4), (-0.05,-4)]), linecolor="black", fillcolor="white", label=false,linewidth=2)
+annotate!(1.27, -3, ("digest_boundary_conditions(boundary_conditions,
+                                             mesh, solver, cache)", 10, :black, :center))
+annotate!(2.6, -5, ("if necessary, converts passed boundary_conditions
+ into a suitable form for processing by Trixi.jl", 9, :black, :right))
+
+plot!(Shape([(-2,-6), (-0.55,-6), (-0.55,-7.1), (-2,-7.1)]), linecolor="black", fillcolor="white", label=false,linewidth=2)
+annotate!(-1.95, -6.5, ("local_leaf_cells(mesh.tree)", 10, :black, :left))
+annotate!(-2, -7.5, ("returns cells for which an element needs to be created (i.e. all leaf cells)", 9, :black, :left))
+plot!([-2.22,-2],[-6.5,-6.5],arrow=true,color=:black,linewidth=2,label="")
+
+plot!(Shape([(-2,-9), (1.73,-9), (1.73,-10.1), (-2,-10.1)]), linecolor="black", fillcolor="white", label=false,linewidth=2)
+annotate!(-1.95, -9.5, ("init_elements(leaf_cell_ids, mesh, equations, dg.basis, RealT, uEltype)", 10, :black, :left))
+annotate!(-2, -10.5, ("creates and initializes elements, projects Gauss-Lobatto basis onto each of them", 9, :black, :left))
+plot!([-2.22,-2],[-9.5,-9.5],arrow=true,color=:black,linewidth=2,label="")
+
+plot!(Shape([(-2,-12), (0.4,-12), (0.4,-13.1), (-2,-13.1)]), linecolor="black", fillcolor="white", label=false,linewidth=2)
+annotate!(-1.95, -12.5, ("init_interfaces(leaf_cell_ids, mesh, elements)", 10, :black, :left))
+annotate!(-2, -13.5, ("creates and initializes interfaces between each pair of adjacent elements of the same size", 9, :black, :left))
+plot!([-2.22,-2],[-12.5,-12.5],arrow=true,color=:black,linewidth=2,label="")
+
+plot!(Shape([(-2,-15), (0.5,-15), (0.5,-16.1), (-2,-16.1)]), linecolor="black", fillcolor="white", label=false,linewidth=2)
+annotate!(-1.95, -15.5, ("init_boundaries(leaf_cell_ids, mesh, elements)", 10, :black, :left))
+annotate!(-2, -17, ("creates and initializes boundaries, remembers each boundary element, as well as the coordinates of
+each boundary node", 9, :black, :left))
+plot!([-2.22,-2],[-15.5,-15.5],arrow=true,color=:black,linewidth=2,label="")
+
+plot!(Shape([(-1.6,-18), (1.3,-18), (1.3,-19.1), (-1.6,-19.1)]), linecolor="black", fillcolor="white", label=false,linewidth=2)
+annotate!(-1.55, -18.5, ("init_mortars(leaf_cell_ids, mesh, elements, dg.mortar)", 10, :black, :left))
+annotate!(-1.6, -20, ("creates and initializes mortars (type of interfaces) between each triple of adjacent coarsened
+and corresponding small elements", 9, :black, :left))
+plot!([-2.22,-1.6],[-18.5,-18.5],arrow=true,color=:black,linewidth=2,label="")
+annotate!(-2.15, -19, ("2D and 3D", 8, :black, :left))
+
+plot!(Shape([(-2,-21), (1.5,-21), (1.5,-23.1), (-2,-23.1)]), linecolor="black", fillcolor="white", label=false,linewidth=2)
+annotate!(-1.95, -22, ("create_cache(mesh, equations, dg.volume_integral, dg, uEltype)
+for 2D and 3D create_cache(mesh, equations, dg.mortar, uEltype)", 10, :black, :left))
+annotate!(-2, -23.5, ("add specialized parts of the cache required to compute the volume integral, etc.", 9, :black, :left))
+plot!([-2.22,-2],[-22,-22],arrow=true,color=:black,linewidth=2,label="")
+
+savefig("Issues/semidiscretize_issue#1215/SemidiscretizationHyperbolic")
\ No newline at end of file
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_boundary_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_boundary_figure.jl
new file mode 100644
index 0000000000..9648f7dc44
--- /dev/null
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_boundary_figure.jl
@@ -0,0 +1,190 @@
+using Plots
+
+function min(coordinates::Vector{Tuple{Float64, Float64}}, i)
+  min=coordinates[1][i]
+  for j in coordinates
+    if min>j[i]
+      min=j[i]
+    end
+  end
+  return min
+end
+
+function max(coordinates::Vector{Tuple{Float64, Float64}}, i)
+  max=coordinates[1][i]
+  for j in coordinates
+    if max<j[i]
+      max=j[i]
+    end
+  end
+  return max
+end
+
+function nodes_project_four(coordinates::Vector{Tuple{Float64, Float64}})
+  nodes_1d=[-1.0, -0.4472135954999579, 0.4472135954999579, 1.0]
+  nodes_2d=Array{Float64,2}(undef, 16,2)
+  for i in range(1,length(nodes_1d))
+    for j in range(1,length(nodes_1d))
+      nodes_2d[(i-1)*4+j,:]=[nodes_1d[i], nodes_1d[j]]
+    end
+  end
+  k_x = (max(coordinates,1)-min(coordinates,1))/2
+  k_y = (max(coordinates,2)-min(coordinates,2))/2
+  b_x = min(coordinates,1)
+  b_y = min(coordinates,2)
+  for i in range(1,Int(length(nodes_2d)/2))
+    nodes_2d[i,1]=k_x*(nodes_2d[i,1]+1)+b_x
+    nodes_2d[i,2]=k_y*(nodes_2d[i,2]+1)+b_y
+  end
+  return nodes_2d
+end
+
+
+import Base.+
++(a::Tuple,b::Tuple) = a .+ b
+
+# level 1
+plot(Shape([(2,0),(2,-2),(0,-2),(0,0)].+[(0.5,-0.75),(0.5,-0.75),(0.5,-0.75),(0.5,-0.75)]), linecolor="black", fillcolor="white", label="elements",legend_position=:right, linewidth=2, size=(800,600), showaxis=false, grid=false, x_lims=(-3,5.5), ylims=(-3.5,3))
+
+nodes_2d=nodes_project_four([(2,0),(2,-2),(0,-2),(0,0)].+[(0.5,-0.75),(0.5,-0.75),(0.5,-0.75),(0.5,-0.75)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = "Gauss-Lobatto nodes", markersize = 5)
+
+# mortars
+plot!([-0.25,0.125], [-1,-1], linecolor="orange", fillcolor="white", label="mortars", linewidth=3)
+plot!([-0.25,0.125], [-2.5,-2.5], linecolor="orange", fillcolor="white", label=false, linewidth=3)
+plot!([0.125,0.125], [-1,-2.5], linecolor="orange", fillcolor="white", label=false, linewidth=3)
+plot!([0.125,0.5], [-1.75,-1.75], linecolor="orange", fillcolor="white", label=false, linewidth=3)
+plot!([0.75,0.75], [0,-0.325], linecolor="orange", fillcolor="white", label=false, linewidth=3)
+plot!([2.25,2.25], [0,-0.325], linecolor="orange", fillcolor="white", label=false, linewidth=3)
+plot!([2.25,0.75], [-0.325,-0.325], linecolor="orange", fillcolor="white", label=false, linewidth=3)
+plot!([1.5,1.5], [-0.75,-0.325], linecolor="orange", fillcolor="white", label=false, linewidth=3)
+
+plot!([2.5,2.5], [-0.75,-2.75], linecolor="green", label="boundaries with nodes", linewidth=15, opacity=0.3)
+plot!([.5,2.5], [-2.75,-2.75], linecolor="green", label=false, linewidth=15, opacity=0.3)
+
+# level 2
+
+# upper right
+# 1
+plot!(Shape([(2,2),(2,1),(1,1),(1,2)].+[(0.75,0.5),(0.75,0.5),(0.75,0.5),(0.75,0.5)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(2,2),(2,1),(1,1),(1,2)].+[(0.75,0.5),(0.75,0.5),(0.75,0.5),(0.75,0.5)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([1.25,1.75], [2,2], linecolor="blue", fillcolor="white", label="interfaces", linewidth=3)
+plot!([2.25,2.25], [1.5,1], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+plot!([2.75,2.75], [2.5,1.5], linecolor="green", label=false, linewidth=15, opacity=0.3)
+plot!([1.75,2.75], [2.5,2.5], linecolor="green", label=false, linewidth=15, opacity=0.3)
+
+# 2
+plot!(Shape([(0,2),(1,2),(1,1),(0,1)].+[(0.25,0.5),(0.25,0.5),(0.25,0.5),(0.25,0.5)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(0,2),(1,2),(1,1),(0,1)].+[(0.25,0.5),(0.25,0.5),(0.25,0.5),(0.25,0.5)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-0.25,0.25], [2,2], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+plot!([0.75,0.75], [1.5,1], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+plot!([.25,1.25], [2.5,2.5], linecolor="green", label=false, linewidth=15, opacity=0.3)
+
+# 3
+plot!(Shape([(0,0),(0,1),(1,1),(1,0)].+[(0.25,0.),(0.25,0.),(0.25,0.),(0.25,0.)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(0,0),(0,1),(1,1),(1,0)].+[(0.25,0.),(0.25,0.),(0.25,0.),(0.25,0.)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([1.25,1.75], [.5,.5], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+plot!([-0.25,0.25], [.5,.5], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+# 4
+plot!(Shape([(2,0),(2,1),(1,1),(1,0)].+[(0.75,0.),(0.75,0.),(0.75,0.),(0.75,0.)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(2,0),(2,1),(1,1),(1,0)].+[(0.75,0.),(0.75,0.),(0.75,0.),(0.75,0.)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([2.75,2.75], [1,0], linecolor="green", label=false, linewidth=15, opacity=0.3)
+
+# upper left
+# 1
+plot!(Shape([(-0,2),(-0,1),(-1,1),(-1,2)].+[(-0.25,0.5),(-0.25,0.5),(-0.25,0.5),(-0.25,0.5)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-0,2),(-0,1),(-1,1),(-1,2)].+[(-0.25,0.5),(-0.25,0.5),(-0.25,0.5),(-0.25,0.5)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-1.25,-1.75], [2,2], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+plot!([-0.75,-0.75], [1,1.5], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+plot!([-1.25,-0.25], [2.5,2.5], linecolor="green", label=false, linewidth=15, opacity=0.3)
+
+# 2
+plot!(Shape([(-2,2),(-1,2),(-1,1),(-2,1)].+[(-0.75,0.5),(-0.75,0.5),(-0.75,0.5),(-0.75,0.5)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-2,2),(-1,2),(-1,1),(-2,1)].+[(-0.75,0.5),(-0.75,0.5),(-0.75,0.5),(-0.75,0.5)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-2.25,-2.25], [1,1.5], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+plot!([-1.75,-2.75], [2.5,2.5], linecolor="green", label=false, linewidth=15, opacity=0.3)
+plot!([-2.75,-2.75], [1.5,2.5], linecolor="green", label=false, linewidth=15, opacity=0.3)
+
+# 3
+plot!(Shape([(-2,0),(-2,1),(-1,1),(-1,0)].+[(-0.75,0.),(-0.75,0.),(-0.75,0.),(-0.75,0.)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-2,0),(-2,1),(-1,1),(-1,0)].+[(-0.75,0.),(-0.75,0.),(-0.75,0.),(-0.75,0.)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-1.75,-1.25], [.5,.5], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+plot!([-2.25,-2.25], [-0.5,0], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+plot!([-2.75,-2.75], [0,1], linecolor="green", label=false, linewidth=15, opacity=0.3)
+
+# 4
+plot!(Shape([(-0,0),(-1,0),(-1,1),(-0,1)].+[(-0.25,0.),(-0.25,0.),(-0.25,0.),(-0.25,0.)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-0,0),(-1,0),(-1,1),(-0,1)].+[(-0.25,0.),(-0.25,0.),(-0.25,0.),(-0.25,0.)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-0.75,-0.75], [-0.5,0], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+# lower left
+# 1
+plot!(Shape([(-0,-0),(-0,-1),(-1,-1),(-1,-0)].+[(-0.25,-0.5),(-0.25,-0.5),(-0.25,-0.5),(-0.25,-0.5)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-0,-0),(-0,-1),(-1,-1),(-1,-0)].+[(-0.25,-0.5),(-0.25,-0.5),(-0.25,-0.5),(-0.25,-0.5)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-1.75,-1.25], [-1,-1], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+plot!([-0.75,-0.75], [-1.5,-2], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+
+# 2
+plot!(Shape([(-2,-1),(-2,0),(-1,-0),(-1,-1)].+[(-0.75,-0.5),(-0.75,-0.5),(-0.75,-0.5),(-0.75,-0.5)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-2,-1),(-2,0),(-1,-0),(-1,-1)].+[(-0.75,-0.5),(-0.75,-0.5),(-0.75,-0.5),(-0.75,-0.5)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-2.25,-2.25], [-1.5,-2], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+plot!([-2.75,-2.75], [-0.5,-1.5], linecolor="green", label=false, linewidth=15, opacity=0.3)
+
+# 3
+plot!(Shape([(-2,-2),(-2,-1),(-1,-1),(-1,-2)].+[(-0.75,-1),(-0.75,-1),(-0.75,-1),(-0.75,-1)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-2.,-2.),(-2.,-1.),(-1.,-1.),(-1.,-2.)].+[(-0.75,-1),(-0.75,-1),(-0.75,-1),(-0.75,-1)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-1.75,-1.25], [-2.5,-2.5], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+plot!([-2.75,-2.75], [-2,-3], linecolor="green", label=false, linewidth=15, opacity=0.3)
+plot!([-2.75,-1.75], [-3,-3], linecolor="green", label=false, linewidth=15, opacity=0.3)
+
+# 4
+plot!(Shape([(-1,-2),(-1,-1),(-0,-1),(-0,-2)].+[(-0.25,-1),(-0.25,-1),(-0.25,-1),(-0.25,-1)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-1.,-2.),(-1.,-1.),(-0.,-1.),(-0.,-2.)].+[(-0.25,-1),(-0.25,-1),(-0.25,-1),(-0.25,-1)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-0.25,-1.25], [-3,-3], linecolor="green", label=false, linewidth=15, opacity=0.3)
+
+savefig("Issues/semidiscretize_issue#1215/boundary")
\ No newline at end of file
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_elements_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_elements_figure.jl
new file mode 100644
index 0000000000..df30fc2198
--- /dev/null
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_elements_figure.jl
@@ -0,0 +1,117 @@
+using Plots
+
+function min(coordinates::Vector{Tuple{Float64, Float64}}, i)
+  min=coordinates[1][i]
+  for j in coordinates
+    if min>j[i]
+      min=j[i]
+    end
+  end
+  return min
+end
+
+function max(coordinates::Vector{Tuple{Float64, Float64}}, i)
+  max=coordinates[1][i]
+  for j in coordinates
+    if max<j[i]
+      max=j[i]
+    end
+  end
+  return max
+end
+
+function nodes_project_four(coordinates::Vector{Tuple{Float64, Float64}})
+  nodes_1d=[-1.0, -0.4472135954999579, 0.4472135954999579, 1.0]
+  nodes_2d=Array{Float64,2}(undef, 16,2)
+  for i in range(1,length(nodes_1d))
+    for j in range(1,length(nodes_1d))
+      nodes_2d[(i-1)*4+j,:]=[nodes_1d[i], nodes_1d[j]]
+    end
+  end
+  k_x = (max(coordinates,1)-min(coordinates,1))/2
+  k_y = (max(coordinates,2)-min(coordinates,2))/2
+  b_x = min(coordinates,1)
+  b_y = min(coordinates,2)
+  for i in range(1,Int(length(nodes_2d)/2))
+    nodes_2d[i,1]=k_x*(nodes_2d[i,1]+1)+b_x
+    nodes_2d[i,2]=k_y*(nodes_2d[i,2]+1)+b_y
+  end
+  return nodes_2d
+end
+
+
+import Base.+
++(a::Tuple,b::Tuple) = a .+ b
+
+# level 1
+plot(Shape([(2,0),(2,-2),(0,-2),(0,0)].+[(0.5,-0.75),(0.5,-0.75),(0.5,-0.75),(0.5,-0.75)]), linecolor="black", fillcolor="white", label="elements",legend_position=:right, linewidth=2, size=(800,600), showaxis=false, grid=false, x_lims=(-3,5.5), ylims=(-3.5,3))
+
+nodes_2d=nodes_project_four([(2,0),(2,-2),(0,-2),(0,0)].+[(0.5,-0.75),(0.5,-0.75),(0.5,-0.75),(0.5,-0.75)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = "Gauss-Lobatto nodes", markersize = 5)
+
+# level 2
+
+# upper right
+plot!(Shape([(2,2),(2,1),(1,1),(1,2)].+[(0.75,0.5),(0.75,0.5),(0.75,0.5),(0.75,0.5)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(2,2),(2,1),(1,1),(1,2)].+[(0.75,0.5),(0.75,0.5),(0.75,0.5),(0.75,0.5)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!(Shape([(0,2),(1,2),(1,1),(0,1)].+[(0.25,0.5),(0.25,0.5),(0.25,0.5),(0.25,0.5)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(0,2),(1,2),(1,1),(0,1)].+[(0.25,0.5),(0.25,0.5),(0.25,0.5),(0.25,0.5)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!(Shape([(0,0),(0,1),(1,1),(1,0)].+[(0.25,0.),(0.25,0.),(0.25,0.),(0.25,0.)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(0,0),(0,1),(1,1),(1,0)].+[(0.25,0.),(0.25,0.),(0.25,0.),(0.25,0.)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!(Shape([(2,0),(2,1),(1,1),(1,0)].+[(0.75,0.),(0.75,0.),(0.75,0.),(0.75,0.)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(2,0),(2,1),(1,1),(1,0)].+[(0.75,0.),(0.75,0.),(0.75,0.),(0.75,0.)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+# upper left
+plot!(Shape([(-0,2),(-0,1),(-1,1),(-1,2)].+[(-0.25,0.5),(-0.25,0.5),(-0.25,0.5),(-0.25,0.5)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-0,2),(-0,1),(-1,1),(-1,2)].+[(-0.25,0.5),(-0.25,0.5),(-0.25,0.5),(-0.25,0.5)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!(Shape([(-2,2),(-1,2),(-1,1),(-2,1)].+[(-0.75,0.5),(-0.75,0.5),(-0.75,0.5),(-0.75,0.5)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-2,2),(-1,2),(-1,1),(-2,1)].+[(-0.75,0.5),(-0.75,0.5),(-0.75,0.5),(-0.75,0.5)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!(Shape([(-2,0),(-2,1),(-1,1),(-1,0)].+[(-0.75,0.),(-0.75,0.),(-0.75,0.),(-0.75,0.)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-2,0),(-2,1),(-1,1),(-1,0)].+[(-0.75,0.),(-0.75,0.),(-0.75,0.),(-0.75,0.)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!(Shape([(-0,0),(-1,0),(-1,1),(-0,1)].+[(-0.25,0.),(-0.25,0.),(-0.25,0.),(-0.25,0.)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-0,0),(-1,0),(-1,1),(-0,1)].+[(-0.25,0.),(-0.25,0.),(-0.25,0.),(-0.25,0.)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+# lower left
+plot!(Shape([(-0,-0),(-0,-1),(-1,-1),(-1,-0)].+[(-0.25,-0.5),(-0.25,-0.5),(-0.25,-0.5),(-0.25,-0.5)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-0,-0),(-0,-1),(-1,-1),(-1,-0)].+[(-0.25,-0.5),(-0.25,-0.5),(-0.25,-0.5),(-0.25,-0.5)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!(Shape([(-2,-1),(-2,0),(-1,-0),(-1,-1)].+[(-0.75,-0.5),(-0.75,-0.5),(-0.75,-0.5),(-0.75,-0.5)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-2,-1),(-2,0),(-1,-0),(-1,-1)].+[(-0.75,-0.5),(-0.75,-0.5),(-0.75,-0.5),(-0.75,-0.5)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!(Shape([(-2,-2),(-2,-1),(-1,-1),(-1,-2)].+[(-0.75,-1),(-0.75,-1),(-0.75,-1),(-0.75,-1)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-2.,-2.),(-2.,-1.),(-1.,-1.),(-1.,-2.)].+[(-0.75,-1),(-0.75,-1),(-0.75,-1),(-0.75,-1)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!(Shape([(-1,-2),(-1,-1),(-0,-1),(-0,-2)].+[(-0.25,-1),(-0.25,-1),(-0.25,-1),(-0.25,-1)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-1.,-2.),(-1.,-1.),(-0.,-1.),(-0.,-2.)].+[(-0.25,-1),(-0.25,-1),(-0.25,-1),(-0.25,-1)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+#savefig("Issues/semidiscretize_issue#1215/elements")
\ No newline at end of file
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_interfaces_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_interfaces_figure.jl
new file mode 100644
index 0000000000..7c2585bb06
--- /dev/null
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_interfaces_figure.jl
@@ -0,0 +1,157 @@
+using Plots
+
+function min(coordinates::Vector{Tuple{Float64, Float64}}, i)
+  min=coordinates[1][i]
+  for j in coordinates
+    if min>j[i]
+      min=j[i]
+    end
+  end
+  return min
+end
+
+function max(coordinates::Vector{Tuple{Float64, Float64}}, i)
+  max=coordinates[1][i]
+  for j in coordinates
+    if max<j[i]
+      max=j[i]
+    end
+  end
+  return max
+end
+
+function nodes_project_four(coordinates::Vector{Tuple{Float64, Float64}})
+  nodes_1d=[-1.0, -0.4472135954999579, 0.4472135954999579, 1.0]
+  nodes_2d=Array{Float64,2}(undef, 16,2)
+  for i in range(1,length(nodes_1d))
+    for j in range(1,length(nodes_1d))
+      nodes_2d[(i-1)*4+j,:]=[nodes_1d[i], nodes_1d[j]]
+    end
+  end
+  k_x = (max(coordinates,1)-min(coordinates,1))/2
+  k_y = (max(coordinates,2)-min(coordinates,2))/2
+  b_x = min(coordinates,1)
+  b_y = min(coordinates,2)
+  for i in range(1,Int(length(nodes_2d)/2))
+    nodes_2d[i,1]=k_x*(nodes_2d[i,1]+1)+b_x
+    nodes_2d[i,2]=k_y*(nodes_2d[i,2]+1)+b_y
+  end
+  return nodes_2d
+end
+
+
+import Base.+
++(a::Tuple,b::Tuple) = a .+ b
+
+# level 1
+plot(Shape([(2,0),(2,-2),(0,-2),(0,0)].+[(0.5,-0.75),(0.5,-0.75),(0.5,-0.75),(0.5,-0.75)]), linecolor="black", fillcolor="white", label="elements",legend_position=:right, linewidth=2, size=(800,600), showaxis=false, grid=false, x_lims=(-3,5.5), ylims=(-3.5,3))
+
+nodes_2d=nodes_project_four([(2,0),(2,-2),(0,-2),(0,0)].+[(0.5,-0.75),(0.5,-0.75),(0.5,-0.75),(0.5,-0.75)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = "Gauss-Lobatto nodes", markersize = 5)
+
+# level 2
+
+# upper right
+# 1
+plot!(Shape([(2,2),(2,1),(1,1),(1,2)].+[(0.75,0.5),(0.75,0.5),(0.75,0.5),(0.75,0.5)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(2,2),(2,1),(1,1),(1,2)].+[(0.75,0.5),(0.75,0.5),(0.75,0.5),(0.75,0.5)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([1.25,1.75], [2,2], linecolor="blue", fillcolor="white", label="interfaces", linewidth=3)
+plot!([2.25,2.25], [1.5,1], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+# 2
+plot!(Shape([(0,2),(1,2),(1,1),(0,1)].+[(0.25,0.5),(0.25,0.5),(0.25,0.5),(0.25,0.5)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(0,2),(1,2),(1,1),(0,1)].+[(0.25,0.5),(0.25,0.5),(0.25,0.5),(0.25,0.5)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-0.25,0.25], [2,2], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+plot!([0.75,0.75], [1.5,1], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+# 3
+plot!(Shape([(0,0),(0,1),(1,1),(1,0)].+[(0.25,0.),(0.25,0.),(0.25,0.),(0.25,0.)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(0,0),(0,1),(1,1),(1,0)].+[(0.25,0.),(0.25,0.),(0.25,0.),(0.25,0.)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([1.25,1.75], [.5,.5], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+plot!([-0.25,0.25], [.5,.5], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+# 4
+plot!(Shape([(2,0),(2,1),(1,1),(1,0)].+[(0.75,0.),(0.75,0.),(0.75,0.),(0.75,0.)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(2,0),(2,1),(1,1),(1,0)].+[(0.75,0.),(0.75,0.),(0.75,0.),(0.75,0.)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+# upper left
+# 1
+plot!(Shape([(-0,2),(-0,1),(-1,1),(-1,2)].+[(-0.25,0.5),(-0.25,0.5),(-0.25,0.5),(-0.25,0.5)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-0,2),(-0,1),(-1,1),(-1,2)].+[(-0.25,0.5),(-0.25,0.5),(-0.25,0.5),(-0.25,0.5)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-1.25,-1.75], [2,2], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+plot!([-0.75,-0.75], [1,1.5], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+# 2
+plot!(Shape([(-2,2),(-1,2),(-1,1),(-2,1)].+[(-0.75,0.5),(-0.75,0.5),(-0.75,0.5),(-0.75,0.5)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-2,2),(-1,2),(-1,1),(-2,1)].+[(-0.75,0.5),(-0.75,0.5),(-0.75,0.5),(-0.75,0.5)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-2.25,-2.25], [1,1.5], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+
+# 3
+plot!(Shape([(-2,0),(-2,1),(-1,1),(-1,0)].+[(-0.75,0.),(-0.75,0.),(-0.75,0.),(-0.75,0.)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-2,0),(-2,1),(-1,1),(-1,0)].+[(-0.75,0.),(-0.75,0.),(-0.75,0.),(-0.75,0.)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-1.75,-1.25], [.5,.5], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+plot!([-2.25,-2.25], [-0.5,0], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+# 4
+plot!(Shape([(-0,0),(-1,0),(-1,1),(-0,1)].+[(-0.25,0.),(-0.25,0.),(-0.25,0.),(-0.25,0.)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-0,0),(-1,0),(-1,1),(-0,1)].+[(-0.25,0.),(-0.25,0.),(-0.25,0.),(-0.25,0.)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-0.75,-0.75], [-0.5,0], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+# lower left
+# 1
+plot!(Shape([(-0,-0),(-0,-1),(-1,-1),(-1,-0)].+[(-0.25,-0.5),(-0.25,-0.5),(-0.25,-0.5),(-0.25,-0.5)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-0,-0),(-0,-1),(-1,-1),(-1,-0)].+[(-0.25,-0.5),(-0.25,-0.5),(-0.25,-0.5),(-0.25,-0.5)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-1.75,-1.25], [-1,-1], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+plot!([-0.75,-0.75], [-1.5,-2], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+
+# 2
+plot!(Shape([(-2,-1),(-2,0),(-1,-0),(-1,-1)].+[(-0.75,-0.5),(-0.75,-0.5),(-0.75,-0.5),(-0.75,-0.5)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-2,-1),(-2,0),(-1,-0),(-1,-1)].+[(-0.75,-0.5),(-0.75,-0.5),(-0.75,-0.5),(-0.75,-0.5)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-2.25,-2.25], [-1.5,-2], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+# 3
+plot!(Shape([(-2,-2),(-2,-1),(-1,-1),(-1,-2)].+[(-0.75,-1),(-0.75,-1),(-0.75,-1),(-0.75,-1)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-2.,-2.),(-2.,-1.),(-1.,-1.),(-1.,-2.)].+[(-0.75,-1),(-0.75,-1),(-0.75,-1),(-0.75,-1)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-1.75,-1.25], [-2.5,-2.5], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+# 4
+plot!(Shape([(-1,-2),(-1,-1),(-0,-1),(-0,-2)].+[(-0.25,-1),(-0.25,-1),(-0.25,-1),(-0.25,-1)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-1.,-2.),(-1.,-1.),(-0.,-1.),(-0.,-2.)].+[(-0.25,-1),(-0.25,-1),(-0.25,-1),(-0.25,-1)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+savefig("Issues/semidiscretize_issue#1215/interfaces")
\ No newline at end of file
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_mortars_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_mortars_figure.jl
new file mode 100644
index 0000000000..9ca085546b
--- /dev/null
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_mortars_figure.jl
@@ -0,0 +1,166 @@
+using Plots
+
+function min(coordinates::Vector{Tuple{Float64, Float64}}, i)
+  min=coordinates[1][i]
+  for j in coordinates
+    if min>j[i]
+      min=j[i]
+    end
+  end
+  return min
+end
+
+function max(coordinates::Vector{Tuple{Float64, Float64}}, i)
+  max=coordinates[1][i]
+  for j in coordinates
+    if max<j[i]
+      max=j[i]
+    end
+  end
+  return max
+end
+
+function nodes_project_four(coordinates::Vector{Tuple{Float64, Float64}})
+  nodes_1d=[-1.0, -0.4472135954999579, 0.4472135954999579, 1.0]
+  nodes_2d=Array{Float64,2}(undef, 16,2)
+  for i in range(1,length(nodes_1d))
+    for j in range(1,length(nodes_1d))
+      nodes_2d[(i-1)*4+j,:]=[nodes_1d[i], nodes_1d[j]]
+    end
+  end
+  k_x = (max(coordinates,1)-min(coordinates,1))/2
+  k_y = (max(coordinates,2)-min(coordinates,2))/2
+  b_x = min(coordinates,1)
+  b_y = min(coordinates,2)
+  for i in range(1,Int(length(nodes_2d)/2))
+    nodes_2d[i,1]=k_x*(nodes_2d[i,1]+1)+b_x
+    nodes_2d[i,2]=k_y*(nodes_2d[i,2]+1)+b_y
+  end
+  return nodes_2d
+end
+
+
+import Base.+
++(a::Tuple,b::Tuple) = a .+ b
+
+# level 1
+plot(Shape([(2,0),(2,-2),(0,-2),(0,0)].+[(0.5,-0.75),(0.5,-0.75),(0.5,-0.75),(0.5,-0.75)]), linecolor="black", fillcolor="white", label="elements",legend_position=:right, linewidth=2, size=(800,600), showaxis=false, grid=false, x_lims=(-3,5.5), ylims=(-3.5,3))
+
+nodes_2d=nodes_project_four([(2,0),(2,-2),(0,-2),(0,0)].+[(0.5,-0.75),(0.5,-0.75),(0.5,-0.75),(0.5,-0.75)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = "Gauss-Lobatto nodes", markersize = 5)
+
+plot!([-0.25,0.125], [-1,-1], linecolor="orange", fillcolor="white", label="mortars", linewidth=3)
+plot!([-0.25,0.125], [-2.5,-2.5], linecolor="orange", fillcolor="white", label=false, linewidth=3)
+plot!([0.125,0.125], [-1,-2.5], linecolor="orange", fillcolor="white", label=false, linewidth=3)
+plot!([0.125,0.5], [-1.75,-1.75], linecolor="orange", fillcolor="white", label=false, linewidth=3)
+plot!([0.75,0.75], [0,-0.325], linecolor="orange", fillcolor="white", label=false, linewidth=3)
+plot!([2.25,2.25], [0,-0.325], linecolor="orange", fillcolor="white", label=false, linewidth=3)
+plot!([2.25,0.75], [-0.325,-0.325], linecolor="orange", fillcolor="white", label=false, linewidth=3)
+plot!([1.5,1.5], [-0.75,-0.325], linecolor="orange", fillcolor="white", label=false, linewidth=3)
+
+# level 2
+
+# upper right
+# 1
+plot!(Shape([(2,2),(2,1),(1,1),(1,2)].+[(0.75,0.5),(0.75,0.5),(0.75,0.5),(0.75,0.5)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(2,2),(2,1),(1,1),(1,2)].+[(0.75,0.5),(0.75,0.5),(0.75,0.5),(0.75,0.5)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([1.25,1.75], [2,2], linecolor="blue", fillcolor="white", label="interfaces", linewidth=3)
+plot!([2.25,2.25], [1.5,1], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+# 2
+plot!(Shape([(0,2),(1,2),(1,1),(0,1)].+[(0.25,0.5),(0.25,0.5),(0.25,0.5),(0.25,0.5)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(0,2),(1,2),(1,1),(0,1)].+[(0.25,0.5),(0.25,0.5),(0.25,0.5),(0.25,0.5)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-0.25,0.25], [2,2], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+plot!([0.75,0.75], [1.5,1], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+# 3
+plot!(Shape([(0,0),(0,1),(1,1),(1,0)].+[(0.25,0.),(0.25,0.),(0.25,0.),(0.25,0.)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(0,0),(0,1),(1,1),(1,0)].+[(0.25,0.),(0.25,0.),(0.25,0.),(0.25,0.)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([1.25,1.75], [.5,.5], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+plot!([-0.25,0.25], [.5,.5], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+# 4
+plot!(Shape([(2,0),(2,1),(1,1),(1,0)].+[(0.75,0.),(0.75,0.),(0.75,0.),(0.75,0.)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(2,0),(2,1),(1,1),(1,0)].+[(0.75,0.),(0.75,0.),(0.75,0.),(0.75,0.)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+# upper left
+# 1
+plot!(Shape([(-0,2),(-0,1),(-1,1),(-1,2)].+[(-0.25,0.5),(-0.25,0.5),(-0.25,0.5),(-0.25,0.5)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-0,2),(-0,1),(-1,1),(-1,2)].+[(-0.25,0.5),(-0.25,0.5),(-0.25,0.5),(-0.25,0.5)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-1.25,-1.75], [2,2], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+plot!([-0.75,-0.75], [1,1.5], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+# 2
+plot!(Shape([(-2,2),(-1,2),(-1,1),(-2,1)].+[(-0.75,0.5),(-0.75,0.5),(-0.75,0.5),(-0.75,0.5)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-2,2),(-1,2),(-1,1),(-2,1)].+[(-0.75,0.5),(-0.75,0.5),(-0.75,0.5),(-0.75,0.5)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-2.25,-2.25], [1,1.5], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+
+# 3
+plot!(Shape([(-2,0),(-2,1),(-1,1),(-1,0)].+[(-0.75,0.),(-0.75,0.),(-0.75,0.),(-0.75,0.)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-2,0),(-2,1),(-1,1),(-1,0)].+[(-0.75,0.),(-0.75,0.),(-0.75,0.),(-0.75,0.)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-1.75,-1.25], [.5,.5], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+plot!([-2.25,-2.25], [-0.5,0], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+# 4
+plot!(Shape([(-0,0),(-1,0),(-1,1),(-0,1)].+[(-0.25,0.),(-0.25,0.),(-0.25,0.),(-0.25,0.)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-0,0),(-1,0),(-1,1),(-0,1)].+[(-0.25,0.),(-0.25,0.),(-0.25,0.),(-0.25,0.)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-0.75,-0.75], [-0.5,0], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+# lower left
+# 1
+plot!(Shape([(-0,-0),(-0,-1),(-1,-1),(-1,-0)].+[(-0.25,-0.5),(-0.25,-0.5),(-0.25,-0.5),(-0.25,-0.5)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-0,-0),(-0,-1),(-1,-1),(-1,-0)].+[(-0.25,-0.5),(-0.25,-0.5),(-0.25,-0.5),(-0.25,-0.5)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-1.75,-1.25], [-1,-1], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+plot!([-0.75,-0.75], [-1.5,-2], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+
+# 2
+plot!(Shape([(-2,-1),(-2,0),(-1,-0),(-1,-1)].+[(-0.75,-0.5),(-0.75,-0.5),(-0.75,-0.5),(-0.75,-0.5)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-2,-1),(-2,0),(-1,-0),(-1,-1)].+[(-0.75,-0.5),(-0.75,-0.5),(-0.75,-0.5),(-0.75,-0.5)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-2.25,-2.25], [-1.5,-2], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+# 3
+plot!(Shape([(-2,-2),(-2,-1),(-1,-1),(-1,-2)].+[(-0.75,-1),(-0.75,-1),(-0.75,-1),(-0.75,-1)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-2.,-2.),(-2.,-1.),(-1.,-1.),(-1.,-2.)].+[(-0.75,-1),(-0.75,-1),(-0.75,-1),(-0.75,-1)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+plot!([-1.75,-1.25], [-2.5,-2.5], linecolor="blue", fillcolor="white", label=false, linewidth=3)
+
+# 4
+plot!(Shape([(-1,-2),(-1,-1),(-0,-1),(-0,-2)].+[(-0.25,-1),(-0.25,-1),(-0.25,-1),(-0.25,-1)]), linecolor="black", fillcolor="white", label=false, linewidth=2)
+
+nodes_2d=nodes_project_four([(-1.,-2.),(-1.,-1.),(-0.,-1.),(-0.,-2.)].+[(-0.25,-1),(-0.25,-1),(-0.25,-1),(-0.25,-1)])
+scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
+
+savefig("Issues/semidiscretize_issue#1215/mortars")
\ No newline at end of file
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_nodes_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_nodes_figure.jl
new file mode 100644
index 0000000000..19d5630b6f
--- /dev/null
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_nodes_figure.jl
@@ -0,0 +1,6 @@
+using Plots
+
+plot([-1,1],[0,0], linecolor="black", label="reference interval", size=(600, 200), ylim=(-0.5,0.5), yaxis=false, grid=false)
+scatter!([-1.0, -0.4472135954999579, 0.4472135954999579, 1.0],[0,0,0,0], color="red", label="Gauss-Lobatto nodes, N=4")
+
+savefig("Issues/semidiscretize_issue#1215/nodes")
\ No newline at end of file
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_treemesh_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_treemesh_figure.jl
new file mode 100644
index 0000000000..2efea8bd14
--- /dev/null
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_treemesh_figure.jl
@@ -0,0 +1,26 @@
+using Plots
+# level 0
+plot(Shape([(2,2),(2,-2),(-2,-2),(-2,2)]), linecolor="black", fillcolor="white", label="0th level, root", linewidth=2, size=(600,600))
+# level 1
+plot!(Shape([(1.97,1.97),(1.97,0),(0,0),(0,1.97)]), linecolor="red", fillcolor="white", label="1st level", linewidth=2)
+plot!(Shape([(-1.97,1.97),(0,1.97),(0,0),(-1.97,0)]), linecolor="red", fillcolor="white", label=false, linewidth=2)
+plot!(Shape([(-1.97,0),(0,0),(0,-1.97),(-1.97,-1.97)]), linecolor="red", fillcolor="white", label=false, linewidth=2)
+plot!(Shape([(1.97,0),(1.97,-1.97),(0,-1.97),(0,0)]), linecolor="red", fillcolor="white", label=false, linewidth=2)
+# level 2
+# upper right
+plot!(Shape([(1.94,1.94),(1.94,1),(1,1),(1,1.94)]), linecolor="blue", fillcolor="white", label="2nd level", linewidth=2)
+plot!(Shape([(0.03,1.94),(1,1.94),(1,1),(0.03,1)]), linecolor="blue", fillcolor="white", label=false, linewidth=2)
+plot!(Shape([(0.03,0.03),(0.03,1),(1,1),(1,0.03)]), linecolor="blue", fillcolor="white", label=false, linewidth=2)
+plot!(Shape([(1.94,0.03),(1.94,1),(1,1),(1,0.03)]), linecolor="blue", fillcolor="white", label=false, linewidth=2)
+# upper left
+plot!(Shape([(-0.03,1.94),(-0.03,1),(-1,1),(-1,1.94)]), linecolor="blue", fillcolor="white", label=false, linewidth=2)
+plot!(Shape([(-1.94,1.94),(-1,1.94),(-1,1),(-1.94,1)]), linecolor="blue", fillcolor="white", label=false, linewidth=2)
+plot!(Shape([(-1.94,0.03),(-1.94,1),(-1,1),(-1,0.03)]), linecolor="blue", fillcolor="white", label=false, linewidth=2)
+plot!(Shape([(-0.03,0.03),(-1,0.03),(-1,1),(-0.03,1)]), linecolor="blue", fillcolor="white", label=false, linewidth=2)
+# lower left
+plot!(Shape([(-0.03,-0.03),(-0.03,-1),(-1,-1),(-1,-0.03)]), linecolor="blue", fillcolor="white", label=false, linewidth=2)
+plot!(Shape([(-1.94,-1),(-1.94,-0.03),(-1,-0.03),(-1,-1)]), linecolor="blue", fillcolor="white", label=false, linewidth=2)
+plot!(Shape([(-1.94,-1.94),(-1.94,-1),(-1,-1),(-1,-1.94)]), linecolor="blue", fillcolor="white", label=false, linewidth=2)
+plot!(Shape([(-1,-1.94),(-1,-1),(-0.03,-1),(-0.03,-1.94)]), linecolor="blue", fillcolor="white", label=false, linewidth=2)
+
+savefig("Issues/semidiscretize_issue#1215/treemesh")
\ No newline at end of file
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/rhs_structure_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/rhs_structure_figure.jl
new file mode 100644
index 0000000000..510c78d78d
--- /dev/null
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/rhs_structure_figure.jl
@@ -0,0 +1,43 @@
+using Plots
+plot(Shape([(-0.4,0.5), (0.4,0.5), (0.4,-0.5), (-0.4,-0.5)]), linecolor="black", fillcolor="white", label=false,linewidth=2, size=(800,600), showaxis=false, grid=false, xlim=(-2,2), ylim=(-17.5,3))
+annotate!(0, 0, ("solve(...) call", 12, :black, :center))
+plot!([0,0],[-0.5,-2.5],arrow=true,color=:black,linewidth=2,label="")
+plot!(Shape([(-1.2,1), (1.2,1), (1.2,-1), (-1.2,-1)]), linecolor=:green, fillcolor=:transparent, label=false,linewidth=1, linestyle=:dash)
+annotate!(0.8, 0, ("Trixi.jl setup", 12, :green, :center))
+
+plot!(Shape([(-1.25,-2.5), (1.25,-2.5), (1.25,-3.5), (-1.25,-3.5)]), linecolor="black", fillcolor="white", label=false,linewidth=2)
+annotate!(0, -3, ("DiffEqBase.__solve(prob, alg, args...; kwargs...)", 12, :black, :center))
+plot!([0,0],[-3.5,-5.5],arrow=true,color=:black,linewidth=2,label="")
+plot!(Shape([(-1.9,-2), (1.9,-2), (1.9,-10), (-1.9,-10)]), linecolor=:red, fillcolor=:transparent, label=false,linewidth=1, linestyle=:dash)
+annotate!(1.4, -6, ("OrdinaryDiffEq.jl", 12, :red, :center))
+
+plot!(Shape([(-0.85,-5.5), (0.85,-5.5), (0.85,-6.5), (-0.85,-6.5)]), linecolor="black", fillcolor="white", label=false,linewidth=2)
+annotate!(0, -6, ("DiffEqBase.solve!(integrator)", 12, :black, :center))
+plot!([0,0],[-6.5,-8.5],arrow=true,color=:black,linewidth=2,label="")
+plot!([0,-0.5],[-6.5,-8.5],arrow=true,color=:black,linewidth=2,label="")
+plot!([0,0.5],[-6.5,-8.5],arrow=true,color=:black,linewidth=2,label="")
+annotate!(0.8, -7.5, ("Specialized for time \nintegration method", 9, :black, :center))
+
+plot!(Shape([(-1.2,-8.5), (1.2,-8.5), (1.2,-9.5), (-1.2,-9.5)]), linecolor="black", fillcolor="white", label=false,linewidth=2)
+annotate!(0, -9, ("perform_step!(integrator, integrator.cache)", 12, :black, :center))
+plot!([0,0],[-9.5,-11.5],arrow=true,color=:black,linewidth=2,label="")
+plot!([0,-0.5],[-9.5,-11.5],arrow=true,color=:black,linewidth=2,label="")
+plot!([0,0.5],[-9.5,-11.5],arrow=true,color=:black,linewidth=2,label="")
+annotate!(0.8, -10.5, ("Specialized for \nsemidiscretization", 9, :black, :center))
+
+plot!(Shape([(-0.95,-11.5), (0.95,-11.5), (0.95,-12.5), (-0.95,-12.5)]), linecolor="black", fillcolor="white", label=false,linewidth=2)
+annotate!(0, -12, ("Trixi.rhs!(du_ode, u_ode, semi, t)", 12, :black, :center))
+plot!([0,0],[-12.5,-14.5],arrow=true,color=:black,linewidth=2,label="")
+plot!([0,-0.5],[-12.5,-14.5],arrow=true,color=:black,linewidth=2,label="")
+plot!([0,0.5],[-12.5,-14.5],arrow=true,color=:black,linewidth=2,label="")
+annotate!(0.8, -13.5, ("Specialized for \nmesh and dg", 9, :black, :center))
+plot!(Shape([(-1.7,-11), (1.7,-11), (1.7,-17), (-1.7,-17)]), linecolor=:blue, fillcolor=:transparent, label=false,linewidth=1, linestyle=:dash)
+annotate!(1.5, -14, ("Trixi.jl", 12, :blue, :center))
+
+plot!(Shape([(-1.4,-14.5), (1.4,-14.5), (1.4,-16.5), (-1.4,-16.5)]), linecolor="black", fillcolor="white", label=false,linewidth=2)
+annotate!(0, -15.5, ("Trixi.rhs!(du, u, t, mesh, equations, initial_condition, \nboundary_conditions, source_terms, dg, cache)", 12, :black, :center))
+
+
+
+plot!([-2,2], [2,2], linecolor="white", fillcolor="white", label=false,linewidth=2)
+savefig("Issues/semidiscretize_issue#1215/rhs!")
\ No newline at end of file
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/semidiscretize_structure_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/semidiscretize_structure_figure.jl
new file mode 100644
index 0000000000..9c8d61dbb6
--- /dev/null
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/semidiscretize_structure_figure.jl
@@ -0,0 +1,51 @@
+using Plots
+plot(Shape([(-1.2,4), (1.2,4), (1.2,3), (-1.2,3)]), linecolor="black", fillcolor="white", label=false,linewidth=2, size=(800,600), showaxis=false, grid=false, xlim=(-2.6,2.6), ylim=(-21.5,4.5))
+annotate!(0, 3.5, ("semidiscretize(semi, tspan; reset_threads)", 10, :black, :center))
+annotate!(0, 2.5, ("creates and returns an ODEProblem object, initialized using rhs!, u0_ode, tspan and semi", 9, :black, :center))
+plot!([0,0],[2,0.5],arrow=true,color=:black,linewidth=2,label="")
+plot!([0,-0.2],[2,0.5],arrow=true,color=:black,linewidth=2,label="")
+plot!([0,0.2],[2,0.5],arrow=true,color=:black,linewidth=2,label="")
+annotate!(0.3,1.25, ("specialized for semi type", 9, :black, :left))
+
+plot!(Shape([(-1.6,0.5), (1.6,0.5), (1.6,-0.5), (-1.6,-0.5)]), linecolor="black", fillcolor="white", label=false,linewidth=2)
+annotate!(0, 0, ("compute_coefficients(t, semi::SemidiscretizationHyperbolic)", 10, :black, :center))
+plot!([0,0],[-0.5,-2],arrow=true,color=:black,linewidth=2,label="")
+
+plot!(Shape([(-1.3,-2), (1.3,-2), (1.3,-3), (-1.3,-3)]), linecolor="black", fillcolor="white", label=false,linewidth=2)
+annotate!(0, -2.5, ("compute_coefficients(initial_conditions, t, semi)", 10, :black, :center))
+plot!([0,0.2],[-3,-4.5],arrow=true,color=:black,linewidth=2,label="")
+plot!([0,-0.87],[-3,-9.5],arrow=true,color=:black,linewidth=2,label="")
+
+plot!(Shape([(0.1,-4.5), (2.5,-4.5), (2.5,-6.5), (0.1,-6.5)]), linecolor="black", fillcolor="white", label=false,linewidth=2)
+annotate!(0.15, -5.5, ("allocate_coefficients(mesh, equations, solver,
+                                 cache)", 10, :black, :left))
+annotate!(0.1, -8, ("initializes u_ode as a 1D zero-vector with a length
+depending on the number of variables, nodes,
+dimensions of mesh and elements, this vector is used
+by OrdinaryDiffEq.jl to keep a solution", 9, :black, :left))
+
+plot!(Shape([(-2.5,-9.5), (0.05,-9.5), (0.05,-11.5), (-2.5,-11.5)]), linecolor="black", fillcolor="white", label=false,linewidth=2)
+annotate!(-2.45, -10.5, ("compute_coefficients!(u_ode, initial_conditions,
+                                    t, semi)", 10, :black, :left))
+plot!([-2.4,-2.4],[-11.5,-18.5],arrow=false,color=:black,linewidth=2,label="")
+
+plot!(Shape([(-2.2,-13), (-0.8,-13), (-0.8,-14), (-2.2,-14)]), linecolor="black", fillcolor="white", label=false,linewidth=2)
+annotate!(-1.5, -13.5, ("wrap_array(u_ode, semi)", 10, :black, :center))
+annotate!(-2.2, -15.2, ("to simplify processing, it wraps the 1D array u_ode created in the allocate_coefficients function in
+a multidimensional one, where dimensions are responsible for variables, nodes on each axis and
+elements", 9, :black, :left))
+plot!([-2.4,-2.2],[-13.5,-13.5],arrow=true,color=:black,linewidth=2,label="")
+
+plot!(Shape([(-1.1,-17.5), (1.7,-17.5), (1.7,-19.5), (-1.1,-19.5)]), linecolor="black", fillcolor="white", label=false,linewidth=2)
+annotate!(-1.05, -18.5, ("compute_coefficients!(u, initial_conditions, t, mesh,
+                                    equations, solver, cache)", 10, :black, :left))
+annotate!(-1.1, -20.5, ("applies an initial conditions to each node of each element for each variable,
+saves in the wrapped u_ode", 9, :black, :left))
+plot!([-2.4,-1.1],[-18.5,-18.5],arrow=true,color=:black,linewidth=2,label="")
+plot!([-2.4,-1.1],[-18.5,-17.5],arrow=true,color=:black,linewidth=2,label="")
+plot!([-2.4,-1.1],[-18.5,-19.5],arrow=true,color=:black,linewidth=2,label="")
+annotate!(-2.4, -20.2, ("specialized for solver
+type and dimensionality
+of mesh", 9, :black, :left))
+
+savefig("Issues/semidiscretize_issue#1215/semidiscretize")
\ No newline at end of file

From 6d5cbb21908d7d607644bc4aa841983d95dd3536 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:42:59 +0200
Subject: [PATCH 31/74] Format_and_last_review_changes

---
 .../behind_the_scenes_simulation_setup.jl     | 30 ++++++++-----------
 docs/make.jl                                  |  3 +-
 2 files changed, 14 insertions(+), 19 deletions(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 762e74eda2..1bd0c53665 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -6,7 +6,6 @@
 # significant changes in the near future. The goal is to clarify some of the more fundamental, *technical* concepts that
 # are applicable to a variety of (also more complex) configurations.
 
-
 # ## Basic setup
 
 # Import essential libraries and specify an equation.
@@ -19,13 +18,12 @@ equations = inearScalarAdvectionEquation2D((-0.2, 0.7))
 coordinates_min = (-2.0, -2.0)
 coordinates_max = (2.0, 2.0)
 
-coarsening_patches = ( # Coarsen cell in the lower-right quarter
-  (type = "box", coordinates_min = [0.0, -2.0], coordinates_max = [2.0, 0.0]), 
-)
+coarsening_patches = ((type = "box", coordinates_min = [0.0, -2.0],
+                       coordinates_max = [2.0, 0.0]),)
 
- mesh = TreeMesh(coordinates_min, coordinates_max, initial_refinement_level=2, 
-                 n_cells_max=30_000,
-                 coarsening_patches=coarsening_patches)
+mesh = TreeMesh(coordinates_min, coordinates_max, initial_refinement_level = 2,
+                n_cells_max = 30_000,
+                coarsening_patches = coarsening_patches)
 
 # The created `TreeMesh` looks like the following:
 
@@ -36,13 +34,12 @@ coarsening_patches = ( # Coarsen cell in the lower-right quarter
 # the reference interval ``[-1, 1]`` in each spatial direction. These nodes will be subsequently used to approximate solutions
 # on each leaf cell of the `TreeMesh`.
 
-solver = DGSEM(polydeg=3)
+solver = DGSEM(polydeg = 3)
 
-# Gauss-Lobatto nodes with `N=4`:
+# Gauss-Lobatto nodes with `polydeg = 3`:
 
 # ![Gauss-Lobatto_nodes_example](https://github.com/trixi-framework/Trixi.jl/assets/119304909/401e5e85-026e-48b6-8a1f-dca0306f3bb0)
 
-
 # ## Overview of the [`SemidiscretizationHyperbolic`](@ref) type
 
 # At this stage, all necessary components for configuring the spatial discretization are in place.
@@ -50,13 +47,14 @@ solver = DGSEM(polydeg=3)
 # throughout the entire solving process. This is where [`SemidiscretizationHyperbolic`](@ref) comes
 # into play.
 
-semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergence_test, solver)
+semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergence_test,
+                                    solver)
 
 # The constructor for the `SemidiscretizationHyperbolic` object calls numerous sub-functions to perform the necessary
 # initialization steps. A brief description of the key sub-functions is provided below.
 
 # - `init_elements(leaf_cell_ids, mesh, equations, dg.basis, RealT, uEltype)`
- 
+
 #   The fundamental elements for approximating a solution are the leaf
 #   cells. This implies that on each leaf cell and in each spatial direction, the solution is treated as a polynomial of the
 #   degree specified in the `DGSEM` solver and evaluated at the Gauss-Lobatto nodes, which were
@@ -130,7 +128,6 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 
 # ![SemidiscretizationHyperbolic_structure](https://github.com/trixi-framework/Trixi.jl/assets/119304909/2cdfe3d1-f88a-4028-b83c-908d34d400cd)
 
-
 # ## Overview of the [`semidiscretize`](@ref) function
 
 # At this stage, we have defined the equations and configured the domain's discretization. The
@@ -143,7 +140,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 # function from the [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) package or to [`Trixi.solve`](@ref).
 
 ode = semidiscretize(semi, (0.0, 1.0));
- 
+
 # The `semidiscretize` function involves a deep tree of recursive calls, with the primary ones
 # explained below.
 
@@ -187,14 +184,14 @@ ode = semidiscretize(semi, (0.0, 1.0));
 
 # ![semidiscretize_structure](https://github.com/trixi-framework/Trixi.jl/assets/119304909/491eddc4-aadb-4e29-8c76-a7c821d0674e)
 
-
 # ## Functions `solve` and `rhs!`
 
 # Once the `ODEProblem` object is initialized, the `solve` function and one of the ODE solvers from
 # the OrdinaryDiffEq.jl package can be utilized to compute an approximated solution using the
 # instructions contained in the `ODEProblem` object.
 
-sol = solve(ode, CarpenterKennedy2N54(williamson_condition=false), dt=0.01, save_everystep=false);
+sol = solve(ode, CarpenterKennedy2N54(williamson_condition = false), dt = 0.01,
+            save_everystep = false);
 
 # Since the `solve` function and the ODE solver have no knowledge
 # of a particular spatial discretization, it is necessary to define a
@@ -226,4 +223,3 @@ using Plots
 plot(sol)
 pd = PlotData2D(sol)
 plot!(getmesh(pd))
-
diff --git a/docs/make.jl b/docs/make.jl
index e97727f422..76ed8a1de5 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -69,8 +69,7 @@ files = [
     "Explicit time stepping" => "time_stepping.jl",
     "Differentiable programming" => "differentiable_programming.jl",
     "Custom semidiscretizations" => "custom_semidiscretization.jl",
-    "Behind the scenes of a simulation setup"
-     => "behind_the_scenes_simulation_setup.jl",
+    "Behind the scenes of a simulation setup" => "behind_the_scenes_simulation_setup.jl",
     ]
 tutorials = create_tutorials(files)
 

From f3d8d6e319b20914b1c4270ce5bb754d37afa9a7 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 12:53:54 +0200
Subject: [PATCH 32/74] spell+output_directory_figures

---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 +-
 .../SemidiscretizationHyperbolic_structure_figure.jl          | 4 ++--
 .../generate_boundary_figure.jl                               | 2 +-
 .../generate_elements_figure.jl                               | 2 +-
 .../generate_interfaces_figure.jl                             | 2 +-
 .../generate_mortars_figure.jl                                | 2 +-
 .../generate_nodes_figure.jl                                  | 2 +-
 .../generate_treemesh_figure.jl                               | 2 +-
 .../rhs_structure_figure.jl                                   | 2 +-
 .../semidiscretize_structure_figure.jl                        | 2 +-
 10 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 1bd0c53665..23cc42ebed 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -126,7 +126,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 # functions called recursively. Without delving into details, the structure of the primary calls
 # can be illustrated as follows:
 
-# ![SemidiscretizationHyperbolic_structure](https://github.com/trixi-framework/Trixi.jl/assets/119304909/2cdfe3d1-f88a-4028-b83c-908d34d400cd)
+# ![SemidiscretizationHyperbolic_structure](https://github.com/trixi-framework/Trixi.jl/assets/119304909/8bf59422-0537-4d7a-9f13-d9b2253c19d7)
 
 # ## Overview of the [`semidiscretize`](@ref) function
 
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/SemidiscretizationHyperbolic_structure_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/SemidiscretizationHyperbolic_structure_figure.jl
index 64bf3af004..cae7b19d47 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/SemidiscretizationHyperbolic_structure_figure.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/SemidiscretizationHyperbolic_structure_figure.jl
@@ -3,7 +3,7 @@ plot(Shape([(-2.3,4.5), (2.35,4.5), (2.35,2.5), (-2.3,2.5)]), linecolor="black",
 annotate!(2.3, 3.5, ("SemidiscretizationHyperbolic(mesh, equations, initial_conditions, solver; source_terms,
 boundary_conditions, RealT, uEltype, initial_cache)          ", 10, :black, :right))
 annotate!(-2.3, 1.5, ("creates and returns SemidiscretizationHyperbolic object, initialized using a mesh, equations,
-initial_coditions, boundary_conditions, source_terms, solver and cache", 9, :black, :left))
+initial_conditions, boundary_conditions, source_terms, solver and cache", 9, :black, :left))
 plot!([-1.2,-1.2],[0.6,-2],arrow=true,color=:black,linewidth=2,label="")
 plot!([-1.2,-1.4],[0.6,-2],arrow=true,color=:black,linewidth=2,label="")
 plot!([-1.2,-1.],[0.6,-2],arrow=true,color=:black,linewidth=2,label="")
@@ -61,4 +61,4 @@ for 2D and 3D create_cache(mesh, equations, dg.mortar, uEltype)", 10, :black, :l
 annotate!(-2, -23.5, ("add specialized parts of the cache required to compute the volume integral, etc.", 9, :black, :left))
 plot!([-2.22,-2],[-22,-22],arrow=true,color=:black,linewidth=2,label="")
 
-savefig("Issues/semidiscretize_issue#1215/SemidiscretizationHyperbolic")
\ No newline at end of file
+savefig("./SemidiscretizationHyperbolic")
\ No newline at end of file
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_boundary_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_boundary_figure.jl
index 9648f7dc44..14475d2133 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_boundary_figure.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_boundary_figure.jl
@@ -187,4 +187,4 @@ scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize
 
 plot!([-0.25,-1.25], [-3,-3], linecolor="green", label=false, linewidth=15, opacity=0.3)
 
-savefig("Issues/semidiscretize_issue#1215/boundary")
\ No newline at end of file
+savefig("./boundary")
\ No newline at end of file
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_elements_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_elements_figure.jl
index df30fc2198..2cc007e077 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_elements_figure.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_elements_figure.jl
@@ -114,4 +114,4 @@ plot!(Shape([(-1,-2),(-1,-1),(-0,-1),(-0,-2)].+[(-0.25,-1),(-0.25,-1),(-0.25,-1)
 nodes_2d=nodes_project_four([(-1.,-2.),(-1.,-1.),(-0.,-1.),(-0.,-2.)].+[(-0.25,-1),(-0.25,-1),(-0.25,-1),(-0.25,-1)])
 scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
 
-#savefig("Issues/semidiscretize_issue#1215/elements")
\ No newline at end of file
+#savefig("./elements")
\ No newline at end of file
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_interfaces_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_interfaces_figure.jl
index 7c2585bb06..9d5e40722f 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_interfaces_figure.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_interfaces_figure.jl
@@ -154,4 +154,4 @@ plot!(Shape([(-1,-2),(-1,-1),(-0,-1),(-0,-2)].+[(-0.25,-1),(-0.25,-1),(-0.25,-1)
 nodes_2d=nodes_project_four([(-1.,-2.),(-1.,-1.),(-0.,-1.),(-0.,-2.)].+[(-0.25,-1),(-0.25,-1),(-0.25,-1),(-0.25,-1)])
 scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
 
-savefig("Issues/semidiscretize_issue#1215/interfaces")
\ No newline at end of file
+savefig("./interfaces")
\ No newline at end of file
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_mortars_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_mortars_figure.jl
index 9ca085546b..f48b410c42 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_mortars_figure.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_mortars_figure.jl
@@ -163,4 +163,4 @@ plot!(Shape([(-1,-2),(-1,-1),(-0,-1),(-0,-2)].+[(-0.25,-1),(-0.25,-1),(-0.25,-1)
 nodes_2d=nodes_project_four([(-1.,-2.),(-1.,-1.),(-0.,-1.),(-0.,-2.)].+[(-0.25,-1),(-0.25,-1),(-0.25,-1),(-0.25,-1)])
 scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
 
-savefig("Issues/semidiscretize_issue#1215/mortars")
\ No newline at end of file
+savefig("./mortars")
\ No newline at end of file
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_nodes_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_nodes_figure.jl
index 19d5630b6f..aff1e2d1d4 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_nodes_figure.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_nodes_figure.jl
@@ -3,4 +3,4 @@ using Plots
 plot([-1,1],[0,0], linecolor="black", label="reference interval", size=(600, 200), ylim=(-0.5,0.5), yaxis=false, grid=false)
 scatter!([-1.0, -0.4472135954999579, 0.4472135954999579, 1.0],[0,0,0,0], color="red", label="Gauss-Lobatto nodes, N=4")
 
-savefig("Issues/semidiscretize_issue#1215/nodes")
\ No newline at end of file
+savefig("./nodes")
\ No newline at end of file
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_treemesh_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_treemesh_figure.jl
index 2efea8bd14..8d2a8173a1 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_treemesh_figure.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_treemesh_figure.jl
@@ -23,4 +23,4 @@ plot!(Shape([(-1.94,-1),(-1.94,-0.03),(-1,-0.03),(-1,-1)]), linecolor="blue", fi
 plot!(Shape([(-1.94,-1.94),(-1.94,-1),(-1,-1),(-1,-1.94)]), linecolor="blue", fillcolor="white", label=false, linewidth=2)
 plot!(Shape([(-1,-1.94),(-1,-1),(-0.03,-1),(-0.03,-1.94)]), linecolor="blue", fillcolor="white", label=false, linewidth=2)
 
-savefig("Issues/semidiscretize_issue#1215/treemesh")
\ No newline at end of file
+savefig("./treemesh")
\ No newline at end of file
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/rhs_structure_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/rhs_structure_figure.jl
index 510c78d78d..19083dad68 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/rhs_structure_figure.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/rhs_structure_figure.jl
@@ -40,4 +40,4 @@ annotate!(0, -15.5, ("Trixi.rhs!(du, u, t, mesh, equations, initial_condition, \
 
 
 plot!([-2,2], [2,2], linecolor="white", fillcolor="white", label=false,linewidth=2)
-savefig("Issues/semidiscretize_issue#1215/rhs!")
\ No newline at end of file
+savefig("./rhs!")
\ No newline at end of file
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/semidiscretize_structure_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/semidiscretize_structure_figure.jl
index 9c8d61dbb6..52b0d573d7 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/semidiscretize_structure_figure.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/semidiscretize_structure_figure.jl
@@ -48,4 +48,4 @@ annotate!(-2.4, -20.2, ("specialized for solver
 type and dimensionality
 of mesh", 9, :black, :left))
 
-savefig("Issues/semidiscretize_issue#1215/semidiscretize")
\ No newline at end of file
+savefig("./semidiscretize")
\ No newline at end of file

From f9591f32c7d57e01349918d60cb46726f57ce1ff Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 13:34:37 +0200
Subject: [PATCH 33/74] spell

---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 23cc42ebed..70e3950189 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -11,7 +11,7 @@
 # Import essential libraries and specify an equation.
 
 using Trixi, OrdinaryDiffEq
-equations = inearScalarAdvectionEquation2D((-0.2, 0.7))
+equations = LinearScalarAdvectionEquation2D((-0.2, 0.7))
 
 # Generate a spatial discretization using a [`TreeMesh`](@ref) with a pre-coarsened set of cells.
 

From 9aa8dd0986f8d20c15256f975867245717eb7b06 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 13:47:14 +0200
Subject: [PATCH 34/74] N->polydeg

---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl   | 2 +-
 .../generate_nodes_figure.jl                                    | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 70e3950189..7d8f2a625f 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -38,7 +38,7 @@ solver = DGSEM(polydeg = 3)
 
 # Gauss-Lobatto nodes with `polydeg = 3`:
 
-# ![Gauss-Lobatto_nodes_example](https://github.com/trixi-framework/Trixi.jl/assets/119304909/401e5e85-026e-48b6-8a1f-dca0306f3bb0)
+# ![Gauss-Lobatto_nodes_example](https://github.com/trixi-framework/Trixi.jl/assets/119304909/1d894611-801e-4f75-bff0-d77ca1c672e5)
 
 # ## Overview of the [`SemidiscretizationHyperbolic`](@ref) type
 
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_nodes_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_nodes_figure.jl
index aff1e2d1d4..b983563f47 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_nodes_figure.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_nodes_figure.jl
@@ -1,6 +1,6 @@
 using Plots
 
 plot([-1,1],[0,0], linecolor="black", label="reference interval", size=(600, 200), ylim=(-0.5,0.5), yaxis=false, grid=false)
-scatter!([-1.0, -0.4472135954999579, 0.4472135954999579, 1.0],[0,0,0,0], color="red", label="Gauss-Lobatto nodes, N=4")
+scatter!([-1.0, -0.4472135954999579, 0.4472135954999579, 1.0],[0,0,0,0], color="red", label="Gauss-Lobatto nodes")
 
 savefig("./nodes")
\ No newline at end of file

From 971e875f5607afc92d7599a29b26894002f24e67 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 14:27:46 +0200
Subject: [PATCH 35/74] add README for plots

---
 .../files/behind_the_scenes_simulation_setup.jl    |  2 +-
 .../Project.toml                                   |  2 ++
 .../README.md                                      | 14 ++++++++++++++
 ...emidiscretizationHyperbolic_structure_figure.jl |  0
 .../{ => src}/generate_boundary_figure.jl          |  0
 .../{ => src}/generate_elements_figure.jl          |  2 +-
 .../{ => src}/generate_interfaces_figure.jl        |  0
 .../{ => src}/generate_mortars_figure.jl           |  0
 .../{ => src}/generate_nodes_figure.jl             |  0
 .../{ => src}/generate_treemesh_figure.jl          |  0
 .../{ => src}/rhs_structure_figure.jl              |  0
 .../{ => src}/semidiscretize_structure_figure.jl   |  0
 12 files changed, 18 insertions(+), 2 deletions(-)
 create mode 100644 docs/literate/src/files/behind_the_scenes_simulation_setup_plots/Project.toml
 create mode 100644 docs/literate/src/files/behind_the_scenes_simulation_setup_plots/README.md
 rename docs/literate/src/files/behind_the_scenes_simulation_setup_plots/{ => src}/SemidiscretizationHyperbolic_structure_figure.jl (100%)
 rename docs/literate/src/files/behind_the_scenes_simulation_setup_plots/{ => src}/generate_boundary_figure.jl (100%)
 rename docs/literate/src/files/behind_the_scenes_simulation_setup_plots/{ => src}/generate_elements_figure.jl (99%)
 rename docs/literate/src/files/behind_the_scenes_simulation_setup_plots/{ => src}/generate_interfaces_figure.jl (100%)
 rename docs/literate/src/files/behind_the_scenes_simulation_setup_plots/{ => src}/generate_mortars_figure.jl (100%)
 rename docs/literate/src/files/behind_the_scenes_simulation_setup_plots/{ => src}/generate_nodes_figure.jl (100%)
 rename docs/literate/src/files/behind_the_scenes_simulation_setup_plots/{ => src}/generate_treemesh_figure.jl (100%)
 rename docs/literate/src/files/behind_the_scenes_simulation_setup_plots/{ => src}/rhs_structure_figure.jl (100%)
 rename docs/literate/src/files/behind_the_scenes_simulation_setup_plots/{ => src}/semidiscretize_structure_figure.jl (100%)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 7d8f2a625f..1b8e7f8e3c 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -62,7 +62,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 #   from the `TreeMesh`, assigns them the label "elements", records their coordinates, and maps the
 #   Gauss-Lobatto nodes from the 1D interval ``[-1, 1]`` onto each axis of every element.
 
-#   ![elements_example](https://github.com/trixi-framework/Trixi.jl/assets/119304909/534131bd-e85b-43d5-860d-2db6e60ce921)
+#   ![elements_example](https://github.com/trixi-framework/Trixi.jl/assets/119304909/9f486670-b579-4e42-8697-439540c8bbb4)
 
 #   The visualization of elements with nodes shown here includes spaces between elements, which do not exist
 #   in reality. This spacing is included only for illustrative purposes to underscore the
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/Project.toml b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/Project.toml
new file mode 100644
index 0000000000..43aec5b7f5
--- /dev/null
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/Project.toml
@@ -0,0 +1,2 @@
+[deps]
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/README.md b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/README.md
new file mode 100644
index 0000000000..c202f52170
--- /dev/null
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/README.md
@@ -0,0 +1,14 @@
+# Plots for the tutorial "Behind the scenes of a simulation setup"
+
+To create all the images from the directory of this README, one should execute the following 
+command.
+```julia
+julia> include.(readdir("src"; join=true))
+```
+To create all images from a different directory, substitute "src" with the PATH to the "src" 
+folder. The resulting images will be generated in your present directory as PNG files.
+
+To generate a specific image, run the following command while replacing "path/to/src" and "file_name" with the appropriate values.
+```julia
+julia> include(joinpath("path/to/src", "file_name"))
+```
\ No newline at end of file
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/SemidiscretizationHyperbolic_structure_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/src/SemidiscretizationHyperbolic_structure_figure.jl
similarity index 100%
rename from docs/literate/src/files/behind_the_scenes_simulation_setup_plots/SemidiscretizationHyperbolic_structure_figure.jl
rename to docs/literate/src/files/behind_the_scenes_simulation_setup_plots/src/SemidiscretizationHyperbolic_structure_figure.jl
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_boundary_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/src/generate_boundary_figure.jl
similarity index 100%
rename from docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_boundary_figure.jl
rename to docs/literate/src/files/behind_the_scenes_simulation_setup_plots/src/generate_boundary_figure.jl
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_elements_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/src/generate_elements_figure.jl
similarity index 99%
rename from docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_elements_figure.jl
rename to docs/literate/src/files/behind_the_scenes_simulation_setup_plots/src/generate_elements_figure.jl
index 2cc007e077..6a98467a4e 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_elements_figure.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/src/generate_elements_figure.jl
@@ -114,4 +114,4 @@ plot!(Shape([(-1,-2),(-1,-1),(-0,-1),(-0,-2)].+[(-0.25,-1),(-0.25,-1),(-0.25,-1)
 nodes_2d=nodes_project_four([(-1.,-2.),(-1.,-1.),(-0.,-1.),(-0.,-2.)].+[(-0.25,-1),(-0.25,-1),(-0.25,-1),(-0.25,-1)])
 scatter!(nodes_2d[:,1], nodes_2d[:,2], color = "red", label = false, markersize = 5)
 
-#savefig("./elements")
\ No newline at end of file
+savefig("./elements")
\ No newline at end of file
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_interfaces_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/src/generate_interfaces_figure.jl
similarity index 100%
rename from docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_interfaces_figure.jl
rename to docs/literate/src/files/behind_the_scenes_simulation_setup_plots/src/generate_interfaces_figure.jl
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_mortars_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/src/generate_mortars_figure.jl
similarity index 100%
rename from docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_mortars_figure.jl
rename to docs/literate/src/files/behind_the_scenes_simulation_setup_plots/src/generate_mortars_figure.jl
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_nodes_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/src/generate_nodes_figure.jl
similarity index 100%
rename from docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_nodes_figure.jl
rename to docs/literate/src/files/behind_the_scenes_simulation_setup_plots/src/generate_nodes_figure.jl
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_treemesh_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/src/generate_treemesh_figure.jl
similarity index 100%
rename from docs/literate/src/files/behind_the_scenes_simulation_setup_plots/generate_treemesh_figure.jl
rename to docs/literate/src/files/behind_the_scenes_simulation_setup_plots/src/generate_treemesh_figure.jl
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/rhs_structure_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/src/rhs_structure_figure.jl
similarity index 100%
rename from docs/literate/src/files/behind_the_scenes_simulation_setup_plots/rhs_structure_figure.jl
rename to docs/literate/src/files/behind_the_scenes_simulation_setup_plots/src/rhs_structure_figure.jl
diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/semidiscretize_structure_figure.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/src/semidiscretize_structure_figure.jl
similarity index 100%
rename from docs/literate/src/files/behind_the_scenes_simulation_setup_plots/semidiscretize_structure_figure.jl
rename to docs/literate/src/files/behind_the_scenes_simulation_setup_plots/src/semidiscretize_structure_figure.jl

From 42e04b8adc6ac8ab87f1d6368ee196da1f44b5eb Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 3 Nov 2023 15:59:02 +0200
Subject: [PATCH 36/74] line length <=100

---
 .../behind_the_scenes_simulation_setup.jl     | 60 ++++++++++---------
 1 file changed, 33 insertions(+), 27 deletions(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 1b8e7f8e3c..45456077e6 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -2,9 +2,10 @@
 
 # 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 this setup
-# does not cover all details, it is based on relatively stable parts of Trixi.jl that are unlikely to undergo
-# significant changes in the near future. The goal is to clarify some of the more fundamental, *technical* concepts that
-# are applicable to a variety of (also more complex) configurations.
+# does not cover all details, it is based on relatively stable parts of Trixi.jl that are unlikely
+# to undergo significant changes in the near future. The goal is to clarify some of the more
+# fundamental, *technical* concepts that are applicable to a variety of (also more complex)
+# configurations.
 
 # ## Basic setup
 
@@ -31,8 +32,8 @@ mesh = TreeMesh(coordinates_min, coordinates_max, initial_refinement_level = 2,
 
 # Instantiate a [`DGSEM`](@ref) solver with a user-specified polynomial degree. The solver
 # will define `polydeg + 1` Gauss-Lobatto nodes and their associated weights within
-# the reference interval ``[-1, 1]`` in each spatial direction. These nodes will be subsequently used to approximate solutions
-# on each leaf cell of the `TreeMesh`.
+# the reference interval ``[-1, 1]`` in each spatial direction. These nodes will be subsequently
+# used to approximate solutions on each leaf cell of the `TreeMesh`.
 
 solver = DGSEM(polydeg = 3)
 
@@ -50,22 +51,24 @@ solver = DGSEM(polydeg = 3)
 semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergence_test,
                                     solver)
 
-# The constructor for the `SemidiscretizationHyperbolic` object calls numerous sub-functions to perform the necessary
-# initialization steps. A brief description of the key sub-functions is provided below.
+# The constructor for the `SemidiscretizationHyperbolic` object calls numerous sub-functions to
+# perform the necessary initialization steps. A brief description of the key sub-functions is
+# provided below.
 
 # - `init_elements(leaf_cell_ids, mesh, equations, dg.basis, RealT, uEltype)`
 
 #   The fundamental elements for approximating a solution are the leaf
-#   cells. This implies that on each leaf cell and in each spatial direction, the solution is treated as a polynomial of the
-#   degree specified in the `DGSEM` solver and evaluated at the Gauss-Lobatto nodes, which were
-#   previously illustrated. The `init_elements` function extracts these leaf cells
-#   from the `TreeMesh`, assigns them the label "elements", records their coordinates, and maps the
-#   Gauss-Lobatto nodes from the 1D interval ``[-1, 1]`` onto each axis of every element.
+#   cells. This implies that on each leaf cell and in each spatial direction, the solution is
+#   treated as a polynomial of the degree specified in the `DGSEM` solver and evaluated at the
+#   Gauss-Lobatto nodes, which were previously illustrated. The `init_elements` function extracts
+#   these leaf cells from the `TreeMesh`, assigns them the label "elements", records their
+#   coordinates, and maps the Gauss-Lobatto nodes from the 1D interval ``[-1, 1]`` onto each axis
+#   of every element.
 
 #   ![elements_example](https://github.com/trixi-framework/Trixi.jl/assets/119304909/9f486670-b579-4e42-8697-439540c8bbb4)
 
-#   The visualization of elements with nodes shown here includes spaces between elements, which do not exist
-#   in reality. This spacing is included only for illustrative purposes to underscore the
+#   The visualization of elements with nodes shown here includes spaces between elements, which do
+#   not exist in reality. This spacing is included only for illustrative purposes to underscore the
 #   separation of elements and the independent projection of nodes onto each element.
 
 # - `init_interfaces(leaf_cell_ids, mesh, elements)`
@@ -88,8 +91,8 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 # - `init_mortars(leaf_cell_ids, mesh, elements, dg.mortar)`
 
 #   Returning to the consideration of different sizes among adjacent elements, within the
-#   `TreeMesh`, adjacent leaf cells can vary in side length by a maximum factor of two. This implies
-#   that a large element has one neighbor of
+#   `TreeMesh`, adjacent leaf cells can vary in side length by a maximum factor of two. This
+#   implies that a large element has one neighbor of
 #   equal size with a connection through an interface, or two neighbors at half the size,
 #   requiring a connection through so called "mortars". In 3D, a large element would have
 #   four small neighbor elements.
@@ -117,10 +120,10 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 # object of type `SemidiscretizationHyperbolic` is initialized using this cache, initial and
 # boundary conditions, equations, mesh and solver.
 
-# In conclusion, a `HyperbolicSemidiscretization`'s primary purpose is to collect equations, the geometric
-# representation of the domain, and approximation instructions, creating specialized structures to
-# interconnect these components in a manner that enables their utilization for the numerical
-# solution of partial differential equations (PDEs).
+# In conclusion, a `HyperbolicSemidiscretization`'s primary purpose is to collect equations, the
+# geometric representation of the domain, and approximation instructions, creating specialized
+# structures to interconnect these components in a manner that enables their utilization for
+# the numerical solution of partial differential equations (PDEs).
 
 # As evident from the earlier description of `SemidiscretizationHyperbolic`, it comprises numerous
 # functions called recursively. Without delving into details, the structure of the primary calls
@@ -137,7 +140,8 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 # The purpose of the [`semidiscretize`](@ref) function is to wrap the semidiscretization as an
 # `ODEProblem` within the specified time interval, while also applying the initial conditions at
 # the initial time. This `ODEProblem` can be subsequently passed to the `solve`
-# function from the [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) package or to [`Trixi.solve`](@ref).
+# function from the [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) package or to
+# [`Trixi.solve`](@ref).
 
 ode = semidiscretize(semi, (0.0, 1.0));
 
@@ -146,11 +150,12 @@ ode = semidiscretize(semi, (0.0, 1.0));
 
 # - `allocate_coefficients(mesh, equations, solver, cache)`
 
-#   To apply initial conditions, a data structure ("container") needs to be generated to store the initial values of
-#   the target variables for each node within each element. The `allocate_coefficients` function
-#   initializes `u_ode` as a 1D vector with a length that depends on the number of variables,
-#   elements, nodes, and dimensions. The use of a 1D vector format allows one to resize the mesh (and thus change the number of elements)
-#   while utilizing the functionalities of OrdinaryDiffEq.jl.
+#   To apply initial conditions, a data structure ("container") needs to be generated to store the
+#   initial values of the target variables for each node within each element. The
+#   `allocate_coefficients` function initializes `u_ode` as a 1D vector with a length that depends
+#   on the number of variables, elements, nodes, and dimensions. The use of a 1D vector format
+#   allows one to resize the mesh (and thus change the number of elements) while utilizing the
+#   functionalities of OrdinaryDiffEq.jl.
 
 # - `wrap_array(u_ode, semi)`
 
@@ -197,7 +202,8 @@ sol = solve(ode, CarpenterKennedy2N54(williamson_condition = false), dt = 0.01,
 # of a particular spatial discretization, it is necessary to define a
 # "right-hand-side function", `rhs!`, within Trixi.jl.
 
-# Trixi.jl includes a set of `rhs!` functions designed to compute `du`, i.e., ``\partial u/\partial t`` according to the structure
+# Trixi.jl includes a set of `rhs!` functions designed to compute `du`, i.e.,
+# ``\partial u/\partial t`` according to the structure
 # of the setup. These `rhs!` functions calculate interface, mortars, and boundary fluxes, in
 # addition to surface and volume integrals, in order to construct the `du` vector. This `du` vector
 # is then used by the time integration method to obtain the solution at the subsequent time step.

From 837cff711e05a594f74548c3e89dece76f84e32f Mon Sep 17 00:00:00 2001
From: Michael Schlottke-Lakemper <michael@sloede.com>
Date: Wed, 8 Nov 2023 11:46:38 +0100
Subject: [PATCH 37/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup_plots/README.md

---
 .../README.md                                         | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/README.md b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/README.md
index c202f52170..011b5c7586 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/README.md
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup_plots/README.md
@@ -1,14 +1,15 @@
 # Plots for the tutorial "Behind the scenes of a simulation setup"
 
-To create all the images from the directory of this README, one should execute the following 
-command.
+To create all the images for the tutorial, execute the following command from the directory of this `README.md`:
 ```julia
+pkg> activate .
 julia> include.(readdir("src"; join=true))
 ```
-To create all images from a different directory, substitute "src" with the PATH to the "src" 
-folder. The resulting images will be generated in your present directory as PNG files.
+To create all images from a different directory, substitute `"src"` with the path to the `src` 
+folder. The resulting images will be generated in your current directory as PNG files.
 
-To generate a specific image, run the following command while replacing "path/to/src" and "file_name" with the appropriate values.
+To generate a specific image, run the following command while replacing `"path/to/src"` and `"file_name"` with the appropriate values:
 ```julia
+pkg> activate .
 julia> include(joinpath("path/to/src", "file_name"))
 ```
\ No newline at end of file

From 49b5516b57a6c2f745b9ecaa6f0a56c06f0138c7 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 10 Nov 2023 08:38:10 +0200
Subject: [PATCH 38/74] add empty lines

---
 .../src/files/behind_the_scenes_simulation_setup.jl       | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 45456077e6..25fece0ed0 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -55,6 +55,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 # perform the necessary initialization steps. A brief description of the key sub-functions is
 # provided below.
 
+
 # - `init_elements(leaf_cell_ids, mesh, equations, dg.basis, RealT, uEltype)`
 
 #   The fundamental elements for approximating a solution are the leaf
@@ -65,12 +66,14 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 #   coordinates, and maps the Gauss-Lobatto nodes from the 1D interval ``[-1, 1]`` onto each axis
 #   of every element.
 
+
 #   ![elements_example](https://github.com/trixi-framework/Trixi.jl/assets/119304909/9f486670-b579-4e42-8697-439540c8bbb4)
 
 #   The visualization of elements with nodes shown here includes spaces between elements, which do
 #   not exist in reality. This spacing is included only for illustrative purposes to underscore the
 #   separation of elements and the independent projection of nodes onto each element.
 
+
 # - `init_interfaces(leaf_cell_ids, mesh, elements)`
 
 #   At this point, the elements with nodes have been defined; however, they lack the necessary
@@ -88,6 +91,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 
 #   ![interfaces_example](https://github.com/trixi-framework/Trixi.jl/assets/119304909/bc3b6b02-afbc-4371-aaf7-c7bdc5a6c540)
 
+
 # - `init_mortars(leaf_cell_ids, mesh, elements, dg.mortar)`
 
 #   Returning to the consideration of different sizes among adjacent elements, within the
@@ -104,6 +108,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 
 #   ![mortars_example](https://github.com/trixi-framework/Trixi.jl/assets/119304909/43a95a60-3a31-4b1f-8724-14049e7a0481)
 
+
 # - `init_boundaries(leaf_cell_ids, mesh, elements)`
 
 #   In order to apply boundary conditions, it is necessary to identify the locations of the
@@ -148,6 +153,7 @@ ode = semidiscretize(semi, (0.0, 1.0));
 # The `semidiscretize` function involves a deep tree of recursive calls, with the primary ones
 # explained below.
 
+
 # - `allocate_coefficients(mesh, equations, solver, cache)`
 
 #   To apply initial conditions, a data structure ("container") needs to be generated to store the
@@ -157,6 +163,7 @@ ode = semidiscretize(semi, (0.0, 1.0));
 #   allows one to resize the mesh (and thus change the number of elements) while utilizing the
 #   functionalities of OrdinaryDiffEq.jl.
 
+
 # - `wrap_array(u_ode, semi)`
 
 #   As previously noted, `u_ode` is constructed as a 1D vector to ensure compatibility with
@@ -173,6 +180,7 @@ ode = semidiscretize(semi, (0.0, 1.0));
 #   This is possible because, from a storage perspective, they share the same stored data, while
 #   access to this data is provided in different ways.
 
+
 # - `compute_coefficients!(u, initial_conditions, t, mesh::DG, equations, solver, cache)`
 
 #   Now the variable `u`, intended to store solutions, has been allocated and wrapped, it is time

From f5674ff0031ea37d46e9f2b417cdf27656b25e41 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 12 Nov 2023 21:31:08 +0200
Subject: [PATCH 39/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl

Co-authored-by: Andrew Winters <andrew.ross.winters@liu.se>
---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 25fece0ed0..2fd9e7342b 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -1,7 +1,7 @@
 #src # Behind the scenes of a 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 this setup
+# happens in the background during the initialization of a simulation. While the setup described herein
 # does not cover all details, it is based on relatively stable parts of Trixi.jl that are unlikely
 # to undergo significant changes in the near future. The goal is to clarify some of the more
 # fundamental, *technical* concepts that are applicable to a variety of (also more complex)

From 7da1488312b11934540d4b8dbe7bca4e7af17add Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 12 Nov 2023 21:31:30 +0200
Subject: [PATCH 40/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl

Co-authored-by: Andrew Winters <andrew.ross.winters@liu.se>
---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 2fd9e7342b..1ea6ea2747 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -2,7 +2,7 @@
 
 # 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 described herein
-# does not cover all details, it is based on relatively stable parts of Trixi.jl that are unlikely
+# does not cover all details, it is involves relatively stable parts of Trixi.jl that are unlikely
 # to undergo significant changes in the near future. The goal is to clarify some of the more
 # fundamental, *technical* concepts that are applicable to a variety of (also more complex)
 # configurations.

From 91fac7f9d47b60b48b8f18b8cbce36796758dd0b Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 12 Nov 2023 21:31:53 +0200
Subject: [PATCH 41/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl

Co-authored-by: Andrew Winters <andrew.ross.winters@liu.se>
---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 1ea6ea2747..83f958a4e5 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -45,7 +45,7 @@ solver = DGSEM(polydeg = 3)
 
 # At this stage, all necessary components for configuring the spatial discretization are in place.
 # The remaining task is to combine these components into a single structure that will be used
-# throughout the entire solving process. This is where [`SemidiscretizationHyperbolic`](@ref) comes
+# throughout the entire simulation process. This is where [`SemidiscretizationHyperbolic`](@ref) comes
 # into play.
 
 semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergence_test,

From 691887e7f94233f5f59ed7ef669164391187e399 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 12 Nov 2023 21:32:25 +0200
Subject: [PATCH 42/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl

Co-authored-by: Andrew Winters <andrew.ross.winters@liu.se>
---
 .../src/files/behind_the_scenes_simulation_setup.jl         | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 83f958a4e5..55192bc261 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -59,9 +59,9 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 # - `init_elements(leaf_cell_ids, mesh, equations, dg.basis, RealT, uEltype)`
 
 #   The fundamental elements for approximating a solution are the leaf
-#   cells. This implies that on each leaf cell and in each spatial direction, the solution is
-#   treated as a polynomial of the degree specified in the `DGSEM` solver and evaluated at the
-#   Gauss-Lobatto nodes, which were previously illustrated. The `init_elements` function extracts
+#   cells. The solution is treated as a polynomial of the degree specified in the `DGSEM`
+#   solver in each spatial direction on each leaf cell. This polynomial approximation is evaluated 
+#   at the Gauss-Lobatto nodes, which were previously illustrated. The `init_elements` function extracts
 #   these leaf cells from the `TreeMesh`, assigns them the label "elements", records their
 #   coordinates, and maps the Gauss-Lobatto nodes from the 1D interval ``[-1, 1]`` onto each axis
 #   of every element.

From 2843ca9d9004ec0c54450348f8b2114a817649b2 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 12 Nov 2023 21:32:48 +0200
Subject: [PATCH 43/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl

Co-authored-by: Andrew Winters <andrew.ross.winters@liu.se>
---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 55192bc261..15d590d8e7 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -84,7 +84,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 #   As demonstrated earlier, the elements can have varying sizes. Let us initially consider
 #   neighbors with equal size. For these elements, the `init_interfaces` function generates
 #   interfaces that store information about adjacent elements, their relative positions, and
-#   allocate containers for sharing solutions between neighbors during the solving process. 
+#   allocate containers for sharing solution data between neighbors during the solution process. 
 
 #   In our visualization, these interfaces would conceptually resemble tubes connecting the
 #   corresponding elements.

From cbbcc626376502255527b3a50d3ebc6c37025412 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 12 Nov 2023 21:33:17 +0200
Subject: [PATCH 44/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl

Co-authored-by: Andrew Winters <andrew.ross.winters@liu.se>
---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 15d590d8e7..fdfe14dcd9 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -132,7 +132,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 
 # As evident from the earlier description of `SemidiscretizationHyperbolic`, it comprises numerous
 # functions called recursively. Without delving into details, the structure of the primary calls
-# can be illustrated as follows:
+# are illustrated as follows:
 
 # ![SemidiscretizationHyperbolic_structure](https://github.com/trixi-framework/Trixi.jl/assets/119304909/8bf59422-0537-4d7a-9f13-d9b2253c19d7)
 

From d7b1f40549646b56132b5cd2e512ba01bb77d092 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 12 Nov 2023 21:33:52 +0200
Subject: [PATCH 45/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl

Co-authored-by: Andrew Winters <andrew.ross.winters@liu.se>
---
 .../literate/src/files/behind_the_scenes_simulation_setup.jl | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index fdfe14dcd9..317548372a 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -143,8 +143,9 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 # conditions, which are already stored in the initialized `SemidiscretizationHyperbolic` object.
 
 # The purpose of the [`semidiscretize`](@ref) function is to wrap the semidiscretization as an
-# `ODEProblem` within the specified time interval, while also applying the initial conditions at
-# the initial time. This `ODEProblem` can be subsequently passed to the `solve`
+# `ODEProblem` within the specified time interval. During this procedure the approximate solution
+#  is created at the given initial time via the specified `initial_condition` function from the 
+#  `SemidiscretizationHyperbolic` object. This `ODEProblem` can be subsequently passed to the `solve`
 # function from the [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) package or to
 # [`Trixi.solve`](@ref).
 

From 01232990a66b6b345f619c6f5fa3de0ce42166e2 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sat, 3 Feb 2024 13:51:28 +0200
Subject: [PATCH 46/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl

Co-authored-by: Joshua Lampert <51029046+JoshuaLampert@users.noreply.github.com>
---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 317548372a..8cb747ac07 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -2,7 +2,7 @@
 
 # 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 described herein
-# does not cover all details, it is involves relatively stable parts of Trixi.jl that are unlikely
+# does not cover all details, it involves relatively stable parts of Trixi.jl that are unlikely
 # to undergo significant changes in the near future. The goal is to clarify some of the more
 # fundamental, *technical* concepts that are applicable to a variety of (also more complex)
 # configurations.

From 01e875a1fa8d2fb3815dbd01a8496080f676e0d4 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sat, 3 Feb 2024 13:41:16 +0200
Subject: [PATCH 47/74] mention method of lines

---
 .../src/files/behind_the_scenes_simulation_setup.jl         | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 8cb747ac07..ea9a46f2a1 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -7,6 +7,12 @@
 # fundamental, *technical* concepts that are applicable to a variety of (also more complex)
 # configurations.
 
+# Trixi.jl follows the method of lines concept for solving partial differential equations.
+# Firstly, the partial differential equations are reduced to an ordinary differential equations
+# by discretizing the space. Subsequently, these new ODEs are solved with methods available in
+# OrdinaryDiffEq.jl or those specifically implemented in Trixi.jl. The following steps elucidate
+# the process of transitioning from PDEs to ODEs within the framework of Trixi.jl.
+
 # ## Basic setup
 
 # Import essential libraries and specify an equation.

From 09484d418e891dade2cd72171047e42262a6e044 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sat, 3 Feb 2024 14:58:34 +0200
Subject: [PATCH 48/74] Update behind_the_scenes_simulation_setup.jl

---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index ea9a46f2a1..fcbec64016 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -244,3 +244,5 @@ using Plots
 plot(sol)
 pd = PlotData2D(sol)
 plot!(getmesh(pd))
+
+Sys.rm("out"; recursive=true, force=true) #hide #md

From af01b53a7e3ad4588c1ab3f0d8c8190cb15181aa Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sat, 3 Feb 2024 23:26:54 +0200
Subject: [PATCH 49/74] Update behind_the_scenes_simulation_setup.jl

---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 --
 1 file changed, 2 deletions(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index fcbec64016..ea9a46f2a1 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -244,5 +244,3 @@ using Plots
 plot(sol)
 pd = PlotData2D(sol)
 plot!(getmesh(pd))
-
-Sys.rm("out"; recursive=true, force=true) #hide #md

From 2872a7d06db84689959726cd3790694a2395e60c Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 4 Feb 2024 11:54:16 +0200
Subject: [PATCH 50/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl

Co-authored-by: Joshua Lampert <51029046+JoshuaLampert@users.noreply.github.com>
---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index ea9a46f2a1..0073acf463 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -131,7 +131,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 # object of type `SemidiscretizationHyperbolic` is initialized using this cache, initial and
 # boundary conditions, equations, mesh and solver.
 
-# In conclusion, a `HyperbolicSemidiscretization`'s primary purpose is to collect equations, the
+# In conclusion, the primary purpose of a `SemidiscretizationHyperbolic` is to collect equations, the
 # geometric representation of the domain, and approximation instructions, creating specialized
 # structures to interconnect these components in a manner that enables their utilization for
 # the numerical solution of partial differential equations (PDEs).

From e2909f914a6caa0395c3fba9311b4e14c3874632 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 11 Feb 2024 18:05:05 +0200
Subject: [PATCH 51/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl

Co-authored-by: Daniel Doehring <doehringd2@gmail.com>
---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 0073acf463..5f575a4c77 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -8,7 +8,7 @@
 # configurations.
 
 # Trixi.jl follows the method of lines concept for solving partial differential equations.
-# Firstly, the partial differential equations are reduced to an ordinary differential equations
+# Firstly, the partial differential equations (PDEs) are reduced to a (potentially huge) system of ordinary differential equations (ODEs)
 # by discretizing the space. Subsequently, these new ODEs are solved with methods available in
 # OrdinaryDiffEq.jl or those specifically implemented in Trixi.jl. The following steps elucidate
 # the process of transitioning from PDEs to ODEs within the framework of Trixi.jl.

From 74d901663e7bf9fe9ed4ee58102fa301ce8da538 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 11 Feb 2024 18:05:24 +0200
Subject: [PATCH 52/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl

Co-authored-by: Daniel Doehring <doehringd2@gmail.com>
---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 5f575a4c77..a7988eaa30 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -9,7 +9,7 @@
 
 # Trixi.jl follows the method of lines concept for solving partial differential equations.
 # Firstly, the partial differential equations (PDEs) are reduced to a (potentially huge) system of ordinary differential equations (ODEs)
-# by discretizing the space. Subsequently, these new ODEs are solved with methods available in
+# by discretizing the spatial derivatives. Subsequently, these new ODEs are solved with methods available in
 # OrdinaryDiffEq.jl or those specifically implemented in Trixi.jl. The following steps elucidate
 # the process of transitioning from PDEs to ODEs within the framework of Trixi.jl.
 

From 5d873b5e16896781cd77a2cce773da96c8cdfc25 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 11 Feb 2024 18:05:31 +0200
Subject: [PATCH 53/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl

Co-authored-by: Daniel Doehring <doehringd2@gmail.com>
---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index a7988eaa30..9f9b7b9a8c 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -64,7 +64,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 
 # - `init_elements(leaf_cell_ids, mesh, equations, dg.basis, RealT, uEltype)`
 
-#   The fundamental elements for approximating a solution are the leaf
+#   The fundamental elements for approximating the solution are the leaf
 #   cells. The solution is treated as a polynomial of the degree specified in the `DGSEM`
 #   solver in each spatial direction on each leaf cell. This polynomial approximation is evaluated 
 #   at the Gauss-Lobatto nodes, which were previously illustrated. The `init_elements` function extracts

From 48bec7ffb15f516c44155aba937a8b20f60b3904 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 11 Feb 2024 18:05:46 +0200
Subject: [PATCH 54/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl

Co-authored-by: Daniel Doehring <doehringd2@gmail.com>
---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 9f9b7b9a8c..27dba62a8b 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -65,7 +65,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 # - `init_elements(leaf_cell_ids, mesh, equations, dg.basis, RealT, uEltype)`
 
 #   The fundamental elements for approximating the solution are the leaf
-#   cells. The solution is treated as a polynomial of the degree specified in the `DGSEM`
+#   cells. The solution is constructed as a polynomial of the degree specified in the `DGSEM`
 #   solver in each spatial direction on each leaf cell. This polynomial approximation is evaluated 
 #   at the Gauss-Lobatto nodes, which were previously illustrated. The `init_elements` function extracts
 #   these leaf cells from the `TreeMesh`, assigns them the label "elements", records their

From d2ef3a3e96d064cdf6be86b5c1a4058fd5a8a0e1 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 11 Feb 2024 18:06:05 +0200
Subject: [PATCH 55/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl

Co-authored-by: Daniel Doehring <doehringd2@gmail.com>
---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 27dba62a8b..7d822c58c6 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -67,7 +67,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 #   The fundamental elements for approximating the solution are the leaf
 #   cells. The solution is constructed as a polynomial of the degree specified in the `DGSEM`
 #   solver in each spatial direction on each leaf cell. This polynomial approximation is evaluated 
-#   at the Gauss-Lobatto nodes, which were previously illustrated. The `init_elements` function extracts
+#   at the Gauss-Lobatto nodes mentioned earlier. The `init_elements` function extracts
 #   these leaf cells from the `TreeMesh`, assigns them the label "elements", records their
 #   coordinates, and maps the Gauss-Lobatto nodes from the 1D interval ``[-1, 1]`` onto each axis
 #   of every element.

From 7f8d27cf96154b302bf235f0f4c333f94f7a2881 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 11 Feb 2024 18:06:20 +0200
Subject: [PATCH 56/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl

Co-authored-by: Daniel Doehring <doehringd2@gmail.com>
---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 7d822c58c6..4db0324591 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -83,7 +83,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 # - `init_interfaces(leaf_cell_ids, mesh, elements)`
 
 #   At this point, the elements with nodes have been defined; however, they lack the necessary
-#   communication functionality. This is crucial because the solutions on the elements are not
+#   communication functionality. This is crucial because the local solution polynomials on the elements are not
 #   independent of each other. Furthermore, nodes on the boundary of adjacent elements share
 #   the same spatial location, requiring a method to combine their solutions.
 

From d338f6e2f5c296d9c41ade446155e63cbf0d2d8d Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 11 Feb 2024 18:07:05 +0200
Subject: [PATCH 57/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl

Co-authored-by: Daniel Doehring <doehringd2@gmail.com>
---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 4db0324591..e59e89319a 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -85,7 +85,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 #   At this point, the elements with nodes have been defined; however, they lack the necessary
 #   communication functionality. This is crucial because the local solution polynomials on the elements are not
 #   independent of each other. Furthermore, nodes on the boundary of adjacent elements share
-#   the same spatial location, requiring a method to combine their solutions.
+#   the same spatial location, which requires a method to combine this into a meaningful solution.
 
 #   As demonstrated earlier, the elements can have varying sizes. Let us initially consider
 #   neighbors with equal size. For these elements, the `init_interfaces` function generates

From 8624a241053557f173f7329f0d9dc957de48709d Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 11 Feb 2024 18:08:19 +0200
Subject: [PATCH 58/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl

Co-authored-by: Daniel Doehring <doehringd2@gmail.com>
---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index e59e89319a..d6ba59be0b 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -218,7 +218,7 @@ sol = solve(ode, CarpenterKennedy2N54(williamson_condition = false), dt = 0.01,
 # "right-hand-side function", `rhs!`, within Trixi.jl.
 
 # Trixi.jl includes a set of `rhs!` functions designed to compute `du`, i.e.,
-# ``\partial u/\partial t`` according to the structure
+# ``\frac{\partial u}{\partial t}`` according to the structure
 # of the setup. These `rhs!` functions calculate interface, mortars, and boundary fluxes, in
 # addition to surface and volume integrals, in order to construct the `du` vector. This `du` vector
 # is then used by the time integration method to obtain the solution at the subsequent time step.

From aae8546a024e3c9d0a88d2e52b9bcd7098002990 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 11 Feb 2024 18:09:54 +0200
Subject: [PATCH 59/74] simplify rhs description

---
 .../src/files/behind_the_scenes_simulation_setup.jl  | 12 ++++--------
 1 file changed, 4 insertions(+), 8 deletions(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index d6ba59be0b..f4fc81d202 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -225,14 +225,10 @@ sol = solve(ode, CarpenterKennedy2N54(williamson_condition = false), dt = 0.01,
 # The `rhs!` function is called by time integration methods in each iteration of the solve loop
 # within OrdinaryDiffEq.jl, with arguments `du`, `u`, `semidiscretization`, and the current time.
 
-# The problem is that `rhs!` functions within Trixi.jl are specialized for specific solver and mesh
-# types. However, the types of arguments passed to `rhs!` by time integration methods do not
-# explicitly provide this information. Consequently, Trixi.jl uses a two-levels approach for `rhs!`
-# functions. The first level is limited to a single function for each `semidiscretization` type,
-# and its role is to redirect data to the target `rhs!`. It performs this by extracting the
-# necessary data from the integrator and passing them, along with the originally received
-# arguments, to the specialized for solver and mesh types `rhs!` function, which is
-# responsible for calculating `du`.
+# Trixi.jl uses a two-levels approach for `rhs!` functions. The first level is limited to a
+# single function for each `semidiscretization` type, and its role is to redirect data to the
+# target `rhs!` for specific solver and mesh types. This target `rhs!` function is responsible
+# for calculating `du`.
 
 # Path from the `solve` function call to the appropriate `rhs!` function call:
 

From c3d140dd0fe47f4b8d817f044a36c0608c060e44 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 11 Feb 2024 18:23:42 +0200
Subject: [PATCH 60/74] format

---
 .../behind_the_scenes_simulation_setup.jl     | 46 ++++++++++---------
 1 file changed, 24 insertions(+), 22 deletions(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index f4fc81d202..1fa2cec299 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -1,17 +1,18 @@
 #src # Behind the scenes of a 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 described herein
-# does not cover all details, it involves relatively stable parts of Trixi.jl that are unlikely
-# to undergo significant changes in the near future. The goal is to clarify some of the more
-# fundamental, *technical* concepts that are applicable to a variety of (also more complex)
-# configurations.
+# 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
+# described herein does not cover all details, it involves relatively stable parts of Trixi.jl that
+# are unlikely to undergo significant changes in the near future. The goal is to clarify some of
+# the more fundamental, *technical* concepts that are applicable to a variety of
+# (also more complex) configurations.
 
 # Trixi.jl follows the method of lines concept for solving partial differential equations.
-# Firstly, the partial differential equations (PDEs) are reduced to a (potentially huge) system of ordinary differential equations (ODEs)
-# by discretizing the spatial derivatives. Subsequently, these new ODEs are solved with methods available in
-# OrdinaryDiffEq.jl or those specifically implemented in Trixi.jl. The following steps elucidate
-# the process of transitioning from PDEs to ODEs within the framework of Trixi.jl.
+# Firstly, the partial differential equations (PDEs) are reduced to a (potentially huge) system of
+# ordinary differential equations (ODEs) by discretizing the spatial derivatives. Subsequently,
+# these new ODEs are solved with methods available in OrdinaryDiffEq.jl or those specifically
+# implemented in Trixi.jl. The following steps elucidate the process of transitioning from PDEs to
+# ODEs within the framework of Trixi.jl.
 
 # ## Basic setup
 
@@ -51,8 +52,8 @@ solver = DGSEM(polydeg = 3)
 
 # At this stage, all necessary components for configuring the spatial discretization are in place.
 # The remaining task is to combine these components into a single structure that will be used
-# throughout the entire simulation process. This is where [`SemidiscretizationHyperbolic`](@ref) comes
-# into play.
+# throughout the entire simulation process. This is where [`SemidiscretizationHyperbolic`](@ref)
+# comes into play.
 
 semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergence_test,
                                     solver)
@@ -83,9 +84,10 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 # - `init_interfaces(leaf_cell_ids, mesh, elements)`
 
 #   At this point, the elements with nodes have been defined; however, they lack the necessary
-#   communication functionality. This is crucial because the local solution polynomials on the elements are not
-#   independent of each other. Furthermore, nodes on the boundary of adjacent elements share
-#   the same spatial location, which requires a method to combine this into a meaningful solution.
+#   communication functionality. This is crucial because the local solution polynomials on the
+#   elements are not independent of each other. Furthermore, nodes on the boundary of adjacent
+#   elements share the same spatial location, which requires a method to combine this into a
+#   meaningful solution.
 
 #   As demonstrated earlier, the elements can have varying sizes. Let us initially consider
 #   neighbors with equal size. For these elements, the `init_interfaces` function generates
@@ -127,12 +129,12 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 
 #   ![boundaries_example](https://github.com/trixi-framework/Trixi.jl/assets/119304909/21996b20-4a22-4dfb-b16a-e2c22c2f29fe)
 
-# All the structures mentioned earlier are collected as a cache of type `NamedTuple`. Subsequently, an
-# object of type `SemidiscretizationHyperbolic` is initialized using this cache, initial and
+# All the structures mentioned earlier are collected as a cache of type `NamedTuple`. Subsequently,
+# an object of type `SemidiscretizationHyperbolic` is initialized using this cache, initial and
 # boundary conditions, equations, mesh and solver.
 
-# In conclusion, the primary purpose of a `SemidiscretizationHyperbolic` is to collect equations, the
-# geometric representation of the domain, and approximation instructions, creating specialized
+# In conclusion, the primary purpose of a `SemidiscretizationHyperbolic` is to collect equations,
+# the geometric representation of the domain, and approximation instructions, creating specialized
 # structures to interconnect these components in a manner that enables their utilization for
 # the numerical solution of partial differential equations (PDEs).
 
@@ -151,9 +153,9 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 # The purpose of the [`semidiscretize`](@ref) function is to wrap the semidiscretization as an
 # `ODEProblem` within the specified time interval. During this procedure the approximate solution
 #  is created at the given initial time via the specified `initial_condition` function from the 
-#  `SemidiscretizationHyperbolic` object. This `ODEProblem` can be subsequently passed to the `solve`
-# function from the [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) package or to
-# [`Trixi.solve`](@ref).
+#  `SemidiscretizationHyperbolic` object. This `ODEProblem` can be subsequently passed to the
+# `solve` function from the [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) package
+# or to [`Trixi.solve`](@ref).
 
 ode = semidiscretize(semi, (0.0, 1.0));
 

From 501b9d5e74d5e3572291000dfdc21b9043784a4a Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 11 Feb 2024 19:32:23 +0200
Subject: [PATCH 61/74] add interpolation to mortars

---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 1fa2cec299..68fd45102a 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -112,6 +112,10 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 #   Mortars store information about the connected elements, their relative positions, and allocate
 #   containers for storing the solutions along the boundaries between these elements.
 
+#   Due to the differing sizes of adjacent elements, it is not feasible to directly map boundary
+#   nodes of adjacent elements. Therefore, the concept of mortars employs a mass-conserving
+#   interpolation function to map boundary nodes from a larger element to a smaller one.
+
 #   In our visualization, mortars are represented as branched tubes.
 
 #   ![mortars_example](https://github.com/trixi-framework/Trixi.jl/assets/119304909/43a95a60-3a31-4b1f-8724-14049e7a0481)

From 072346b3c1582c812c1b0356b158dd9f1036735b Mon Sep 17 00:00:00 2001
From: Daniel Doehring <doehringd2@gmail.com>
Date: Sun, 11 Feb 2024 19:35:11 +0100
Subject: [PATCH 62/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl

---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 68fd45102a..7b043d8036 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -7,8 +7,8 @@
 # the more fundamental, *technical* concepts that are applicable to a variety of
 # (also more complex) configurations.
 
-# Trixi.jl follows the method of lines concept for solving partial differential equations.
-# Firstly, the partial differential equations (PDEs) are reduced to a (potentially huge) system of
+# Trixi.jl follows the method of lines concept for solving partial differential equations (PDEs).
+# Firstly, the PDEs are reduced to a (potentially huge) system of
 # ordinary differential equations (ODEs) by discretizing the spatial derivatives. Subsequently,
 # these new ODEs are solved with methods available in OrdinaryDiffEq.jl or those specifically
 # implemented in Trixi.jl. The following steps elucidate the process of transitioning from PDEs to

From 2c9c31049b9f2802d044b2d75bfc18972a80eeb0 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 11 Feb 2024 20:41:29 +0200
Subject: [PATCH 63/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl

Co-authored-by: Daniel Doehring <doehringd2@gmail.com>
---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 7b043d8036..63da75cc68 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -10,7 +10,7 @@
 # Trixi.jl follows the method of lines concept for solving partial differential equations (PDEs).
 # Firstly, the PDEs are reduced to a (potentially huge) system of
 # ordinary differential equations (ODEs) by discretizing the spatial derivatives. Subsequently,
-# these new ODEs are solved with methods available in OrdinaryDiffEq.jl or those specifically
+# these generated ODEs may be solved with methods available in OrdinaryDiffEq.jl or those specifically
 # implemented in Trixi.jl. The following steps elucidate the process of transitioning from PDEs to
 # ODEs within the framework of Trixi.jl.
 

From 623b74884900c39db6debfaa559b54694448cf3c Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 11 Feb 2024 20:41:55 +0200
Subject: [PATCH 64/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl

Co-authored-by: Daniel Doehring <doehringd2@gmail.com>
---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 63da75cc68..04043b9a11 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -38,7 +38,7 @@ mesh = TreeMesh(coordinates_min, coordinates_max, initial_refinement_level = 2,
 # ![TreeMesh_example](https://github.com/trixi-framework/Trixi.jl/assets/119304909/d5ef76ee-8246-4730-a692-b472c06063a3)
 
 # Instantiate a [`DGSEM`](@ref) solver with a user-specified polynomial degree. The solver
-# will define `polydeg + 1` Gauss-Lobatto nodes and their associated weights within
+# will define `polydeg + 1` [Gauss-Lobatto nodes](https://en.wikipedia.org/wiki/Gaussian_quadrature#Gauss%E2%80%93Lobatto_rules) and their associated weights within
 # the reference interval ``[-1, 1]`` in each spatial direction. These nodes will be subsequently
 # used to approximate solutions on each leaf cell of the `TreeMesh`.
 

From 244d6f8845517ea9eac2773d558f200864073267 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 11 Feb 2024 20:42:13 +0200
Subject: [PATCH 65/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl

Co-authored-by: Daniel Doehring <doehringd2@gmail.com>
---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 04043b9a11..810683dea6 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -7,7 +7,7 @@
 # the more fundamental, *technical* concepts that are applicable to a variety of
 # (also more complex) configurations.
 
-# Trixi.jl follows the method of lines concept for solving partial differential equations (PDEs).
+# Trixi.jl follows the [method of lines](http://www.scholarpedia.org/article/Method_of_lines) concept for solving partial differential equations (PDEs).
 # Firstly, the PDEs are reduced to a (potentially huge) system of
 # ordinary differential equations (ODEs) by discretizing the spatial derivatives. Subsequently,
 # these generated ODEs may be solved with methods available in OrdinaryDiffEq.jl or those specifically

From 0ca226d1167873c3dcc8488724667bafd31ec43d Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 11 Feb 2024 20:42:22 +0200
Subject: [PATCH 66/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl

Co-authored-by: Daniel Doehring <doehringd2@gmail.com>
---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 810683dea6..9092903c6d 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -70,7 +70,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 #   solver in each spatial direction on each leaf cell. This polynomial approximation is evaluated 
 #   at the Gauss-Lobatto nodes mentioned earlier. The `init_elements` function extracts
 #   these leaf cells from the `TreeMesh`, assigns them the label "elements", records their
-#   coordinates, and maps the Gauss-Lobatto nodes from the 1D interval ``[-1, 1]`` onto each axis
+#   coordinates, and maps the Gauss-Lobatto nodes from the 1D interval ``[-1, 1]`` onto each coordinate axis
 #   of every element.
 
 

From 1eb79973cba4ac4c4613d1600627b5056495f061 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 11 Feb 2024 20:29:56 +0200
Subject: [PATCH 67/74] add resizability explanation

---
 .../src/files/behind_the_scenes_simulation_setup.jl    | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 9092903c6d..61979b5e27 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -170,12 +170,12 @@ ode = semidiscretize(semi, (0.0, 1.0));
 # - `allocate_coefficients(mesh, equations, solver, cache)`
 
 #   To apply initial conditions, a data structure ("container") needs to be generated to store the
-#   initial values of the target variables for each node within each element. The
-#   `allocate_coefficients` function initializes `u_ode` as a 1D vector with a length that depends
-#   on the number of variables, elements, nodes, and dimensions. The use of a 1D vector format
-#   allows one to resize the mesh (and thus change the number of elements) while utilizing the
-#   functionalities of OrdinaryDiffEq.jl.
+#   initial values of the target variables for each node within each element.
 
+#   Since only one-dimensional `Array`s are `resize!`able in Julia, we use `Vector`s as an internal
+#   storage for the target variables and `resize!` them whenever needed, e.g. to change the number
+#   of elements. Then, during the solving process the same memory is reused by `unsafe_wrap`ping
+#   multi-dimensional `Array`s around the internal storage.
 
 # - `wrap_array(u_ode, semi)`
 

From 9d9a541ebf474b47cc9a146c7446f6800097351f Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 11 Feb 2024 20:31:23 +0200
Subject: [PATCH 68/74] Update behind_the_scenes_simulation_setup.jl

---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 61979b5e27..40098f211f 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -163,7 +163,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 
 ode = semidiscretize(semi, (0.0, 1.0));
 
-# The `semidiscretize` function involves a deep tree of recursive calls, with the primary ones
+# The `semidiscretize` function involves a deep tree of subsequent calls, with the primary ones
 # explained below.
 
 

From 9ebd5e4003478b1f7292808507fa3bccac128011 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 11 Feb 2024 21:33:08 +0200
Subject: [PATCH 69/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl

Co-authored-by: Daniel Doehring <doehringd2@gmail.com>
---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 40098f211f..56672fb631 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -88,6 +88,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 #   elements are not independent of each other. Furthermore, nodes on the boundary of adjacent
 #   elements share the same spatial location, which requires a method to combine this into a
 #   meaningful solution.
+# Here [Riemann solvers](https://en.wikipedia.org/wiki/Riemann_solver#Approximate_solvers) come into play which can handle the principal ambiguity of a multi-valued solution at the same spatial location.
 
 #   As demonstrated earlier, the elements can have varying sizes. Let us initially consider
 #   neighbors with equal size. For these elements, the `init_interfaces` function generates

From c39e5d92d317206515c182e87ff05647dbadfe43 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Sun, 11 Feb 2024 20:34:20 +0200
Subject: [PATCH 70/74] format

---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 56672fb631..3bef250abd 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -88,7 +88,9 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 #   elements are not independent of each other. Furthermore, nodes on the boundary of adjacent
 #   elements share the same spatial location, which requires a method to combine this into a
 #   meaningful solution.
-# Here [Riemann solvers](https://en.wikipedia.org/wiki/Riemann_solver#Approximate_solvers) come into play which can handle the principal ambiguity of a multi-valued solution at the same spatial location.
+#   Here [Riemann solvers](https://en.wikipedia.org/wiki/Riemann_solver#Approximate_solvers)
+#   come into play which can handle the principal ambiguity of a multi-valued solution at the
+#   same spatial location.
 
 #   As demonstrated earlier, the elements can have varying sizes. Let us initially consider
 #   neighbors with equal size. For these elements, the `init_interfaces` function generates

From 7ff423c2acdc85c83eb4de102ed3f8e9c5c38b84 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Tue, 13 Feb 2024 11:03:46 +0200
Subject: [PATCH 71/74] add introduction as 2nd tutorial

---
 docs/literate/src/files/index.jl | 43 +++++++++++++++++++-------------
 docs/make.jl                     |  2 +-
 2 files changed, 26 insertions(+), 19 deletions(-)

diff --git a/docs/literate/src/files/index.jl b/docs/literate/src/files/index.jl
index 1fc025d84d..c72bc7e45b 100644
--- a/docs/literate/src/files/index.jl
+++ b/docs/literate/src/files/index.jl
@@ -21,20 +21,27 @@
 # fundamental structure of a Trixi.jl setup, the visualization of results, and the development
 # process for Trixi.jl.
 
-# ### [2 Introduction to DG methods](@ref scalar_linear_advection_1d)
+# ### [2 Behind the scenes of a simulation setup](@ref behind_the_scenes_simulation_setup)
+#-
+# 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.
+
+# ### [3 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.
 
-# ### [3 DGSEM with flux differencing](@ref DGSEM_FluxDiff)
+# ### [4 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.
 
-# ### [4 Shock capturing with flux differencing and stage limiter](@ref shock_capturing)
+# ### [5 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
@@ -42,20 +49,20 @@
 # explained and added to an exemplary simulation of the Sedov blast wave with the 2D compressible Euler
 # equations.
 
-# ### [5 Non-periodic boundary conditions](@ref non_periodic_boundaries)
+# ### [6 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.
 
-# ### [6 DG schemes via `DGMulti` solver](@ref DGMulti_1)
+# ### [7 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).
 
-# ### [7 Other SBP schemes (FD, CGSEM) via `DGMulti` solver](@ref DGMulti_2)
+# ### [8 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
@@ -63,7 +70,7 @@
 # For instance, we show how to set up a finite differences (FD) scheme and a continuous Galerkin
 # (CGSEM) method.
 
-# ### [8 Upwind FD SBP schemes](@ref upwind_fdsbp)
+# ### [9 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
@@ -71,42 +78,42 @@
 # schemes in the `DGMulti` framework, the interface is based on the package
 # [SummationByPartsOperators.jl](https://github.com/ranocha/SummationByPartsOperators.jl).
 
-# ### [9 Adding a new scalar conservation law](@ref adding_new_scalar_equations)
+# ### [10 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.
 
-# ### [10 Adding a non-conservative equation](@ref adding_nonconservative_equation)
+# ### [11 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.
 
-# ### [11 Parabolic terms](@ref parabolic_terms)
+# ### [12 Parabolic terms](@ref parabolic_terms)
 #-
 # This tutorial describes how parabolic terms are implemented in Trixi.jl, e.g.,
 # to solve the advection-diffusion equation.
 
-# ### [12 Adding new parabolic terms](@ref adding_new_parabolic_terms)
+# ### [13 Adding new parabolic terms](@ref adding_new_parabolic_terms)
 #-
 # This tutorial describes how new parabolic terms can be implemented using Trixi.jl.
 
-# ### [13 Adaptive mesh refinement](@ref adaptive_mesh_refinement)
+# ### [14 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.
 
-# ### [14 Structured mesh with curvilinear mapping](@ref structured_mesh_mapping)
+# ### [15 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.
 
-# ### [15 Unstructured meshes with HOHQMesh.jl](@ref hohqmesh_tutorial)
+# ### [16 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
@@ -115,26 +122,26 @@
 # 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`.
 
-# ### [16 P4est mesh from gmsh](@ref p4est_from_gmsh)
+# ### [17 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.
 
-# ### [17 Explicit time stepping](@ref time_stepping)
+# ### [18 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.
 
-# ### [18 Differentiable programming](@ref differentiable_programming)
+# ### [19 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.
 
-# ### [19 Custom semidiscretization](@ref custom_semidiscretization)
+# ### [20 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.
diff --git a/docs/make.jl b/docs/make.jl
index d8e98ee96c..c3b52bda9a 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -54,6 +54,7 @@ files = [
         "Create first setup" => ("first_steps", "create_first_setup.jl"),
         "Changing Trixi.jl itself" => ("first_steps", "changing_trixi.jl"),
     ],
+    "Behind the scenes of a simulation setup" => "behind_the_scenes_simulation_setup.jl",
     # Topic: DG semidiscretizations
     "Introduction to DG methods" => "scalar_linear_advection_1d.jl",
     "DGSEM with flux differencing" => "DGSEM_FluxDiff.jl",
@@ -76,7 +77,6 @@ files = [
     "Explicit time stepping" => "time_stepping.jl",
     "Differentiable programming" => "differentiable_programming.jl",
     "Custom semidiscretizations" => "custom_semidiscretization.jl",
-    "Behind the scenes of a simulation setup" => "behind_the_scenes_simulation_setup.jl",
     ]
 tutorials = create_tutorials(files)
 

From c16b49706a37e147144c12cc6414ae226aa311df Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Tue, 13 Feb 2024 11:05:04 +0200
Subject: [PATCH 72/74] fix

---
 docs/literate/src/files/index.jl | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/docs/literate/src/files/index.jl b/docs/literate/src/files/index.jl
index c72bc7e45b..6d5800c3b6 100644
--- a/docs/literate/src/files/index.jl
+++ b/docs/literate/src/files/index.jl
@@ -23,10 +23,12 @@
 
 # ### [2 Behind the scenes of a simulation setup](@ref behind_the_scenes_simulation_setup)
 #-
-# 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.
+# 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
+# described herein does not cover all details, it involves relatively stable parts of Trixi.jl that
+# are unlikely to undergo significant changes in the near future. The goal is to clarify some of
+# 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)
 #-

From 49fb0076df7327b2dea40b13fd3b1aeef97347f6 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Thu, 15 Feb 2024 14:35:23 +0200
Subject: [PATCH 73/74] Update
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl

Co-authored-by: Joshua Lampert <51029046+JoshuaLampert@users.noreply.github.com>
---
 docs/literate/src/files/behind_the_scenes_simulation_setup.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 3bef250abd..900bd86623 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -146,7 +146,7 @@ semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergen
 # the numerical solution of partial differential equations (PDEs).
 
 # As evident from the earlier description of `SemidiscretizationHyperbolic`, it comprises numerous
-# functions called recursively. Without delving into details, the structure of the primary calls
+# functions called subsequently. Without delving into details, the structure of the primary calls
 # are illustrated as follows:
 
 # ![SemidiscretizationHyperbolic_structure](https://github.com/trixi-framework/Trixi.jl/assets/119304909/8bf59422-0537-4d7a-9f13-d9b2253c19d7)

From a502c36b97bcb36f27301af3e0a3a87f88ffa622 Mon Sep 17 00:00:00 2001
From: ArseniyKholod <119304909+ArseniyKholod@users.noreply.github.com>
Date: Fri, 16 Feb 2024 10:32:23 +0200
Subject: [PATCH 74/74] add unsafe_wrap explanation

---
 .../src/files/behind_the_scenes_simulation_setup.jl         | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
index 900bd86623..c93660e9bc 100644
--- a/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
+++ b/docs/literate/src/files/behind_the_scenes_simulation_setup.jl
@@ -186,8 +186,10 @@ ode = semidiscretize(semi, (0.0, 1.0));
 #   OrdinaryDiffEq.jl. However, for internal use within Trixi.jl, identifying which part of the
 #   vector relates to specific variables, elements, or nodes can be challenging.
 
-#   This is why the `u_ode` vector is wrapped by the `wrap_array` function to create a
-#   multidimensional array `u`, with each dimension representing variables, nodes and elements.
+#   This is why the `u_ode` vector is wrapped by the `wrap_array` function using `unsafe_wrap`
+#   to form a multidimensional array `u`. In this array, the first dimension corresponds to
+#   variables, followed by N dimensions corresponding to nodes for each of N space dimensions.
+#   The last dimension corresponds to the elements. 
 #   Consequently, navigation within this multidimensional array becomes noticeably easier.
 
 #   "Wrapping" in this context involves the creation of a reference to the same storage location