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 void in a user specialization of AccessTraits<T>. It exists to allow constrained partial specializations (e.g., with std::enable_if or requires).

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 be void.

If T is passed to a constructor, the return type must decay to the Value template argument of the spatial index.

If T is passed to query(), the return type must decay to a valid ArborX predicate, e.g., one generated by nearest() or intersects().

It must be callable from the device, which means it needs to be marked with the KOKKOS_FUNCTION macro.

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 element v(i). AccessTraits::memory_space is 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 the ArborX::Point built from the coordinates v(i, 0), v(i, 1), … in row i. 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_space is 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).