volumential.expansion_wrangler_interface#

The stage-by-stage contract every volumential wrangler implements.

An expansion wrangler is the object the FMM driver in volumential.volume_fmm calls once per tree stage: form multipoles, coarsen them upward, translate, refine locals downward, evaluate. The interface here mirrors boxtree.fmm so that a volumential wrangler is a drop-in for a boxtree one; the concrete implementations live in volumential.wranglers.

volumential.expansion_wrangler_interface.FMMArray#: Whatever array flavour a stage hands to the next one: a pyopencl.array.Array, a numpy.ndarray, or an object array holding one of those per output kernel. Backends disagree on the flavour, so the interface deliberately does not pin it down.

volumential.expansion_wrangler_interface.BoxIndexArray#: A per-box or per-box-pair index array, in tree order.

volumential.expansion_wrangler_interface.StageResult#: What one FMM stage hands back: the stage’s array (see FMMArray) paired with a timing future for the driver’s profiling hooks, or None in place of the future when the backend does not time the stage.

class volumential.expansion_wrangler_interface.ExpansionWranglerInterface[source]#

Bases: object

Abstract expansion handling interface. The interface is adapted from, and stays compatible with boxtree/fmm.

Note

__metaclass__ is Python 2 spelling and has no effect here, so the abstractmethod() decorators below are documentation rather than an enforced contract: subclasses are not checked for completeness, and this class stays instantiable with method bodies that return None. Argument lists are not enforced either.

abstractmethod multipole_expansion_zeros() → Any[source]#: Construct arrays to store multipole expansions for all boxes

abstractmethod local_expansion_zeros() → Any[source]#: Construct arrays to store multipole expansions for all boxes

abstractmethod output_zeros() → Any[source]#: Construct arrays to store potential values for all target points

abstractmethod reorder_sources(source_array: Any) → Any[source]#: Return a copy of source_array in tree source order. source_array is in user source order.

abstractmethod reorder_targets(source_array: Any) → Any[source]#: Return a copy of target_array in tree source order. target_array is in user target order.

abstractmethod reorder_potentials(potentials: Any) → Any[source]#: Return a copy of potentials in user target order. source_weights is in tree target order.

abstractmethod form_multipoles(level_start_source_box_nrs: Any, source_boxes: Any, src_weights: Any) → Any[source]#: Return an expansions array containing multipole expansions in source_boxes due to sources with src_weights.

abstractmethod coarsen_multipoles(level_start_source_parent_box_nrs: Any, source_parent_boxes: Any, mpoles: Any) → Any[source]#

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

Returns:: mpoles

abstractmethod eval_direct(target_boxes: Any, neighbor_sources_starts: Any, neighbor_sources_lists: Any) → Any[source]#

For each box in target_boxes, evaluate the influence of the neighbor sources due to src_weights

This step amounts to looking up the corresponding entries in a pre-built table.

Returns:: a new potential array, see output_zeros().

abstractmethod multipole_to_local(level_start_target_or_target_parent_box_nrs: Any, target_or_target_parent_boxes: Any, starts: Any, lists: Any, mpole_exps: Any) → Any[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.

Returns:: a new (local) expansion array.

abstractmethod eval_multipoles(level_start_target_box_nrs: Any, target_boxes: Any, starts: Any, lists: Any, mpole_exps: Any) → Any[source]#

For each box in target_boxes, evaluate the multipole expansion in mpole_exps in the nearby boxes given in starts and lists, and return a new potential array.

Returns:: a new potential array, see output_zeros().

abstractmethod form_locals(level_start_target_or_target_parent_box_nrs: Any, target_or_target_parent_boxes: Any, starts: Any, lists: Any, src_weights: Any) → Any[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.

Returns:: a new local expansion array

abstractmethod refine_locals(level_start_target_or_target_parent_box_nrs: Any, target_or_target_parent_boxes: Any, local_exps: Any) → Any[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:: local_exps

abstractmethod eval_locals(level_start_target_box_nrs: Any, target_boxes: Any, local_exps: Any) → Any[source]#

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

Returns:: a new potential array, see output_zeros().

abstractmethod finalize_potentials(potentials: Any) → Any[source]#: Postprocess the reordered potentials. This is where global scaling factors could be applied.

class volumential.expansion_wrangler_interface.TreeIndependentDataForWranglerInterface[source]#

Bases: object

Abstract tree-independent data interface. The interface is adapted from, and stays compatible with boxtree/fmm.

Holds the parts of a wrangler that outlive any single pyopencl.CommandQueue – generated code, expansion factories, kernel lists – so that wranglers themselves can be short-lived.

abstractmethod get_wrangler(*args: Any, **kwargs: Any) → ExpansionWranglerInterface[source]#: Makes a wrangler object.