QBX internals

Note

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

Refinement

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

Helper functions

pytential.qbx.refinement.make_empty_refine_flags(actx, density_discr)

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

Parameters:

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

Returns:

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

Refiner driver

class pytential.qbx.refinement.RefinerCodeContainer(actx: PyOpenCLArrayContext)

class pytential.qbx.refinement.RefinerWrangler(array_context: PyOpenCLArrayContext, code_container)

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)

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.

Parameters:

• places – A GeometryCollection.

• refine_discr_stage – Defines up to which stage the refinement should be performed. One of QBX_SOURCE_STAGE1, QBX_SOURCE_STAGE2 or QBX_SOURCE_QUAD_STAGE2.

• group_factory – An instance of meshmode.discretization.ElementGroupFactory. Used for discretizing the coarse refined mesh.

• kernel_length_scale – The kernel length scale, or None if not applicable. All elements are refined to below this size.

• maxiter – The maximum number of refiner iterations.

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

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

class pytential.qbx.target_assoc.QBXTargetAssociation(valuedict: Mapping[str, Any] | None = None, exclude: Sequence[str] | None = None, **kwargs: Any)

target_to_center

Target association driver

class pytential.qbx.target_assoc.TargetAssociationCodeContainer(actx: PyOpenCLArrayContext)

class pytential.qbx.target_assoc.TargetAssociationWrangler(array_context: PyOpenCLArrayContext, code_container)

pytential.qbx.target_assoc.associate_targets_to_qbx_centers(places: GeometryCollection, geometry, wrangler: TargetAssociationWrangler, target_discrs_and_qbx_sides, target_association_tolerance, debug: bool = True, wait_for: WaitList = None)

Associate targets to centers in a layer potential source.

Parameters:

• places – A GeometryCollection.

• geometry – Name of the source geometry in places for which to associate targets.

• wrangler – An instance of TargetAssociationWrangler

• target_discrs_and_qbx_sides –

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

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

Raises:

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

Returns:

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: GeometryCollection, source_dd: DOFDescriptor, code_getter: QBXFMMGeometryDataCodeContainer, target_discrs_and_qbx_sides: Sequence[tuple[TargetOrDiscretization, QBXForcedLimit]], target_association_tolerance: float, tree_kind, debug: bool | None = None)

Attributes

places

A GeometryCollection containing the QBXLayerPotentialSource.

source_dd

Symbolic name for the QBXLayerPotentialSource in the collection places.

code_getter: QBXFMMGeometryDataCodeContainer

target_discrs_and_qbx_sides

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.

ambient_dim

coord_dtype

Expansion centers

ncenters

flat_centers()

Return an object array of (interleaved) center coordinates.

coord_t [ambient_dim][ncenters]

Methods

target_info()

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

tree()

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

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

traversal()

Return a boxtree.traversal.FMMTraversalInfo.

Parameters:

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.

qbx_center_to_target_box()

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.

global_qbx_flags()

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.

global_qbx_centers()

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.

user_target_to_center()

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.

center_to_tree_targets()

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.

non_qbx_box_target_lists()

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()

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

Parameters:

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

Note

This only works for two-dimensional geometries.

The following methods implement the boxtree.pyfmmlib_integration.FMMLibRotationDataInterface.

m2l_rotation_lists()

m2l_rotation_angles()

Subordinate data structures

class pytential.qbx.geometry.TargetInfo

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.

targets

Shape: [dim,ntargets]

target_discr_starts

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.)

ntargets

class pytential.qbx.geometry.CenterToTargetList

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().

starts

Shape: [ncenters+1]

lists

Lists of targets in tree order. Use with starts.

Enums of special values

class pytential.qbx.geometry.target_state

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

NO_QBX_NEEDED

FAILED

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: FromSepSmallerCrit)

property build_leaf_to_ball_lookup

property build_traversal

copy_targets_kernel()

filter_center_and_target_ids(particle_id_dtype)

property key_value_sort

property pick_used_centers

qbx_center_to_target_box_lookup(particle_id_dtype, box_id_dtype)

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)

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)

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

form_global_qbx_locals(src_weight_vecs)

translate_box_local_to_qbx_local(local_exps)

eval_qbx_expansions(qbx_expansions)

pytential.qbx.fmm.drive_fmm(expansion_wrangler, src_weight_vecs, timing_data=None)

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

Parameters:

• geo_data – A pytential.qbx.geometry.QBXFMMGeometryData instance.

• expansion_wrangler – An object exhibiting the boxtree.fmm.ExpansionWranglerInterface.

• src_weight_vecs – A sequence of source ‘density/weights/charges’. Passed unmodified to expansion_wrangler.

• timing_data – Either None or a dictionary that collects timing data.

Returns the potentials computed by expansion_wrangler.

See also boxtree.fmm.drive_fmm().

Cost model

Note

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)

Provides modeled costs for individual translations or evaluations.

pytential.qbx.cost.make_pde_aware_translation_cost_model(dim, nlevels)

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)

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>)

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

• To obtain operation counts only, use get_unit_calibration_params() with qbx_cost_per_stage() or qbx_cost_per_box().

• To calibrate the model, pass operation counts per stage together with timing data to estimate_kernel_specific_calibration_params().

• To evaluate the calibrated models, pass the kernel-specific calibration parameters from estimate_kernel_specific_calibration_params() to qbx_cost_per_stage() or qbx_cost_per_box().

class pytential.qbx.cost.QBXCostModel(translation_cost_model_factory=<function make_pde_aware_translation_cost_model>)

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')

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

Parameters:

• 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".

Returns:

a dict which maps kernels to calibration parameters.

Evaluating

AbstractQBXCostModel.qbx_cost_per_stage(queue, geo_data, kernel, kernel_arguments, calibration_params)

AbstractQBXCostModel.qbx_cost_per_box(queue, geo_data, kernel, kernel_arguments, calibration_params)

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

Utilities

abstractmethod AbstractFMMCostModel.aggregate_over_boxes(per_box_result)

Sum all entries of per_box_result into a number.

Parameters:

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

Returns:

a float, the result of the sum.

static AbstractQBXCostModel.get_unit_calibration_params()