From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Tue, 5 Jan 2021 00:39:06 +0000 (-0700)
Subject: Better explain the purpose of the L-singularity function.
X-Git-Tag: v9.3.0-rc1~665^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fea65d9ddb62942c3c4daaee272340c0ced00b58;p=dealii.git

Better explain the purpose of the L-singularity function.
---

diff --git a/include/deal.II/base/function_lib.h b/include/deal.II/base/function_lib.h
index e4b9a83c60..589a2fd654 100644
--- a/include/deal.II/base/function_lib.h
+++ b/include/deal.II/base/function_lib.h
@@ -381,11 +381,29 @@ namespace Functions
 
 
   /**
-   * Harmonic singularity on the L-shaped domain in 2D.
+   * A function that solves the Laplace equation (with specific
+   * boundary values but zero right hand side) and that has a
+   * singularity at the center of the L-shaped domain in 2D (i.e.,
+   * at the location of the re-entrant corner of this non-convex
+   * domain).
    *
    * The function is given in polar coordinates by $r^{\frac{2}{3}}
-   * \sin(\frac{2}{3} \phi)$ with a singularity at the origin and should be
-   * used with GridGenerator::hyper_L().
+   * \sin(\frac{2}{3} \phi)$ with a singularity at the origin and
+   * should be used with GridGenerator::hyper_L(). Here, $\phi$ is
+   * defined as the *clockwise* angle against the positive $x$-axis.
+   *
+   * This function is often used to illustrate that the solutions of the Laplace
+   * equation
+   * @f[
+   *   -\Delta u = 0
+   * @f]
+   * can be singular even if the boundary values are smooth. (Here, if the
+   * domain is the L-shaped domain $(-1,1)^2 \backslash [0,1]^2$, the
+   * boundary values for $u$ are zero on the two line segments adjacent to the
+   * origin, and equal to $r^{\frac{2}{3}} \sin(\frac{2}{3} \phi)$ on the
+   * remaining parts of the boundary.) The function itself remains bounded on
+   * the domain, but its gradient is of the form $r^{-1/3}$ in the vicinity of
+   * the origin and consequently diverges as one approaches the origin.
    *
    * @ingroup functions
    */