28f8ec1mesh-pde-solver: upload a quad mesh, solve PDEs on the surface in-browserJeremy Magland 1# CLAUDE.md
3Tips for future agents working in this repo.
5## Architecture
7```
f4de30dSimplify the solver to run-per-solve; drop the uihtml event bridgeJeremy Magland 8matlab/ the MATLAB project each solve runs standalone
9 main.m `mip load --install surfacefun` -> jsondecode params.json
10 -> solve_pde('mesh.msh', params) -> write result.json
43c610bUse surfacemesh.import instead of the hand-rolled mesh readersJeremy Magland 11 solve_pde.m surfacemesh.import -> resample -> surfaceop -> per-patch data
28f8ec1mesh-pde-solver: upload a quad mesh, solve PDEs on the surface in-browserJeremy Magland 12src/mesh/ Pyodide + meshio upload pipeline (bridge.py runs in Pyodide)
f4de30dSimplify the solver to run-per-solve; drop the uihtml event bridgeJeremy Magland 13src/engine/ run-per-solve wrapper over numbl/browser's
14 createNumblSession: solve() boots a fresh session with
15 mesh.msh + params.json staged, reads result.json back via
16 session.readFile, and disposes the worker. numbl owns the
17 worker, VFS, mip bootstrap, and IndexedDB package
18 persistence; prewarm() at page load triggers the one-time
19 package download.
28f8ec1mesh-pde-solver: upload a quad mesh, solve PDEs on the surface in-browserJeremy Magland 20src/pde/presets.ts PDE definitions, presets, size limits
21src/render/ three.js SurfaceView (mesh preview / solution) + parula
22scripts/engine-test.mjs headless Node check of the whole MATLAB pipeline
23```
25## Key gotchas
43c610bUse surfacemesh.import instead of the hand-rolled mesh readersJeremy Magland 27- **numbl >= 0.4.11 from npm.** Needs `NumblSession.readFile` (0.4.10) plus
28 enumeration-class support and the 1×1-tensor broadcast-assignment fix
29 (0.4.11 — surfacefun's `surfacemesh.patchtype` / `dealm` idiom depend on
30 both). To develop against a local numbl checkout, point package.json at
31 `file:../../numbl` and run `npm run build:lib && npm run build:browser`
32 there after source changes; when switching back to a `^` range,
33 `rm -rf node_modules package-lock.json && npm install` (else `npm ci` fails
34 on the stale `file:` link).
35- **surfacemesh.import needs MSH 4.1.** surfacefun's gmsh reader
36 (`+surfacemesh/+import/gmsh.m`) parses MSH 4.1 node-entity blocks, not
37 2.2. `src/mesh/bridge.py` and `scripts/make_samples.py` both write the
38 canonical 4.1 form (one surface entity block, sequential 1-based ids,
39 type-3 quads). Uploaded .msh files in other layouts pass through meshio
40 and get rewritten to 4.1.
f4de30dSimplify the solver to run-per-solve; drop the uihtml event bridgeJeremy Magland 41- **Solve errors reject the solve() promise** with the MATLAB error message
42 (a failed script run is a numbl bootError). Each solve is a fresh session,
43 so nothing needs to stay alive across failures.
28f8ec1mesh-pde-solver: upload a quad mesh, solve PDEs on the surface in-browserJeremy Magland 44- **jsonencode collapses 1-element vectors to scalars.** Patch arrays are
45 (p+1)^2 >= 9 long so it never bites here, but remember it when adding
46 payload fields.
47- Package caching: numbl/browser persists /system (mip + installed
43c610bUse surfacemesh.import instead of the hand-rolled mesh readersJeremy Magland 48 packages) in IndexedDB, wiped after 30 min of inactivity (numbl's default;
49 lowered from 24 h so a rebuilt surfacefun package refreshes without a manual
50 clear) — the prewarm session at page load re-downloads ~28 MB after a wipe;
51 solves after that only pay a per-run `mip load` (~1 s). Delete the
52 `numbl-embed-system` IndexedDB database to force a cold boot.
54## Testing
56- `npm run engine-test` — full headless solve in Node against the local
57 numbl build (dist-lib), including a quantitative eigenfunction check. It
f4de30dSimplify the solver to run-per-solve; drop the uihtml event bridgeJeremy Magland 58 runs matlab/main.m standalone per solve (as the browser does), sharing
59 one VFS across solves as the stand-in for IndexedDB persistence, and
28f8ec1mesh-pde-solver: upload a quad mesh, solve PDEs on the surface in-browserJeremy Magland 60 passes the mip search path explicitly, exercising the same
61 searchPaths-scan behavior the numbl/browser session relies on. Downloads
62 are cached in `.cache/` keyed by URL; delete the cache to test fresh
63 installs.
64- `python3 <venv>/bin/python` with meshio 5.3.5 can exercise
65 `src/mesh/bridge.py` outside Pyodide (redirect its `/work` constant).
66- Browser verification (Pyodide upload path, session boot, IndexedDB
67 persistence across reloads, 3D view) is manual: `npm run dev`.