[INFRA] Import NVIDIA/CCCL upstream as optimization reference library

CCCL (CUDA C++ Core Libraries) provides:
- CUB: device/block/warp-level GPU primitives (reduce, scan, sort, topk)
- Thrust: high-level parallel algorithms (transform_reduce, sort, scan)
- libcudacxx: CUDA C++ standard library (atomics, barriers, memory)
- cudax: experimental features (memory resources, allocators)
- Tuning policies: per-SM hardware-specific algorithm parameters

Competition optimization vectors mapped to CCCL:
- Output TPS (83% weight): warp_reduce, block_reduce, device_topk
- Input TPS (14% weight): device_scan, block_load, prefetch
- Cache TPS (3% weight): prefix caching strategy patterns
- Memory (0.9 util): pooled/cached/buddy allocators

Source: https://github.com/NVIDIA/cccl (shallow clone, HEAD only)
License: Apache-2.0

cccl_upstream/examples/basic/CMakeLists.txt

@@ -0,0 +1,53 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+cmake_minimum_required(VERSION 3.18 FATAL_ERROR)
+
+project(CCCLDemo CUDA)
+
+# This example uses the CMake Package Manager (CPM) to simplify fetching CCCL from GitHub
+# For more information, see https://github.com/cpm-cmake/CPM.cmake
+include(cmake/CPM.cmake)
+
+# We define these as variables so they can be overridden in CI to pull from a PR instead of CCCL `main`
+# In your project, these variables are unnecessary and you can just use the values directly
+set(
+  CCCL_REPOSITORY
+  "https://github.com/NVIDIA/cccl"
+  CACHE STRING
+  "Git repository to fetch CCCL from"
+)
+set(CCCL_TAG "main" CACHE STRING "Git tag/branch to fetch from CCCL repository")
+
+# This will automatically clone CCCL from GitHub and make the exported cmake targets available
+CPMAddPackage(NAME CCCL GIT_REPOSITORY "${CCCL_REPOSITORY}" GIT_TAG ${CCCL_TAG})
+
+# Default to building for the GPU on the current system
+if (NOT DEFINED CMAKE_CUDA_ARCHITECTURES)
+  set(CMAKE_CUDA_ARCHITECTURES native)
+endif()
+
+# Creates a cmake executable target for the main program
+add_executable(example_project example.cu)
+target_compile_features(example_project PUBLIC cuda_std_17)
+
+# "Links" the CCCL Cmake target to the `example_project` executable. This configures everything needed to use
+# CCCL headers, including setting up include paths, compiler flags, etc.
+target_link_libraries(example_project PRIVATE CCCL::CCCL)
+
+# This is only relevant for internal testing and not needed by end users.
+include(CTest)
+enable_testing()
+add_test(NAME example_project COMMAND example_project)

cccl_upstream/examples/basic/README.md

@@ -0,0 +1,141 @@
+
+# Example Project Using CCCL From GitHub
+
+Many CUDA C++ users are accustomed to using CCCL headers (Thrust, CUB, libcu++) provided with the [NVIDIA CUDA Toolkit](https://developer.nvidia.com/cuda-toolkit) or [NVIDIA HPC SDK](https://developer.nvidia.com/hpc-sdk).
+
+In addition, we also support using CCCL directly from GitHub.
+The primary benefit is that this allows users to use the latest version of CCCL without having to wait for a new release of the CUDA Toolkit or HPC SDK.
+
+This example demonstrates how to use CCCL from GitHub in a CMake project.
+
+## Overview
+
+This is a standalone example of how to use [CCCL](https://github.com/nvidia/cccl) in a CMake project.
+
+This example demonstrates fetching CCCL from GitHub and linking it with a simple example CUDA program ([`example.cu`](example.cu)) that utilizes the headers from CCCL.
+
+This is intended to be a starting point for users who want to use CCCL in their own projects.
+
+## How to Adapt This Example to Your Project
+
+This example is intended to be a starting point for users who want to use CCCL in their own projects.
+In order to adapt this example to your project, you will need to do the following:
+1. Download `CPM.cmake` into your project's `cmake/` directory ([see below for instructions](#downloading-cpm)).
+2. Add the following lines to your project's `CMakeLists.txt` file:
+   ```cmake
+   include(cmake/CPM.cmake)
+
+   # This will automatically clone CCCL from GitHub and make the exported cmake targets available
+   CPMAddPackage(
+       NAME CCCL
+       GITHUB_REPOSITORY nvidia/cccl
+       GIT_TAG main # Fetches the latest commit on the main branch
+   )
+
+   # If you're building an executable
+   add_executable(your_executable your_file.cu)
+   target_link_libraries(your_executable PRIVATE CCCL::CCCL)
+
+   # Alternatively, if you're building a library
+   add_library(your_library SHARED your_file.cu)
+   target_link_libraries(your_library PRIVATE CCCL::CCCL)
+   ```
+   See the [CMakeLists.txt](CMakeLists.txt) file in this directory for a complete example.
+3. Configure and build your project as normal and verify that it builds successfully.
+
+For more information on using CPM, see [below](#using-cmake-package-manager).
+
+## Using CMake Package Manager
+
+This example uses the CMake Package Manager (CPM) to fetch CCCL from GitHub.
+
+See the [CMakeLists.txt](CMakeLists.txt) file in this directory for the complete example.
+
+If you are not familiar with CPM, you can find more information [here](https://github.com/cpm-cmake/CPM.cmake).
+In short, CPM is a CMake module that simplifies dependency management for CMake projects.
+It automatically downloads and integrates dependencies into your CMake project.
+
+### Downloading CPM
+
+In order to get the latest version of CPM.cmake, you can run the following command in the root directory of your project:
+
+```bash
+mkdir -p cmake
+wget -O cmake/CPM.cmake https://github.com/cpm-cmake/CPM.cmake/releases/latest/download/get_cpm.cmake
+```
+
+This will download and create the file `cmake/CPM.cmake` in your project directory.
+Most projects will want to commit this file to their source control system.
+You can then use `include(cmake/CPM.cmake)` in your project's `CMakeLists.txt` file to include CPM in your project.
+
+Alternatively, you can add the following logic to your `CMakeLists.txt` to download CPM if it is not already present in your project directory.
+
+```cmake
+set(CPM_DOWNLOAD_VERSION 0.34.0)
+
+if(CPM_SOURCE_CACHE)
+  set(CPM_DOWNLOAD_LOCATION "${CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
+elseif(DEFINED ENV{CPM_SOURCE_CACHE})
+  set(CPM_DOWNLOAD_LOCATION "$ENV{CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
+else()
+  set(CPM_DOWNLOAD_LOCATION "${CMAKE_BINARY_DIR}/cmake/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
+endif()
+
+if(NOT (EXISTS ${CPM_DOWNLOAD_LOCATION}))
+  message(STATUS "Downloading CPM.cmake to ${CPM_DOWNLOAD_LOCATION}")
+  file(DOWNLOAD
+       https://github.com/TheLartians/CPM.cmake/releases/download/v${CPM_DOWNLOAD_VERSION}/CPM.cmake
+       ${CPM_DOWNLOAD_LOCATION}
+  )
+endif()
+
+include(${CPM_DOWNLOAD_LOCATION})
+```
+
+## Building and Running the Example
+
+Most people will want to adapt this example to their own project as described [above](#how-to-adapt-this-example-to-your-project). If you would like to build and run this example as-is, you will need to follow the instructions below.
+
+### Prerequisites
+
+If you would like to build and run this example as-is, you will need:
+
+- A CUDA-capable GPU
+- NVIDIA CUDA Toolkit (12 or later)
+- CMake (3.14 or later)
+- A C++17 standard-compliant compiler
+- git
+
+### Instructions
+
+1. Clone this repository to your local machine.
+   ```bash
+   git clone https://github.com/NVIDIA/cccl.git
+   ```
+
+2. Enter the directory of the cloned repository.
+   ```bash
+   cd cccl/examples/example_project
+   ```
+
+3. Run the CMake configure step
+   ```bash
+   cmake -S . -B build
+   ```
+   Alternatively,
+   ```bash
+   mkdir -p build
+   cd build
+   cmake ..
+   ```
+4. Run the CMake build step.
+   ```bash
+   cmake --build .
+   ```
+
+6. Run the executable.
+   ```bash
+   ./build/example_project
+   ```
+
+If everything is configured correctly, the program will execute and print the sum of an array of integers, demonstrating the use of cccl.

cccl_upstream/examples/basic/example.cu

@@ -0,0 +1,84 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*
+This is a simple example demonstrating the use of CCCL functionality from Thrust, CUB, and libcu++.
+
+The example computes the sum of an array of integers using a simple parallel reduction. Each thread block
+computes the sum of a subset of the array using cuB::BlockRecuce. The sum of each block is then reduced
+to a single value using an atomic add via cuda::atomic_ref from libcu++. The result is stored in a device_vector
+from Thrust. The sum is then printed to the console.
+*/
+
+#include <cub/block/block_reduce.cuh>
+
+#include <thrust/device_vector.h>
+
+#include <cuda/atomic>
+
+#include <cstdio>
+#include <iostream>
+
+constexpr int block_size = 256;
+
+__global__ void sumKernel(int const* data, int* result, std::size_t N)
+{
+  using BlockReduce = cub::BlockReduce<int, block_size>;
+
+  __shared__ typename BlockReduce::TempStorage temp_storage;
+
+  int index = threadIdx.x + blockIdx.x * blockDim.x;
+
+  int sum = 0;
+  if (index < N)
+  {
+    sum += data[index];
+  }
+
+  sum = BlockReduce(temp_storage).Sum(sum);
+
+  if (threadIdx.x == 0)
+  {
+    cuda::atomic_ref<int, cuda::thread_scope_device> atomic_result(*result);
+    atomic_result.fetch_add(sum, cuda::memory_order_relaxed);
+  }
+}
+
+int main()
+{
+  std::size_t N = 1000;
+  thrust::device_vector<int> data(N, 1);
+  thrust::device_vector<int> result(1);
+
+  int num_blocks = (N + block_size - 1) / block_size;
+
+  sumKernel<<<num_blocks, block_size>>>(
+    thrust::raw_pointer_cast(data.data()), thrust::raw_pointer_cast(result.data()), N);
+
+  auto err = cudaDeviceSynchronize();
+  if (err != cudaSuccess)
+  {
+    std::cout << "Error: " << cudaGetErrorString(err) << '\n';
+    return -1;
+  }
+
+  std::cout << "Sum: " << result[0] << '\n';
+
+  assert(result[0] == N);
+
+  return 0;
+}