| name | verify-example |
| description | Run a Poisson example headlessly on the CPU backend to verify that library or kernel changes still converge to the right solution. Use after changing src/ internals or example kernels. |
| tools | Bash, Glob, Grep, Read, Edit |
Verify example
Run one of the examples/Poisson/*.jl scripts as a smoke/convergence test
without a GPU or a display.
1. Pick the example
1D/2D/3D_Poisson.jl — direct sparse solves, fastest sanity check*_Poisson_AD.jl — CPU pseudo-transient (PT) solvers with ForwardDiff*_Poisson_AD_KA.jl — KernelAbstractions PT solvers (CPU/GPU backends)
Prefer the example closest to the changed code; for src/ changes the plain
3D_Poisson.jl plus one KA script is usually enough.
2. Make it headless and cheap
Run a modified copy (or include with overrides) — do not commit these
edits:
- backend:
const backend = CPU() (KA scripts hardcode CUDABackend())
- grid: shrink
n (e.g. 8–16 per dimension) so the run takes seconds
- plotting: skip the GLMakie block (everything after the iteration loop and
display(to)), or run with xvfb-run if the figure itself is under test
- iterations: PT loops break on
nr/nr0 < epsi; leave the tolerance alone so
convergence is actually exercised
julia --project -t auto /tmp/example_modified.jl
3. What "passing" means
- The convergence trace (
Iter. xxxxx: r/r0) must decrease monotonically
over checkpoints and reach the tolerance — not stall, not NaN
(the scripts already error("NaNs")).
- For PT scripts, both assembly variants (atomic and colored) must agree:
same trace when swapping which one is enabled.
- For solution correctness, compare against the direct-solve example on the
same mesh/BCs, or against an analytic case: uniform source with
homogeneous Dirichlet BCs on the unit cube has a known symmetric bump
(and matches
examples/Poisson/KA_sandbox/poisson_2step.jl).
- Beware trivial setups: zero source with constant-matching BCs converges
instantly to a constant and verifies nothing.
4. Report
Quote the final nr/nr0, the iteration count, and which variants were run.
If the trace diverges or stalls, bisect: backend (CPU vs GPU), assembly
variant (atomic vs colored), element order (Q1 vs Q2) — in that order.
