From 7fd1fc2a5ccf22ce972c11b3cb0c950a9d543f72 Mon Sep 17 00:00:00 2001 From: Matt Wala Date: Wed, 28 Jun 2017 23:48:39 -0500 Subject: [PATCH 1/2] Rename HelmholtzExpansionWrangler to FMMLibExpansionWrangler (follow up to 721f1ac2e39ec463fda753ea820e21bda953369c in boxtree). --- pytential/qbx/fmmlib.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pytential/qbx/fmmlib.py b/pytential/qbx/fmmlib.py index fd1dc4db..bb95cb30 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, -- GitLab From 4d275fc11279a46622da6e6335e494085b69bbb6 Mon Sep 17 00:00:00 2001 From: Matt Wala Date: Thu, 29 Jun 2017 00:38:13 -0500 Subject: [PATCH 2/2] Improve the QBX internals docs: 1) Fix some broken references in the geometry docs. 2) Add target association to the docs. 3) Various minor fixes --- doc/qbx.rst | 10 ++++ pytential/qbx/geometry.py | 41 ++-------------- pytential/qbx/refinement.py | 16 +++++- pytential/qbx/target_assoc.py | 92 ++++++++++++++++++++++------------- 4 files changed, 88 insertions(+), 71 deletions(-) diff --git a/doc/qbx.rst b/doc/qbx.rst index 46244da1..b4969866 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/geometry.py b/pytential/qbx/geometry.py index b08370df..8c4611c0 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 2ab598d8..6c47a104 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 946fe96b..1a447396 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. -- GitLab