Note
For ArborX 1.x, see ArborX::AccessTraits (v1)
AccessTraits¶
Defined in header <ArborX_AccessTraits.hpp>
ArborX::AccessTraits is a customization point, not a class to instantiate.
It tells the spatial index constructor (e.g.,
BoundingVolumeHierarchy constructor)
how much data to index and how to access that data, or a spatial index query
(e.g., BoundingVolumeHierarchy::query())
what predicates to query for.
ArborX does not implement AccessTraits for arbitrary types.
To pass your own data container T to a constructor or to query(),
specialize ArborX::AccessTraits<T> and provide the members listed below.
ArborX only provides specializations for Kokkos views
(see Provided specializations).
Note
The declaration below documents the requirements a specialization must satisfy. It is not the declaration of a primary template with these members. The primary template in the header is an empty stub, only used to diagnose missing specializations at compile time.
-
template<typename T, typename Enable = void>
struct AccessTraits¶ Requirements on a specialization
AccessTraits<T>.- Template Parameters:
T – User data container.
Enable – Always
voidin a user specialization ofAccessTraits<T>. It exists to allow constrained partial specializations (e.g., withstd::enable_iforrequires).
-
type memory_space¶
Must name a valid Kokkos memory space in which the data resides.
-
KOKKOS_FUNCTION static auto size(T const &data)¶
- Parameters:
data – Data argument passed to the spatial index constructor or
query().- Returns:
The number of values (primitives or predicates). The return type must be an integral type.
-
KOKKOS_FUNCTION static decltype(auto) get(T const &data, decltype(size(data)) i)¶
- Parameters:
data – Data argument passed to the spatial index constructor or
query().i – Position of the value to return.
- Returns:
The
i-th value. The return type must not bevoid.
If
Tis passed to a constructor, the return type must decay to theValuetemplate argument of the spatial index.If
Tis passed toquery(), the return type must decay to a valid ArborX predicate, e.g., one generated bynearest()orintersects().It must be callable from the device, which means it needs to be marked with the
KOKKOS_FUNCTIONmacro.
Provided specializations¶
ArborX provides partial specializations for Kokkos views of rank 1 and 2.
-
template<typename View>
requires (Kokkos::is_view_v<View> && View::rank() == 1)
struct AccessTraits<View>¶ AccessTraits::get()returns a const reference to the elementv(i).AccessTraits::memory_spaceis the memory space of the view.
-
template<typename View>
requires (Kokkos::is_view_v<View> && View::rank() == 2)
struct AccessTraits<View>¶ AccessTraits::get()returns by value theArborX::Pointbuilt from the coordinatesv(i, 0),v(i, 1), … in rowi. A statically known second extent determines the dimension of the point; for a dynamic second extent, a three-dimensional point is built from the first three columns.AccessTraits::memory_spaceis the memory space of the view.
Example¶
The example below specializes AccessTraits for two user types:
PointCloud, passed to the constructor of the BoundingVolumeHierarchie
spatial index to provide the points, and Spheres, passed to query() to
provide the predicates.
#include <ArborX.hpp>
#include <Kokkos_Core.hpp>
#include <array>
#include <iostream>
#include <numeric>
struct PointCloud
{
float *d_x;
float *d_y;
float *d_z;
int N;
};
struct Spheres
{
float *d_x;
float *d_y;
float *d_z;
float *d_r;
int N;
};
template <>
struct ArborX::AccessTraits<PointCloud>
{
static KOKKOS_FUNCTION std::size_t size(PointCloud const &cloud)
{
return cloud.N;
}
static KOKKOS_FUNCTION auto get(PointCloud const &cloud, std::size_t i)
{
return ArborX::Point{cloud.d_x[i], cloud.d_y[i], cloud.d_z[i]};
}
using memory_space = Kokkos::CudaSpace;
};
template <>
struct ArborX::AccessTraits<Spheres>
{
static KOKKOS_FUNCTION std::size_t size(Spheres const &d) { return d.N; }
static KOKKOS_FUNCTION auto get(Spheres const &d, std::size_t i)
{
return ArborX::intersects(
ArborX::Sphere{ArborX::Point{d.d_x[i], d.d_y[i], d.d_z[i]}, d.d_r[i]});
}
using memory_space = Kokkos::CudaSpace;
};
int main(int argc, char *argv[])
{
Kokkos::ScopeGuard guard(argc, argv);
constexpr std::size_t N = 10;
std::array<float, N> a;
float *d_a;
cudaMalloc(&d_a, sizeof(a));
std::iota(std::begin(a), std::end(a), 1.0);
cudaStream_t stream;
cudaStreamCreate(&stream);
Kokkos::push_finalize_hook([stream]() { cudaStreamDestroy(stream); });
cudaMemcpyAsync(d_a, a.data(), sizeof(a), cudaMemcpyHostToDevice, stream);
Kokkos::Cuda cuda{stream};
ArborX::BoundingVolumeHierarchy bvh{cuda, PointCloud{d_a, d_a, d_a, N}};
Kokkos::View<ArborX::Point<3> *, Kokkos::CudaSpace> points("Example::points",
0);
Kokkos::View<int *, Kokkos::CudaSpace> offset("Example::offset", 0);
ArborX::query(bvh, cuda, Spheres{d_a, d_a, d_a, d_a, N}, points, offset);
Kokkos::parallel_for(
"Example::print_points", Kokkos::RangePolicy(cuda, 0, N),
KOKKOS_LAMBDA(int i) {
for (int j = offset(i); j < offset(i + 1); ++j)
{
printf("%i: (%.1f, %.1f, %.1f)\n", i, points(j)[0], points(j)[1],
points(j)[2]);
}
});
return 0;
}
See examples/access_traits/example_host_access_traits.cpp for an example
of an AccessTraits specialization for host data (std::vector).