Add generic device policies

docs/sphinx/user_guide/feature/policies.rst

@@ -730,6 +730,33 @@ GPU Policies for SYCL
           configuration. SYCL dimension 2 always exists and should be used as
           one would use the x dimension in CUDA and HIP.  
 
+Device policy aliases
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To simplify transitions between GPU backends (CUDA/HIP/SYCL) and reduce
+downstream preprocessor conditionals, RAJA provides a small set of
+``device_*`` policy aliases that resolve to the *active* GPU backend.
+
+In particular, the following aliases are available when compiling for a GPU
+device backend (i.e., when one of ``RAJA_CUDA_ACTIVE``, ``RAJA_HIP_ACTIVE``,
+or ``RAJA_SYCL_ACTIVE`` is defined):
+
+  * ``device_exec<BLOCK_SIZE>`` (maps to ``cuda_exec`` / ``hip_exec`` /
+    ``sycl_exec``)
+  * ``device_launch_t`` (maps to ``cuda_launch_t`` / ``hip_launch_t`` /
+    ``sycl_launch_t``)
+  * ``device_global_size_{x,y,z}_direct<N>`` (maps to
+    ``cuda/hip_global_size_*`` or ``sycl_global_{2,1,0}``)
+  * ``device_global_thread_{x,y,z}``, ``device_thread_{x,y,z}_{direct,loop}``,
+    and ``device_block_{x,y,z}_{direct,loop}`` (maps to the corresponding
+    backend loop/index mapping policies)
+
+For SYCL, these aliases use CUDA-like (x,y,z) naming with the standard RAJA
+mapping described above: x corresponds to SYCL dimension 2, y to dimension 1,
+and z to dimension 0.
+
+See also the example ``examples/device-policy-aliases.cpp``.
+
 ======================================== ============= ==============================
 SYCL Execution Policies                  Works with    Brief description
 ======================================== ============= ==============================

docs/sphinx/user_guide/tutorial/launch_basic.rst

@@ -57,6 +57,18 @@ then enclosed by a host/device lambda which takes a
 ``RAJA::LaunchContext`` object, which may be used to control the flow 
 within the kernel, for example by creating thread-team synchronization points.
 
+.. note::
+  RAJA treats ``Teams(i,j,k)`` and ``Threads(i,j,k)`` as an (x,y,z) ordering.
+  For users who prefer SYCL's (dim0, dim1, dim2) ordering, RAJA provides
+  ``Teams::sycl_order(dim0, dim1, dim2)`` and
+  ``Threads::sycl_order(dim0, dim1, dim2)``, which map to the RAJA (x,y,z)
+  ordering. For example::
+
+    RAJA::LaunchParams(RAJA::Teams::sycl_order(g0, g1, g2),
+                       RAJA::Threads::sycl_order(l0, l1, l2))
+
+  See also the example ``examples/launch-device-policy-aliases.cpp``.
+
 Inside the execution space, developers write a kernel using nested
 ``RAJA::loop`` methods. The manner in which each loop is executed 
 is determined by a template parameter type, which

examples/CMakeLists.txt

@@ -23,6 +23,14 @@ raja_add_executable(
   NAME dynamic-forall
   SOURCES dynamic-forall.cpp)
 
+raja_add_executable(
+  NAME device-policy-aliases
+  SOURCES device-policy-aliases.cpp)
+
+raja_add_executable(
+  NAME launch-device-policy-aliases
+  SOURCES launch-device-policy-aliases.cpp)
+
 if (RAJA_ENABLE_JIT)
   raja_add_executable(
     NAME forall-jit

examples/device-policy-aliases.cpp

@@ -0,0 +1,114 @@
+//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~//
+// Copyright (c) Lawrence Livermore National Security, LLC and other
+// RAJA Project Developers. See top-level LICENSE and COPYRIGHT
+// files for dates and other details. No copyright assignment is required
+// to contribute to RAJA.
+//
+// SPDX-License-Identifier: (BSD-3-Clause)
+//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~//
+
+//
+// Device policy aliases example
+//
+// This example demonstrates:
+//   - Backend-generic GPU execution policies via RAJA::device_*
+//   - CUDA-like x/y/z naming for SYCL (x->2, y->1, z->0) in those aliases
+//   - RAJA::Teams::sycl_order / RAJA::Threads::sycl_order for expressing a
+//     launch grid in SYCL's (dim0,dim1,dim2) ordering.
+//
+// Notes:
+//   - RAJA::device_* aliases are defined only in a GPU device compile pass
+//     (RAJA_GPU_ACTIVE). If you compile this file as host-only, it will fall
+//     back to a sequential path.
+//
+
+#include <iostream>
+
+#include "RAJA/RAJA.hpp"
+#include "RAJA/util/resource.hpp"
+
+static void printDims(const char* label, const int v[3])
+{
+  std::cout << label << " (x,y,z)=(" << v[0] << "," << v[1] << "," << v[2]
+            << ")\n";
+}
+
+int main(int, char**)
+{
+  constexpr int N = 1024;
+
+  // Demonstrate the (dim0,dim1,dim2)->(x,y,z) mapping helpers for RAJA::launch.
+  {
+    const auto threads_xyz = RAJA::Threads(8, 4, 2);
+    const auto threads_sycl = RAJA::Threads::sycl_order(/*dim0=*/2,
+                                                        /*dim1=*/4,
+                                                        /*dim2=*/8);
+    printDims("Threads(x,y,z)", threads_xyz.value);
+    printDims("Threads::sycl_order(dim0,dim1,dim2)", threads_sycl.value);
+  }
+
+  RAJA::resources::Host host {};
+  int* a = host.allocate<int>(N);
+  int* b = host.allocate<int>(N);
+  int* c = host.allocate<int>(N);
+
+  for (int i = 0; i < N; ++i)
+  {
+    a[i] = i;
+    b[i] = 2 * i;
+    c[i] = 0;
+  }
+
+#if defined(RAJA_GPU_ACTIVE)
+  // Use RAJA::device_exec to select the active GPU backend (CUDA/HIP/SYCL).
+  //
+  // The matching resource type is inferred from the execution policy.
+  auto device_res = RAJA::resources::get_default_resource<RAJA::device_exec<256>>();
+
+  int* d_a = device_res.allocate<int>(N);
+  int* d_b = device_res.allocate<int>(N);
+  int* d_c = device_res.allocate<int>(N);
+
+  device_res.memcpy(d_a, a, sizeof(int) * N);
+  device_res.memcpy(d_b, b, sizeof(int) * N);
+
+  RAJA::forall<RAJA::device_exec<256>>(device_res, RAJA::RangeSegment(0, N),
+                                      [=] RAJA_DEVICE(int i) {
+                                        d_c[i] = d_a[i] + d_b[i];
+                                      });
+
+  device_res.memcpy(c, d_c, sizeof(int) * N);
+  device_res.wait();
+
+  device_res.deallocate(d_a);
+  device_res.deallocate(d_b);
+  device_res.deallocate(d_c);
+
+  std::cout << "Computed on device using RAJA::device_exec<256>\n";
+#else
+  RAJA::forall<RAJA::seq_exec>(host, RAJA::RangeSegment(0, N), [=](int i) {
+    c[i] = a[i] + b[i];
+  });
+  std::cout << "Computed on host (no RAJA_GPU_ACTIVE)\n";
+#endif
+
+  // Quick correctness check.
+  bool ok = true;
+  for (int i = 0; i < N; ++i)
+  {
+    if (c[i] != a[i] + b[i])
+    {
+      ok = false;
+      std::cerr << "Mismatch at i=" << i << " got " << c[i]
+                << " expected " << (a[i] + b[i]) << "\n";
+      break;
+    }
+  }
+
+  host.deallocate(a);
+  host.deallocate(b);
+  host.deallocate(c);
+
+  return ok ? 0 : 1;
+}
+

examples/launch-device-policy-aliases.cpp

@@ -0,0 +1,188 @@
+//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~//
+// Copyright (c) Lawrence Livermore National Security, LLC and other
+// RAJA Project Developers. See top-level LICENSE and COPYRIGHT
+// files for dates and other details. No copyright assignment is required
+// to contribute to RAJA.
+//
+// SPDX-License-Identifier: (BSD-3-Clause)
+//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~//
+
+//
+// RAJA::launch with device policy aliases
+//
+// This example shows how to write a single RAJA::launch kernel using the
+// RAJA::device_* aliases so the same source can target CUDA, HIP, or SYCL
+// without downstream #if/#ifdef in user code.
+//
+// It also demonstrates Teams/Threads ordering helpers:
+//   - RAJA::Teams(x,y,z) and RAJA::Threads(x,y,z) are RAJA's canonical
+//   ordering.
+//   - RAJA::Teams::sycl_order(dim0,dim1,dim2) and Threads::sycl_order(...)
+//     express SYCL's (dim0,dim1,dim2) ordering and map to RAJA (x,y,z).
+//
+
+#include <iostream>
+#include <string>
+
+#include "RAJA/RAJA.hpp"
+#include "RAJA/util/resource.hpp"
+
+/*
+ * Define host/device launch policies.
+ *
+ * When compiling for a GPU backend, the RAJA::device_* aliases resolve to the
+ * active backend (CUDA/HIP/SYCL). When compiling host-only, we fall back to
+ * pure host policies.
+ */
+using host_launch = RAJA::seq_launch_t;
+
+#if defined(RAJA_GPU_ACTIVE)
+using device_launch = RAJA::device_launch_t<false>;
+#endif
+
+using launch_policy = RAJA::LaunchPolicy<
+  host_launch
+#if defined(RAJA_GPU_ACTIVE)
+  , device_launch
+#endif
+  >;
+
+/*
+ * Define team and thread loop policies.
+ *
+ * These use RAJA::device_* aliases on GPU and expand to seq_exec on host.
+ */
+using teams_x = RAJA::LoopPolicy<
+  RAJA::seq_exec
+#if defined(RAJA_GPU_ACTIVE)
+  , RAJA::device_block_x_direct
+#endif
+  >;
+
+using teams_y = RAJA::LoopPolicy<
+  RAJA::seq_exec
+#if defined(RAJA_GPU_ACTIVE)
+  , RAJA::device_block_y_direct
+#endif
+  >;
+
+using threads_x = RAJA::LoopPolicy<
+  RAJA::seq_exec
+#if defined(RAJA_GPU_ACTIVE)
+  , RAJA::device_thread_x_direct
+#endif
+  >;
+
+using threads_y = RAJA::LoopPolicy<
+  RAJA::seq_exec
+#if defined(RAJA_GPU_ACTIVE)
+  , RAJA::device_thread_y_direct
+#endif
+  >;
+
+int main(int argc, char** argv)
+{
+  constexpr int nteams_x   = 2;
+  constexpr int nteams_y   = 3;
+  constexpr int nthreads_x = 4;
+  constexpr int nthreads_y = 5;
+
+  constexpr int len = nteams_y * nteams_x * nthreads_y * nthreads_x;
+
+  RAJA::ExecPlace place = RAJA::ExecPlace::HOST;
+
+#if defined(RAJA_GPU_ACTIVE)
+  if (argc != 2) {
+    RAJA_ABORT_OR_THROW("Usage: launch-device-policy-aliases host|device");
+  }
+
+  std::string exec_space = argv[1];
+  if (!(exec_space.compare("host") == 0 || exec_space.compare("device") == 0)) {
+    RAJA_ABORT_OR_THROW("Usage: launch-device-policy-aliases host|device");
+  }
+
+  if (exec_space.compare("host") == 0) { place = RAJA::ExecPlace::HOST; }
+  if (exec_space.compare("device") == 0) { place = RAJA::ExecPlace::DEVICE; }
+#else
+  (void)argc;
+  (void)argv;
+#endif
+
+  // Default host resource for host allocations/checks.
+  RAJA::resources::Host host_res {};
+  int* out_host = host_res.allocate<int>(len);
+
+  for (int i = 0; i < len; ++i) {
+    out_host[i] = -1;
+  }
+
+#if defined(RAJA_GPU_ACTIVE)
+  auto device_res = RAJA::resources::get_default_resource<device_launch>();
+  int* out_device = device_res.allocate<int>(len);
+  device_res.memcpy(out_device, out_host, sizeof(int) * len);
+  device_res.wait();
+
+  int* out_ptr = (place == RAJA::ExecPlace::DEVICE) ? out_device : out_host;
+#else
+  int* out_ptr = out_host;
+#endif
+
+  // RAJA launch grid configuration is specified in (x,y,z). For SYCL-minded
+  // users, sycl_order(dim0,dim1,dim2) provides an explicit mapping.
+  RAJA::LaunchParams params_raja(RAJA::Teams(nteams_x, nteams_y, 1),
+                                 RAJA::Threads(nthreads_x, nthreads_y, 1));
+
+  RAJA::LaunchParams params_sycl(
+      RAJA::Teams::sycl_order(/*dim0=*/1, /*dim1=*/nteams_y, /*dim2=*/nteams_x),
+      RAJA::Threads::sycl_order(/*dim0=*/1, /*dim1=*/nthreads_y,
+                                /*dim2=*/nthreads_x));
+
+  // Use the RAJA-ordered params for execution (it is backend-independent).
+  // params_sycl is included to demonstrate equivalent spelling.
+  (void)params_sycl;
+
+  RAJA::launch<launch_policy>(place,
+                              params_raja,
+                              [=] RAJA_HOST_DEVICE(RAJA::LaunchContext ctx) {
+
+    RAJA::loop<teams_y>(ctx, RAJA::RangeSegment(0, nteams_y), [&] (int by) {
+      RAJA::loop<teams_x>(ctx, RAJA::RangeSegment(0, nteams_x), [&] (int bx) {
+
+        RAJA::loop<threads_y>(ctx, RAJA::RangeSegment(0, nthreads_y), [&] (int ty) {
+          RAJA::loop<threads_x>(ctx, RAJA::RangeSegment(0, nthreads_x), [&] (int tx) {
+
+            int i = (((by * nteams_x) + bx) * nthreads_y + ty) * nthreads_x + tx;
+            out_ptr[i] = i;
+
+          });
+        });
+
+      });
+    });
+
+  });
+
+#if defined(RAJA_GPU_ACTIVE)
+  if (place == RAJA::ExecPlace::DEVICE) {
+    device_res.memcpy(out_host, out_device, sizeof(int) * len);
+    device_res.wait();
+  }
+
+  device_res.deallocate(out_device);
+#endif
+
+  bool ok = true;
+  for (int i = 0; i < len; ++i) {
+    if (out_host[i] != i) {
+      ok = false;
+      std::cerr << "Mismatch at i=" << i << " got " << out_host[i]
+                << " expected " << i << "\n";
+      break;
+    }
+  }
+
+  host_res.deallocate(out_host);
+
+  std::cout << (ok ? "PASS\n" : "FAIL\n");
+  return ok ? 0 : 1;
+}

include/RAJA/RAJA.hpp

@@ -97,6 +97,8 @@
 #include "RAJA/policy/desul.hpp"
 #endif
 
+#include "RAJA/policy/device.hpp"
+
 #include "RAJA/index/IndexSet.hpp"
 
 //