API Reference
=============

Every supported module of :mod:`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.

.. autosummary::
   :toctree: generated
   :recursive:

   volumential

Module map
----------

Package entry point
^^^^^^^^^^^^^^^^^^^

:mod:`volumential` re-exports the handful of names most programs need and owns
the process-wide optimization and caching switches;
:mod:`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
:mod:`volumential.meshgen`.  Adaptive refinement and coarsening of the tree of
boxes, including 2:1 level restriction, live in
:mod:`volumential.tree_interactive_build`, and the geometry objects handed to
the wranglers (bounding boxes, quadrature points, traversals) are assembled in
:mod:`volumential.geometry`.

Singular integrals
^^^^^^^^^^^^^^^^^^

:mod:`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.

:mod:`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;
:mod:`volumential.list1_symmetry` discovers them and
:mod:`volumential.orbit_arithmetic` canonicalizes table entries under them.
:mod:`volumential.list1_gallery` enumerates the interaction cases that can
occur in *list 1*, and :mod:`volumential.list1` evaluates them on device
through the CSR interaction lists produced by the traversal.

Tables are stored in SQLite format and managed through
:class:`volumential.table_manager.NearFieldInteractionTableManager`.
Fixed-parameter tables can also be assembled from a certified reduced kernel
expansion by :mod:`volumential.rke_table_assembly`.

Expansions and the volume FMM
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

:mod:`volumential.expansion_wrangler_interface` states the interface the
volume FMM drives; :mod:`volumential.wranglers` implements it with a
:mod:`sumpy` and a :mod:`pyfmmlib` far-field backend, and
:mod:`volumential.expansion_wrangler_fpnd` re-exports that package unchanged.
:mod:`volumential.volume_fmm` drives the whole evaluation, and
:mod:`volumential.phase_profile` times its phases.

The volume potential is obtained over the internal box mesh; to get values on
another mesh, :mod:`volumential.interpolation` interpolates between box mesh
and :mod:`meshmode` discretizations.  The interpolation is :math:`O(N \log N)`,
but it is almost always indistinguishable from :math:`O(N)` in practice, since
the geometry lookup takes a very small fraction of the total runtime.

Sources and densities
^^^^^^^^^^^^^^^^^^^^^

:mod:`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.
:mod:`volumential.gaussian` supplies Gaussian fixtures, and
:mod:`volumential.symbolic` the symbolic expressions and evaluators the
drivers build densities from.

Support modules
^^^^^^^^^^^^^^^

:mod:`volumential.tools` re-exports, unchanged, what now lives in focused
modules: the :mod:`loopy` kernel cache wrapper
(:mod:`volumential.kernel_cache`), scalar-field expression evaluation
(:mod:`volumential.expression_eval`) and the box-specific operators
(:mod:`volumential.box_operators`).  :mod:`volumential.lagrange` holds the
barycentric Lagrange weights, and :mod:`volumential.opcounters` the explicit
operation counters and the build-routing readout that timing runs report.

Indices
-------

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`