088be4cAn interactive tutorial on the Dirichlet problem, accuracy against costJeremy Magland 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.
e5fc8c6An introduction and static figures, and the MATLAB written plainly againJeremy Magland 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,
6292f12A benchmark chapter, and offline benchmarks to compare it againstJeremy Magland 17and lays out the five domains the chapters work on. Every chapter also carries one or
e5fc8c6An introduction and static figures, and the MATLAB written plainly againJeremy Magland 18two static diagrams, drawn as inline SVG, so that a page says something before its
19labs are run.
088be4cAn interactive tutorial on the Dirichlet problem, accuracy against costJeremy Magland 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
e5fc8c6An introduction and static figures, and the MATLAB written plainly againJeremy Magland 37**Introduction** — Laplace's and Poisson's equations, the Dirichlet, Neumann and
1a8bb6aMake the cross-language benchmark measure the languagesJeremy Magland 38Robin boundary conditions, what accuracy-against-cost means here, and the five
e5fc8c6An introduction and static figures, and the MATLAB written plainly againJeremy Magland 39domains the chapters work on.
088be4cAn interactive tutorial on the Dirichlet problem, accuracy against costJeremy Magland 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.
6292f12A benchmark chapter, and offline benchmarks to compare it againstJeremy Magland 7311. **Benchmarks: one problem, every method** — the Pac-Man domain, whose curved
74 boundary and re-entrant corner are unfair to everybody; the four families of
75 methods on one work-precision plot; and offline runs of the two best methods
76 in real MATLAB, Python and Julia (see `bench/`), which the plot can load so
77 that browser and native timings from the same machine share an axis.
79A **shared MATLAB library** page lists the small function files every lab boots
80with.
82## Using it
84Each lab has controls above the figures and, behind the "show script" button, the
85method itself. Edit the script and press run: the session reboots with your version
86compiled in, and the figures are whatever your code produces. Ctrl-Enter (Cmd-Enter)
87runs from inside the editor, and "reset" restores the original.
89Some labs run as soon as the chapter opens; the heavier ones wait for the run
90button, which the caption says.
e5fc8c6An introduction and static figures, and the MATLAB written plainly againJeremy Magland 92## Requirements
94numbl **0.4.19 or later**. The tutorial runs on 0.4.18 but is far slower there:
95several JIT limitations that this tutorial's profiling turned up were fixed in
960.4.19, and the MATLAB here is written in the plain form those fixes allow.
088be4cAn interactive tutorial on the Dirichlet problem, accuracy against costJeremy Magland 98## Development
100```
101npm install
102npm run dev # vite dev server
103npm run build # typecheck and bundle to dist/
104npm run test:matlab # the .m layer, through the numbl CLI (needs a numbl checkout)
105npm run test:browser # the built app in headless Chrome
6b05697Check the deployed site, not just a local build of itJeremy Magland 106npm run test:site # the deployed site, in headless Chrome
6292f12A benchmark chapter, and offline benchmarks to compare it againstJeremy Magland 109The offline benchmarks for Chapter 11 live in `bench/`, with their own README;
1a8bb6aMake the cross-language benchmark measure the languagesJeremy Magland 110they need only whichever of MATLAB, Python (NumPy and SciPy), or Julia is at
111hand, and each writes a JSON file that the benchmark chapter's plot loads. That
112README also records the three rules that keep a cross-language comparison from
113measuring the author instead of the languages.
e5fc8c6An introduction and static figures, and the MATLAB written plainly againJeremy Magland 115`test:matlab` needs a numbl clone; set `NUMBL_DIR` if it is not at `~/src/numbl`,
116and build its CLI (`npm run build:cli` in that checkout) after updating it — the
117tests run `dist-cli/cli.js`, not the TypeScript sources.
088be4cAn interactive tutorial on the Dirichlet problem, accuracy against costJeremy Magland 118Every assertion in it is a number claimed somewhere in the prose, so a failure means
119either the code or the text is wrong. `test:browser` needs `npm run build` first, and
120takes `--shots` to write a full-page screenshot of each chapter into `tmp/`.
122See [CLAUDE.md](CLAUDE.md) for how the pieces fit together, and in particular for the
123numbl performance rules that the drivers are written around.
0b6ac9cBuild and publish the site from the vault's CI on every push to mainJeremy Magland 125## Deployment
127`.cofferdam/workflows/deploy.yml` builds the page on every push to `main` and
128publishes it as the repository's site on the vault, at
129`/tutorials/laplace-dirichlet/site/`. The build is a plain `npm ci && npm run
130build`; `vite.config.ts` uses a relative `base`, so the sub-path needs no
131configuration. Note that the vault serves sites sandboxed, which makes
132`localStorage` throw rather than degrade: nothing here touches it, and nothing
6b05697Check the deployed site, not just a local build of itJeremy Magland 133here should start. `npm run test:site` loads the deployed page and checks that
134numbl really does run there, which serving the build locally cannot tell you.
088be4cAn interactive tutorial on the Dirichlet problem, accuracy against costJeremy Magland 136## Licence
138Apache-2.0.