Reference documentation for deal.II version GIT relicensing-136-gb80d0be4af 2024-03-18 08:20:02+00:00
\(\newcommand{\dealvcentcolon}{\mathrel{\mathop{:}}}\) \(\newcommand{\dealcoloneq}{\dealvcentcolon\mathrel{\mkern-1.2mu}=}\) \(\newcommand{\jump}[1]{\left[\!\left[ #1 \right]\!\right]}\) \(\newcommand{\average}[1]{\left\{\!\left\{ #1 \right\}\!\right\}}\)
Loading...
Searching...
No Matches
Tutorial programs

New to deal.II? You might want to start with tutorial step-1 and work your way up to step-5. At that point you can explore what features you are interested in and look at the large collection of programs listed below.

The deal.II tutorial contains a collection of programs, each more or less built atop of previous ones, which demonstrate various aspects of the library. Each such example has the following structure:

  1. Introduction: What the program does, including the mathematical model, and what programming techniques are new.
  2. The commented program: An extensively documented listing of the source code.
  3. Results: The output of the program, with comments and interpretation.
  4. The plain program: The source code stripped of all comments.

You can browse the available tutorial programs

  1. as a graph that shows how the major concepts of each tutorial programs builds on previous ones (though each program may also use minor pieces from other programs not specifically connected in the graph).
  2. as a list that provides a short synopsis of each program.
  3. or grouped by topic.

The programs are in the examples/ directory of your local deal.II installation. After compiling the library itself, if you go into one of the tutorial directories, you can configure the program by typing cmake ., build it via make and run it using make run. The latter command also compiles the program if that has not already been done. The CMakeLists.txt files in the different directories are based on the autopilot style CMakeLists.txt example.

Note
Some of the tutorial programs also jointly form the geodynamics demonstration suite. More, often more complex but less well documented, deal.II-based programs than the ones that form the tutorial can also be found in the The deal.II code gallery .

Connections between tutorial programs

The following graph shows the connections between tutorial programs and how their major components build on each other. Click on any of the boxes to go to one of the programs. If you hover your mouse pointer over a box, a brief description of the program should appear.

dot_inline_dotgraph_1.png

Legend:

dot_inline_dotgraph_2.png

Tutorial programs listed by number

step-1

Creating a grid. A simple way to write it to a file.
Keywords: Triangulation, GridGenerator::hyper_cube(), GridGenerator::hyper_shell(), GridOut, Triangulation::execute_coarsening_and_refinement()

step-2

Associate degrees of freedom to each vertex and compute the resulting sparsity pattern of matrices. Show that renumbering reduces the bandwidth of matrices significantly, i.e. clusters nonzero entries around the diagonal.
Keywords: FE_Q, DynamicSparsityPattern, DoFTools::make_sparsity_pattern(), DoFHandler::distribute_dofs(), DoFRenumbering, SparsityPattern

step-3

Actually solve Laplace's problem. Object-orientation. Assembling matrices and vectors. Boundary values.
Keywords: FEValues, VectorTools::interpolate_boundary_values(), MatrixTools::apply_boundary_values(), SolverCG, Vector, SparseMatrix, DataOut

step-4

This example is programmed in a way that it is independent of the dimension for which we want to solve Laplace's equation; we will solve the equation in 2D and 3D, although the program is exactly the same. Non-constant right hand side function. Non-homogeneous boundary values.
Keywords: VectorTools::point_value(), VectorTools::compute_mean_value()

step-5

Computations on successively refined grids. Reading a grid from disk. Some optimizations. Using assertions. Non-constant coefficient in the elliptic operator (yielding the extended Poisson equation). Preconditioning the CG solver for the linear system of equations.
Keywords: PreconditionSSOR, GridIn, SphericalManifold

step-6

Adaptive local refinement. Handling of hanging nodes. Higher order elements. Catching exceptions in the main function.
Keywords: DoFTools::make_hanging_node_constraints(), AffineConstraints::distribute_local_to_global(), KellyErrorEstimator, GridRefinement::refine_and_coarsen_fixed_number()

step-7

Helmholtz equation. Non-homogeneous Neumann boundary conditions and boundary integrals. Verification of correctness of computed solutions. Computing the error between exact and numerical solution and output of the data in tables. Using counted pointers.
Keywords: FEFaceValues, VectorTools::integrate_difference(), VectorTools::compute_global_error(), TableHandler

step-8

The elasticity equations will be solved instead of Laplace's equation. The solution is vector-valued and the equations form a system with as many equations as the dimension of the space in which it is posed.
Keywords: FESystem

step-9

Linear advection equation, assembling the system of equations in parallel using multi-threading, implementing a refinement criterion based on a finite difference approximation of the gradient.
Keywords: TensorFunction, WorkStream::run(), SolverGMRES

step-10

Higher order mappings. Do not solve equations, but rather compute the value of pi to high accuracy.
Keywords: MappingQ, FE_Nothing, ConvergenceTable, GridOut, FEFaceValues

step-11

Solving a Laplace problem with higher order mappings. Using mean value constraints and intermediate representations of sparsity patterns.
Keywords: AffineConstraints, DoFTools::extract_boundary_dofs(), TableHandler

step-12

Discontinuous Galerkin methods for linear advection problems.
Keywords: FEInterfaceValues, MeshWorker::mesh_loop(), DoFTools::make_flux_sparsity_pattern()

step-12b

A variant of step-12 (for linear advection problems), but using the MeshWorker framework for the assembly of linear systems.

step-13

Software design questions and how to write a modular, extensible finite element program.

step-14

Duality based error estimators, more strategies to write a modular, extensible finite element program.
Keywords: KellyErrorEstimator

step-15

A nonlinear elliptic problem: The minimal surface equation. Newton's method. Transferring a solution across mesh refinement.
Keywords: SolutionTransfer

step-16

Multigrid preconditioning of the Laplace equation on adaptive meshes.
Keywords: Multigrid, PreconditionMG, mg::Matrix, MGTransferPrebuilt, MeshWorker::mesh_loop(), MGLevelObject, MGConstrainedDoFs

step-16b

A variant of step-16 but with MeshWorker for assembly: Multigrid preconditioning of the Laplace equation on adaptive meshes.

step-17

Using PETSc for linear algebra; running in parallel on clusters of computers linked together by MPI.
Keywords: PETScWrappers::MPI::SparseMatrix, ConditionalOStream, PETScWrappers::PreconditionBlockJacobi

step-18

A time dependent problem; using a much simplified version of implementing elasticity; moving meshes; handling large scale output of parallel programs. Simple implicit (backward Euler) time stepping.
Keywords: parallel::shared::Triangulation, DataOutInterface::write_vtu_with_pvtu_record()

step-19

Coupling particles to the solution of partial differential equations.
Keywords: Particles

step-20

Mixed finite elements. Using block matrices and block vectors to define more complicated solvers and preconditioners working on the Schur complement.
Keywords: FEValuesExtractors, LinearOperator, TensorFunction, FE_RaviartThomas

step-21

The time dependent two-phase flow in porous media. Extensions of mixed Laplace discretizations. More complicated block solvers. Simple explicit (forward Euler) time stepping.
Keywords: TensorFunction, FE_RaviartThomas, VectorTools::project(), DiscreteTime

step-22

Solving the Stokes equations of slow fluid flow on adaptive meshes. More on Schur complement solvers. Advanced use of the AffineConstraints class.
Keywords: AffineConstraints, VectorTools::compute_no_normal_flux_constraints(), SparseILU, SparseDirectUMFPACK, BlockDynamicSparsityPattern

step-23

Finally a "real" time dependent problem, the wave equation. Fractional time stepping (explicit, fully implicit and Crank-Nicolson method).
Keywords: MatrixCreator, VectorTools::project()

step-24

A variant of step-23 with absorbing boundary conditions, and extracting practically useful data. Implicit time stepping.
Keywords: VectorTools::point_value()

step-25

The sine-Gordon soliton equation, which is a nonlinear variant of the time dependent wave equation covered in step-23 and step-24. Fractional time stepping.
Keywords: FunctionTime, VectorTools::integrate_difference()

step-26

The heat equation, solved on a mesh that is adapted every few time steps. Fractional time stepping.
Keywords: KellyErrorEstimator, SolutionTransfer, VectorTools::interpolate(), VectorTools::create_right_hand_side()

step-27

The hp-finite element method.
Keywords: hp::FECollection, hp::QCollection, hp::Refinement, FESeries::Fourier, Triangulation::create_triangulation()

step-28

Multiple grids for solving a multigroup diffusion equation in nuclear physics simulating a nuclear reactor core.

step-29

Solving a complex-valued Helmholtz equation. Sparse direct solvers. Dealing with parameter files.

step-30

Anisotropic refinement for DG finite element methods.

step-31

Time-dependent Stokes flow driven by temperature differences in a fluid. Adaptive meshes that change between time steps. Implicit/explicit time stepping.

step-32

A massively parallel solver for time-dependent Stokes flow driven by temperature differences in a fluid. Adapting methods for real-world equations. Implicit/explicit time stepping.

step-33

A nonlinear hyperbolic conservation law: The Euler equations of compressible gas dynamics. Fractional time stepping.

step-34

Boundary element methods (BEM) of low order: Exterior irrotational flow. The ParsedFunction class.

step-35

A projection solver for the Navier–Stokes equations.

step-36

Using SLEPc for linear algebra; solving an eigenspectrum problem. The Schrödinger wave equation.

step-37

Solving a Poisson problem with a multilevel preconditioner without explicitly storing the matrix (a matrix-free method) in a massively parallel context.

step-38

Solving the Laplace-Beltrami equation on curved manifolds embedded in higher dimensional spaces.

step-39

Solving Poisson's equation once more, this time with the interior penalty method, one of the discontinuous Galerkin methods developed for this problem. Error estimator, adaptive meshes, and multigrid preconditioner, all using the MeshWorker framework.

step-40

Techniques for the massively parallel solution of the Laplace equation (up to 10,000s of processors).

step-41

Solving the obstacle problem, a variational inequality.

step-42

A solver for an elasto-plastic contact problem, running on parallel machines.

step-43

Advanced techniques for the simulation of porous media flow. Explicit time stepping.

step-44

Finite strain hyperelasticity based on a three-field formulation. Implicit time stepping.
Keywords: CellDataStorage, FEValuesExtractors, WorkStream::run, BlockSparseMatrix, BlockVector, ComponentSelectFunction, Physics::Elasticity, FullMatrix::extract_submatrix_from(), FullMatrix::scatter_matrix_to(), LinearOperator, SolverSelector, PreconditionSelector, ReductionControl, MappingQEulerian

step-45

Periodic boundary conditions.
Keywords: GridTools::collect_periodic_faces(), GridTools::PeriodicFacePair, Triangulation::add_periodicity()

step-46

Coupling different kinds of equations in different parts of the domain.

step-47

Solving the fourth-order biharmonic equation using the \(C^0\) Interior Penalty (C0IP) method.
Keywords: FEInterfaceValues

step-48

Explicit time stepping for the Sine–Gordon equation based on a diagonal mass matrix. Efficient implementation of (nonlinear) finite element operators.

step-49

Advanced mesh creation and manipulation techniques.

step-50

Geometric multigrid on adaptive meshes distributed in parallel.
Keywords: Multigrid, MGLevelObject, MGConstrainedDoFs, IndexSet, MGTools, PreconditionMG, MatrixFree, FEInterfaceValues, MeshWorker::mesh_loop()

step-51

Solving the convection-diffusion equation with a hybridizable discontinuous Galerkin method using face elements.

step-52

Solving the time dependent neutron diffusion equation using Runge-Kutta methods. Explicit and implicit time stepping.

step-53

Describing the geometry of complex domains and curved boundaries.

step-54

Using CAD files to describe the boundary of your domain.
Keywords: Manifold, OpenCASCADE::read_IGES(), OpenCASCADE::NormalProjectionManifold

step-55

Solving the Stokes problem in parallel.

step-56

Geometric Multigrid for Stokes.

step-57

Incompressible, stationary Navier Stokes equations.

step-58

The nonlinear Schrödinger equation.

step-59

Solving a Poisson problem discretized with an interior penalty DG method and a multilevel preconditioner in a matrix-free fashion using a massively parallel implementation.
Keywords: FEFaceEvaluation, FE_DGQHermite

step-60

Distributed Lagrange multipliers for the solution of Poisson problems in complex domains with constraints defined on non-matching grids.

step-61

Solving the Poisson problem with the "weak Galerkin" finite element method.

step-62

Resonance frequency and bandgap of a phononic crystal. Elastic wave equation in the frequency domain with Perfectly Matched Layer boundary conditions. Parallelization via MUMPS and MPI.

step-63

Block smoothers for geometric multigrid. A scalar convection diffusion equation is solved with different additive or multiplicative multigrid smoothers.
Keywords: Multigrid, MeshWorker::mesh_loop(), MGSmootherPrecondition, RelaxationBlock, DoFRenumbering::downstream()

step-64

Solving a Helmholtz problem using matrix-free methods on the GPU with MPI parallelization.
Keywords: LinearAlgebra::CUDAWrappers, CUDAWrappers::MatrixFree

step-65

The TransfiniteInterpolationManifold and MappingQCache classes for advanced manifold operations.

step-66

A matrix-free geometric multigrid solver for a nonlinear problem.
Keywords: MatrixFree, Multigrid, MGTransferMatrixFree::interpolate_to_mg(), MatrixFreeTools::compute_diagonal(), TransfiniteInterpolationManifold, MappingQGeneric

step-67

Solving the Euler equations of compressible gas dynamics with an explicit time integrator and high-order discontinuous Galerkin methods based on matrix-free implementations.

step-68

Simulation of the motion of massless tracer particles in a vortical flow. Parallel simulation of the advection of particles with load balancing.
Keywords: Particles

step-69

Hyperbolic conservation laws: a first-order guaranteed maximum wavespeed method for the compressible Euler equations. Explicit time stepping.

step-70

A fluid structure interaction problem on fully distributed non-matching grids, using penalty methods, and a coupling constructed through a ParticleHandler object.
Keywords: Particles

step-71

Constitutive modelling: a demonstration of how automatic and symbolic differentiation can be used to rapidly implement a complex coupled constitutive law.
Keywords: Automatic differentiation, Symbolic differentiation, Constitutive modelling

step-72

A nonlinear elliptic problem: The minimal surface equation. Newton's method. Using automatic differentiation to linearize the residual, or to compute the full linear system from an energy functional.
Keywords: Automatic differentiation, MeshWorker::mesh_loop()

step-74

The Symmetric interior penalty Galerkin (SIPG) method for Poisson's equation.
Keywords: MeshWorker::mesh_loop(), FEInterfaceValues, ConvergenceTable

step-75

Solving the Laplace equation on hp-adaptive meshes with MatrixFree methods on thousands of processors.
Keywords: parallel::distributed::Triangulation, hp::Refinement, MatrixFree

step-76

Like step-67, but for demonstrating MPI-3.0 shared-memory features.
Keywords: MatrixFree, MatrixFree::cell_loop()

step-77

The nonlinear minimal surface equation revisited. Interfacing with SUNDIALS' KINSOL nonlinear solver.

step-78

Solving the Black-Scholes equation for options pricing in 1d.

step-79

A topology optimization program for elastic media using the solid isotropic material penalization (SIMP) formulation.

step-81

Solving the complex-valued time-harmonic Maxwell equations.

step-82

Solving the fourth-order biharmonic equation using a lifting operator approach.

step-85

Solving the Poisson equation using the cut finite element method.
Keywords: FEInterfaceValues, NonMatching::FEImmersedSurfaceValues

step-87

Evaluation of finite element solutions at arbitrary points within a distributed mesh with application to two-phase flow.
Keywords: Utilities::MPI::RemotePointEvaluation, VectorTools::point_values()

Tutorial programs grouped by topics

Basic techniques

Creating a grid. A simple way to write it to a file

step-1

Degrees of freedom

step-2

Solving the Laplace equation

step-3

Dimension independent programming, non-zero data

step-4

Computing on uniformly refined meshes

step-5

Adaptivity

step-6, step-26

Evaluating errors

step-7

Nonlinear problems, Newton's method

step-15

Advanced techniques

Multithreading

step-9, step-28, step-32, step-44, step-48, step-51, step-69

Block solvers and preconditioners

step-20, step-21, step-22, step-31, step-32, step-43, step-44, step-55, step-56, step-57, step-60, step-70

Using Trilinos

step-31, step-32, step-33, step-40, step-41, step-42, step-43, step-50, step-55, step-71, step-72, step-75

Parallelization via PETSc and MPI

step-17, step-18, step-40, step-50, step-55

Parallelization via Trilinos and MPI

step-32, step-40, step-42, step-50, step-55, step-70

Parallelization via MUMPS and MPI

step-62

Parallelization via CUDA and MPI

step-64

Parallelization on very large numbers of processors

step-32, step-37, step-40, step-42, step-50, step-55, step-59, step-66, step-67, step-69, step-70, step-75

Input parameter handling

step-28, step-29, step-32, step-33, step-34, step-35, step-36, step-42, step-44, step-60, step-62, step-69, step-70, step-71, step-72

Higher order mappings

step-10, step-11, step-32, step-60, step-65, step-66, step-67

Error indicators and estimators

step-6, step-9, step-14, step-39, step-50, step-74

Transferring solutions across mesh refinement

step-15, step-28, step-31, step-32, step-33, step-42, step-43, step-57, step-70

Discontinuous Galerkin methods

step-12, step-12b, step-21, step-39, step-46, step-47, step-51, step-59, step-61, step-67, step-74, step-82

hp-finite elements

step-27, step-46, step-75

Anisotropic refinement for DG finite element methods

step-30

Computing Jacobians from residuals, automatic and symbolic differentiation

step-33, step-71, step-72

Operator splitting

step-21, step-31, step-32, step-58

Boundary element methods, curved manifolds

step-32, step-34, step-38, step-53, step-54, step-65

Periodic boundary conditions

step-45, step-59

Matrix-free methods with sum factorization

step-37, step-48, step-50, step-59, step-64, step-66, step-67, step-75, step-76

Advanced meshes and geometries

step-49, step-53, step-54, step-65

Non-matching algorithms

step-60, step-70, step-85, step-87

HDF5 and Python

step-62

Particles

step-19, step-68, step-70

Linear solvers

Conjugate Gradient solver

step-3

Preconditioned CG solver

step-5

BiCGStab

step-9

Direct solvers

step-29, step-44, step-47, step-46, step-58, step-62, step-81, step-82

Multilevel preconditioners

step-16, step-16b step-31, step-32, step-37, step-39, step-41, step-42, step-43, step-50, step-56, step-59, step-63, step-66, step-75

Parallel solvers

step-17, step-18, step-32, step-37, step-40, step-42, step-50, step-55, step-59, step-66, step-75

Block and Schur complement solvers

step-20, step-21, step-22, step-31, step-32, step-43, step-55, step-56, step-57, step-60, step-70

Decoupled projection solvers

step-35

Linear Newton systems from nonlinear equations

step-33, step-41, step-42, step-44, step-57

Eigenvalue solvers

step-36

Linear operators

step-44, step-60, step-70

Other equations

Helmholtz equation

step-7, step-29, step-62, step-64

Elasticity and elasto-plasticity equations

step-8, step-42, step-46, step-62

Heat equation

step-26

Minimal surface equation

step-15

Quasi-static elasticity equations

step-18, step-44

Transport (advection) equations

step-9, step-21, step-31, step-32, step-43, step-51

The nonlinear hyperbolic Euler system of compressible gas dynamics

step-33, step-67, step-69

Mixed Laplace, Darcy, Porous media

step-20, step-21, step-43

Stokes and incompressible Navier-Stokes flow

step-22, step-31, step-32, step-35, step-46, step-55, step-56, step-57, step-70

The wave equation, in linear and nonlinear variants

step-23, step-24, step-25, step-48, step-58

A multigroup diffusion problem in neutron transport

step-28

Irrotational flow

step-34

An eigenspectrum problem

step-36

Fourth-order biharmonic equation

step-47, step-82

The obstacle problem, a variational inequality

step-41, step-42

The nonlinear Schrödinger equation

step-58

The time-harmonic Maxwell equations

step-81

Coupling different equations in different parts of the domain

step-46

Vector problems

Elasticity and elasto-plasticity equations

step-8, step-42

Mixed Laplace

step-20

Mixed Laplace plus an advection equation

step-21, step-43

Incompressible Stokes and Navier-Stokes flow

step-22, step-31, step-32, step-35, step-55, step-56, step-57, step-70

A complex-valued Helmholtz problem

step-29

The Euler equations of compressible gas dynamics

step-33, step-67, step-69

Coupling different equations in different parts of the domain

step-46

Time dependent problems

The heat equation

step-26

Quasi-static elasticity

step-18, step-44

Porous media flow

step-21, step-43

The wave equation, in linear and nonlinear variants

step-23, step-24, step-25, step-48, step-58

Time dependent Stokes flow driven by buoyancy

step-31, step-32

The Euler equations of compressible gas dynamics

step-33, step-67, step-69

The nonlinear Schrödinger equation

step-58

Time dependent neutron diffusion equation

step-52

Time dependent fluid structure interaction problems step-70