API Reference#
Every supported module of volumential has a generated page below, built
from its docstring and its members. (The one exception is
volumential.qbfem, a 2019 finite-element experiment that nothing in the
tree imports and that is not part of the supported API.) Start from the
package page for the full module tree, or use the map further down to find the
module that owns a given piece of the volume FMM.
Volumential computes 2D and 3D volume potentials using the fast multipole method. |
Module map#
Package entry point#
volumential re-exports the handful of names most programs need and owns
the process-wide optimization and caching switches;
volumential.version owns the version tuple and the kernel revision that
is mixed into generated-kernel cache keys.
Box mesh generation#
The volume FMM operates over a box-shaped mesh generated by
volumential.meshgen. Adaptive refinement and coarsening of the tree of
boxes, including 2:1 level restriction, live in
volumential.tree_interactive_build, and the geometry objects handed to
the wranglers (bounding boxes, quadrature points, traversals) are assembled in
volumential.geometry.
Singular integrals#
volumential.singular_integral_2d uses Duffy-type transforms to
desingularize the integrands. It is 2D only, good at special kernel types
(specifically 1/r), and its complicated control flow is inefficient to
parallelize, so it only supports CPU multi-threading.
volumential.nearfield_potential_table uses Duffy-type radial
desingularization quadrature to build near-field tables in 2D and 3D.
Near-field tabulation#
The set of symmetry operations that can speed up precomputation depends on the
dimension and on the symmetry properties of the kernel;
volumential.list1_symmetry discovers them and
volumential.orbit_arithmetic canonicalizes table entries under them.
volumential.list1_gallery enumerates the interaction cases that can
occur in list 1, and volumential.list1 evaluates them on device
through the CSR interaction lists produced by the traversal.
Tables are stored in SQLite format and managed through
volumential.table_manager.NearFieldInteractionTableManager.
Fixed-parameter tables can also be assembled from a certified reduced kernel
expansion by volumential.rke_table_assembly.
Expansions and the volume FMM#
volumential.expansion_wrangler_interface states the interface the
volume FMM drives; volumential.wranglers implements it with a
sumpy and a pyfmmlib far-field backend, and
volumential.expansion_wrangler_fpnd re-exports that package unchanged.
volumential.volume_fmm drives the whole evaluation, and
volumential.phase_profile times its phases.
The volume potential is obtained over the internal box mesh; to get values on
another mesh, volumential.interpolation interpolates between box mesh
and meshmode discretizations. The interpolation is \(O(N \log N)\),
but it is almost always indistinguishable from \(O(N)\) in practice, since
the geometry lookup takes a very small fraction of the total runtime.
Sources and densities#
volumential.function_extension continues a source density given on a
curved domain to the surrounding box using layer potentials, so that the
extended values can be evaluated directly on volume quadrature targets.
volumential.gaussian supplies Gaussian fixtures, and
volumential.symbolic the symbolic expressions and evaluators the
drivers build densities from.
Support modules#
volumential.tools re-exports, unchanged, what now lives in focused
modules: the loopy kernel cache wrapper
(volumential.kernel_cache), scalar-field expression evaluation
(volumential.expression_eval) and the box-specific operators
(volumential.box_operators). volumential.lagrange holds the
barycentric Lagrange weights, and volumential.opcounters the explicit
operation counters and the build-routing readout that timing runs report.