QBX internals#


This page documents pytential internals and is not typically needed in end-user applications.


The refiner takes a layer potential source and refines it until it satisfies three global QBX refinement criteria:

  • Condition 1 (Expansion disk undisturbed by sources)

    A center must be closest to its own source.

  • Condition 2 (Sufficient quadrature sampling from all source elements)

    The quadrature contribution from each element is as accurate as from the center’s own source element.

  • Condition 3 (Element size bounded based on kernel length scale)

    The element size is bounded by a kernel length scale. This applies only to Helmholtz kernels.

Warnings emitted by refinement#

class pytential.qbx.refinement.RefinerNotConvergedWarning[source]#

Helper functions#

pytential.qbx.refinement.make_empty_refine_flags(actx, density_discr)[source]#

Return an array on the device suitable for use as element refine flags.


density_discr – An instance of a meshmode.discretization.Discretization.


A pyopencl.array.Array suitable for use as refine flags, initialized to zero.

Refiner driver#

class pytential.qbx.refinement.RefinerCodeContainer(actx: PyOpenCLArrayContext)[source]#
class pytential.qbx.refinement.RefinerWrangler(array_context: PyOpenCLArrayContext, code_container)[source]#
pytential.qbx.refinement.refine_geometry_collection(places, group_factory=None, refine_discr_stage=None, kernel_length_scale=None, force_stage2_uniform_refinement_rounds=None, scaled_max_curvature_threshold=None, expansion_disturbance_tolerance=None, maxiter=None, debug=None, visualize=False)[source]#

Entry point for refining all the QBXLayerPotentialSource in the given collection. The GeometryCollection performs on-demand refinement, but this function can be used to tweak the parameters.


Target association#

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 elements for refinement.

Requesting a target side#

A target may further specify how it should be treated by target association.

Values for target side requests#




Volume target. If near a QBX center, the value from the QBX expansion is returned, otherwise the volume potential is returned.


Surface target. Return interior limit from interior-side QBX expansion.


Surface target. Return exterior limit from exterior-side QBX expansion.


Volume target. If within an interior QBX disk, the value from the QBX expansion is returned, otherwise the volume potential is returned.


Volume target. If within an exterior QBX disk, the value from the QBX expansion is returned, otherwise the volume potential is returned.

Return values#

class pytential.qbx.target_assoc.QBXTargetAssociation(valuedict=None, exclude=None, **kwargs)[source]#

Target association driver#

class pytential.qbx.target_assoc.TargetAssociationCodeContainer(actx: PyOpenCLArrayContext)[source]#
class pytential.qbx.target_assoc.TargetAssociationWrangler(array_context: PyOpenCLArrayContext, code_container)[source]#
pytential.qbx.target_assoc.associate_targets_to_qbx_centers(places, geometry, wrangler, target_discrs_and_qbx_sides, target_association_tolerance, debug=True, wait_for=None)[source]#

Associate targets to centers in a layer potential source.


pytential.qbx.QBXTargetAssociationFailedException – when target association failed to find a center for a target. The returned exception object contains suggested refine flags.


A QBXTargetAssociation.

Data structures describing geometry#

For each invocation of the QBX FMM with a distinct set of (target, side request) pairs, pytential.qbx.QBXLayerPotentialSource creates an instance of QBXFMMGeometryData.

The module is described in top-down fashion, with the (conceptually) highest-level objects first.

Geometry data#

class pytential.qbx.geometry.QBXFMMGeometryData(places, source_dd, code_getter, target_discrs_and_qbx_sides, target_association_tolerance, tree_kind, debug=None)[source]#



A GeometryCollection containing the QBXLayerPotentialSource.


Symbolic name for the QBXLayerPotentialSource in the collection places.


The QBXFMMGeometryDataCodeContainer for this object.


A list of tuples (discr, sides), where discr is a meshmode.discretization.Discretization or a pytential.target.TargetBase instance, and sides is an array of (numpy.int8) side requests for each target.

The side request can take on the values found in Values for target side requests.


Expansion centers


Return an object array of (interleaved) center coordinates.

coord_t [ambient_dim][ncenters]



Return a TargetInfo. Output is cached. Use obj.<method_name>.clear_cache(obj) to clear.


Build and return a boxtree.Tree for this source with these targets.

Output is cached. Use obj.<method_name>.clear_cache(obj) to clear.


Return a boxtree.traversal.FMMTraversalInfo.


merge_close_lists – Use merged close lists. (See boxtree.traversal.FMMTraversalInfo.merge_close_lists())

Output is cached. Use obj.<method_name>.clear_cache(obj) to clear.


Return a lookup table of length ncenters indicating the target box in which each QBX disk is located.

Output is cached. Use obj.<method_name>.clear_cache(obj) to clear.


Return an array of numpy.int8 of length ncenters indicating whether each center can use gloal QBX, i.e. whether a single expansion can mediate interactions from all sources to all targets for which it is valid. If global QBX can be used, the center’s entry will be 1, otherwise it will be 0.

(If not, local QBX is needed, and the center may only be able to mediate some of the interactions to a given target.)

Output is cached. Use obj.<method_name>.clear_cache(obj) to clear.


Build a list of indices of QBX centers that use global QBX. This indexes into the global list of targets, (see target_info()) of which the QBX centers occupy the first ncenters.

Centers without any associated targets are excluded.


Find which QBX center, if any, is to be used for each target. target_state.NO_QBX_NEEDED if none. target_state.FAILED if a center needs to be used, but none was found. See center_to_tree_targets() for the reverse look-up table.

Shape: [ntargets] of boxtree.Tree.particle_id_dtype, with extra values from target_state allowed. Targets occur in user order.


Return a CenterToTargetList. See user_target_to_center() for the reverse look-up table with targets in user order. Output is cached. Use obj.<method_name>.clear_cache(obj) to clear.


Build a list of targets per box that don’t need to bother with QBX. Returns a boxtree.tree.FilteredTargetListsInTreeOrder. (I.e. a new target order is created for these targets, as we expect there to be many of them.)

Output is cached. Use obj.<method_name>.clear_cache(obj) to clear.


Plot most of the information contained in a QBXFMMGeometryData object, for debugging.


highlight_centers – If not None, an object with which the array of centers can be indexed to find the highlighted centers.


This only works for two-dimensional geometries.

The following methods implement the boxtree.pyfmmlib_integration.FMMLibRotationDataInterface.


Subordinate data structures#

class pytential.qbx.geometry.TargetInfo[source]#

Describes the internal structure of the QBX FMM’s list of targets. The list consists of QBX centers, then target points for each target discretization. The starts of the target points for each target discretization are given by target_discr_starts.


Shape: [dim,ntargets]


Shape: [ndiscrs+1]

Start indices of targets for each target discretization.

The first entry here is the start of the targets for the first target discretization. (The QBX centers start at index 0, a fact which is not explicitly represented.)

class pytential.qbx.geometry.CenterToTargetList[source]#

A lookup table of targets covered by each QBX disk. Indexed by global number of QBX center, lists[start[i]:start[i+1]] indicates numbers of the overlapped targets in tree target order.

See QBXFMMGeometryData.center_to_tree_targets().


Shape: [ncenters+1]


Lists of targets in tree order. Use with starts.

Enums of special values#

class pytential.qbx.geometry.target_state[source]#

This enumeration contains special values that are used in the array returned by QBXFMMGeometryData.user_target_to_center().


The code is unable to compute an accurate potential for this target. This happens if it is determined that QBX is required to compute an accurate potential, but no suitable center is found.

Geometry description code container#

class pytential.qbx.geometry.QBXFMMGeometryDataCodeContainer(actx: PyOpenCLArrayContext, ambient_dim: int, debug: bool, _well_sep_is_n_away: int, _from_sep_smaller_crit: str)[source]#
property build_leaf_to_ball_lookup#
property build_traversal#
property key_value_sort#
property pick_used_centers#
qbx_center_to_target_box_lookup(particle_id_dtype, box_id_dtype)[source]#
property rotation_classes_builder#

Fast multipole driver#

class pytential.qbx.fmm.QBXSumpyTreeIndependentDataForWrangler(cl_context, multipole_expansion_factory, local_expansion_factory, qbx_local_expansion_factory, target_kernels, source_kernels)[source]#
class pytential.qbx.fmm.QBXExpansionWrangler(tree_indep, geo_data, dtype, qbx_order, fmm_level_to_order, source_extra_kwargs, kernel_extra_kwargs, translation_classes_data=None, _use_target_specific_qbx=None)[source]#

A specialized implementation of the boxtree.fmm.ExpansionWranglerInterface for the QBX FMM. The conventional (‘point’) FMM is carried out on a filtered set of targets (see pytential.qbx.geometry.QBXFMMGeometryData.non_qbx_box_target_lists()), and thus all non-QBX potential arrays handled by this wrangler don’t include all targets in the tree, just the non-QBX ones.

QBX-specific methods

pytential.qbx.fmm.drive_fmm(expansion_wrangler, src_weight_vecs, timing_data=None, traversal=None)[source]#

Top-level driver routine for the QBX fast multipole calculation.


Returns the potentials computed by expansion_wrangler.

See also boxtree.fmm.drive_fmm().

Cost model#


This module is experimental. Its interface is subject to change until this notice is removed.

This module helps predict the running time of each step of QBX, as an extension of the similar module boxtree.cost in boxtree.

QBXTranslationCostModel describes the translation or evaluation cost of a single operation. For example, m2qbxl describes the cost for translating a single multipole expansion to a QBX local expansion.

AbstractQBXCostModel uses QBXTranslationCostModel and kernel-specific calibration parameter to compute the total cost of each step of QBX in each box. QBXCostModel is one implementation of AbstractQBXCostModel using OpenCL.

examples/cost.py in the source distribution demonstrates how the calibration and evaluation are performed.

Translation Cost of a Single Operation#

class pytential.qbx.cost.QBXTranslationCostModel(ncoeffs_qbx, ncoeffs_fmm_by_level, uses_point_and_shoot)[source]#

Provides modeled costs for individual translations or evaluations.

pytential.qbx.cost.make_pde_aware_translation_cost_model(dim, nlevels)[source]#

Create a cost model for FMM translation operators that make use of the knowledge that the potential satisfies a PDE.

pytential.qbx.cost.make_taylor_translation_cost_model(dim, nlevels)[source]#

Create a cost model for FMM translation based on Taylor expansions in Cartesian coordinates.

Cost Model Classes#

class pytential.qbx.cost.AbstractQBXCostModel(translation_cost_model_factory=<function make_pde_aware_translation_cost_model>)[source]#

An interface to obtain both QBX operation counts and calibrated (e.g. in seconds) cost estimates.

class pytential.qbx.cost.QBXCostModel(translation_cost_model_factory=<function make_pde_aware_translation_cost_model>)[source]#

This class is an implementation of interface AbstractQBXCostModel using pyopencl.

Calibration (Generate Calibration Parameters)#

AbstractQBXCostModel.estimate_kernel_specific_calibration_params(model_results, timing_results, time_field_name='wall_elapsed')[source]#

Get kernel-specific calibration parameters from samples of model costs and real costs.

  • model_results – a list of modeled costs. Each model cost can be obtained from BoundExpression.cost_per_stage with “constant_one” for argument calibration_params.

  • timing_results – a list of timing data. Each timing data can be obtained from BoundExpression.eval.

  • time_field_name – a str, the field name from the timing result. Usually this can be "wall_elapsed" or "process_elapsed".


a dict which maps kernels to calibration parameters.


AbstractQBXCostModel.qbx_cost_per_stage(queue, geo_data, kernel, kernel_arguments, calibration_params)[source]#
AbstractQBXCostModel.qbx_cost_per_box(queue, geo_data, kernel, kernel_arguments, calibration_params)[source]#

To get the cost from BoundExpression, refer to pytential.symbolic.execution.BoundExpression.cost_per_stage() and pytential.symbolic.execution.BoundExpression.cost_per_box().


abstract AbstractFMMCostModel.aggregate_over_boxes(per_box_result)[source]#

Sum all entries of per_box_result into a number.


per_box_result – an object of numpy.ndarray or pyopencl.array.Array, the result to be sumed.


a float, the result of the sum.

static AbstractQBXCostModel.get_unit_calibration_params()[source]#