User guide

How the volume FMM is put together, and what each part of it costs you.

• The volume-FMM workflow
• Anatomy of a near-field interaction
• Choosing a wrangler
• Near-Field Symmetry Reduction
• Near-field table build routing
• Derivative Support
• Helmholtz Split Formulation
• M1 Kernel Coverage
• Validation Matrix

The volume-FMM workflow is the one to read first: it walks the pipeline from a box mesh to a potential and says which module owns each stage. Anatomy of a near-field interaction is the visual bridge for a newcomer: one target box, the table-driven neighborhood, and the far-field FMM path. The remaining pages go deep on the parts that are not obvious from the source — Near-Field Symmetry Reduction on why the stored table is far smaller than the number of interactions it serves and what the SQLite cache actually holds; Near-field table build routing on how a table build is routed, how the loud fallback to the slow scalar builder announces itself, and how to refuse a table whose provenance cannot be verified; Derivative Support on the derivative wrappers and their sign bookkeeping; Helmholtz Split Formulation on the near-field split that makes one table family serve a range of wave numbers.

Choosing a wrangler is the one to read before quoting a far-field timing: which of the two wranglers to prefer for which kernel, dimension and device class, with the measurements behind the advice. It changes no default.

M1 Kernel Coverage and Validation Matrix record what is supported and what is actually tested, so a gap shows up as a gap rather than as an absent test name.