SimpleDiscontinuousGalerkin.jl API

SimpleDiscontinuousGalerkin

SimpleDiscontinuousGalerkin.jl is a Julia package that implements some basic discontinuous Galerkin (DG) methods for the solution of hyperbolic partial differential equations (PDEs). The package is designed to be simple and easy to use and understand. It is intended for educational purposes and to provide a starting point for more complex DG methods. For a more comprehensive and advanced implementation of DG methods, we recommend using the package Trixi.jl. This package can be understood as a minimalistic version of Trixi.jl, which is designed to be easy to understand and modify. Many design concepts are inspired by Trixi.jl, but the implementation is much simpler and more straightforward.

SimpleDiscontinuousGalerkin.jl builds on the foundations of the package SummationByPartsOperators.jl.

See also: SimpleDiscontinuousGalerkin.jl

AbstractEquations{NDIMS, NVARS}

An abstract supertype of specific equations such as the linear advection equation. The type parameters encode the number of spatial dimensions (NDIMS) and the number of primary variables (NVARS) of the physics model.

cons2cons(u, equations)

Return the conservative variables u. While this function is as trivial as identity, it is also as useful.

cons2entropy(u, equations)

Return the entropy variables from the conservative variables u for the given system of equations. The entropy variables are defined as the derivative of the entropy with respect to the conservative variables.

default_analysis_errors(equations)

Default analysis errors used by the AnalysisCallback.

default_analysis_integrals(equations)

Default analysis integrals used by the AnalysisCallback.

eachvariable(equations::AbstractEquations)

Return an iterator over the indices that specify the location in relevant data structures for the variables in equations. In particular, not the variables themselves are returned.

entropy(u, equations)

Return the entropy of the conservative variables u for the given system of equations.

entropy_timederivative

The semi-discrete time derivative of the entropy, which can be used in the AnalysisCallback to compute the time derivative of the entropy.

get_name(equations::AbstractEquations)

Return the canonical, human-readable name for the given system of equations.

Examples

julia> SimpleDiscontinuousGalerkin.get_name(LinearAdvectionEquation1D(1.0))
"LinearAdvectionEquation1D"

mass(u, equations)

Return the mass of the conservative variables u for the given system of equations.

LinearAdvectionEquation1D

The linear scalar advection equation

\[\partial_t u + a \partial_1 u = 0\]

in one space dimension with constant velocity a.

flux_godunov(u_ll, u_rr, equations::LinearAdvectionEquation1D)

Godunov (upwind) flux for the 1D linear scalar advection equation. Essentially first order upwind, see e.g. https://math.stackexchange.com/a/4355076/805029 .

flux_central(u_ll, u_rr, orientation_or_normal_direction, equations::AbstractEquations)

The classical central numerical flux f((u_ll) + f(u_rr)) / 2. When this flux is used as volume flux, the discretization is equivalent to the classical weak form DG method (except floating point errors).

InhomogeneousMesh{NDIMS, RealT}
InhomogeneousMesh(coordinates)

Create an inhomogeneous one-dimensional mesh from the given coordinates.

Mesh

Struct that holds the information for a simple homogeneous one-dimensional mesh.

Mesh(xmin, xmax, N_elements)

Create a simple homogeneous one-dimensional mesh from xmin to xmax with N_elements elements.

OversetGridMesh{NDIMS, RealT, MeshLeft, MeshRight}
OversetGridMesh(mesh_left, mesh_right)

Create an overset grid (Chimera) mesh that combines two meshes, mesh_left and mesh_right, which have an overlap region.

element_spacing(mesh::AbstractMesh)

Return the spacing of the elements in the mesh. This is the length of each element, which is the same for all elements in a homogeneous Mesh and can be different for each element in an InhomogeneousMesh.

element_spacing(mesh::AbstractMesh, element)

Return the length of the element element in the mesh.

left_element_boundary(mesh::AbstractMesh, element)

Return the left boundary coordinate of the element element in the mesh.

xmax(mesh::AbstractMesh)

Return the maximum coordinate of the mesh.

xmin(mesh::AbstractMesh)

Return the minimum coordinate of the mesh.

boundary_condition_do_nothing = BoundaryConditionDoNothing()

Imposing no boundary condition just evaluates the flux at the inner state.

boundary_condition_periodic = BoundaryConditionPeriodic()

A singleton struct indicating periodic boundary conditions.

BoundaryConditionDirichlet(boundary_value_function)

Create a Dirichlet boundary condition that uses the function boundary_value_function to specify the values at the boundary. This can be used to create a boundary condition that specifies exact boundary values by passing the exact solution of the equation. The passed boundary value function will be called with the same arguments as an initial condition function is called, i.e., as

boundary_value_function(x, t, equations)

where x specifies the coordinates, t is the current time, and equation is the corresponding system of equations.

Examples

julia> BoundaryConditionDirichlet(initial_condition_convergence_test)

DG(; basis, surface_integral, volume_integral)

Create a discontinuous Galerkin method. If basis isa LegendreDerivativeOperator, this creates a DGSEM.

eachnode(solver::DG, element)

Return an iterator over the indices that specify the location in relevant data structures for the nodes in a specific element in solver. In particular, not the nodes themselves are returned.

get_variable(u, v, ::DG)

Return the solution belonging to the variable v of the solution u at one time step as a vector at every node across all elements.

DGSEM(; RealT=Float64, polydeg::Integer,
        surface_flux=flux_central,
        surface_integral=SurfaceIntegralWeakForm(surface_flux),
        volume_integral=VolumeIntegralWeakForm())

Create a discontinuous Galerkin spectral element method (DGSEM) using a LegendreDerivativeOperator with polynomials of degree polydeg.

FDSBP(D; RealT=Float64,
         surface_flux=flux_central,
         surface_integral=SurfaceIntegralWeakForm(surface_flux),
         volume_integral=VolumeIntegralWeakForm())

Create a discontinuous Galerkin method using a summation-by-parts operator D from SummationByPartsOperators.jl. This is similar to the DGSEM, but uses a general derivative operator instead of a Legendre derivative operator.

PerElementBasis{BasisType}

Basis, which can hold a different SBP operator for each element. This is used in PerElementFDSBP to allow for different bases on each element.

PerElementFDSBP(bases::Vector{BasisType};
                surface_flux = flux_central,
                surface_integral = SurfaceIntegralWeakForm(surface_flux),
                volume_integral = VolumeIntegralWeakForm()) where BasisType

Create a discontinuous Galerkin method using different bases for each element. This is like FDSBP, but allows for a different SBP operator on each element. See also: PerElementBasis.

SurfaceIntegralStrongForm(surface_flux=flux_central, surface_flux_boundary=surface_flux)

The classical strong form surface integral type for FD/DG methods. It uses surface_flux for the interior fluxes and surface_flux_boundary for the boundary fluxes.

See also VolumeIntegralStrongForm.

SurfaceIntegralWeakForm(surface_flux=flux_central, surface_flux_boundary=surface_flux)

The classical weak form surface integral type for DG methods as explained in standard textbooks. It uses surface_flux for the interior fluxes and surface_flux_boundary for the boundary fluxes.

See also VolumeIntegralWeakForm.

References

• Kopriva (2009) Implementing Spectral Methods for Partial Differential Equations: Algorithms for Scientists and Engineers doi: 10.1007/978-90-481-2261-5
• Hesthaven, Warburton (2007) Nodal Discontinuous Galerkin Methods: Algorithms, Analysis, and Applications doi: 10.1007/978-0-387-72067-8

VolumeIntegralFluxDifferencing(volume_flux=flux_central)

Volume integral type for DG methods based on SBP operators and flux differencing using a symmetric two-point volume_flux. This volume_flux needs to satisfy the interface of numerical fluxes.

To be used together with SurfaceIntegralWeakForm.

VolumeIntegralFluxDifferencingStrongForm(volume_flux=flux_central)

Volume integral type for DG methods based on SBP operators and flux differencing using a symmetric two-point volume_flux. This volume_flux needs to satisfy the interface of numerical fluxes.

This is the strong formulation, which means it should be used together with SurfaceIntegralStrongForm.

VolumeIntegralStrongForm()

The classical strong form volume integral type for FD/DG methods.

VolumeIntegralWeakForm()

The classical weak form volume integral type for DG methods as explained in standard textbooks.

References

• Kopriva (2009) Implementing Spectral Methods for Partial Differential Equations: Algorithms for Scientists and Engineers doi: 10.1007/978-90-481-2261-5
• Hesthaven, Warburton (2007) Nodal Discontinuous Galerkin Methods: Algorithms, Analysis, and Applications doi: 10.1007/978-0-387-72067-8

Semidiscretization

A struct containing everything needed to describe a spatial semidiscretization of an equation.

Semidiscretization(mesh, equations, initial_condition, solver;
                   boundary_conditions = boundary_condition_periodic)

Construct a semidiscretization of a PDE.

grid(semi)

Get the grid of a semidiscretization.

flat_grid(semi)

Return a vector of the coordinates of all nodes in semi, flattened across all elements. This is useful for plotting or other operations that require a single vector of coordinates.

get_variable(u, v, semi)

Return the solution belonging to the variable v of the solution u at one time step as a vector at every node across all elements.

semidiscretize(semi::Semidiscretization, tspan)

Wrap the semidiscretization semi as an ODE problem in the time interval tspan that can be passed to solve from the SciML ecosystem.

AnalysisCallback(semi; interval=0,
                       extra_analysis_errors=Symbol[],
                       extra_analysis_integrals=(),
                       io=stdout)

Analyze a numerical solution every interval time steps. The L2- and the L∞-norm for each component are computed by default. Additional errors can be computed, e.g. by passing extra_analysis_errors = (:conservation_error,).

Further scalar functions func in extra_analysis_integrals are applied to the numerical solution and integrated over the computational domain. Some examples for this are mass, and entropy. You can also write your own function with the same signature as the examples listed above and pass it via extra_analysis_integrals. The computed errors and intergrals are saved for each timestep and can be obtained by calling errors and integrals.

During the Simulation, the AnalysisCallback will print information to io.

errors(analysis_callback)

Return the computed errors for each timestep as a named tuple. The shape of each entry is (nvariables, ntimesteps).

integrals(analysis_callback)

Return the computed integrals for each time step as a named tuple.

tstops(analysis_callback)

Return the time values that correspond to the saved values of the errors and integrals.

SummaryCallback(io::IO = stdout)

Create and return a callback that resets the timer at the beginning of a simulation and prints the timer values at the end of the simulation.