Python API

This section provides the auto-generated API for the Python modules hypoct and hypoct.tools.

hypoct

Python module for interfacing with hypoct.

class hypoct.Tree(x, adap='a', elem='p', siz=0, occ=1, lvlmax=-1, ext=0)

Build hyperoctree.

Parameters:

• x (numpy.ndarray) – Point coordinates, where the coordinate of point i is x[:,i].
• adap ({‘a’, ‘u’}) – Adaptivity setting: adaptive (‘a’), uniform (‘u’). This specifies whether nodes are divided adaptively or to a uniformly fine level.
• elem ({‘p’, ‘e’, ‘s’}) – Element type: point (‘p’), element (‘e’), sparse element (‘s’). This specifies whether the input points represent true points or general elements (with sizes) that can extend beyond node boundaries. The element type determines how points are assigned to nodes and also how node neighbors are defined (see find_neighbors()). If elem = ‘p’, then siz is ignored. Points and elements are intended to interact densely with each other, whereas sparse elements are intended to interact only by overlap.
• siz (numpy.ndarray) – Sizes associated with each point. If siz is a single float, then it is automatically expanded into an appropriately sized constant array. Not accessed if elem = ‘p’.
• occ (int) – Maximum leaf occupancy. Requires occ > 0.
• lvlmax (int) – Maximum tree depth. The root is defined to have level zero. No maximum if lvlmax < 0.
• ext (numpy.ndarray) – Extent of root node. If ext[i] <= 0, then the extent in dimension i is calculated from the data. Its primary use is to force nodes to conform to a a specified geometry (see find_neighbors()). If ext is a single float, then it is automatically expanded into an appropriately sized constant array.

find_neighbors(per=False)

Find neighbors.

The definition of a neighbor depends on the element type (see Tree()).

For points (elem = ‘p’), the neighbors of a given node consist of:

• All nodes at the same level immediately adjoining it (“one over”).
• All non-empty nodes at a coarser level (parent or above) immediately adjoining it.

For elements and sparse elements (elem = ‘e’ or ‘s’), first let the extension of a node be the spatial region corresponding to all possible point distributions belonging to that node.

Then for elements (elem = ‘e’), the neighbors of a given node consist of:

• All nodes at the same level separated by at most the node’s size (“two over”)
• All non-empty nodes at a coarser level (parent or above) whose extensions are separated from its own extension by less than its extension’s size.

Finally, for sparse elements (elem = ‘s’), the neighbors consist of:

• All nodes at the same level immediately adjoining it (“one over”).
• All non-empty nodes at a coarser level (parent or above) whose extensions overlap with its own extension.

In all cases, a node is not considered its own neighbor.

This routine requires that the child and geometry data have already been generated. If this is not the case, then this is done automatically.

See generate_child_data() and generate_geometry_data().

Parameters:per (numpy.ndarray) – Periodicity of root note. The domain is periodic in dimension i if per[i] = True. If per is a single bool, then it is automatically expanded into an appropriately sized constant array. Use ext in Tree() to control the extent of the root.

generate_child_data()

Generate child data.

generate_geometry_data()

Generate geometry data.

get_interaction_lists()

Get interaction lists.

The interaction list of a given node consists of:

• All nodes at the same level that are children of the neighbors of the node’s parent but not neighbors of the node itself.
• All non-empty nodes at a coarser level (parent or above) that are neighbors of the node’s parent but not neighbors of the node itself.

This routine requires that the neighbor data have already been generated. If this is not the case, then this is done automatically (at default settings).

See find_neighbors().

search(x, siz=0, mlvl=-1)

Search hyperoctree.

The element type of the points to search for are assumed to be the same as that used to construct the tree (see Tree()).

This routine requires that the child and geometry data have already been generated. If this is not the case, then this is done automatically.

See generate_child_data() and generate_geometry_data().

Parameters:

• x (numpy.ndarray) – Point coordinates to search for, where the coordinate of point i is x[:,i]`.
• siz (numpy.ndarray) – Sizes associated with each point. If siz is a single float, then it is automatically expanded into an appropriately sized constant array. Not accessed if elem = ‘p’.
• mlvl (int) – Maximum tree depth to search. Defaults to full tree depth if mlvl < 0.

Returns:

Tree traversal array. The node containing point i at level j has index trav[i,j]; if no such node exists, then trav[i,j] = 0.

Return type:

numpy.ndarray

hypoct.tools

Additional tools for hypoct.

class hypoct.tools.TreeViewer(tree)

View binary and quadtrees (1D and 2D hyperoctrees).

Parameters:tree (hypoct.Tree) – Hyperoctree.

draw_base(c='k', **kwargs)

Draw wireframe outlines of all nodes in the tree.

Accepts all matplotlib.pyplot.plot() keyword arguments.

draw_interactive(draw_neighbors=True, draw_interaction_list=True, base_c='k', node_alpha=0.5, node_color='b', nbor_alpha=0.5, nbor_color='r', ilst_alpha=0.5, ilst_color='g', point_c='k', **kwargs)

Draw each node in the tree sequentially via an interactive session (press Enter to continue) along with all neighbor and interaction list data, if available.

All keyword arguments prefaced with ‘base_’ are passed to draw_base(); those prefaced with ‘node_’ are passed to draw_node() when drawing each node; those prefaced with ‘nbor_’ are passed to draw_node() when drawing each node neighbor; and those prefaced with ‘ilst_’ are passed to draw_node() when drawing each node in the interaction list.

See draw_base() and draw_node().

Parameters:

• draw_neighbors (bool) – Whether to draw neighbors.
• draw_interaction_list (bool) – Whether to draw interaction lists.

draw_node(index, level=None, draw_points=True, update=True, node_alpha=0.5, node_color='b', point_c='k', **kwargs)

Draw node patch and, optionally, all points contained within it.

The node is drawn as a matplotlib.patches.Rectangle instance. Points are drawn using matplotlib.pyplot.scatter().

All keyword arguments prefaced with ‘node_’ are passed to the node drawing routine with the prefix stripped, and, similarly all arguments prefixed with ‘point_’ are passed to the point drawing routine with the prefix stripped. For example, setting node_color=’r’ and point_c=’b’ passes the keyword argument color=’r’ to the node drawer and c=’b’ to the point drawer.

Parameters:

• index (int) – Node index.
• level (int) – Level of node. If None, the level is found automatically.
• draw_points (bool) – Whether to draw points contained in the node.
• update (bool) – Whether to update the plot after drawing the node.