1# The Dirichlet problem: accuracy against cost
3An interactive tutorial on solving the Dirichlet problem for Laplace's and Poisson's
4equations, in one and two dimensions, with every method written as a MATLAB-syntax
5script that you can edit and run in the page. It runs in your browser through
6[numbl](https://numbl.org); there is no server, nothing to install, and nothing is
7sent anywhere.
9The organising idea is that every problem in it has an exact solution known in
10closed form, by construction, so the error of every computation is known at every
11point to full precision. What the tutorial then measures is not whether a method
12works but what accuracy it delivers for what cost, and under which conditions that
13answer changes.
15An introduction, before Chapter 1, defines Laplace's and Poisson's equations and the
16Dirichlet, Neumann and Robin boundary conditions, states what the tutorial measures,
17and lays out the four domains the chapters work on. Every chapter also carries one or
18two static diagrams, drawn as inline SVG, so that a page says something before its
19labs are run.
21## The problems
23In one dimension, Laplace's equation is $u'' = 0$ and its solution is a straight
24line, so Part I uses Poisson's equation $-u'' = f$ with the source manufactured from
25a chosen solution. Five solutions are available, differing in how hard they are to
26resolve: an entire function of moderate amplitude, an oscillatory one, a narrow
27Gaussian, a boundary layer, and one that is $C^2$ but not $C^3$.
29In two dimensions the equation is Laplace's, and the exact solutions are harmonic
30functions written down in closed form: $e^x \sin y$, $\operatorname{Re}(x+iy)^k$,
31$e^{ky}\sin kx$, and $\log|z - z_0|$ with the singularity just outside the domain.
32Their boundary traces are the data, so the only error in the computation is the
33error of the method.
35## The chapters
37**Introduction** — Laplace's and Poisson's equations, the Dirichlet, Neumann and
38Robin boundary conditions, what accuracy-against-cost means here, and the four
39domains the chapters work on.
41**One dimension**
431. **Ground truth by construction** — manufactured solutions, the three-point
44 scheme, the tridiagonal solve, and what the error field looks like.
452. **Second order, to its limit** — the condition number $\kappa \approx 0.4N^2$,
46 the roundoff floor near $10^{-8.5}$, and Richardson extrapolation.
473. **Two more orders, almost free** — Numerov's compact fourth-order scheme, which
48 changes only the right-hand side, and how to read a work-precision diagram.
494. **Chebyshev collocation** — a dense matrix, geometric convergence to $10^{-13}$
50 with 64 points, and the two situations that take that away.
52**Two dimensions**
545. **The five-point Laplacian** — harmonic ground truth, second order, and the
55 $O(N^6)$ wall of a dense solve.
566. **The fast Poisson solver** — the same system diagonalised by the discrete sine
57 transform: a million unknowns in half a second, identical answers.
587. **Sixth order for the same price** — the compact nine-point stencil, which is
59 sixth-order accurate on Laplace's equation and uses the same fast solver, and
60 two-dimensional Chebyshev collocation by matrix decomposition.
618. **Iterating instead of solving** — Jacobi, Gauss-Seidel, SOR, conjugate
62 gradients and a multigrid V-cycle on one problem, and the question of when to
63 stop.
65**Beyond the square**
679. **A corner, and what it costs** — the L-shaped domain, the loss of second order
68 to the $r^{2/3}$ singularity, and the method of particular solutions, which puts
69 the singularity into the basis and reaches $10^{-14}$.
7010. **Boundary integral equations** — a smooth curved domain, the double-layer
71 potential, a second-kind Fredholm equation, the spectral accuracy of the
72 periodic trapezoid rule, and the close-evaluation problem that comes with it.
74A **shared MATLAB library** page lists the small function files every lab boots
75with.
77## Using it
79Each lab has controls above the figures and, behind the "show script" button, the
80method itself. Edit the script and press run: the session reboots with your version
81compiled in, and the figures are whatever your code produces. Ctrl-Enter (Cmd-Enter)
82runs from inside the editor, and "reset" restores the original.
84Some labs run as soon as the chapter opens; the heavier ones wait for the run
85button, which the caption says.
87## Requirements
89numbl **0.4.19 or later**. The tutorial runs on 0.4.18 but is far slower there:
90several JIT limitations that this tutorial's profiling turned up were fixed in
910.4.19, and the MATLAB here is written in the plain form those fixes allow.
93## Development
95```
96npm install
97npm run dev # vite dev server
98npm run build # typecheck and bundle to dist/
99npm run test:matlab # the .m layer, through the numbl CLI (needs a numbl checkout)
100npm run test:browser # the built app in headless Chrome
101```
103`test:matlab` needs a numbl clone; set `NUMBL_DIR` if it is not at `~/src/numbl`,
104and build its CLI (`npm run build:cli` in that checkout) after updating it — the
105tests run `dist-cli/cli.js`, not the TypeScript sources.
106Every assertion in it is a number claimed somewhere in the prose, so a failure means
107either the code or the text is wrong. `test:browser` needs `npm run build` first, and
108takes `--shots` to write a full-page screenshot of each chapter into `tmp/`.
110See [CLAUDE.md](CLAUDE.md) for how the pieces fit together, and in particular for the
111numbl performance rules that the drivers are written around.
113## Deployment
115`.cofferdam/workflows/deploy.yml` builds the page on every push to `main` and
116publishes it as the repository's site on the vault, at
117`/tutorials/laplace-dirichlet/site/`. The build is a plain `npm ci && npm run
118build`; `vite.config.ts` uses a relative `base`, so the sub-path needs no
119configuration. Note that the vault serves sites sandboxed, which makes
120`localStorage` throw rather than degrade: nothing here touches it, and nothing
121here should start.
123## Licence
125Apache-2.0.