Overview

This is the documentation for the saddle-point finite-element project written using the deal.II finite-element library. The program solves a vector-valued elliptic system on a two-dimensional disk that arises from a saddle-point formulation used to compute the harmonic Riesz representation of a given functional in the dual space of \(H^1\).

The two unknown fields, denoted \(p\) and \(u\), are coupled through a boundary integral that involves the surface (tangential) Laplacian on the boundary \(\Gamma=\partial\Omega\). The program demonstrates a number of deal.II features that, taken together, are not covered by any single tutorial program:

the use of a vector-valued FESystem with two scalar components (inspired by step-20),
the assembly of a boundary integral that uses the tangential gradient \(\nabla_\Gamma v = \nabla v - n(n\cdot\nabla v)\) (inspired by step-38),
a ConvergenceTable that automatically writes a LaTeX-ready error table with reduction rates,
a ParameterHandler-driven input file (see param/param.prm) so that the user can change finite-element degree, refinement cycles, solver tolerance, and even the analytic right-hand side function without recompiling, and
a FunctionParser-based right-hand side, allowing arbitrary symbolic expressions to be supplied at run time.

How to read this manual

This documentation is organized into two top-level pages, intended to be read in order:

Introduction — mathematical formulation, weak form, manufactured solutions, and high-level walk-through of the program.
Results — instructions to build and run the code, sample output, convergence tables, and a discussion of how the observed error rates match the theoretical expectations.

In addition, the source files (in include/ and source/) are documented function by function. Use the Files and Classes tabs above to browse them.

Source layout

The project is organized as follows:

saddle-point/
├── include/
│   ├── step-6.h           ← declarations of class SaddlePointProblem<dim>
│   └── rhs_function.h     ← templated RHSFunction<dim> with several test cases
├── source/
│   ├── main.cc            ← program entry point and exception handling
│   ├── step-6.cc          ← implementation of SaddlePointProblem<dim> (assembly, solve, output)
│   ├── solution.cc        ← manufactured solution class Solution<dim,n_eq>
│   └── exact-solution.cc  ← alternative ExactSolution<dim,n_eq> class
├── doc/                   ← this Doxygen documentation
├── param/
│   └── param.prm          ← run-time parameters (degree, cycles, tolerance, rhs)
└── CMakeLists.txt

Quick start

After installing deal.II and configuring the build directory once, type

cd saddle-point/build

make distclean && cmake .. && make -j8 && ./step-6 ./../param/param.prm

to clean any previous build, regenerate the makefiles, compile, and run the program with the default parameter file. The Results page reproduces a typical session and discusses the resulting convergence tables.

Author: Xianzhi Wang

Date: Spring 2025