CUDA Quantum Python API¶

Python bindings for CUDA Quantum.

Program Construction¶

cudaq.make_kernel(*args, **kwargs)¶

Overloaded function.

make_kernel() -> cudaq::kernel_builder<>

Create and return a Kernel that accepts no arguments.

Returns:: An empty kernel function to be used for quantum program construction. This kernel is non-parameterized and accepts no arguments.
Return type:: Kernel

# Example:
# Non-parameterized kernel.
kernel = cudaq.make_kernel()

```
make_kernel(*args) -> tuple
```

Create a Kernel that takes the provided types as arguments. Returns a tuple containing the kernel and a QuakeValue for each kernel argument.

Note

The following types are supported as kernel arguments: int, float, list/List, cudaq.qubit, or cudaq.qreg.

Parameters:: *arguments – A variable amount of types for the kernel function to accept as arguments.
Returns:: A tuple containing an empty kernel function and a QuakeValue handle for each argument that was passed into make_kernel().
Return type:: tuple[Kernel, QuakeValue, ...]

# Example:
# Parameterized kernel that accepts an `int` and `float` as arguments.
kernel, int_value, float_value = cudaq.make_kernel(int, float)

class cudaq.Kernel¶

The Kernel provides an API for dynamically constructing quantum circuits. The Kernel programmatically represents the circuit as an MLIR function using the Quake dialect.

Note

See make_kernel() for the Kernel constructor.

name¶

The name of the Kernel function. Read-only.

Type:: str

arguments¶

The arguments accepted by the Kernel function. Read-only.

Type:: List[QuakeValue]

argument_count¶

The number of arguments accepted by the Kernel function. Read-only.

Type:: int

qalloc(*args, **kwargs)¶

Overloaded function.

qalloc(self: _pycudaq.Kernel) -> cudaq::QuakeValue

Allocate a single qubit and return a handle to it as a QuakeValue.

Returns:: A handle to the allocated qubit in the MLIR.
Return type:: QuakeValue

# Example:
kernel = cudaq.make_kernel()
qubit = kernel.qalloc()

qalloc(self: _pycudaq.Kernel, qubit_count: int) -> cudaq::QuakeValue

Allocate a register of qubits of size qubit_count and return a handle to them as a QuakeValue.

Parameters:: qubit_count (int) – The number of qubits to allocate.
Returns:: A handle to the allocated qubits in the MLIR.
Return type:: QuakeValue

# Example:
kernel = cudaq.make_kernel()
qubits = kernel.qalloc(10)

qalloc(self: _pycudaq.Kernel, qubit_count: cudaq::QuakeValue) -> cudaq::QuakeValue

Allocate a register of qubits of size qubit_count (where qubit_count is an existing QuakeValue) and return a handle to them as a new QuakeValue.

Parameters:: qubit_count (QuakeValue) – The parameterized number of qubits to allocate.
Returns:: A handle to the allocated qubits in the MLIR.
Return type:: QuakeValue

# Example:
# Create a kernel that takes an int as its argument.
kernel, qubit_count = cudaq.make_kernel(int)
# Allocate the variable number of qubits.
qubits = kernel.qalloc(qubit_count)

__str__()¶

__str__(self: _pycudaq.Kernel) -> str

Return the Kernel as a string in its MLIR representation using the Quake dialect.

__call__()¶

__call__(self: _pycudaq.Kernel, *args) -> None

Just-In-Time (JIT) compile self (Kernel), and call the kernel function at the provided concrete arguments.

Parameters:: *arguments (Optional[Any]) – The concrete values to evaluate the kernel function at. Leave empty if the target kernel doesn’t accept any arguments.

# Example:
# Create a kernel that accepts an int and float as its arguments.
kernel, qubit_count, angle = cudaq.make_kernel(int, float)
# Parameterize the number of qubits by `qubit_count`.
qubits = kernel.qalloc(qubit_count)
# Apply an `rx` rotation on the first qubit by `angle`.
kernel.rx(angle, qubits[0])
# Call the `Kernel` on the given number of qubits (5) and at  a concrete angle (pi).
kernel(5, 3.14)

x()¶

x(self: _pycudaq.Kernel, target: cudaq::QuakeValue) -> None

Apply a x gate to the given target qubit or qubits.

Parameters:: target (QuakeValue) – The qubit or qubits to apply x to.

# Example:
kernel = cudaq.make_kernel()
# Allocate qubit/s to the `kernel`.
qubits = kernel.qalloc(5)
# Apply a x gate to the qubit/s.
kernel.x(qubits)

cx(*args, **kwargs)¶

Overloaded function.

cx(self: _pycudaq.Kernel, control: cudaq::QuakeValue, target: cudaq::QuakeValue) -> None

Apply a controlled-x operation to the given target qubit, with the provided control qubit.

Parameters:

control (QuakeValue) – The control qubit for the operation. Must be a single qubit, registers are not a valid control argument.
target (QuakeValue) – The target qubit of the operation.

# Example:
kernel = cudaq.make_kernel()
control = kernel.qalloc()
target = kernel.qalloc()
# Apply a controlled-x between the two qubits.
kernel.cx(control=control, target=target)

cx(self: _pycudaq.Kernel, controls: List[cudaq::QuakeValue], target: cudaq::QuakeValue) -> None

Apply a controlled-x operation to the given target qubits, with the provided list of control qubits.

Parameters:

controls (QuakeValue) – The list of qubits to use as controls for the operation.
target (QuakeValue) – The target qubit of the operation.

# Example:
kernel = cudaq.make_kernel()
controls = kernel.qalloc(2)
target = kernel.qalloc()
# Apply a controlled-x to the target qubit, with the two control qubits.
kernel.cx(controls=[controls[0], controls[1]], target=target)

y()¶

y(self: _pycudaq.Kernel, target: cudaq::QuakeValue) -> None

Apply a y gate to the given target qubit or qubits.

Parameters:: target (QuakeValue) – The qubit or qubits to apply y to.

# Example:
kernel = cudaq.make_kernel()
# Allocate qubit/s to the `kernel`.
qubits = kernel.qalloc(5)
# Apply a y gate to the qubit/s.
kernel.y(qubits)

cy(*args, **kwargs)¶

Overloaded function.

cy(self: _pycudaq.Kernel, control: cudaq::QuakeValue, target: cudaq::QuakeValue) -> None

Apply a controlled-y operation to the given target qubit, with the provided control qubit.

Parameters:

control (QuakeValue) – The control qubit for the operation. Must be a single qubit, registers are not a valid control argument.
target (QuakeValue) – The target qubit of the operation.

# Example:
kernel = cudaq.make_kernel()
control = kernel.qalloc()
target = kernel.qalloc()
# Apply a controlled-y between the two qubits.
kernel.cy(control=control, target=target)

cy(self: _pycudaq.Kernel, controls: List[cudaq::QuakeValue], target: cudaq::QuakeValue) -> None

Apply a controlled-y operation to the given target qubits, with the provided list of control qubits.

Parameters:

controls (QuakeValue) – The list of qubits to use as controls for the operation.
target (QuakeValue) – The target qubit of the operation.

# Example:
kernel = cudaq.make_kernel()
controls = kernel.qalloc(2)
target = kernel.qalloc()
# Apply a controlled-y to the target qubit, with the two control qubits.
kernel.cy(controls=[controls[0], controls[1]], target=target)

z()¶

z(self: _pycudaq.Kernel, target: cudaq::QuakeValue) -> None

Apply a z gate to the given target qubit or qubits.

Parameters:: target (QuakeValue) – The qubit or qubits to apply z to.

# Example:
kernel = cudaq.make_kernel()
# Allocate qubit/s to the `kernel`.
qubits = kernel.qalloc(5)
# Apply a z gate to the qubit/s.
kernel.z(qubits)

cz(*args, **kwargs)¶

Overloaded function.

cz(self: _pycudaq.Kernel, control: cudaq::QuakeValue, target: cudaq::QuakeValue) -> None

Apply a controlled-z operation to the given target qubit, with the provided control qubit.

Parameters:

control (QuakeValue) – The control qubit for the operation. Must be a single qubit, registers are not a valid control argument.
target (QuakeValue) – The target qubit of the operation.

# Example:
kernel = cudaq.make_kernel()
control = kernel.qalloc()
target = kernel.qalloc()
# Apply a controlled-z between the two qubits.
kernel.cz(control=control, target=target)

cz(self: _pycudaq.Kernel, controls: List[cudaq::QuakeValue], target: cudaq::QuakeValue) -> None

Apply a controlled-z operation to the given target qubits, with the provided list of control qubits.

Parameters:

controls (QuakeValue) – The list of qubits to use as controls for the operation.
target (QuakeValue) – The target qubit of the operation.

# Example:
kernel = cudaq.make_kernel()
controls = kernel.qalloc(2)
target = kernel.qalloc()
# Apply a controlled-z to the target qubit, with the two control qubits.
kernel.cz(controls=[controls[0], controls[1]], target=target)

h()¶

h(self: _pycudaq.Kernel, target: cudaq::QuakeValue) -> None

Apply a h gate to the given target qubit or qubits.

Parameters:: target (QuakeValue) – The qubit or qubits to apply h to.

# Example:
kernel = cudaq.make_kernel()
# Allocate qubit/s to the `kernel`.
qubits = kernel.qalloc(5)
# Apply a h gate to the qubit/s.
kernel.h(qubits)

ch(*args, **kwargs)¶

Overloaded function.

ch(self: _pycudaq.Kernel, control: cudaq::QuakeValue, target: cudaq::QuakeValue) -> None

Apply a controlled-h operation to the given target qubit, with the provided control qubit.

Parameters:

control (QuakeValue) – The control qubit for the operation. Must be a single qubit, registers are not a valid control argument.
target (QuakeValue) – The target qubit of the operation.

# Example:
kernel = cudaq.make_kernel()
control = kernel.qalloc()
target = kernel.qalloc()
# Apply a controlled-h between the two qubits.
kernel.ch(control=control, target=target)

ch(self: _pycudaq.Kernel, controls: List[cudaq::QuakeValue], target: cudaq::QuakeValue) -> None

Apply a controlled-h operation to the given target qubits, with the provided list of control qubits.

Parameters:

controls (QuakeValue) – The list of qubits to use as controls for the operation.
target (QuakeValue) – The target qubit of the operation.

# Example:
kernel = cudaq.make_kernel()
controls = kernel.qalloc(2)
target = kernel.qalloc()
# Apply a controlled-h to the target qubit, with the two control qubits.
kernel.ch(controls=[controls[0], controls[1]], target=target)

s()¶

s(self: _pycudaq.Kernel, target: cudaq::QuakeValue) -> None

Apply a s gate to the given target qubit or qubits.

Parameters:: target (QuakeValue) – The qubit or qubits to apply s to.

# Example:
kernel = cudaq.make_kernel()
# Allocate qubit/s to the `kernel`.
qubits = kernel.qalloc(5)
# Apply a s gate to the qubit/s.
kernel.s(qubits)

cs(*args, **kwargs)¶

Overloaded function.

cs(self: _pycudaq.Kernel, control: cudaq::QuakeValue, target: cudaq::QuakeValue) -> None

Apply a controlled-s operation to the given target qubit, with the provided control qubit.

Parameters:

control (QuakeValue) – The control qubit for the operation. Must be a single qubit, registers are not a valid control argument.
target (QuakeValue) – The target qubit of the operation.

# Example:
kernel = cudaq.make_kernel()
control = kernel.qalloc()
target = kernel.qalloc()
# Apply a controlled-s between the two qubits.
kernel.cs(control=control, target=target)

cs(self: _pycudaq.Kernel, controls: List[cudaq::QuakeValue], target: cudaq::QuakeValue) -> None

Apply a controlled-s operation to the given target qubits, with the provided list of control qubits.

Parameters:

controls (QuakeValue) – The list of qubits to use as controls for the operation.
target (QuakeValue) – The target qubit of the operation.

# Example:
kernel = cudaq.make_kernel()
controls = kernel.qalloc(2)
target = kernel.qalloc()
# Apply a controlled-s to the target qubit, with the two control qubits.
kernel.cs(controls=[controls[0], controls[1]], target=target)

t()¶

t(self: _pycudaq.Kernel, target: cudaq::QuakeValue) -> None

Apply a t gate to the given target qubit or qubits.

Parameters:: target (QuakeValue) – The qubit or qubits to apply t to.

# Example:
kernel = cudaq.make_kernel()
# Allocate qubit/s to the `kernel`.
qubits = kernel.qalloc(5)
# Apply a t gate to the qubit/s.
kernel.t(qubits)

ct(*args, **kwargs)¶

Overloaded function.

ct(self: _pycudaq.Kernel, control: cudaq::QuakeValue, target: cudaq::QuakeValue) -> None

Apply a controlled-t operation to the given target qubit, with the provided control qubit.

Parameters:

control (QuakeValue) – The control qubit for the operation. Must be a single qubit, registers are not a valid control argument.
target (QuakeValue) – The target qubit of the operation.

# Example:
kernel = cudaq.make_kernel()
control = kernel.qalloc()
target = kernel.qalloc()
# Apply a controlled-t between the two qubits.
kernel.ct(control=control, target=target)

ct(self: _pycudaq.Kernel, controls: List[cudaq::QuakeValue], target: cudaq::QuakeValue) -> None

Apply a controlled-t operation to the given target qubits, with the provided list of control qubits.

Parameters:

controls (QuakeValue) – The list of qubits to use as controls for the operation.
target (QuakeValue) – The target qubit of the operation.

# Example:
kernel = cudaq.make_kernel()
controls = kernel.qalloc(2)
target = kernel.qalloc()
# Apply a controlled-t to the target qubit, with the two control qubits.
kernel.ct(controls=[controls[0], controls[1]], target=target)

rx(*args, **kwargs)¶

Overloaded function.

rx(self: _pycudaq.Kernel, parameter: cudaq::QuakeValue, target: cudaq::QuakeValue) -> None

Apply rx to the given target qubit, parameterized by the provided kernel argument (parameter).

Parameters:

parameter (QuakeValue) – The kernel argument to parameterize the rx gate over.
target (QuakeValue) – The target qubit of the rx gate.

# Example:
# Create a kernel that accepts a float, `angle`, as its argument.
kernel, angle = cudaq.make_kernel(float)
qubit = kernel.qalloc()
# Apply an rx to the kernel at `angle`.
kernel.rx(parameter=angle, target=qubit)

rx(self: _pycudaq.Kernel, parameter: float, target: cudaq::QuakeValue) -> None

Apply rx to the given target qubit, parameterized by the provided double value (parameter).

Parameters:

parameter (float) – The double value to parameterize the rx gate over.
target (QuakeValue) – The target qubit of the rx gate.

# Example:
kernel = cudaq.make_kernel()
# Apply an rx to the kernel at a concrete parameter value.
kernel.rx(parameter=3.14, target=qubit)

ry(*args, **kwargs)¶

Overloaded function.

ry(self: _pycudaq.Kernel, parameter: cudaq::QuakeValue, target: cudaq::QuakeValue) -> None

Apply ry to the given target qubit, parameterized by the provided kernel argument (parameter).

Parameters:

parameter (QuakeValue) – The kernel argument to parameterize the ry gate over.
target (QuakeValue) – The target qubit of the ry gate.

# Example:
# Create a kernel that accepts a float, `angle`, as its argument.
kernel, angle = cudaq.make_kernel(float)
qubit = kernel.qalloc()
# Apply an ry to the kernel at `angle`.
kernel.ry(parameter=angle, target=qubit)

ry(self: _pycudaq.Kernel, parameter: float, target: cudaq::QuakeValue) -> None

Apply ry to the given target qubit, parameterized by the provided double value (parameter).

Parameters:

parameter (float) – The double value to parameterize the ry gate over.
target (QuakeValue) – The target qubit of the ry gate.

# Example:
kernel = cudaq.make_kernel()
# Apply an ry to the kernel at a concrete parameter value.
kernel.ry(parameter=3.14, target=qubit)

rz(*args, **kwargs)¶

Overloaded function.

rz(self: _pycudaq.Kernel, parameter: cudaq::QuakeValue, target: cudaq::QuakeValue) -> None

Apply rz to the given target qubit, parameterized by the provided kernel argument (parameter).

Parameters:

parameter (QuakeValue) – The kernel argument to parameterize the rz gate over.
target (QuakeValue) – The target qubit of the rz gate.

# Example:
# Create a kernel that accepts a float, `angle`, as its argument.
kernel, angle = cudaq.make_kernel(float)
qubit = kernel.qalloc()
# Apply an rz to the kernel at `angle`.
kernel.rz(parameter=angle, target=qubit)

rz(self: _pycudaq.Kernel, parameter: float, target: cudaq::QuakeValue) -> None

Apply rz to the given target qubit, parameterized by the provided double value (parameter).

Parameters:

parameter (float) – The double value to parameterize the rz gate over.
target (QuakeValue) – The target qubit of the rz gate.

# Example:
kernel = cudaq.make_kernel()
# Apply an rz to the kernel at a concrete parameter value.
kernel.rz(parameter=3.14, target=qubit)

mx()¶

mx(self: _pycudaq.Kernel, target: cudaq::QuakeValue, register_name: str = '') -> cudaq::QuakeValue

Measure the given qubit or qubits in the X-basis. The optional register_name may be used to retrieve results of this measurement after execution on the QPU. If the measurement call is saved as a variable, it will return a QuakeValue handle to the measurement instruction.

Parameters:

target (QuakeValue) – The qubit or qubits to measure.
register_name (Optional[str]) – The optional name to provide the results of the measurement. Defaults to an empty string.

Returns:

A handle to this measurement operation in the MLIR.

Return type:

QuakeValue

Note

Measurements may be applied both mid-circuit and at the end of the circuit. Mid-circuit measurements are currently only supported through the use of c_if().

# Example:
kernel = cudaq.make_kernel()
# Allocate qubit/s to measure.
qubit = kernel.qalloc()
# Measure the qubit/s in the X-basis.
kernel.mx(qubit)

my()¶

my(self: _pycudaq.Kernel, target: cudaq::QuakeValue, register_name: str = '') -> cudaq::QuakeValue

Measure the given qubit or qubits in the Y-basis. The optional register_name may be used to retrieve results of this measurement after execution on the QPU. If the measurement call is saved as a variable, it will return a QuakeValue handle to the measurement instruction.

Parameters:

target (QuakeValue) – The qubit or qubits to measure.
register_name (Optional[str]) – The optional name to provide the results of the measurement. Defaults to an empty string.

Returns:

A handle to this measurement operation in the MLIR.

Return type:

QuakeValue

Note

Measurements may be applied both mid-circuit and at the end of the circuit. Mid-circuit measurements are currently only supported through the use of c_if().

# Example:
kernel = cudaq.make_kernel()
# Allocate qubit/s to measure.
qubit = kernel.qalloc()
# Measure the qubit/s in the Y-basis.
kernel.my(qubit)

mz()¶

mz(self: _pycudaq.Kernel, target: cudaq::QuakeValue, register_name: str = '') -> cudaq::QuakeValue

Measure the given qubit or qubits in the Z-basis. The optional register_name may be used to retrieve results of this measurement after execution on the QPU. If the measurement call is saved as a variable, it will return a QuakeValue handle to the measurement instruction.

Parameters:

target (QuakeValue) – The qubit or qubits to measure.
register_name (Optional[str]) – The optional name to provide the results of the measurement. Defaults to an empty string.

Returns:

A handle to this measurement operation in the MLIR.

Return type:

QuakeValue

Note

Measurements may be applied both mid-circuit and at the end of the circuit. Mid-circuit measurements are currently only supported through the use of c_if().

# Example:
kernel = cudaq.make_kernel()
# Allocate qubit/s to measure.
qubit = kernel.qalloc()
# Measure the qubit/s in the Z-basis.
kernel.mz(target=qubit)

c_if()¶

c_if(self: _pycudaq.Kernel, measurement: cudaq::QuakeValue, function: function) -> None

Apply the function to the Kernel if the provided single-qubit measurement returns the 1-state.

Parameters:

measurement (QuakeValue) – The handle to the single qubit measurement instruction.
function (Callable) – The function to conditionally apply to the Kernel.

Raises:

RuntimeError – If the provided measurement is on more than 1 qubit.

# Example:
# Create a kernel and allocate a single qubit.
kernel = cudaq.make_kernel()
qubit = kernel.qalloc()

# Define a function that performs certain operations on the
# kernel and the qubit.
def then_function():
    kernel.x(qubit)
kernel.x(qubit)

# Measure the qubit.
measurement = kernel.mz(qubit)
# Apply `then_function` to the `kernel` if the qubit was measured
# in the 1-state.
kernel.c_if(measurement, then_function)

adjoint()¶

adjoint(self: _pycudaq.Kernel, target: _pycudaq.Kernel, *args) -> None

Apply the adjoint of the target kernel in-place to self.

Parameters:

target (Kernel) – The kernel to take the adjoint of.
*target_arguments (Optional[QuakeValue]) – The arguments to the target kernel. Leave empty if the target kernel doesn’t accept any arguments.

Raises:

RuntimeError – if the *target_arguments passed to the adjoint call don’t match the argument signature of target.

# Example:
target_kernel = cudaq.make_kernel()
qubit = target_kernel.qalloc()
target_kernel.x(qubit)

# Apply the adjoint of `target_kernel` to `kernel`.
kernel = cudaq.make_kernel()
kernel.adjoint(target_kernel)

control()¶

control(self: _pycudaq.Kernel, target: _pycudaq.Kernel, control: cudaq::QuakeValue, *args) -> None

Apply the target kernel as a controlled operation in-place to self.Uses the provided control as control qubit/s for the operation.

Parameters:

target (Kernel) – The kernel to apply as a controlled operation in-place to self.
control (QuakeValue) – The control qubit or register to use when applying target.
*target_arguments (Optional[QuakeValue]) – The arguments to the target kernel. Leave empty if the target kernel doesn’t accept any arguments.

Raises:

RuntimeError – if the *target_arguments passed to the control call don’t match the argument signature of target.

# Example:
# Create a `Kernel` that accepts a qubit as an argument.
# Apply an X-gate on that qubit.
target_kernel, qubit = cudaq.make_kernel(cudaq.qubit)
target_kernel.x(qubit)

# Create another `Kernel` that will apply `target_kernel`
# as a controlled operation.
kernel = cudaq.make_kernel()
control_qubit = kernel.qalloc()
target_qubit = kernel.qalloc()
# In this case, `control` performs the equivalent of a
# controlled-X gate between `control_qubit` and `target_qubit`.
kernel.control(target_kernel, control_qubit, target_qubit)

apply_call()¶

apply_call(self: _pycudaq.Kernel, target: _pycudaq.Kernel, *args) -> None

Apply a call to the given target kernel within the function-body of self at the provided target_arguments.

Parameters:

target (Kernel) – The kernel to call from within self.
*target_arguments (Optional[QuakeValue]) – The arguments to the target kernel. Leave empty if the target kernel doesn’t accept any arguments.

Raises:

RuntimeError – if the *target_arguments passed to the apply call don’t match the argument signature of target.

# Example:
# Build a `Kernel` that's parameterized by a `cudaq.qubit`.
target_kernel, other_qubit = cudaq.make_kernel(cudaq.qubit)
target_kernel.x(other_qubit)

# Build a `Kernel` that will call `target_kernel` within its
# own function body.
kernel = cudaq.make_kernel()
qubit = kernel.qalloc()
# Use `qubit` as the argument to `target_kernel`.
kernel.apply_call(target_kernel, qubit)
# The final measurement of `qubit` should return the 1-state.
kernel.mz(qubit)

Kernel Execution¶

cudaq.sample()¶

sample(kernel: _pycudaq.Kernel, *args, shots_count: int = 1000, noise_model: Optional[_pycudaq.NoiseModel] = None) -> cudaq::sample_result

Sample the state of the provided kernel at the specified number of circuit executions (shots_count).

Parameters:

kernel (Kernel) – The Kernel to execute shots_count times on the QPU.
*arguments (Optional[Any]) – The concrete values to evaluate the kernel function at. Leave empty if the kernel doesn’t accept any arguments.
shots_count (Optional[int]) – The number of kernel executions on the QPU. Defaults to 1000. Key-word only.
noise_model (Optional[NoiseModel]) – The optional NoiseModel to add noise to the kernel execution on the simulator. Defaults to an empty noise model.

Returns:

A dictionary containing the measurement count results for the Kernel.

Return type:

SampleResult

cudaq.sample_async()¶

sample_async(kernel: _pycudaq.Kernel, *args, shots_count: int = 1000, qpu_id: int = 0) -> _pycudaq.AsyncSampleResult

Asynchronously sample the state of the provided kernel at the specified number of circuit executions (shots_count). When targeting a quantum platform with more than one QPU, the optional qpu_id allows for control over which QPU to enable. Will return a future whose results can be retrieved via future.get().

Parameters:

kernel (Kernel) – The Kernel to execute shots_count times on the QPU.
*arguments (Optional[Any]) – The concrete values to evaluate the kernel function at. Leave empty if the kernel doesn’t accept any arguments.
shots_count (Optional[int]) – The number of kernel executions on the QPU. Defaults to 1000. Key-word only.
qpu_id (Optional[int]) – The optional identification for which QPU on the platform to target. Defaults to zero. Key-word only.

Returns:

A dictionary containing the measurement count results for the Kernel.

Return type:

AsyncSampleResult

cudaq.observe()¶

observe(kernel: _pycudaq.Kernel, spin_operator: cudaq::spin_op, *args, shots_count: int = -1) -> cudaq::observe_result

Compute the expected value of the spin_operator with respect to the kernel. If the kernel accepts arguments, it will be evaluated with respect to kernel(*arguments).

Parameters:

kernel (Kernel) – The Kernel to evaluate the expectation value with respect to.
spin_operator (SpinOperator) – The Hermitian spin operator to calculate the expectation of.
*arguments (Optional[Any]) – The concrete values to evaluate the kernel function at. Leave empty if the kernel doesn’t accept any arguments.
shots_count (Optional[int]) – The number of shots to use for QPU execution. Defaults to 1 shot. Key-word only.

Returns:

A data-type containing the expectation value of the spin_operator with respect to the kernel(*arguments). If shots_count was provided, the ObserveResult will also contain a SampleResult dictionary.

Return type:

ObserveResult

cudaq.observe_async()¶

observe_async(kernel: _pycudaq.Kernel, spin_operator: cudaq::spin_op, *args, qpu_id: int = 0, shots_count: int = -1) -> cudaq::async_result<cudaq::observe_result>

Compute the expected value of the spin_operator with respect to the kernel asynchronously. If the kernel accepts arguments, it will be evaluated with respect to kernel(*arguments). When targeting a quantum platform with more than one QPU, the optional qpu_id allows for control over which QPU to enable. Will return a future whose results can be retrieved via future.get().

Parameters:

kernel (Kernel) – The Kernel to evaluate the expectation value with respect to.
spin_operator (SpinOperator) – The Hermitian spin operator to calculate the expectation of.
*arguments (Optional[Any]) – The concrete values to evaluate the kernel function at. Leave empty if the kernel doesn’t accept any arguments.
qpu_id (Optional[int]) – The optional identification for which QPU on the platform to target. Defaults to zero. Key-word only.
shots_count (Optional[int]) – The number of shots to use for QPU execution. Defaults to 1 shot. Key-word only.

Returns:

A future containing the result of the call to observe.

Return type:

AsyncObserveResult

cudaq.vqe(*args, **kwargs)¶

Overloaded function.

vqe(kernel: _pycudaq.Kernel, spin_operator: _pycudaq.SpinOperator, optimizer: _pycudaq.optimizers.optimizer, parameter_count: int, shots: int = -1) -> Tuple[float, List[float]]

vqe(kernel: _pycudaq.Kernel, spin_operator: _pycudaq.SpinOperator, optimizer: _pycudaq.optimizers.optimizer, parameter_count: int, argument_mapper: function, shots: int = -1) -> Tuple[float, List[float]]

vqe(kernel: _pycudaq.Kernel, gradient_strategy: _pycudaq.gradients.gradient, spin_operator: _pycudaq.SpinOperator, optimizer: _pycudaq.optimizers.optimizer, parameter_count: int, shots: int = -1) -> Tuple[float, List[float]]

vqe(kernel: _pycudaq.Kernel, gradient_strategy: _pycudaq.gradients.gradient, spin_operator: _pycudaq.SpinOperator, optimizer: _pycudaq.optimizers.optimizer, parameter_count: int, argument_mapper: function, shots: int = -1) -> Tuple[float, List[float]]

Backend Configuration¶

cudaq.set_noise()¶

set_noise(arg0: cudaq::noise_model) -> None

Set the underlying noise model.

cudaq.unset_noise()¶

unset_noise() -> None

Clear backend simulation from any existing noise models.

cudaq.set_qpu()¶

set_qpu(arg0: str, **kwargs) -> None

Specifies which backend quantum kernels will be executed on. Possible values can be queried using the list_qpus. You may also specify the name of an external simulation plugin. Can specify str:str key value pairs as kwargs to configure the backend.

cudaq.list_qpus()¶

list_qpus() -> List[str]

Lists all available backends. Use set_qpu to execute code on one of these backends.

Data Types¶

class cudaq.QuakeValue¶

A QuakeValue represents a handle to an individual function argument of a Kernel, or a return value from an operation within it. As documented in make_kernel(), a QuakeValue can hold values of the following types: int, float, list/List, qubit, or qreg. The QuakeValue can also hold kernel operations such as qubit allocations and measurements.

__add__(*args, **kwargs)¶

Overloaded function.

__add__(self: _pycudaq.QuakeValue, other: float) -> _pycudaq.QuakeValue

Return the sum of self (QuakeValue) and other (float).

Raises:: RuntimeError – if the underlying QuakeValue type is not a float.

# Example:
kernel, value = cudaq.make_kernel(float)
new_value: QuakeValue = value + 5.0

__add__(self: _pycudaq.QuakeValue, other: _pycudaq.QuakeValue) -> _pycudaq.QuakeValue

Return the sum of self (QuakeValue) and other (QuakeValue).

Raises:: RuntimeError – if the underlying QuakeValue type is not a float.

# Example:
kernel, values = cudaq.make_kernel(list)
new_value: QuakeValue = values[0] + values[1]

__radd__()¶

__radd__(self: _pycudaq.QuakeValue, other: float) -> _pycudaq.QuakeValue

Return the sum of other (float) and self (QuakeValue).

Raises:: RuntimeError – if the underlying QuakeValue type is not a float.

# Example:
kernel, value = cudaq.make_kernel(float)
new_value: QuakeValue = 5.0 + value

__sub__(*args, **kwargs)¶

Overloaded function.

__sub__(self: _pycudaq.QuakeValue, other: float) -> _pycudaq.QuakeValue

Return the difference of self (QuakeValue) and other (float).

Raises:: RuntimeError – if the underlying QuakeValue type is not a float.

# Example:
kernel, value = cudaq.make_kernel(float)
new_value: QuakeValue = value - 5.0

__sub__(self: _pycudaq.QuakeValue, other: _pycudaq.QuakeValue) -> _pycudaq.QuakeValue

Return the difference of self (QuakeValue) and other (QuakeValue).

Raises:: RuntimeError – if the underlying QuakeValue type is not a float.

# Example:
kernel, values = cudaq.make_kernel(list)
new_value: QuakeValue = values[0] - values[1]

__rsub__()¶

__rsub__(self: _pycudaq.QuakeValue, other: float) -> _pycudaq.QuakeValue

Return the difference of other (float) and self (QuakeValue).

Raises:: RuntimeError – if the underlying QuakeValue type is not a float.

# Example:
kernel, value = cudaq.make_kernel(float)
new_value: QuakeValue = 5.0 - value

__neg__()¶

__neg__(self: _pycudaq.QuakeValue) -> _pycudaq.QuakeValue

Return the negation of self (QuakeValue).

Raises:: RuntimeError – if the underlying QuakeValue type is not a float.

# Example:
kernel, value = cudaq.make_kernel(float)
new_value: QuakeValue = -value

__mul__(*args, **kwargs)¶

Overloaded function.

__mul__(self: _pycudaq.QuakeValue, other: float) -> _pycudaq.QuakeValue

Return the product of self (QuakeValue) with other (float).

Raises:: RuntimeError – if the underlying QuakeValue type is not a float.

# Example:
kernel, value = cudaq.make_kernel(float)
new_value: QuakeValue = value * 5.0

__mul__(self: _pycudaq.QuakeValue, other: _pycudaq.QuakeValue) -> _pycudaq.QuakeValue

Return the product of self (QuakeValue) with other (QuakeValue).

Raises:: RuntimeError – if the underlying QuakeValue type is not a float.

# Example:
kernel, values = cudaq.make_kernel(list)
new_value: QuakeValue = values[0] * values[1]

__rmul__()¶

__rmul__(self: _pycudaq.QuakeValue, other: float) -> _pycudaq.QuakeValue

Return the product of other (float) with self (QuakeValue).

Raises:: RuntimeError – if the underlying QuakeValue type is not a float.

# Example:
kernel, value = cudaq.make_kernel(float)
new_value: QuakeValue = 5.0 * value

__getitem__()¶

__getitem__(self: _pycudaq.QuakeValue, index: int) -> _pycudaq.QuakeValue

Return the element of self at the provided index.

Note

Only list or qreg type QuakeValue’s may be indexed.

Parameters:: index (int) – The element of self that you’d like to return.
Returns:: Returns a new QuakeValue for the index-th element of self.
Return type:: QuakeValue
Raises:: RuntimeError – if self is a non-subscriptable QuakeValue.

class cudaq.qubit¶

The data-type representing a qubit argument to a Kernel function.

# Example:
kernel, qubit = cudaq.make_kernel(cudaq.qubit)

class cudaq.qreg¶

The data-type representing a register of qubits as an argument to a Kernel function.

# Example:
kernel, qreg = cudaq.make_kernel(cudaq.qreg)

class cudaq.SpinOperator¶

__eq__()¶

__eq__(self: _pycudaq.SpinOperator, arg0: _pycudaq.SpinOperator) -> bool

Return true if the two SpinOperator’s are equal. Equality does not consider the coefficients.

__add__(*args, **kwargs)¶

Overloaded function.

__add__(self: _pycudaq.SpinOperator, arg0: _pycudaq.SpinOperator) -> _pycudaq.SpinOperator

Add the given SpinOperator to this one and return result as a new cudaq.SpinOperator.

__add__(self: _pycudaq.SpinOperator, arg0: float) -> _pycudaq.SpinOperator

Add a double to the given SpinOperator and return result as a new cudaq.SpinOperator.

__radd__()¶

__radd__(self: _pycudaq.SpinOperator, arg0: float) -> _pycudaq.SpinOperator

Add a SpinOperator to the given double and return result as a new cudaq.SpinOperator.

__sub__(*args, **kwargs)¶

Overloaded function.

__sub__(self: _pycudaq.SpinOperator, arg0: _pycudaq.SpinOperator) -> _pycudaq.SpinOperator

Subtract the given SpinOperator from this one and return result as a new cudaq.SpinOperator.

__sub__(self: _pycudaq.SpinOperator, arg0: float) -> _pycudaq.SpinOperator

Subtract a double from the given SpinOperator and return result as a new cudaq.SpinOperator.

__rsub__()¶

__rsub__(self: _pycudaq.SpinOperator, arg0: float) -> _pycudaq.SpinOperator

Subtract a SpinOperator from the given double and return result as a new cudaq.v=SpinOperator.

__mul__(*args, **kwargs)¶

Overloaded function.

__mul__(self: _pycudaq.SpinOperator, arg0: _pycudaq.SpinOperator) -> _pycudaq.SpinOperator

Multiply the given cudaq.SpinOperator’s together and return result as a new cudaq.SpinOperator.

__mul__(self: _pycudaq.SpinOperator, arg0: float) -> _pycudaq.SpinOperator

Multiply the SpinOperator by the given double and return result as a new cudaq.SpinOperator.

__mul__(self: _pycudaq.SpinOperator, arg0: complex) -> _pycudaq.SpinOperator

Multiply the SpinOperator by the given complex value and return result as a new cudaq.SpinOperator.

__rmul__(*args, **kwargs)¶

Overloaded function.

__rmul__(self: _pycudaq.SpinOperator, arg0: float) -> _pycudaq.SpinOperator

Multiply the double by the given SpinOperator and return result as a new cudaq.SpinOperator.

__rmul__(self: _pycudaq.SpinOperator, arg0: complex) -> _pycudaq.SpinOperator

Multiply the complex value by the given SpinOperator and return result as a new cudaq.SpinOperator.

__getitem__()¶

__getitem__(self: _pycudaq.SpinOperator, index: int) -> _pycudaq.SpinOperator

Return the term of this SpinOperator at the provided index as a new cudaq.SpinOperator.

dump()¶

dump(self: _pycudaq.SpinOperator) -> None

Print a string representation of this SpinOperator.

get_coefficients()¶

get_coefficients(self: _pycudaq.SpinOperator) -> List[complex]

Return all term coefficients in this SpinOperator.

get_qubit_count()¶

get_qubit_count(self: _pycudaq.SpinOperator) -> int

Return the number of qubits this SpinOperator is on.

get_term_coefficient()¶

get_term_coefficient(self: _pycudaq.SpinOperator, term: int) -> complex

Return the coefficient of this SpinOperator at the given term index.

get_term_count()¶

get_term_count(self: _pycudaq.SpinOperator) -> int

Return the number of terms in this SpinOperator.

is_identity()¶

is_identity(self: _pycudaq.SpinOperator) -> bool

Returns a bool indicating if this SpinOperator is equal to the identity.

static random()¶

random(arg0: int, arg1: int) -> _pycudaq.SpinOperator

Return a random spin_op on the given number of qubits and composed of the given number of terms.

slice()¶

slice(self: _pycudaq.SpinOperator, arg0: int, arg1: int) -> _pycudaq.SpinOperator

Return a slice of this SpinOperator. The slice starts at the term index and contains the following count terms.

to_string()¶

to_string(self: _pycudaq.SpinOperator) -> str

Return a string representation of this SpinOperator.

spin.i()¶

i(target: int) -> cudaq::spin_op

Return an identity cudaq.SpinOperator on the given target qubit index.

spin.x()¶

x(target: int) -> cudaq::spin_op

Return an X cudaq.SpinOperator on the given target qubit index.

spin.y()¶

y(target: int) -> cudaq::spin_op

Return a Y cudaq.SpinOperator on the given target qubit index.

spin.z()¶

z(target: int) -> cudaq::spin_op

Return a Z cudaq.SpinOperator on the given target qubit index.

class cudaq.SampleResult¶

A data-type containing the results of a call to sample(). This includes all measurement counts data from both mid-circuit and terminal measurements.

Note

At this time, mid-circuit measurements are not directly supported. Mid-circuit measurements may only be used if they are passed through to c_if.

register_names¶

A list of the names of each measurement register that are stored in self.

Type:: List[str]

__getitem__()¶

__getitem__(self: _pycudaq.SampleResult, bitstring: str) -> int

Return the measurement counts for the given bitstring.

Parameters:: bitstring (str) – The binary string to return the measurement data of.
Returns:: The number of times the given bitstring was measured during the shots_count number of executions on the QPU.
Return type:: float

__iter__()¶

__iter__(self: _pycudaq.SampleResult) -> Iterator

Iterate through the SampleResult dictionary.

__len__()¶

__len__(self: _pycudaq.SampleResult) -> int

Return the number of elements in self. Equivalent to the number of uniquely measured bitstrings.

clear()¶

clear(self: _pycudaq.SampleResult) -> None

Clear out all metadata from self.

count()¶

count(self: _pycudaq.SampleResult, bitstring: str, register_name: str = '__global__') -> int

Return the number of times the given bitstring was observed.

Parameters:

bitstring (str) – The binary string to return the measurement counts for.
register_name (Optional[str]) – The optional measurement register name to extract the probability from. Defaults to the ‘__global__’ register.

Returns:

The number of times the given bitstring was measured during the experiment.

Return type:

int

dump()¶

dump(self: _pycudaq.SampleResult) -> None

Print a string of the raw measurement counts data to the terminal.

expectation_z()¶

expectation_z(self: _pycudaq.SampleResult, register_name: str = '__global__') -> float

Return the expectation value in the Z-basis of the Kernel that was sampled.

get_marginal_counts()¶

get_marginal_counts(self: _pycudaq.SampleResult, marginal_indices: List[int], *, register_name: str = '__global__') -> _pycudaq.SampleResult

Extract the measurement counts data for the provided subset of qubits (marginal_indices).

Parameters:

marginal_indices (list[int]) – A list of the qubit indices to extract the measurement data from.
register_name (Optional[str]) – The optional measurement register name to extract the counts data from. Defaults to the ‘__global__’ register.

Returns:

A new SampleResult dictionary containing the extracted measurement data.

Return type:

SampleResult

get_register_counts()¶

get_register_counts(self: _pycudaq.SampleResult, register_name: str) -> _pycudaq.SampleResult

Extract the provided sub-register (register_name) as a new SampleResult.

get_sequential_data()¶

get_sequential_data(self: _pycudaq.SampleResult, register_name: str = '__global__') -> List[str]

Return the data from the given register (register_name) as it was collected sequentially. A list of measurement results, not collated into a map.

items()¶

items(self: _pycudaq.SampleResult) -> Iterator

Return the key/value pairs in this SampleResult dictionary.

most_probable()¶

most_probable(self: _pycudaq.SampleResult, register_name: str = '__global__') -> str

Return the bitstring that was measured most frequently in the experiment.

Parameters:: register_name (Optional[str]) – The optional measurement register name to extract the most probable bitstring from. Defaults to the ‘__global__’ register.
Returns:: The most frequently measured binary string during the experiment.
Return type:: str

probability()¶

probability(self: _pycudaq.SampleResult, bitstring: str, register_name: str = '__global__') -> float

Return the probability of measuring the given bitstring.

Parameters:

bitstring (str) – The binary string to return the measurement probability of.
register_name (Optional[str]) – The optional measurement register name to extract the probability from. Defaults to the ‘__global__’ register.

Returns:

The probability of measuring the given bitstring. Equivalent to the proportion of the total times the bitstring was measured vs. the number of experiments (shots_count).

Return type:

float

values()¶

values(self: _pycudaq.SampleResult) -> Iterator

Return all values (the counts) in this SampleResult dictionary.

class cudaq.AsyncSampleResult¶

A data-type containing the results of a call to sample_async(). The AsyncSampleResult contains a future, whose SampleResult may be returned via an invocation of the get method. This kicks off a wait on the current thread until the results are available. See future for more information on this programming pattern.

get()¶

get(self: _pycudaq.AsyncSampleResult) -> cudaq::sample_result

Return the SampleResult from the asynchronous sample execution.

class cudaq.ObserveResult¶

A data-type containing the results of a call to observe(). This includes any measurement counts data, as well as the global expectation value of the user-defined spin_operator.

counts(*args, **kwargs)¶

Overloaded function.

counts(self: _pycudaq.ObserveResult) -> cudaq::sample_result

Returns a SampleResult dictionary with the measurement results from the experiment. The result for each individual term of the spin_operator is stored in its own measurement register. Each register name corresponds to the string representation of the spin term (without any coefficients).

counts(self: _pycudaq.ObserveResult, sub_term: cudaq::spin_op) -> cudaq::sample_result

Given a sub_term of the global spin_operator that was passed to observe(), return its measurement counts.

Parameters:: sub_term (SpinOperator) – An individual sub-term of the spin_operator.
Returns:: The measurement counts data for the individual sub_term.
Return type:: SampleResult

dump()¶

dump(self: _pycudaq.ObserveResult) -> None

Dump the raw data from the SampleResult that are stored in ObserveResult to the terminal.

expectation_z(*args, **kwargs)¶

Overloaded function.

expectation_z(self: _pycudaq.ObserveResult) -> float

Return the expectation value of the spin_operator that was provided in observe().

expectation_z(self: _pycudaq.ObserveResult, sub_term: cudaq::spin_op) -> float

Return the expectation value of an individual sub_term of the global spin_operator that was passed to observe().

Parameters:: sub_term (SpinOperator) – An individual sub-term of the spin_operator.
Returns:: The expectation value of the sub_term with respect to the Kernel that was passed to observe().
Return type:: float

class cudaq.AsyncObserveResult¶

A data-type containing the results of a call to observe_async(). The AsyncObserveResult contains a future, whose ObserveResult may be returned via an invocation of the get method. This kicks off a wait on the current thread until the results are available. See future for more information on this programming pattern.

get()¶

get(self: _pycudaq.AsyncObserveResult) -> _pycudaq.ObserveResult

Return the ObserveResult from the asynchronous observe execution.

class cudaq.OptimizationResult¶

Optimizers¶

class cudaq.optimizers.GradientDescent¶

property initial_parameters¶: Set the initial parameter values for the optimization.

property lower_bounds¶: Set the lower value bound for the optimization parameters.

property max_iterations¶: Set the maximum number of optimizer iterations.

optimize()¶

optimize(self: _pycudaq.optimizers.GradientDescent, dimensions: int, function: function) -> Tuple[float, List[float]]

Run cudaq.optimize() on the provided objective function.

property upper_bounds¶: Set the upper value bound for the optimization parameters.

class cudaq.optimizers.COBYLA¶

property initial_parameters¶: Set the initial parameter values for the optimization.

property lower_bounds¶: Set the lower value bound for the optimization parameters.

property max_iterations¶: Set the maximum number of optimizer iterations.

optimize()¶

optimize(self: _pycudaq.optimizers.COBYLA, dimensions: int, function: function) -> Tuple[float, List[float]]

Run cudaq.optimize() on the provided objective function.

property upper_bounds¶: Set the upper value bound for the optimization parameters.

class cudaq.optimizers.NelderMead¶

property initial_parameters¶: Set the initial parameter values for the optimization.

property lower_bounds¶: Set the lower value bound for the optimization parameters.

property max_iterations¶: Set the maximum number of optimizer iterations.

optimize()¶

optimize(self: _pycudaq.optimizers.NelderMead, dimensions: int, function: function) -> Tuple[float, List[float]]

Run cudaq.optimize() on the provided objective function.

property upper_bounds¶: Set the upper value bound for the optimization parameters.

class cudaq.optimizers.LBFGS¶

property initial_parameters¶: Set the initial parameter values for the optimization.

property lower_bounds¶: Set the lower value bound for the optimization parameters.

property max_iterations¶: Set the maximum number of optimizer iterations.

optimize()¶

optimize(self: _pycudaq.optimizers.LBFGS, dimensions: int, function: function) -> Tuple[float, List[float]]

Run cudaq.optimize() on the provided objective function.

property upper_bounds¶: Set the upper value bound for the optimization parameters.

Gradients¶

class cudaq.gradients.gradient¶

class cudaq.gradients.CentralDifference¶

compute()¶

compute(self: _pycudaq.gradients.gradient, parameter_vector: List[float], function: function) -> List[float]

class cudaq.gradients.ParameterShift¶

compute()¶

compute(self: _pycudaq.gradients.gradient, parameter_vector: List[float], function: function) -> List[float]

Noisy Simulation¶

class cudaq.NoiseModel¶

The cudaq NoiseModel defines a set of KrausChannels applied to specific qubits after the invocation specified quantum operations.

__init__()¶

__init__(self: _pycudaq.NoiseModel) -> None

Construct an empty noise model.

add_channel()¶

add_channel(self: _pycudaq.NoiseModel, arg0: str, arg1: List[int], arg2: _pycudaq.KrausChannel) -> None

Add the given KrausChannel to be applied after invocation of the specified quantum operation.

get_channels()¶

get_channels(self: _pycudaq.NoiseModel, arg0: str, arg1: List[int]) -> List[_pycudaq.KrausChannel]

Return the KrausChannels that make up this noise model.

class cudaq.BitFlipChannel¶

class cudaq.PhaseFlipChannel¶

class cudaq.DepolarizationChannel¶

class cudaq.AmplitudeDampingChannel¶

class cudaq.KrausChannel¶

The KrausChannel is composed of a list of KrausOperators and is applied to a specific qubit or set of qubits.

__getitem__()¶

__getitem__(self: _pycudaq.KrausChannel, arg0: int) -> _pycudaq.KrausOperator

Return the ith KrausOperator in this KrausChannel.

append()¶

append(self: _pycudaq.KrausChannel, arg0: _pycudaq.KrausOperator) -> None

Add a KrausOperator to this KrausChannel.

class cudaq.KrausOperator¶

The KrausOperator is represented by a matrix and serves as an element of a quantum channel such that Sum Ki Ki^dag = I.

property col_count¶: The number of columns in the matrix representation of this KrausOperator

property row_count¶: The number of rows in the matrix representation of this KrausOperator