CUDA Quantum Python API¶

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: cudaq._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: cudaq._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: cudaq._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: cudaq._pycudaq.Kernel) -> str

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

__call__()¶

__call__(self: cudaq._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: cudaq._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: cudaq._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: cudaq._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: cudaq._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: cudaq._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: cudaq._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: cudaq._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: cudaq._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: cudaq._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: cudaq._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: cudaq._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: cudaq._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: cudaq._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)

sdg()¶

sdg(self: cudaq._pycudaq.Kernel, arg0: cudaq::QuakeValue) -> None

Apply a rotation on the z-axis of -90 degrees to the given target qubit/s.

cs(*args, **kwargs)¶

Overloaded function.

cs(self: cudaq._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: cudaq._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: cudaq._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)

tdg()¶

tdg(self: cudaq._pycudaq.Kernel, arg0: cudaq::QuakeValue) -> None

Apply a rotation on the z-axis of -45 degrees to the given target qubit/s.

ct(*args, **kwargs)¶

Overloaded function.

ct(self: cudaq._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: cudaq._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: cudaq._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: cudaq._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: cudaq._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: cudaq._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: cudaq._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: cudaq._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)

r1(*args, **kwargs)¶

Overloaded function.

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

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

Parameters:

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

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

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

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

Parameters:

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

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

swap()¶

swap(self: cudaq._pycudaq.Kernel, first: cudaq::QuakeValue, second: cudaq::QuakeValue) -> None

Swap the states of the provided qubits.

# Example:
kernel = cudaq.make_kernel()
# Allocate qubit/s to the `kernel`.
qubits = kernel.qalloc(2)
# Place the 0th qubit in the 1-state.
kernel.x(qubits[0])

# Swap their states.
kernel.swap(qubits[0], qubits[1])

mx()¶

mx(self: cudaq._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: cudaq._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: cudaq._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: cudaq._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: cudaq._pycudaq.Kernel, target: cudaq._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: cudaq._pycudaq.Kernel, target: cudaq._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: cudaq._pycudaq.Kernel, target: cudaq._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: cudaq._pycudaq.Kernel, *args, shots_count: int = 1000, noise_model: Optional[cudaq._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: cudaq._pycudaq.Kernel, *args, shots_count: int = 1000, qpu_id: int = 0) -> cudaq._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: cudaq._pycudaq.Kernel, spin_operator: cudaq::spin_op, *args, shots_count: int = -1, noise_model: Optional[cudaq::noise_model] = None, execution: Optional[type] = None) -> 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.
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 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: cudaq._pycudaq.Kernel, spin_operator: cudaq::spin_op, *args, qpu_id: int = 0, shots_count: int = -1, noise_model: Optional[cudaq::noise_model] = None) -> 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.
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 future containing the result of the call to observe.

Return type:

AsyncObserveResult

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

Overloaded function.

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

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

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

vqe(kernel: cudaq._pycudaq.Kernel, gradient_strategy: cudaq._pycudaq.gradients.gradient, spin_operator: cudaq._pycudaq.SpinOperator, optimizer: cudaq._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_target(*args, **kwargs)¶

Overloaded function.

set_target(arg0: cudaq._pycudaq.Target, **kwargs) -> None

Set the cudaq.Target to be used for CUDA Quantum kernel execution. Can provide optional, target-specific configuration data via Python kwargs.

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

Set the cudaq.Target with given name to be used for CUDA Quantum kernel execution. Can provide optional, target-specific configuration data via Python kwargs.

cudaq.has_target()¶

has_target(arg0: str) -> bool

Return true if the cudaq.Target with the given name exists.

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

Overloaded function.

get_target(arg0: str) -> cudaq._pycudaq.Target

Return the cudaq.Target with the given name. Will raise an exception if the name is not valid.

```
get_target() -> cudaq._pycudaq.Target
```

Return the cudaq.Target with the given name. Will raise an exception if the name is not valid.

cudaq.get_targets()¶

get_targets() -> List[cudaq._pycudaq.Target]

Return all available cudaq.Target instances on the current system.

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: cudaq._pycudaq.QuakeValue, other: float) -> cudaq._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: cudaq._pycudaq.QuakeValue, other: cudaq._pycudaq.QuakeValue) -> cudaq._pycudaq.QuakeValue

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

Raises:: RuntimeError – if the underlying QuakeValue type is not the same type as self.

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

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

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

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

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

__radd__()¶

__radd__(self: cudaq._pycudaq.QuakeValue, other: float) -> cudaq._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: cudaq._pycudaq.QuakeValue, other: float) -> cudaq._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: cudaq._pycudaq.QuakeValue, other: cudaq._pycudaq.QuakeValue) -> cudaq._pycudaq.QuakeValue

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

Raises:: RuntimeError – if the underlying QuakeValue type is not the same type as self.

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

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

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

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

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

__rsub__()¶

__rsub__(self: cudaq._pycudaq.QuakeValue, other: float) -> cudaq._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: cudaq._pycudaq.QuakeValue) -> cudaq._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: cudaq._pycudaq.QuakeValue, other: float) -> cudaq._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: cudaq._pycudaq.QuakeValue, other: cudaq._pycudaq.QuakeValue) -> cudaq._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: cudaq._pycudaq.QuakeValue, other: float) -> cudaq._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__(*args, **kwargs)¶

Overloaded function.

__getitem__(self: cudaq._pycudaq.QuakeValue, index: int) -> cudaq._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.

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

Return the element of self at the provided index.

Note

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

Parameters:: index (QuakeValue) – 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.

slice()¶

slice(self: cudaq._pycudaq.QuakeValue, start: int, count: int) -> cudaq._pycudaq.QuakeValue

Return a slice of the given QuakeValue as a new QuakeValue.

Note:
The underlying QuakeValue must be a list or veq.

Args:
start (int) : The index to begin the slice from. count (int) : The number of elements to extract after the start index.

Returns:

QuakeValueA new QuakeValue containing a slice of self from
the start-th element to start + count-th element.

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.ComplexMatrix¶

The ComplexMatrix is a thin wrapper around a matrix of complex<double> elements.

__getitem__()¶

__getitem__(self: cudaq._pycudaq.ComplexMatrix, arg0: int, arg1: int) -> complex

Return the matrix element at i, j.

__str__()¶

__str__(self: cudaq._pycudaq.ComplexMatrix) -> str

Write this matrix to a string representation.

minimal_eigenvalue()¶

minimal_eigenvalue(self: cudaq._pycudaq.ComplexMatrix) -> complex

Return the lowest eigenvalue for this ComplexMatrix.

class cudaq.SpinOperator¶

__eq__()¶

__eq__(self: cudaq._pycudaq.SpinOperator, arg0: cudaq._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: cudaq._pycudaq.SpinOperator, arg0: cudaq._pycudaq.SpinOperator) -> cudaq._pycudaq.SpinOperator

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

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

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

__radd__()¶

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

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

__sub__(*args, **kwargs)¶

Overloaded function.

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

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

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

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

__rsub__()¶

__rsub__(self: cudaq._pycudaq.SpinOperator, arg0: float) -> cudaq._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: cudaq._pycudaq.SpinOperator, arg0: cudaq._pycudaq.SpinOperator) -> cudaq._pycudaq.SpinOperator

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

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

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

__mul__(self: cudaq._pycudaq.SpinOperator, arg0: complex) -> cudaq._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: cudaq._pycudaq.SpinOperator, arg0: float) -> cudaq._pycudaq.SpinOperator

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

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

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

__iter__()¶

__iter__(self: cudaq._pycudaq.SpinOperator) -> Iterator

distribute_terms()¶

distribute_terms(self: cudaq._pycudaq.SpinOperator, arg0: int) -> List[cudaq._pycudaq.SpinOperator]

Return a list of SpinOperator representing a distribution of the terms in this SpinOperator into equally sized chunks.

dump()¶

dump(self: cudaq._pycudaq.SpinOperator) -> None

Print a string representation of this SpinOperator.

for_each_pauli()¶

for_each_pauli(self: cudaq._pycudaq.SpinOperator, arg0: function) -> None

For a single cudaq.SpinOperator term, apply the given function to each pauli element in the term. The function must have void(pauli, int) signature where pauli is the Pauli matrix type and the int is the qubit index.

for_each_term()¶

for_each_term(self: cudaq._pycudaq.SpinOperator, arg0: function) -> None

Apply the given function to all terms in this cudaq.SpinOperator. The input function must have void(SpinOperator) signature.

get_coefficient()¶

get_coefficient(self: cudaq._pycudaq.SpinOperator) -> complex

Return the coefficient of this SpinOperator. Must be a SpinOperator with one term, otherwise an exception is thrown.

get_qubit_count()¶

get_qubit_count(self: cudaq._pycudaq.SpinOperator) -> int

Return the number of qubits this SpinOperator is on.

get_raw_data()¶

get_raw_data(self: cudaq._pycudaq.SpinOperator) -> Tuple[List[List[bool]], List[complex]]

get_term_count()¶

get_term_count(self: cudaq._pycudaq.SpinOperator) -> int

Return the number of terms in this SpinOperator.

is_identity()¶

is_identity(self: cudaq._pycudaq.SpinOperator) -> bool

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

static random()¶

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

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

serialize()¶

serialize(self: cudaq._pycudaq.SpinOperator) -> List[float]

Return a serialized representation of the SpinOperator. Specifically, this encoding is via a vector of doubles. The encoding is as follows: for each term, a list of doubles where the ith element is a 3.0 for a Y, a 1.0 for a X, and a 2.0 for a Z on qubit i, followed by the real and imaginary part of the coefficient. Each term is appended to the array forming one large 1d array of doubles. The array is ended with the total number of terms represented as a double.

to_matrix()¶

to_matrix(self: cudaq._pycudaq.SpinOperator) -> cudaq._pycudaq.ComplexMatrix

Return self as a ComplexMatrix.

to_string()¶

to_string(self: cudaq._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: cudaq._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: cudaq._pycudaq.SampleResult) -> Iterator

Iterate through the SampleResult dictionary.

__len__()¶

__len__(self: cudaq._pycudaq.SampleResult) -> int

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

clear()¶

clear(self: cudaq._pycudaq.SampleResult) -> None

Clear out all metadata from self.

count()¶

count(self: cudaq._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: cudaq._pycudaq.SampleResult) -> None

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

expectation_z()¶

expectation_z(self: cudaq._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: cudaq._pycudaq.SampleResult, marginal_indices: List[int], *, register_name: str = '__global__') -> cudaq._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: cudaq._pycudaq.SampleResult, register_name: str) -> cudaq._pycudaq.SampleResult

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

get_sequential_data()¶

get_sequential_data(self: cudaq._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: cudaq._pycudaq.SampleResult) -> Iterator

Return the key/value pairs in this SampleResult dictionary.

most_probable()¶

most_probable(self: cudaq._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: cudaq._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: cudaq._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: cudaq._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: cudaq._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: cudaq._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: cudaq._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: cudaq._pycudaq.ObserveResult) -> float

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

expectation_z(self: cudaq._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: cudaq._pycudaq.AsyncObserveResult) -> cudaq._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: cudaq._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: cudaq._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: cudaq._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: cudaq._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: cudaq._pycudaq.gradients.gradient, parameter_vector: List[float], function: function, funcAtX: float) -> List[float]

class cudaq.gradients.ParameterShift¶

compute()¶

compute(self: cudaq._pycudaq.gradients.gradient, parameter_vector: List[float], function: function, funcAtX: float) -> 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: cudaq._pycudaq.NoiseModel) -> None

Construct an empty noise model.

add_channel()¶

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

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

get_channels()¶

get_channels(self: cudaq._pycudaq.NoiseModel, arg0: str, arg1: List[int]) -> List[cudaq._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: cudaq._pycudaq.KrausChannel, arg0: int) -> cudaq._pycudaq.KrausOperator

Return the KrausOperator at the given index in this KrausChannel.

append()¶

append(self: cudaq._pycudaq.KrausChannel, arg0: cudaq._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