Anatomy of a near-field interaction#

The central numerical idea in Volumential is easier to understand as a picture than as a wrangler class name.

Schematic. A five by five block of boxes. The target box and its eight neighbors are table lookups, the target box's own interaction included; the outer ring is handled by the FMM with multipole and local expansions.

Schematic, not computed output: a uniform neighborhood. Adaptive traversals add relationships between levels, but the split is the same: difficult local integrals are tabulated; well-separated interactions stay on the ordinary FMM path.#

Why the neighboring boxes are special#

For a volume potential

\[ u(\boldsymbol{x}) = \int_\Omega G(\boldsymbol{x}, \boldsymbol{y}) f(\boldsymbol{y})\, \mathrm{d}\boldsymbol{y}, \]

the target can lie inside the source box. The kernel is then genuinely singular. In neighboring boxes it is finite but near-singular. The tensor-product point quadrature that is perfectly useful for well-separated particles is the wrong tool for those interactions.

Volumential therefore changes how the local interaction is evaluated, not the far-field algorithm.

What is tabulated#

For a fixed kernel, dimension, quadrature order and source-box scale, the near-field table stores the integral of the kernel against the source basis for each target node and relative interaction case. Building those entries uses singular-aware quadrature; applying them later is a lookup/reconstruction operation.

That is why the table can be reused when the source density changes. It is about the local geometry and kernel, not about the values of \(f\) in one run.

What still goes through the FMM#

Well-separated boxes use the volume quadrature nodes as weighted particles. Multipole and local expansions are ordinary sumpy/FMM machinery. The two paths are accumulated into the same target potential.

Schematic flow chart. The source density at the box quadrature nodes goes into a tree with its traversal, then splits into a near-field path, a precomputed table lookup, and a far-field path, ordinary FMM expansions; the two paths add up to the potential.

Schematic, not computed output: the two paths of the computation. The volume-FMM workflow names the objects and modules behind each box.#

On a graded tree#

An adaptive tree is kept 2:1 balanced: leaves that touch differ by at most one level. That keeps List 1 inside the cases the table stores, neighbours of half, equal and twice the size of the target box, and the far field needs nothing more (volumential.tree_interactive_build).

It does let one kind of far-field pair come closer than the others. A box can be split while a neighbour of the same size stays a leaf, and that leaf then reaches the children of the split box that do not touch it through List 4. It is twice the size of such a target box and only half its own size away from it; a List 2 or List 3 source is never closer than its own size. The far field integrates it like every other source, by point quadrature at its nodes, and at half a box size that quadrature is much worse. On 2-D trees graded over two or three levels, at q_order 4 to 8, the error these pairs add is 7 to 2800 times the error of the far pairs one to two source sizes away, and the gap grows with q_order.

In the total error they are a minor term so far. On a 16 x 16 tree refined twice around a narrow source (535 leaves on levels 4 to 6), at q_order 8 they account for 21% of the max error, which is 2.9e-9, and 2% of the relative L2 error; at q_order 4 they do not show. Integrating them from an upsampled source is #178, which has the measurements.

Where symmetry enters#

The tabulated neighborhood contains many interactions that are equivalent under box symmetries. Volumential stores canonical cases and reconstructs the others online instead of storing every geometrically equivalent entry.

Continue with:

This page is deliberately conceptual. Those pages remain the source of truth for the exact interaction-case encoding, adaptive traversal details and cache payload.