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)[source]#

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.

  • 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[source]#

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)[source]#

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)[source]#

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

abstract reorder_potentials(potentials)[source]#

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)[source]#
abstract local_expansions_view(local_exps, level)[source]#

Translations

abstract form_multipoles(level_start_source_box_nrs, source_boxes, src_weight_vecs)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#
__init__(dim, kernel, ifgrad=False)[source]#
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)[source]#

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[source]#

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

m2l_rotation_lists()[source]#

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

m2l_rotation_angles()[source]#

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

class boxtree.pyfmmlib_integration.FMMLibRotationData(queue, trav)[source]#

An implementation of the FMMLibRotationDataInterface.

__init__(queue, trav)[source]#
class boxtree.pyfmmlib_integration.FMMLibRotationDataNotSuppliedWarning[source]#