Running your first CUDA-Q Program¶

Now that you have defined your first quantum kernel, let’s look at different options for how to execute it. In CUDA-Q, quantum circuits are stored as quantum kernels. For estimating the probability distribution of a measured quantum state in a circuit, we use the sample function call, and for computing the expectation value of a quantum state with a given observable, we use the observe function call.

Observe¶

The observe function allows us to calculate expectation values for a defined quantum operator, that is the value of \(\bra{\psi}H\ket{\psi}\), where \(H\) is the desired operator and \(\ket{\psi}\) is the quantum state after executing a given kernel.

Python

The cudaq.observe() method takes a kernel and its arguments as inputs, along with a cudaq.SpinOperator.

Using the cudaq.spin module, operators may be defined as a linear combination of Pauli strings. Functions, such as cudaq.spin.i(), cudaq.spin.x(), cudaq.spin.y(), cudaq.spin.z() may be used to construct more complex spin Hamiltonians on multiple qubits.

C++

The cudaq::observe method takes a kernel and its arguments as inputs, along with a cudaq::spin_op.

Within the cudaq::spin namespace, operators may be defined as a linear combination of Pauli strings. Functions, such as cudaq::spin::i, cudaq::spin::x, cudaq::spin::y, cudaq::spin::z may be used to construct more complex spin Hamiltonians on multiple qubits.

Below is an example of a spin operator object consisting of a Z(0) operator, or a Pauli Z-operator on the qubit zero. This is followed by the construction of a kernel with a single qubit in an equal superposition. The Hamiltonian is printed to confirm it has been constructed properly.

Python

import cudaq
from cudaq import spin

operator = spin.z(0)
print(operator)  # prints: [1+0j] Z


@cudaq.kernel
def kernel():
    qubit = cudaq.qubit()
    h(qubit)

C++

#include <cudaq.h>
#include <cudaq/algorithm.h>

#include <iostream>

using namespace cudaq::spin;

__qpu__ void kernel() {
  cudaq::qubit qubit;
  h(qubit);
}

int main() {
  cudaq::spin_op spin_operator = z(0);
  // Prints: [1+0j] Z
  std::cout << spin_operator.to_string() << "\n";

The observe function takes a kernel, any kernel arguments, and a spin operator as inputs and produces an ObserveResult object. The expectation value can be printed using the expectation method.

Note

It is important to exclude a measurement in the kernel, otherwise the expectation value will be determined from a collapsed classical state. For this example, the expected result of 0.0 is produced.

Python

result = cudaq.observe(kernel, operator)
print(result.expectation())  # prints: 0.0

C++

  auto result_0 = cudaq::observe(kernel, spin_operator);
  // Expectation value of kernel with respect to single `Z` term
  // should print: 0.0
  std::cout << "<kernel | spin_operator | kernel> = " << result_0.expectation()
            << "\n";

Unlike sample, the default shots_count for observe is 1. This result is deterministic and equivalent to the expectation value in the limit of infinite shots. To produce an approximate expectation value from sampling, shots_count can be specified to any integer.

Python

result = cudaq.observe(kernel, operator, shots_count=1000)
print(result.expectation())  # prints non-zero value

C++

  auto result_1 = cudaq::observe(1000, kernel, spin_operator);
  // Expectation value of kernel with respect to single `Z` term,
  // but instead of a single deterministic execution of the kernel,
  // we sample over 1000 shots. We should now print an expectation
  // value that is close to, but not quite, zero.
  // Example: 0.025
  std::cout << "<kernel | spin_operator | kernel> = " << result_1.expectation()
            << "\n";
}

Similar to sample_async above, observe also supports asynchronous execution. More information about parallelizing execution can be found at Multi-Processor Platforms page.

Running on a GPU¶

Python

Using cudaq.set_target(), different targets can be specified for kernel execution.

C++

Using the --target argument to nvq++, different targets can be specified for kernel execution.

If a local GPU is detected, the target will default to nvidia. Otherwise, the CPU-based simulation target, qpp-cpu, will be selected.

We will demonstrate the benefits of using a GPU by sampling our GHZ kernel with 25 qubits and a shots_count of 1 million. Using a GPU accelerates this task by more than 35x. To learn about all of the available targets and ways to accelerate kernel execution, visit the Backends page.

Python

import sys
import timeit

# Will time the execution of our sample call.
code_to_time = 'cudaq.sample(kernel, qubit_count, shots_count=1000000)'
qubit_count = int(sys.argv[1]) if 1 < len(sys.argv) else 25

# Execute on CPU backend.
cudaq.set_target('qpp-cpu')
print('CPU time')  # Example: 27.57462 s.
print(timeit.timeit(stmt=code_to_time, globals=globals(), number=1))

if cudaq.num_available_gpus() > 0:
    # Execute on GPU backend.
    cudaq.set_target('nvidia')
    print('GPU time')  # Example: 0.773286 s.
    print(timeit.timeit(stmt=code_to_time, globals=globals(), number=1))

C++

To compare the performance, we can create a simple timing script that isolates just the call to cudaq::sample. We are still using the same GHZ kernel as earlier, but the following modification made to the main function:

int main(int argc, char *argv[]) {
  auto qubit_count = 1 < argc ? atoi(argv[1]) : 25;
  auto shots_count = 1000000;
  auto start = std::chrono::high_resolution_clock::now();

  // Timing just the sample execution.
  auto result = cudaq::sample(shots_count, kernel, qubit_count);

  auto stop = std::chrono::high_resolution_clock::now();
  auto duration = std::chrono::duration<double>(stop - start);
  std::cout << "It took " << duration.count() << " seconds.\n";
}

First we execute on the CPU backend:

nvq++ --target=qpp-cpu sample.cpp
./a.out

seeing an output of the order: It took 22.8337 seconds.

Now we can execute on the GPU enabled backend:

nvq++ --target=nvidia sample.cpp
./a.out

seeing an output of the order: It took 3.18988 seconds.

Running your first CUDA-Q Program¶

Sample¶

Observe¶

Running on a GPU¶