The Dirichlet problem: accuracy against cost#

An interactive tutorial on solving the Dirichlet problem for Laplace's and Poisson's equations, in one and two dimensions, with every method written as a MATLAB-syntax script that you can edit and run in the page. It runs in your browser through numbl; there is no server, nothing to install, and nothing is sent anywhere.

The organising idea is that every problem in it has an exact solution known in closed form, by construction, so the error of every computation is known at every point to full precision. What the tutorial then measures is not whether a method works but what accuracy it delivers for what cost, and under which conditions that answer changes.

An introduction, before Chapter 1, defines Laplace's and Poisson's equations and the Dirichlet, Neumann and Robin boundary conditions, states what the tutorial measures, and lays out the four domains the chapters work on. Every chapter also carries one or two static diagrams, drawn as inline SVG, so that a page says something before its labs are run.

The problems#

In one dimension, Laplace's equation is $u'' = 0$ and its solution is a straight line, so Part I uses Poisson's equation $-u'' = f$ with the source manufactured from a chosen solution. Five solutions are available, differing in how hard they are to resolve: an entire function of moderate amplitude, an oscillatory one, a narrow Gaussian, a boundary layer, and one that is $C^2$ but not $C^3$.

In two dimensions the equation is Laplace's, and the exact solutions are harmonic functions written down in closed form: $e^x \sin y$, $\operatorname{Re}(x+iy)^k$, $e^{ky}\sin kx$, and $\log|z - z_0|$ with the singularity just outside the domain. Their boundary traces are the data, so the only error in the computation is the error of the method.

The chapters#

Introduction — Laplace's and Poisson's equations, the Dirichlet, Neumann and Robin boundary conditions, what accuracy-against-cost means here, and the four domains the chapters work on.

One dimension

1. Ground truth by construction — manufactured solutions, the three-point scheme, the tridiagonal solve, and what the error field looks like.
2. Second order, to its limit — the condition number $\kappa \approx 0.4N^2$, the roundoff floor near $10^{-8.5}$, and Richardson extrapolation.
3. Two more orders, almost free — Numerov's compact fourth-order scheme, which changes only the right-hand side, and how to read a work-precision diagram.
4. Chebyshev collocation — a dense matrix, geometric convergence to $10^{-13}$ with 64 points, and the two situations that take that away.

Two dimensions

5. The five-point Laplacian — harmonic ground truth, second order, and the $O(N^6)$ wall of a dense solve.
6. The fast Poisson solver — the same system diagonalised by the discrete sine transform: a million unknowns in half a second, identical answers.
7. Sixth order for the same price — the compact nine-point stencil, which is sixth-order accurate on Laplace's equation and uses the same fast solver, and two-dimensional Chebyshev collocation by matrix decomposition.
8. Iterating instead of solving — Jacobi, Gauss-Seidel, SOR, conjugate gradients and a multigrid V-cycle on one problem, and the question of when to stop.

Beyond the square

9. A corner, and what it costs — the L-shaped domain, the loss of second order to the $r^{2/3}$ singularity, and the method of particular solutions, which puts the singularity into the basis and reaches $10^{-14}$.
10. Boundary integral equations — a smooth curved domain, the double-layer potential, a second-kind Fredholm equation, the spectral accuracy of the periodic trapezoid rule, and the close-evaluation problem that comes with it.

A shared MATLAB library page lists the small function files every lab boots with.

Using it#

Each lab has controls above the figures and, behind the "show script" button, the method itself. Edit the script and press run: the session reboots with your version compiled in, and the figures are whatever your code produces. Ctrl-Enter (Cmd-Enter) runs from inside the editor, and "reset" restores the original.

Some labs run as soon as the chapter opens; the heavier ones wait for the run button, which the caption says.

Requirements#

numbl 0.4.19 or later. The tutorial runs on 0.4.18 but is far slower there: several JIT limitations that this tutorial's profiling turned up were fixed in 0.4.19, and the MATLAB here is written in the plain form those fixes allow.

Development#

npm install
npm run dev            # vite dev server
npm run build          # typecheck and bundle to dist/
npm run test:matlab    # the .m layer, through the numbl CLI (needs a numbl checkout)
npm run test:browser   # the built app in headless Chrome

test:matlab needs a numbl clone; set NUMBL_DIR if it is not at ~/src/numbl, and build its CLI (npm run build:cli in that checkout) after updating it — the tests run dist-cli/cli.js, not the TypeScript sources. Every assertion in it is a number claimed somewhere in the prose, so a failure means either the code or the text is wrong. test:browser needs npm run build first, and takes --shots to write a full-page screenshot of each chapter into tmp/.

See CLAUDE.md for how the pieces fit together, and in particular for the numbl performance rules that the drivers are written around.

Licence#

Apache-2.0.