FMM driver

boxtree.fmm.drive_fmm(wrangler: ExpansionWranglerInterface, src_weight_vecs, timing_data=None, global_src_idx_all_ranks=None, global_tgt_idx_all_ranks=None)

Top-level driver routine for a fast multipole calculation.

In part, this is intended as a template for custom FMMs, in the sense that you may copy and paste its source code as a starting point.

Nonetheless, many common applications (such as point-to-point FMMs) can be covered by supplying the right expansion_wrangler to this routine.

Parameters:

• expansion_wrangler – An object exhibiting the ExpansionWranglerInterface. For distributed implementation, this wrangler should be a subclass of boxtree.distributed.calculation.DistributedExpansionWrangler.

• src_weight_vecs – A sequence of source ‘density/weights/charges’. Passed unmodified to expansion_wrangler. For distributed implementation, this argument is only significant on the root rank, but worker ranks still need to supply a dummy vector.

• timing_data – Either None, or a dict that is populated with timing information for the stages of the algorithm (in the form of TimingResult), if such information is available.

• global_src_idx_all_ranks – Only used in the distributed implementation. A list of length nranks, where the i-th entry is a numpy.ndarray representing the global indices of sources in the local tree on rank i. Each entry can be returned from generate_local_tree. This argument is only significant on the root rank.

• global_tgt_idx_all_ranks – Only used in the distributed implementation. A list of length nranks, where the i-th entry is a numpy.ndarray representing the global indices of targets in the local tree on rank i. Each entry can be returned from generate_local_tree. This argument is only significant on the root rank.

Returns:

the potentials computed by expansion_wrangler. For the distributed implementation, the potentials are gathered and returned on the root rank; this function returns None on the worker ranks.

class boxtree.fmm.TreeIndependentDataForWrangler

An object that can be used to store information for efficient wrangler execution that depends on the kernel but not the tree and/or the traversal.

Examples of such data include generated code for carrying out translations.

Note

Instances of this type should not hold a reference (and thereby be specific to) a boxtree.Tree instance. Their purpose is to host caches for generated translation code that is reusable across trees. It is OK for these instances to be specific to a given kernel (or set of kernels).

class boxtree.fmm.ExpansionWranglerInterface(tree_indep: TreeIndependentDataForWrangler, traversal: FMMTraversalInfo)

Abstract expansion handling interface for use with drive_fmm().

See this test code for a very simple sample implementation.

Note

Wranglers may hold a reference (and thereby be specific to) a boxtree.Tree instance. TreeIndependentDataForWrangler exists to hold data that is more broadly reusable.

Functions that support returning timing data return a value supporting the TimingFuture interface.

Changed in version 2018.1: Changed (a subset of) functions to return timing data.

tree_indep

An instance of (a typically wrangler-dependent subclass of) TreeIndependentDataForWrangler.

traversal

An instance of FMMTraversalInfo.

tree

Particle ordering

abstract reorder_sources(source_array)

Return a copy of source_array in tree source order. source_array is in user source order.

abstract reorder_potentials(potentials)

Return a copy of potentials in user target order. source_weights is in tree target order.

Views into arrays of expansions

abstract multipole_expansions_view(mpole_exps, level)

abstract local_expansions_view(local_exps, level)

Translations

abstract form_multipoles(level_start_source_box_nrs, source_boxes, src_weight_vecs)

Return an expansions array containing multipole expansions in source_boxes due to sources with src_weight_vecs. All other expansions must be zero.

Returns:

A pair (mpoles, timing_future).

abstract coarsen_multipoles(level_start_source_parent_box_nrs, source_parent_boxes, mpoles)

For each box in source_parent_boxes, gather (and translate) the box’s children’s multipole expansions in mpole and add the resulting expansion into the box’s multipole expansion in mpole.

Returns:

A pair (mpoles, timing_future).

abstract eval_direct(target_boxes, neighbor_sources_starts, neighbor_sources_lists, src_weight_vecs)

For each box in target_boxes, evaluate the influence of the neighbor sources due to src_weight_vecs, which use CSR-like interaction list storage and are indexed like target_boxes.

Returns:

A pair (pot, timing_future), where pot is a a new potential array.

abstract multipole_to_local(level_start_target_or_target_parent_box_nrs, target_or_target_parent_boxes, starts, lists, mpole_exps)

For each box in target_or_target_parent_boxes, translate and add the influence of the multipole expansion in mpole_exps into a new array of local expansions. starts and lists use CSR-like interaction list storage, and starts is indexed like target_or_target_parent_boxes.

Returns:

A pair (pot, timing_future) where pot is a new (local) expansion array.

abstract eval_multipoles(target_boxes_by_source_level, from_sep_smaller_by_level, mpole_exps)

For a level i, each box in target_boxes_by_source_level[i], evaluate the multipole expansion in mpole_exps in the nearby boxes given in from_sep_smaller_by_level, and return a new potential array. starts and lists in from_sep_smaller_by_level[i] use CSR-like interaction list storage and starts is indexed like target_boxes_by_source_level[i].

Returns:

A pair (pot, timing_future) where pot is a new potential array.

abstract form_locals(level_start_target_or_target_parent_box_nrs, target_or_target_parent_boxes, starts, lists, src_weight_vecs)

For each box in target_or_target_parent_boxes, form local expansions due to the sources in the nearby boxes given in starts and lists, and return a new local expansion array. starts and lists use CSR-like interaction list storage and starts is indexed like target_or_target_parent_boxes.

Returns:

A pair (pot, timing_future) where pot is a new local expansion array.

abstract refine_locals(level_start_target_or_target_parent_box_nrs, target_or_target_parent_boxes, local_exps)

For each box in child_boxes, translate the box’s parent’s local expansion in local_exps and add the resulting expansion into the box’s local expansion in local_exps.

Returns:

A pair (local_exps, timing_future).

abstract eval_locals(level_start_target_box_nrs, target_boxes, local_exps)

For each box in target_boxes, evaluate the local expansion in local_exps and return a new potential array.

Returns:

A pair (pot, timing_future) where pot is a new potential array.

abstract finalize_potentials(potentials, template_ary)

Postprocess the reordered potentials. This is where global scaling factors could be applied. This is distinct from reorder_potentials() because some derived FMMs (notably the QBX FMM) do their own reordering.

Parameters:

template_ary – If the array type used inside of the FMM is different from the array type used by the user (e.g. boxtree.pyfmmlib_integration.FMMLibExpansionWrangler uses numpy.ndarray internally, this array can be used to help convert the output back to the user’s array type (typically pyopencl.array.Array).

Integrates boxtree with pyfmmlib.

class boxtree.pyfmmlib_integration.FMMLibTreeIndependentDataForWrangler(dim, kernel, ifgrad=False)

__init__(dim, kernel, ifgrad=False)

class boxtree.pyfmmlib_integration.FMMLibExpansionWrangler(tree_indep, traversal, *, helmholtz_k=None, fmm_level_to_order=None, dipole_vec=None, dipoles_already_reordered=False, order=None, optimized_m2l_precomputation_memory_cutoff_bytes=100000000, rotation_data=None)

Implements the boxtree.fmm.ExpansionWranglerInterface by using pyfmmlib.

Timing results returned by this wrangler contains the values wall_elapsed and (optionally, if supported) process_elapsed, which measure wall time and process time in seconds, respectively.

Internal bits

class boxtree.pyfmmlib_integration.FMMLibRotationDataInterface

Abstract interface for additional, optional data for precomputation of rotation matrices passed to the expansion wrangler.

m2l_rotation_lists()

Return a numpy array mapping entries of List 2 to rotation classes.

m2l_rotation_angles()

Return a numpy array mapping List 2 rotation classes to rotation angles.

class boxtree.pyfmmlib_integration.FMMLibRotationData(queue, trav)

An implementation of the FMMLibRotationDataInterface.

__init__(queue, trav)

class boxtree.pyfmmlib_integration.FMMLibRotationDataNotSuppliedWarning