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 five 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.
11. Benchmarks: one problem, every method — the Pac-Man domain, whose curved boundary and re-entrant corner are unfair to everybody; the four families of methods on one work-precision plot; and offline runs of the two best methods in real MATLAB, Python and Julia (see bench/), which the plot can load so that browser and native timings from the same machine share an axis.

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
npm run test:site      # the deployed site, in headless Chrome

The offline benchmarks for Chapter 11 live in bench/, with their own README; they need only whichever of MATLAB, Python + NumPy, or Julia is at hand, and each writes a JSON file that the benchmark chapter's plot loads.

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.

Deployment#

.cofferdam/workflows/deploy.yml builds the page on every push to main and publishes it as the repository's site on the vault, at /tutorials/laplace-dirichlet/site/. The build is a plain npm ci && npm run build; vite.config.ts uses a relative base, so the sub-path needs no configuration. Note that the vault serves sites sandboxed, which makes localStorage throw rather than degrade: nothing here touches it, and nothing here should start. npm run test:site loads the deployed page and checks that numbl really does run there, which serving the build locally cannot tell you.

Licence#

Apache-2.0.