ArborX::DistributedTree::query

ArborX / Spatial indexes / ArborX::DistributedTree

ArborX::DistributedTree<MemorySpace, Value, IndexableGetter, BoundingVolume>::query()

template <typename ExecutionSpace, typename Predicates, typename Callback>
void query(ExecutionSpace const& space,
           Predicates const& predicates,
           Callback const& callback) const; // (1)

template <typename ExecutionSpace, typename Predicates, typename Indices,
          typename Offsets>
void query(ExecutionSpace const& space,
           Predicates const& predicates,
           Indices& indices,
           Offsets& offsets) const; // (2)

template <typename ExecutionSpace, typename Predicates, typename Callback,
          typename Values, typename Offsets>
void query(ExecutionSpace const& space,
           Predicates const& predicates,
           Callback const& callback,
           Values& values,
           Offsets& offsets) const; // (3)

1. Executes callbacks on all found results

For spatial predicates, the call finds all primitives meeting the passed predicates, invoking the callback when a primitive meets a predicate. Conceptually equivalent to

for (auto predicate : predicates)
  for (auto primitive : primitives)
    if (predicate(primitive))
      callback(predicate, primitive);

For nearest predicates, the call finds the specified number of the nearest primitives for each predicate, and invokes callback on those results. Conceptually equivalent to

for (auto predicate : predicates)
  for (auto primitive : k_nearest_primitives_of_predicate)
    callback(predicate, primitive);

2. Finds all primitives meeting the predicates and record results in {values, offsets}. values stores the values of the objects stored in the tree that satisfy the predicates. offsets stores the locations in the values view that start a predicate, that is, predicates(i) is satisfied by primitives(indexable_getter(values(j))) for offsets(i) <= j < offsets(i+1). Following the usual convention, offsets(n) == values.size(), where n is the number of queries that were performed and values.size() is the total number of collisions.

3. TODO

Parameters

space	-	execution space that specifies where to execute code
predicates	-	predicates to check against the primitives
callback	-	callable function object to invoke when a primitive satisfies a predicate
values	-	values whose indexables satisfy the predicates
offsets	-	predicate offsets in values

Type requirements

• MemorySpace must be accessible from ExecutionSpace. (Kokkos::SpaceAccessibility<ExecutionSpace, MemorySpace>::accessible must be true.)
• A specialization of ArborX::AccessTraits must match the Predicates as the template argument.
• The member type ArborX::AccessTraits<Predicates>::memory_space must be accessible from ExecutionSpace.
• The static member function ArborX::AccessTraits<Predicates>::get() return type must decay to a valid ArborX predicate. Such predicate may be generated by one of the functions listed below:
  • ArborX::nearest()
  • ArborX::intersects()
• Callback must be a valid ArborX callback
• Values and Offsets must be (managed) Kokkos views accessible from ExecutionSpace.

Return value

(none)

Complexity

O(M log N) where M is the number of predicates (i.e. the value returned by ArborX::AccessTraits<Predicates>::size(predicates)) and N is the number of primitives stored in the data structure (this->size()).

Exceptions

Memory allocation with Kokkos may throw.

Notes

query() must be called by all MPI ranks in the MPI communicator that was used in the DistributedTree constructor.

Example

See also