--- title: 'ArborX: Portable Geometric Search Library' url: https://www.emergentmind.com/topics/arborx type: topic --- # ArborX: Portable Geometric Search Library ArborX is a performance portable geometric search library built on top of Kokkos, originally introduced as an open-source C++ library for modern supercomputing architectures and later extended to support exascale applications and a broader algorithmic surface in version 2.0. Its core abstraction is a bounding-volume-hierarchy (BVH) index over geometric primitives, used to accelerate range, $k$-nearest-neighbor, collision, and ray queries, while preserving portability across host and device back ends through Kokkos execution and memory spaces. In the 2.0 release, ArborX exposes a unified C++20 API that runs efficiently on NVIDIA CUDA, AMD HIP, Intel SYCL, and multicore CPUs with OpenMP or Pthreads, and it adds a generalized interface, callbacks, distributed search, brute-force fallback, ray tracing, clustering, Euclidean minimum spanning tree (EMST), and moving-least-squares (MLS) interpolation [1908.11807] [2409.10743] [2507.23700]. ## 1. Origins, objectives, and application domain ArborX was developed to address a specific combination of requirements that earlier C++ spatial-index libraries did not target simultaneously: low-overhead parallel tree build, batched query execution on millions of points with predictable memory usage, and performance portability across multi-core CPUs, many-core GPUs, and future architectures [1908.11807]. The 2019 description places these requirements in scientific applications such as computational mechanics, multiphysics coupling, computer vision, cosmology, mesh searches, particle-in-cell, SPH, and Lagrangian-Eulerian couplers, where proximity search is a recurring kernel and brute-force all-pairs comparisons cost $O(n^2)$ [1908.11807]. The library’s later evolution was strongly shaped by exascale cosmology. The 2024 exascale paper describes ArborX as developed as part of the Exascale Computing Project (ECP), and it ties major enhancements to a collaboration with the HACC cosmology code, where in-situ halo finding is implemented with DBSCAN and each MPI rank handles hundreds of millions of particles [2409.10743]. That paper emphasizes that the pressure to support exascale supercomputers from different vendors required performance portability not only for the search index itself but also for the clustering workflow layered on top of it [2409.10743]. Version 2.0 broadens the scope beyond the original BVH-centric interface. The technical report characterizes the release by five design goals: generalized interface, callbacks, distributed search, expanded algorithms, and performance improvements [2507.23700]. A common misconception is that ArborX is only a BVH wrapper for 3D axis-aligned boxes. That description matches the 1.x API, but the 2.0 release explicitly expands the admissible value types, bounding volumes, problem dimensions, and query execution modes [2507.23700]. ## 2. Core search structures and traversal model The original ArborX design uses a binary BVH in which each node stores an axis-aligned bounding box (AABB) that encloses either two children or exactly one user primitive; in 3D, an AABB is represented by two points, $(x_{\min}, y_{\min}, z_{\min})$ and $(x_{\max}, y_{\max}, z_{\max})$ [1908.11807]. The 2019 paper describes a fully data-parallel, top-down “linear BVH” build driven by Morton codes, together with iterative stack-based search kernels for range and $k$-nearest-neighbor queries [1908.11807]. In ray-tracing literature, BVH quality is often discussed through the Surface Area Heuristic, $$ \mathrm{SAH}(\text{node}) = C_{\mathrm{trav}} + \frac{S(A_{\mathrm{left}})}{S(A_{\mathrm{node}})} \cdot C_{\mathrm{left}} + \frac{S(A_{\mathrm{right}})}{S(A_{\mathrm{node}})} \cdot C_{\mathrm{right}}, $$ but the original ArborX implementation deliberately chose Morton-code splitting to keep build time low in settings where the tree is rebuilt frequently at each time-step [1908.11807]. The exascale paper gives a more implementation-centric account of the same index. It describes a GPU-ready BVH over $N$ primitives, stored in two contiguous arrays of size $2N-1$ in flattened form, with each node holding a $2 \times d$ array of doubles for the AABB, child indices or a rope index after stackless transformation, and leaf payloads as point indices or small lists of point indices [2409.10743]. That work emphasizes rope-based stackless traversal: the right-child pointer of an internal node is replaced with a rope, the index of the next subtree to traverse if the current node fails intersection tests, and every leaf also receives a rope [2409.10743]. Range queries then proceed as purely stackless traversals, while $k$-nearest searches use a per-thread min-heap of size $k$ plus a small stack of nodes still to be visited in distance order [2409.10743]. ArborX publications use different asymptotic descriptions for BVH construction. The 2019 paper states $$ T_{\mathrm{build}}(n)=O(n\log n), $$ with the parallel sort as the dominant cost [1908.11807]. The exascale paper describes Morton-code computation in $O(N)$ work, a parallel radix sort on Morton keys in $O(N)$ time with a small constant, Apetrei et al.’s $O(N)$ LBVH construction, and an $O(N)$ rope-recovery pass, summarizing this as $T_{\rm build}(N)=O(N)$ work, $O(\log N)$ span, memory $O(N)$ [2409.10743]. By contrast, the 2.0 technical report states “BVH build (Apetrei): $T_{\rm build}(N)=O(N \log N)$” and gives per-query traversal as approximately $O(\log N + k)$ [2507.23700]. This suggests that the literature is using different accounting conventions for the role of sorting, rather than presenting a single canonical asymptotic statement. A similar historical variation appears in memory-layout descriptions. The 2019 paper emphasizes Structure-of-Arrays storage for node minima, maxima, and child indices [1908.11807]. The exascale paper describes an Array-of-Structs-of-Arrays (AoSoA) layout to balance vector-load efficiency with coalescing [2409.10743]. The 2.0 report again describes node data in Structure of Arrays (SoA) for coalesced GPU loads, with leaf pointers to value indices in a separate array [2507.23700]. A plausible implication is that the precise internal layout is an implementation detail that has evolved with hardware tuning and release objectives. ## 3. Interface evolution and generalized API in version 2.0 The 1.x interface was intentionally narrow. The technical report’s recap of API v1 shows a `BVH` class with a hardwired `bounding_volume_type = ArborX::Box`, a constructor from primitives, and a `query()` method returning only indices and offsets in CSR-style form [2507.23700]. Its listed limitations are explicit: hardwired to 3D AABBs, no execution-space argument leading to global fencing, returns only indices plus offsets, and no callbacks or user-data in leaves [2507.23700]. Version 2.0 replaces that design with a templated `BVH` and an explicit execution-space argument on both construction and query [2507.23700]. The report identifies the key expansions as arbitrary `Value` types and a user-supplied `IndexableGetter` for any geometry, an enum of bounding volumes via template argument, explicit `ExecutionSpace` for overlap with other Kokkos kernels, and three overloads of `query()` for zero, one, or many outputs per match [2507.23700]. The class also exposes `size()`, `empty()`, and `bounds()` [2507.23700]. The architectural rationale is tightly tied to Kokkos. In version 2.0, all data lives in `Kokkos::View<>` containers parameterized by a `MemorySpace`, and both construction and query routines take a Kokkos execution space so that work can be dispatched on arbitrary GPU streams or CPU threads [2507.23700]. The same report states that vendor-tuned kernels for sorting and reductions use Thrust, rocThrust, and oneDPL [2507.23700]. The generalized interface is summarized by three design points that materially alter user integration: arbitrary user data types, flexible bounding volumes, and dimension up to 10 on both CPU and GPU [2507.23700]. This interface evolution also clarifies a recurring misunderstanding about ArborX output semantics. In 1.x, the library returned only materialized search results in CSR-style arrays [2507.23700]. In 2.0, callbacks are a first-class execution model, so result processing can happen in place during traversal and large temporary arrays need not be materialized at all [2507.23700]. ## 4. Query modes, callbacks, and algorithmic expansion Callbacks are the main semantic addition in ArborX 2.0. The technical report defines them as a mechanism that lets users run arbitrary code on each `(predicate, value)` match inside traversal [2507.23700]. It presents two forms. The “pure callback” variant executes user code for each match without stored output, while the “callback with output” variant requires `output_type` and uses an emitter to append user-defined outputs [2507.23700]. The stated purpose is to allow in-place processing of query results without materializing large temporary arrays [2507.23700]. Traversal can also terminate early when callbacks return a `Terminate` tag [2507.23700]. ArborX 2.0 is no longer restricted to a single search data structure. The report adds a brute-force index for cases where “for small $N$ or degenerate point clouds, a brute-force index is often competitive” [2507.23700]. Its internal organization is simple—values in a contiguous `Kokkos::View` and a nested `Kokkos::parallel_for` over queries and data—and its complexity is given as trivial build $O(1)$ and query $$ T_{\mathrm{bruteforce}}=\Theta(Q \cdot N) $$ for $Q$ queries and $N$ primitives [2507.23700]. The same document contrasts this with BVH behavior as $O(N \log N)$ build and $O(Q \cdot \log N + \text{total\_hits})$ query [2507.23700]. The algorithmic envelope has also widened. The 2.0 release lists ray tracing predicates, density-based clustering (DBSCAN), EMST, and MLS interpolation among supported algorithms [2507.23700]. For ray tracing, geometry is represented as `Ray = (origin, direction)`, and predicates include `nearest(k)` for the first $k$ intersections, `intersect` for all intersections, and `ordered_intersect` for hits sorted by distance [2507.23700]. The report describes a traversal pipeline of ray–node AABB tests, leaf-level ray–geometry intersection for triangle, box, or sphere, and early termination or sorting buffers depending on predicate semantics [2507.23700]. For DBSCAN, the report gives the standard formulation with points $\{p_i\}$, parameters $\varepsilon$ and `minPts`, neighborhood $$ N_\varepsilon(p)=\{q \mid \|p-q\| \le \varepsilon\}, $$ and core points determined by $|N_\varepsilon(p)| \ge \text{minPts}$ [2507.23700]. It lists two implementations—FDBSCAN for sparse data and FDBSCAN-DenseBox for high local density—and states that both use ArborX for $\varepsilon$-neighborhood queries in parallel [2507.23700]. EMST is described as a complete graph with weights $w_{ij}=\|p_i-p_j\|$ and Kruskal’s or Prim’s algorithm accelerated by nearest-neighbor search, while MLS interpolation uses nearest queries to define local windows for weighted least squares [2507.23700]. ## 5. Distributed search and exascale DBSCAN workflows Distributed search in ArborX 2.0 is organized through `ArborX::DistributedTree`, which wraps a local BVH together with a global BVH over local AABBs [2507.23700]. Each MPI rank builds a local $\mathrm{BVH}_i$ over its data, all ranks exchange local AABBs to build a coarse global $\mathrm{BVH}_0$, and each query is first routed through $\mathrm{BVH}_0$ to a subset of ranks before local refinement on the destination ranks [2507.23700]. The report gives per-query communication complexity as $O(\log P)$ messages plus volume proportional to the number of overlapping ranks, and local cost as $O(\log N_i + k_i)$ [2507.23700]. GPU-aware MPI support is explicitly part of the 2.0 design goals [2507.23700]. The exascale paper provides the most detailed distributed DBSCAN formulation. Within each MPI rank, all $N_r$ points are inserted into a local BVH, and boundary points are communicated in a halo of radius $\varepsilon$ to neighbors so that global connectivity is preserved [2409.10743]. The paper states that this ghost exchange costs $O(N_r^{2/3})$ messages in a regular domain decomposition and later summarizes MPI exchange as $O(N_r^{2/3})$ data volume in one neighbor-round [2409.10743]. On the GPU, the computation is split into two Kokkos kernels: core identification, which issues a range query with early termination once the count hits `minPts`, and cluster merging, which performs pairwise traversal over all $(i,j)$ with $\|x_i-x_j\| \le \varepsilon$ and atomically unions points in a disjoint-set structure whenever thread $i$ visits $j$ and $i$ is core [2409.10743]. Because only pairs with $i