Building Trees

Manipulating Trees of Boxes

These functions manipulate instances of TreeOfBoxes.

Note

These functions currently keep their bulk data in numpy.ndarray instances. This contrasts with the particle-based tree (Tree), which operates on data in pyopencl.array.Array instances). Along with the rest of boxtree, this will migrate to arraycontext in the future.

boxtree.make_tree_of_boxes_root(bbox: ndarray) → TreeOfBoxes

Make the minimal tree of boxes, consisting of a single root box filling bbox.

Parameters:

bbox – a 2-by-dim numpy array of [lower_bounds, upper_bounds] for the bounding box.

Note

bbox is expected to be square (with tolerances as accepted by numpy.allclose()).

boxtree.refine_tree_of_boxes(tob: TreeOfBoxes, refine_flags: ndarray) → TreeOfBoxes

Make a refined copy of tob where boxes flagged with refine_flags are refined.

boxtree.uniformly_refine_tree_of_boxes(tob: TreeOfBoxes) → TreeOfBoxes

Make a uniformly refined copy of tob.

boxtree.coarsen_tree_of_boxes(tob: TreeOfBoxes, coarsen_flags: ndarray, error_on_ignored_flags: bool = True) → TreeOfBoxes

Make a coarsened copy of tob where boxes flagged with coarsen_flags are coarsened.

boxtree.refine_and_coarsen_tree_of_boxes(tob: TreeOfBoxes, refine_flags: Optional[ndarray] = None, coarsen_flags: Optional[ndarray] = None, error_on_ignored_flags: bool = True) → TreeOfBoxes

Make a refined/coarsened copy. When children of the same parent box are marked differently, the refinement flag takes priority.

Both refinement and coarsening flags can only be set of leaves. To prevent drastic mesh change, coarsening is only executed when a leaf box is marked for coarsening, and its parent’s children are all leaf boxes (so that change in the number of boxes is bounded per box flagged). Please note that the above behavior may be subject to change in the future.

Parameters:

• refine_flags – a boolean array of size nboxes.

• coarsen_flags – a boolean array of size nboxes.

• error_on_ignored_flags – if true, an exception is raised when enforcing level restriction requires ignoring some coarsening flags.

Returns:

a processed copy of the tree.

boxtree.make_meshmode_mesh_from_leaves(tob: TreeOfBoxes) → Tuple[Mesh, ndarray]

Make a Mesh from the leaf boxes of the tree of boxes tob.

Returns:

A tuple of the mesh and a vector of the element number -> box number mapping.

Building Particle-Based Trees

These functions produce instances of the particle-based Tree.

Note

These functions currently keep their bulk data in in pyopencl.array.Array instances. This contrasts with the box-based tree (TreeOfBoxes), which operates on data in numpy.ndarray instances. Along with the rest of boxtree, both will migrate to arraycontext in the future.

class boxtree.TreeBuilder(context)

__init__(context)

Parameters:

context – A pyopencl.Context.

__call__(queue, particles, kind='adaptive', max_particles_in_box=None, allocator=None, debug=False, targets=None, source_radii=None, target_radii=None, stick_out_factor=None, refine_weights=None, max_leaf_refine_weight=None, wait_for=None, extent_norm=None, bbox=None, **kwargs)

Parameters:

• queue – a pyopencl.CommandQueue instance

• particles – an object array of (XYZ) point coordinate arrays.

• kind –

  One of the following strings:

  • ’adaptive’

  • ’adaptive-level-restricted’

  • ’non-adaptive’

  ’adaptive’ requests an adaptive tree without level restriction. See Supported tree kinds for further explanation.

• targets – an object array of (XYZ) point coordinate arrays or None. If None, particles act as targets, too. Must have the same (inner) dtype as particles.

• source_radii –

  If not None, a pyopencl.array.Array of the same dtype as particles.

  If this is given, targets must also be given, i.e. sources and targets must be separate. See Sources and targets with extent.

• target_radii – Like source_radii, but for targets.

• stick_out_factor – See Tree.stick_out_factor and Sources and targets with extent.

• refine_weights – If not None, a pyopencl.array.Array of the type numpy.int32. A box will be split if it has a cumulative refine_weight greater than max_leaf_refine_weight. If this is given, max_leaf_refine_weight must also be given and max_particles_in_box must be None.

• max_leaf_refine_weight – If not None, specifies the maximum weight of a leaf box.

• max_particles_in_box – If not None, specifies the maximum number of particles in a leaf box. If this is given, both refine_weights and max_leaf_refine_weight must be None.

• wait_for – may either be None or a list of pyopencl.Event instances for whose completion this command waits before starting execution.

• extent_norm – "l2" or "linf". Indicates the norm with respect to which particle stick-out is measured. See Tree.extent_norm.

• bbox – Bounding box of either type: 1. A dim-by-2 array, with each row to be [min, max] coordinates in its corresponding axis direction. 2. (Internal use only) of the same type as returned by boxtree.bounding_box.make_bounding_box_dtype. When given, this bounding box is used for tree building. Otherwise, the bounding box is determined from particles in such a way that it is square and is slightly larger at the top (so that scaled coordinates are always < 1). When supplied, the bounding box must be square and have all the particles in its closure.

• kwargs – Used internally for debugging.

Returns:

a tuple (tree, event), where tree is an instance of Tree, and event is a pyopencl.Event for dependency management.