Update manufactured solutions documentation

docs/notebooks/10-appendix-convergence-testing.ipynb

@@ -27,23 +27,38 @@
     "- The method of manufactured solutions (MMS) can be used to test the order of time integration and compare various discretizations of the same initial-boundary-value problem."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "a1413cf5",
+   "metadata": {},
+   "source": [
+    "# Method of Manufactured Solution (MMS)\n",
+    "\n",
+    "The main idea of this approach is to construct test cases where the solution to a problem is known a-priori. This means for example when testing the discretization of a spatial derivative, one considers functions, where the continuous counterpart can be computed analytically. We make this more precise in the following sections.\n",
+    "A detailed introduction to MMS can be found [here](https://www.osti.gov/servlets/purl/759450-wLI4Ux/native/).\n"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "eb058f7c",
    "metadata": {},
    "source": [
-    "## Testing spatial order of convergence\n",
+    "## 1. Testing spatial order of convergence\n",
     "\n",
     "In the following we show some examples which are all part of the CI testing of the codebase. They can be found in the test folder in the files `test_laplace.py` and `test_rhs.py`.\n",
     "\n",
-    "In a nutshell, it is as simple as this\n",
+    "In a nutshell, it is as simple as this (for the leading example $-\\Delta u = \\text{rhs}$)\n",
     "\n",
-    "1. Define a test function $u(x,y,z)$ which is given analytically in sympy logic\n",
-    "2. Compute the exact solution to the right-hand side and evaluate it on the defined grid $$\\text{rhs}_\\text{analytic}=\\text{rhs}_\\text{analytic}(x_i, y_j, z_k),$$ where $(x_i, y_j, z_k)$ are the discrete positions in the regular meshgrid.\n",
-    "3. Compute the discrete initial field $u_\\text{numeric}(x_i, y_j, z_k)$ and the corresponding numerical right-hand side $$\\text{rhs}_\\text{numeric}=\\text{rhs}_\\text{numeric}(u_\\text{numeric})$$\n",
+    "1. Define a test function $u_\\text{analytic}(x,y,z)$ which is given analytically in sympy logic\n",
+    "2. Compute the exact solution to the right-hand side (e.g. $\\text{rhs}_\\text{analytic} = -\\Delta u_\\text{analytic}$ via sympy) and evaluate it on the defined grid $$\\text{rhs}_\\text{analytic}=\\text{rhs}_\\text{analytic}(x_i, y_j, z_k),$$ where $(x_i, y_j, z_k)$ are the discrete positions in the regular meshgrid.\n",
+    "3. Compute the discrete initial field $u_\\text{numeric}(x_i, y_j, z_k)$ and the corresponding numerical right-hand side (e.g. $\\text{rhs}_\\text{numeric} = - \\Delta_h  u_\\text{numeric}$ for a stencil $\\Delta_h$) $$\\text{rhs}_\\text{numeric}=\\text{rhs}_\\text{numeric}(u_\\text{numeric})$$\n",
     "4. Compute the relative $L_2$ error i.e. the discrete $L_2$–norm of the difference $\\text{rhs}_\\text{numeric}-\\text{rhs}_\\text{analytic}$ divided by the $L_2$–norm of the analytical solution $$\\epsilon = \\sqrt{\\sum_{i,j,k} (\\text{rhs}_\\text{numeric}-\\text{rhs}_\\text{analytic})^2} \\bigg/ \\sqrt{\\sum_{i,j,k} (\\text{rhs}_\\text{analytic})^2}$$\n",
     "\n",
-    "Repeat the scheme for various spatial discretizations $\\Delta x$ on the same physical domain with the same analytical reference."
+    "Repeat the scheme for various spatial discretizations $\\Delta x$ on the same physical domain with the same analytical reference. Since it is known from the theory that the error $\\epsilon$ scales like a constant times $h^p$ for the mesh width $h = \\max\\{\\Delta x, \\Delta y, \\Delta z \\}$ and some integer $p$, we obtain the relation\n",
+    "$$\n",
+    "\\log \\epsilon \\sim \\log C + p \\log h ,\n",
+    "$$\n",
+    "which corresponds in a log-log-plot to a straight line with slope $p$. This slope $p$ (computed via linear regression) is then compared to the theoretically expected exponent to validate the implementation."
    ]
   },
   {
@@ -342,6 +357,8 @@
    "source": [
     "### Testing ODE right-hand sides\n",
     "\n",
+    "The ODEs are all given in the form $\\partial_t u = \\text{rhs}(t,u)$, e.g. for Allen-Cahn in the form $\\text{rhs}(t,u) = \\Delta u + g(t,u)$.\n",
+    "\n",
     "The above procedure has been adapted to automatically test all implementations of ODE classes by comparing the ``rhs_analytic`` to the results produced by ``rhs``. This ensures two things\n",
     "1. Does the ``rhs`` function implement a discretized version of the envisioned PDE?\n",
     "2. Does the chosen discretization converge at the expected spatial order of convergence?\n",
@@ -415,10 +432,39 @@
    "id": "da5b50fd",
    "metadata": {},
    "source": [
-    "## Method of Manufactured Solution (MMS)\n",
-    "\n",
-    "A detailed introduction to MMS can be found [here](https://www.osti.gov/servlets/purl/759450-wLI4Ux/native/).\n",
-    "More tests tbd."
+    "## 2. Time-dependent problems"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8b19ecef",
+   "metadata": {},
+   "source": [
+    "The idea of manufactured solutions can further be generalized to problems of the form\n",
+    "$$\n",
+    "\\partial_t u (t,x) = \\text{rhs}(t,x,u)\n",
+    "$$\n",
+    "where for example in Allen-Cahn $\\text{rhs}(t,x,u) = \\Delta u + g(t,u)$. For a general problem it is often difficult to test the problem with a known solution in order to determine if the code produces the correct solution. One can therefore simply study the modified problem\n",
+    "$$\n",
+    "\\partial_t u (t,x) = \\text{rhs}(t,x,u) + f_{\\text{ex}}(t,x) \\qquad (+)\n",
+    "$$\n",
+    "with an artificial forcing term $f_{\\text{ex}}$. This allows the following construction:\n",
+    "1. Choose some analytically given function $u (t,x)$.\n",
+    "2. Define $f_{\\text{ex}}(t,x) = \\partial_t u (t,x) - \\text{rhs}(t,x,u)$ (again computable via sympy)\n",
+    "3. Then $u$ is by construction the exact solution to (+).\n",
+    "\n",
+    "If we now pass problem (+) to the solver (i.e. the right-hand side as well as the artificial forcing), then we can compare its approximations at time $t_n$ denoted by $u_{h,n}$ to the exact solution $u(t_n,x_i, y_j, z_k)$. Thus, we can determine if the error behaves asymptotically (i.e. as the time-step size and the mesh width tend to zero) with the correct order. \n",
+    "\n",
+    "\n",
+    "TODO: automate temporal and spatial testing via pre-defined test function which constructs the forcing term."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "758f6eab",
+   "metadata": {},
+   "source": [
+    "### More tests tbd."
    ]
   }
  ],