diff --git a/doc/qbx.rst b/doc/qbx.rst index 46244da1086be469757fed4251ebdd946ed83af3..b49698663b9de46e643f571ee46f3148f603c4d0 100644 --- a/doc/qbx.rst +++ b/doc/qbx.rst @@ -3,11 +3,21 @@ QBX internals ============= +.. note:: + + This page documents :mod:`pytential` internals and is not typically + needed in end-user applications. + Refinement ---------- .. automodule:: pytential.qbx.refinement +Target association +------------------ + +.. automodule:: pytential.qbx.target_assoc + Data structures describing geometry ----------------------------------- diff --git a/pytential/qbx/fmmlib.py b/pytential/qbx/fmmlib.py index fd1dc4db89bb3628afb8cf35d218ee7d1ff5347a..bb95cb30a904b8592ea7b25f6d6d3d6089e19df6 100644 --- a/pytential/qbx/fmmlib.py +++ b/pytential/qbx/fmmlib.py @@ -26,7 +26,7 @@ import numpy as np from pytools import memoize_method import pyopencl as cl # noqa import pyopencl.array # noqa: F401 -from boxtree.pyfmmlib_integration import HelmholtzExpansionWrangler +from boxtree.pyfmmlib_integration import FMMLibExpansionWrangler from sumpy.kernel import HelmholtzKernel @@ -105,7 +105,7 @@ class ToHostTransferredGeoDataWrapper(object): # {{{ fmmlib expansion wrangler -class QBXFMMLibHelmholtzExpansionWrangler(HelmholtzExpansionWrangler): +class QBXFMMLibHelmholtzExpansionWrangler(FMMLibExpansionWrangler): def __init__(self, code, queue, geo_data, dtype, qbx_order, fmm_level_to_order, source_extra_kwargs, diff --git a/pytential/qbx/geometry.py b/pytential/qbx/geometry.py index b08370dfe697b2acc482256a2770d42c5d46d2a6..8c4611c01b0e3821e954e7cd2949020259025197 100644 --- a/pytential/qbx/geometry.py +++ b/pytential/qbx/geometry.py @@ -40,15 +40,8 @@ logger = logging.getLogger(__name__) # {{{ docs __doc__ = """ - -.. note:: - - This module documents :mod:`pytential` internals and is not typically - needed in end-user applications. - -This module documents data structures created for the execution of the QBX -FMM. For each pair of (target discretizations, kernels), -:class:`pytential.discretization.qbx.QBXDiscretization` creates an instance of +For each invocation of the QBX FMM with a distinct set of (target, side request) +pairs, :class:`pytential.qbx.QBXLayerPotentialSource` creates an instance of :class:`QBXFMMGeometryData`. The module is described in top-down fashion, with the (conceptually) @@ -62,8 +55,6 @@ Geometry data Subordinate data structures ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. autoclass:: CenterInfo() - .. autoclass:: TargetInfo() .. autoclass:: CenterToTargetList() @@ -288,7 +279,7 @@ class QBXFMMGeometryData(object): .. attribute:: lpot_source - The :class:`pytential.discretization.qbx.QBXDiscretization` + The :class:`pytential.qbx.QBXLayerPotentialSource` acting as the source geometry. .. attribute:: target_discrs_and_qbx_sides @@ -301,29 +292,8 @@ class QBXFMMGeometryData(object): *sides* is an array of (:class:`numpy.int8`) side requests for each target. - The side request can take the following values for each target: - - ===== ============================================== - Value Meaning - ===== ============================================== - 0 Volume target. If near a QBX center, - the value from the QBX expansion is returned, - otherwise the volume potential is returned. - - -1 Surface target. Return interior limit from - interior-side QBX expansion. - - +1 Surface target. Return exterior limit from - exterior-side QBX expansion. - - -2 Volume target. If within an *interior* QBX disk, - the value from the QBX expansion is returned, - otherwise the volume potential is returned. - - +2 Volume target. If within an *exterior* QBX disk, - the value from the QBX expansion is returned, - otherwise the volume potential is returned. - ===== ============================================== + The side request can take on the values + found in :ref:`qbx-side-request-table`. .. attribute:: cl_context @@ -335,7 +305,6 @@ class QBXFMMGeometryData(object): .. attribute:: ncenters .. automethod:: centers() - .. automethod:: radii() .. rubric :: Methods diff --git a/pytential/qbx/refinement.py b/pytential/qbx/refinement.py index 2ab598d85ba17e38c2533e9486bc597756a89156..6c47a1047e735bfa27d960129d96930dddde852a 100644 --- a/pytential/qbx/refinement.py +++ b/pytential/qbx/refinement.py @@ -61,11 +61,23 @@ three global QBX refinement criteria: The panel size is bounded by a kernel length scale. This applies only to Helmholtz kernels. -.. autoclass:: RefinerCodeContainer -.. autoclass:: RefinerWrangler +Warnings emitted by refinement +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. autoclass:: RefinerNotConvergedWarning +Helper functions +^^^^^^^^^^^^^^^^ + .. autofunction:: make_empty_refine_flags + +Refiner driver +^^^^^^^^^^^^^^ + +.. autoclass:: RefinerCodeContainer + +.. autoclass:: RefinerWrangler + .. autofunction:: refine_for_global_qbx """ diff --git a/pytential/qbx/target_assoc.py b/pytential/qbx/target_assoc.py index 946fe96b9ca7ad73f7685021ca2f128ea8bd5359..1a447396860a22f1c8a3bfe3c69539d4c5852350 100644 --- a/pytential/qbx/target_assoc.py +++ b/pytential/qbx/target_assoc.py @@ -46,18 +46,65 @@ unwrap_args = AreaQueryElementwiseTemplate.unwrap_args import logging logger = logging.getLogger(__name__) +__doc__ = """ +The goal of target association is to: + * decide which targets require QBX, + * decide which centers to use for targets that require QBX, + * if no good centers are available for a target that requires QBX, + flag the appropriate panels for refinement. + +Requesting a target side +^^^^^^^^^^^^^^^^^^^^^^^^ + +A target may further specify how it should be treated by target association. + +.. _qbx-side-request-table: + +.. table:: Values for target side requests + + ===== ============================================== + Value Meaning + ===== ============================================== + 0 Volume target. If near a QBX center, + the value from the QBX expansion is returned, + otherwise the volume potential is returned. + + -1 Surface target. Return interior limit from + interior-side QBX expansion. + + +1 Surface target. Return exterior limit from + exterior-side QBX expansion. + + -2 Volume target. If within an *interior* QBX disk, + the value from the QBX expansion is returned, + otherwise the volume potential is returned. + + +2 Volume target. If within an *exterior* QBX disk, + the value from the QBX expansion is returned, + otherwise the volume potential is returned. + ===== ============================================== + +Return values +^^^^^^^^^^^^^ + +.. autoclass:: QBXTargetAssociation + +.. autoclass:: QBXTargetAssociationFailedException + +Target association driver +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: TargetAssociationCodeContainer + +.. autoclass:: TargetAssociationWrangler + +.. autofunction:: associate_targets_to_qbx_centers +""" + + # -# TODO: -# - Documentation -# -#================== # HOW DOES TARGET ASSOCIATION WORK? # -# The goal of the target association is to: -# a) decide which targets require QBX, and -# b) decide which centers to use for targets that require QBX, and -# c) if no good centers are available for a target that requires QBX, -# flag the appropriate panels for refinement. # # The flow chart of what happens to target t is shown below. Pass names are in # parentheses: @@ -82,6 +129,7 @@ logger = logging.getLogger(__name__) # |Associate t with the | # |best available center. | # +-----------------------+ +# # {{{ kernels @@ -668,7 +716,7 @@ def associate_targets_to_qbx_centers(lpot_source, wrangler, target_discrs_and_qbx_sides, target_association_tolerance, debug=True, wait_for=None): """ - Entry point for calling the target associator. + Associate targets to centers in a layer potential source. :arg lpot_source: An instance of :class:`QBXLayerPotentialSource` @@ -685,29 +733,7 @@ def associate_targets_to_qbx_centers(lpot_source, wrangler, an array of (:class:`numpy.int8`) side requests for each target. - The side request can take the following values for each target: - - ===== ============================================== - Value Meaning - ===== ============================================== - 0 Volume target. If near a QBX center, - the value from the QBX expansion is returned, - otherwise the volume potential is returned. - - -1 Surface target. Return interior limit from - interior-side QBX expansion. - - +1 Surface target. Return exterior limit from - exterior-side QBX expansion. - - -2 Volume target. If within an *interior* QBX disk, - the value from the QBX expansion is returned, - otherwise the volume potential is returned. - - +2 Volume target. If within an *exterior* QBX disk, - the value from the QBX expansion is returned, - otherwise the volume potential is returned. - ===== ============================================== + The side request can take on the values in :ref:`qbx-side-request-table`. :raises QBXTargetAssociationFailedException: when target association failed to find a center for a target.