1# fastandaccurate
3Speed and accuracy benchmarks for PDE solvers.
5Live site: https://concept-collection.github.io/fastandaccurate/
7A limitation of most solver comparisons is that they fix a
8discretization, which quietly decides much of the outcome. Here each
9**problem** is posed in the continuum with an exact reference solution;
10a solver chooses its own discretization and is scored at
11problem-specified evaluation points. The central object is the
12**work-precision curve**: error against compute time as the solver's
13resolution varies. No single ranking is presented; which curve wins can
14differ by accuracy regime, instance, and machine.
16Solvers are usually MATLAB function files. Most run via
17[numbl](https://numbl.org) (MATLAB syntax in the browser and in node),
18both on the site and from the command line; some run only in real
19MATLAB through the command line, and their results are marked as not
20reproducible in the browser. Two registry entries may share one file:
21the `-mat` solvers are their numbl twin's `solver.m` run in real MATLAB,
22so that pair of curves measures the runtime rather than the method. A
23problem's interface also has a TypeScript form, for a solver that cannot
24be a MATLAB file: `mfs-gpu` is the same method as `mfs` written in
25TypeScript and WGSL and run on a WebGPU device. Each problem defines its
26own interface and instances in a written specification; interfaces are
27per problem rather than shared.
29## Problems
31- [laplace-dirichlet-2d](docs/problems/laplace-dirichlet-2d.md) —
32 interior Dirichlet Laplace problem on a star-shaped domain, data
33 manufactured from an exact harmonic function whose singularities sit an
34 adjustable distance outside the boundary.
36## Results
38Results are work-precision sweeps stored as JSON files in
39[fastandaccurate-results](https://github.com/concept-collection/fastandaccurate-results)
40and added by pull request; the site reads that repository statically.
41Every result records its provenance: instance spec and hash, solver id
42and version, protocol, runtime, numbl version, and machine. Solvers
43included on the site can be rerun in the browser on the problem page to
44compare against the committed curves.
46## Running benchmarks outside the browser
48The command line installs from the site itself (node 20 or newer):
50```
51npx https://concept-collection.github.io/fastandaccurate/cli.tgz run --label "my workstation"
52```
54Note that npx caches by the exact URL string; the site offers the URL
55with a `?v=<commit>` suffix so each deployment is a fresh install.
57The solvers whose runtime is `matlab` need `matlab` on the PATH; the run
58skips them when it is absent. `chunkie-dlp` needs one thing more, the
59[mip](https://mip.sh) package manager on the MATLAB path, from which the
60harness installs chunkie and its FLAM and fmm2d dependencies on first
61use. Taking chunkie from mip rather than from a source clone is what
62makes its accelerated code path available without a Fortran compiler on
63the machine, since the mip fmm2d package ships a compiled MEX binary per
64platform.
66The solvers whose runtime is `webgpu` need a WebGPU device. In the
67browser that is `navigator.gpu`; outside it, it is the optional
68[`webgpu`](https://www.npmjs.com/package/webgpu) package (prebuilt Google
69Dawn). That package is 68 MB, so the published command line does not ship
70it and a run without it skips those solvers; `npm install webgpu` in a
71checkout is enough to have them.
73Useful flags: `--instance <id>`, `--solver <id>`, `--repeats N` (the
74minimum timed runs per point; each point is then repeated until it has
75used the `--time-budget`, 0.5 s by default), `--max-n N`, `--out dir`.
76To benchmark your own solver, point the harness at a MATLAB function file
77implementing the problem's interface:
79```
80npx https://concept-collection.github.io/fastandaccurate/cli.tgz run \
81 --solver-file my_method.m --solver-id my-method
82```
84The resulting JSON files can be loaded on the site (load result file) to
85view them against the committed curves, and submitted by PR to the
86results repository. To add a solver to the site itself (so visitors can
87rerun it in the browser), PR the solver directory and a manifest entry
88to this repository; see `src/solvers/`.
90## Development
92```
93npm install
94npm run dev # local dev server
95npm test # solver convergence tests through numbl in node
96npm run test:matlab # the same for the MATLAB-runtime solvers (needs matlab)
97npm run test:gpu # the same for the WebGPU solvers (needs a device)
98npm run build # type-check, site build, CLI tarball (dist/)
99npm run check-app # headless end-to-end check of the built site
100npm run check-gpu # headless check that a WebGPU solver runs in a page
101```
103Only `npm test` runs in CI, since a GitHub runner has neither MATLAB nor a
104GPU; the other three skip cleanly where their runtime is missing and are
105meant to be run locally before pushing solver changes.
107Layout: `src/problems/` holds problem specs, instances, exact solutions,
108the problem-side MATLAB and its TypeScript form; `src/solvers/` the
109solver files and manifests; `src/harness/` the shared runner, sweep,
110timing policy, and result schema (used identically by the browser worker
111and the CLI); `src/app/` the React site; `src/cli/` the command line.
113Deployed to GitHub Pages by `.github/workflows/deploy.yml` on push to
114main.
116## License
118Apache-2.0