ArborX::DistributedTree::query

ArborX / Spatial indexes / ArborX::DistributedTree

ArborX::DistributedTree<MemorySpace>::query()

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

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; // (2)

1. Finds all primitives meeting the predicates on all MPI processes and records results in {indices_and_ranks, offsets}. indices_and_ranks stores the indices of the objects that satisfy the predicates as well as the MPI rank. offsets stores the locations in the indices_and_ranks view that start a predicate, that is, predicates(i) is satisfied by primitives(indices_and_ranks(j).first) on MPI rank indices_and_ranks(j).second for offsets(i) <= j < offsets(i+1). Following the usual convention, offsets(n) == indices_and_ranks.size(), where nis the number of queries that were performed andindices_and_ranks.size() is the total number of collisions. This overload can be used with [ArborX::intersects](ArborX%3A%3Aintersects) and ArborX::nearest predicates.

2. Finds all primitives meeting the predicates on all MPI processes and records results in {values, offsets}. indices stores the indices of the objects that satisfy the predicates as well as the MPI rank. offsets stores the locations in the indices view that start a predicate, that is, the results for predicates(i) are stored in 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. The user is responsible for filling the values argument using the provided callback. At the moment, this overload can only be used for ArborX::intersects predicates.

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	-	results stored for each primitive meeting a predicate according to the callback provided
indices_and_ranks	-	local index and MPI rank of the primitives that satisfy the predicates
offsets	-	predicate offsets in indices

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 first template argument and ArborX::PredicatesTag as second argument.
• The member type ArborX::AccessTraits<Predicates,ArborX::PredicatesTag>::memory_space must be accessible from ExecutionSpace.
• The static member function ArborX::AccessTraits<Predicates,ArborX::PredicatesTag>::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 Functor with signature

template <typename Predicate, typename OutputFunctor>
KOKKOS_FUNCTION void operator()(Predicate const &, int primitive_index,
                                OutputFunctor const &out) const

that stores results for every primitive that matches the predicate by invoking OutputFunctor on the result. The result type must match the value type of Values.

• Values must be a (managed) Kokkos::View. Its value type must match the result type the callback invokes its output functor argument with.

• IndicesAndRanks must be a (managed) Kokkos::View of a Kokkos::pair of integral types accessible from ExecutionSpace.

• Offsets must be a (managed) Kokkos::View of integral types 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,ArborX::PredicatesTag>::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 related to the given MPI communicator collectively.

Example

See also