CUDA-Q follows a kernel-based model similar to CUDA: you write quantum kernels (__qpu__ functions), compile them, then invoke them from classical host code. The runtime handles scheduling, execution, and result collection.

1. Define kernel: C++ struct with operator()() __qpu__
2. Invoke kernel: call cudaq::sample() or cudaq::observe() from host code
3. Receive results: measurement outcomes or expectation values
4. Process classically: use results to drive optimization, ML, etc.

#include "cudaq.h"
#include <vector>
 
// Define kernel family
struct Ansatz {
  void operator()(std::vector<double> params) __qpu__ {
    auto n = params.size();
    cudaq::qvector q(n);
 
    // Ansatz: RY layers
    for (size_t i = 0; i < n; i++) {
      ry(params[i], q[i]);
    }
 
    // Entangle
    for (size_t i = 0; i < n - 1; i++) {
      cx(q[i], q[i+1]);
    }
 
    mz(q);
  }
};
 
int main() {
  std::vector<double> params = {0.5, 1.0, 1.5};
 
  // Execute kernel: sample returns bitstring statistics
  auto result = cudaq::sample<Ansatz>(1000, params);
 
  // Process results
  for (auto& [bitstring, count] : result) {
    printf("%s: %lu\n", bitstring.c_str(), count);
  }
 
  return 0;
}

CUDA-Q abstracts the backend: same kernel code runs on simulators (CPU, GPU) or real hardware. Set backend at runtime via cudaq::set_target().