CUDA-Q Python API¶

Program Construction¶

cudaq.make_kernel(*args)¶

Create a Kernel: An empty kernel function to be used for quantum program construction. This kernel is non-parameterized if it accepts no arguments, else takes the provided types as arguments.

Returns a kernel if it is non-parameterized, else a tuple containing the kernel and a QuakeValue for each kernel argument.

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

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

class cudaq.PyKernel(argTypeList)¶

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

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

cudaq.Kernel¶: alias of PyKernel

class cudaq.PyKernelDecorator(function, verbose=False, module=None, kernelName=None, funcSrc=None, signature=None, location=None, overrideGlobalScopedVars=None)¶

The PyKernelDecorator serves as a standard Python decorator that takes the decorated function as input and optionally lowers its AST representation to executable code via MLIR. This decorator enables full JIT compilation mode, where the function is lowered to an MLIR representation.

This decorator exposes a call overload that executes the code via the MLIR ExecutionEngine for the MLIR mode.

__call__(*args)¶: Invoke the CUDA-Q kernel. JIT compilation of the kernel AST to MLIR will occur here if it has not already occurred, except when the target requires custom handling.

__str__()¶: Return the MLIR Module string representation for this kernel.

compile()¶: Compile the Python function AST to MLIR. This is a no-op if the kernel is already compiled.

extract_c_function_pointer(name=None)¶: Return the C function pointer for the function with given name, or with the name of this kernel if not provided.

static from_json(jStr, overrideDict=None)¶: Convert a JSON string into a new PyKernelDecorator object.

merge_kernel(otherMod)¶: Merge the kernel in this PyKernelDecorator (the ModuleOp) with the provided ModuleOp.

synthesize_callable_arguments(funcNames)¶: Given this Kernel has callable block arguments, synthesize away these callable arguments with the in-module FuncOps with given names. The name at index 0 in the list corresponds to the first callable block argument, index 1 to the second callable block argument, etc.

to_json()¶: Convert self to a JSON-serialized version of the kernel such that from_json can reconstruct it elsewhere.

static type_to_str(t)¶: This converts types to strings in a clean JSON-compatible way. int -> ‘int’ list[float] -> ‘list[float]’ List[float] -> ‘list[float]’

cudaq.kernel(function=None, **kwargs)¶

The cudaq.kernel represents the CUDA-Q language function attribute that programmers leverage to indicate the following function is a CUDA-Q kernel and should be compile and executed on an available quantum coprocessor.

Verbose logging can be enabled via verbose=True.

Kernel Execution¶

cudaq.sample(kernel, *args, shots_count=1000, noise_model=None)¶

Sample the state generated by the provided kernel at the given kernel arguments over the specified number of circuit executions (shots_count). Each argument in arguments provided can be a list or ndarray of arguments of the specified kernel argument type, and in this case, the sample functionality will be broadcasted over all argument sets and a list of sample_result instances will be returned.

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. For example, if the kernel takes two float values as input, the sample call should be structured as cudaq.sample(kernel, firstFloat, secondFloat). For broadcasting of the sample function, the arguments should be structured as a list or ndarray of argument values of the specified kernel argument type.
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, or a list of such results in the case of sample function broadcasting.

Return type:

SampleResult or list[SampleResult]

cudaq.sample_async()¶

cudaq.sample_async(kernel: object, \*args, shots_count: int = 1000, qpu_id: int = 0) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.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(kernel, spin_operator, *args, shots_count=0, noise_model=None, execution=None)¶

Compute the expected value of the spin_operator with respect to the kernel. If the input spin_operator is a list of SpinOperator then compute the expected value of every operator in the list and return a list of results. If the kernel accepts arguments, it will be evaluated with respect to kernel(*arguments). Each argument in arguments provided can be a list or ndarray of arguments of the specified kernel argument type, and in this case, the observe functionality will be broadcasted over all argument sets and a list of observe_result instances will be returned. If both the input spin_operator and arguments are broadcast lists, a nested list of results over arguments then spin_operator will be returned.

Parameters:

kernel (Kernel) – The Kernel to evaluate the expectation value with respect to.
spin_operator (SpinOperator or list[SpinOperator]) – The Hermitian spin operator to calculate the expectation of, or a list of such operators.
*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 implying no shots-based sampling. 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), or a list of such results in the case of observe function broadcasting. If shots_count was provided, the ObserveResult will also contain a SampleResult dictionary.

Return type:

ObserveResult

cudaq.observe_async()¶

cudaq.observe_async(kernel: object, spin_operator: object, \*args, qpu_id: int = 0, shots_count: int = -1) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.AsyncObserveResult

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 implying no shots-based sampling. Key-word only.

Returns:

A future containing the result of the call to observe.

Return type:

AsyncObserveResult

cudaq.get_state()¶

cudaq.get_state(arg0: object, \*args) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.State

Return the State of the system after execution of the provided kernel.

Parameters:

kernel (Kernel) – The Kernel to execute 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.

# Example:
import numpy as np

# Define a kernel that will produced the all |11...1> state.
kernel = cudaq.make_kernel()
qubits = kernel.qalloc(3)
# Prepare qubits in the 1-state.
kernel.x(qubits)

# Get the state of the system. This will execute the provided kernel
# and, depending on the selected target, will return the state as a
# vector or matrix.
state = cudaq.get_state(kernel)
print(state)

cudaq.get_state_async()¶

cudaq.get_state_async(kernel: object, \*args, qpu_id: int = 0) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.AsyncStateResult

Asynchronously retrieve the state generated by the given quantum kernel. 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 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.
qpu_id (Optional[int]) – The optional identification for which QPU on the platform to target. Defaults to zero. Key-word only.

Returns:

Quantum state (state vector or density matrix) data).

Return type:

AsyncStateResult

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

Overloaded function.

cudaq.vqe(kernel: object, spin_operator: object, optimizer: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.optimizers.optimizer, parameter_count: int, shots: int = -1) → tuple[float, list[float]]
cudaq.vqe(kernel: object, spin_operator: object, optimizer: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.optimizers.optimizer, parameter_count: int, argument_mapper: Callable, shots: int = -1) → tuple[float, list[float]]
cudaq.vqe(kernel: object, gradient_strategy: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.gradients.gradient, spin_operator: object, optimizer: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.optimizers.optimizer, parameter_count: int, shots: int = -1) → tuple[float, list[float]]
cudaq.vqe(kernel: object, gradient_strategy: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.gradients.gradient, spin_operator: object, optimizer: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.optimizers.optimizer, parameter_count: int, argument_mapper: Callable, shots: int = -1) → tuple[float, list[float]]

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

Overloaded function.

cudaq.draw(arg0: str, arg1: object, \*args) → str

Return a string representing the drawing of the execution path, in the format specified as the first argument. If the format is ‘ascii’, the output will be a UTF-8 encoded string. If the format is ‘latex’, the output will be a LaTeX string.

Parameters:

format (str) – The format of the output. Can be ‘ascii’ or ‘latex’.
kernel (Kernel) – The Kernel to draw.
*arguments (Optional[Any]) – The concrete values to evaluate the kernel function at. Leave empty if the kernel doesn’t accept any arguments.

cudaq.draw(arg0: object, \*args) → str

Return a UTF-8 encoded string representing drawing of the execution path, i.e., the trace, of the provided kernel.

Parameters:

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

Returns:

The UTF-8 encoded string of the circuit, without measurement operations.

# Example
import cudaq
@cudaq.kernel
def bell_pair():
    q = cudaq.qvector(2)
    h(q[0])
    cx(q[0], q[1])
    mz(q)
print(cudaq.draw(bell_pair))
# Output
#      ╭───╮
# q0 : ┤ h ├──●──
#      ╰───╯╭─┴─╮
# q1 : ─────┤ x ├
#           ╰───╯

# Example with arguments
import cudaq
@cudaq.kernel
def kernel(angle:float):
    q = cudaq.qubit()
    h(q)
    ry(angle, q)
print(cudaq.draw(kernel, 0.59))
# Output
#      ╭───╮╭──────────╮
# q0 : ┤ h ├┤ ry(0.59) ├
#      ╰───╯╰──────────╯

cudaq.translate()¶

cudaq.translate(kernel: object, \*args, format: str = 'qir') → str

Return a UTF-8 encoded string representing drawing of the execution path, i.e., the trace, of the provided kernel.

Parameters:

format (str) – format to translate to. Available formats: qir, qir-base, qir-adaptive, openqasm2.
kernel (Kernel) – The Kernel to translate.
*arguments (Optional[Any]) – The concrete values to evaluate the kernel function at. Leave empty if the kernel doesn’t accept any arguments.
Note – Translating functions with arguments to OpenQASM 2.0 is not supported.

Returns:

The UTF-8 encoded string of the circuit, without measurement operations.

# Example
import cudaq
@cudaq.kernel
def bell_pair():
    q = cudaq.qvector(2)
    h(q[0])
    cx(q[0], q[1])
    mz(q)
print(cudaq.translate(bell_pair, format="qir"))

# Output
; ModuleID = 'LLVMDialectModule'
source_filename = 'LLVMDialectModule'

%Array = type opaque
%Result = type opaque
%Qubit = type opaque

...
...

define void @__nvqpp__mlirgen__function_variable_qreg._Z13variable_qregv() local_unnamed_addr {
  %1 = tail call %Array* @__quantum__rt__qubit_allocate_array(i64 2)
  ...
  %8 = tail call %Result* @__quantum__qis__mz(%Qubit* %4)
  %9 = tail call %Result* @__quantum__qis__mz(%Qubit* %7)
  tail call void @__quantum__rt__qubit_release_array(%Array* %1)
  ret void
}

Dynamics¶

Computes the time evolution of one or more initial state(s) under the defined operator(s).

Parameters:

hamiltonian – Operator that describes the behavior of a quantum system without noise.
dimensions – A mapping that specifies the number of levels, that is the dimension, of each degree of freedom that any of the operator arguments acts on.
schedule – A sequence that generates a mapping of keyword arguments to their respective value. The keyword arguments are the parameters needed to evaluate any of the operators passed to evolve. All required parameters for evaluating an operator and their documentation, if available, can be queried by accessing the parameter property of the operator.
initial_state – A single state or a sequence of states of a quantum system.
collapse_operators – A sequence of operators that describe the influence of noise on the quantum system.
observables – A sequence of operators for which to compute their expectation value during evolution. If store_intermediate_results is set to True, the expectation values are computed after each step in the schedule, and otherwise only the final expectation values at the end of the evolution are computed.
shots_count – Optional integer, if provided, it is the number of shots to use for QPU execution.

Returns:

A single evolution result if a single initial state is provided, or a sequence of evolution results representing the data computed during the evolution of each initial state. See EvolveResult for more information about the data computed during evolution.

Asynchronously computes the time evolution of one or more initial state(s) under the defined operator(s). See cudaq.evolve for more details about the parameters passed here.

Returns:: The handle to a single evolution result if a single initial state is provided, or a sequence of handles to the evolution results representing the data computed during the evolution of each initial state. See the EvolveResult for more information about the data computed during evolution.

Backend Configuration¶

cudaq.has_target()¶

cudaq.has_target(arg0: str) → bool

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

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

Overloaded function.

cudaq.get_target(arg0: str) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.Target

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

cudaq.get_target() → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.Target

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

cudaq.get_targets()¶

cudaq.get_targets() → list[cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.Target]

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

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

Overloaded function.

cudaq.set_target(arg0: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.Target, \*\*kwargs) → None

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

cudaq.set_target(arg0: str, \*\*kwargs) → None

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

cudaq.reset_target()¶

cudaq.reset_target() → None

Reset the current cudaq.Target to the default.

cudaq.set_noise()¶

cudaq.set_noise(arg0: cudaq.NoiseModel) → None

Set the underlying noise model.

cudaq.unset_noise()¶

cudaq.unset_noise() → None

Clear backend simulation from any existing noise models.

cudaq.initialize_cudaq()¶

cudaq.initialize_cudaq(\*\*kwargs) → None

Initialize the CUDA-Q environment.

cudaq.num_available_gpus()¶

cudaq.num_available_gpus() → int

The number of available GPUs detected on the system.

cudaq.set_random_seed()¶

cudaq.set_random_seed(arg0: int) → None

Provide the seed for backend quantum kernel simulation.

Data Types¶

class cudaq.SimulationPrecision¶

Enumeration describing the precision of the underyling simulation.

Members:

fp32

fp64

property name¶

object) -> str :noindex:

Type:

name(self

class cudaq.Target¶

The cudaq.Target represents the underlying infrastructure that CUDA-Q kernels will execute on. Instances of cudaq.Target describe what simulator they may leverage, the quantum_platform required for execution, and a description for the target.

property description¶: A string describing the features for this cudaq.Target.

get_precision()¶

get_precision(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.Target) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.SimulationPrecision

Return the simulation precision for the current target.

is_emulated()¶

is_emulated(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.Target) → bool

Returns true if the emulation mode for the target has been activated.

is_remote()¶

is_remote(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.Target) → bool

Returns true if the target consists of a remote REST QPU.

property name¶: The name of the cudaq.Target.

num_qpus()¶

num_qpus(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.Target) → int

Return the number of QPUs available in this cudaq.Target.

property platform¶: The name of the quantum_platform implementation this cudaq.Target leverages.

property simulator¶: The name of the simulator this cudaq.Target leverages. This will be empty for physical QPUs.

class cudaq.State¶

A data-type representing the quantum state of the internal simulator. This type is not user-constructible and instances can only be retrieved via the cudaq.get_state(...) function or the static cudaq.State.from_data() method.

amplitude(*args, **kwargs)¶

Overloaded function.

amplitude(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.State, arg0: list[int]) → complex

Return the amplitude of a state in computational basis.

# Example:
# Create a simulation state.
state = cudaq.get_state(kernel)
# Return the amplitude of |0101>, assuming this is a 4-qubit state.
amplitude = state.amplitude([0,1,0,1])

amplitude(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.State, arg0: str) → complex

Return the amplitude of a state in computational basis.

# Example:
# Create a simulation state.
state = cudaq.get_state(kernel)
# Return the amplitude of |0101>, assuming this is a 4-qubit state.
amplitude = state.amplitude('0101')

amplitudes(*args, **kwargs)¶

Overloaded function.

amplitudes(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.State, arg0: list[list[int]]) → list[complex]

Return the amplitude of a list of states in computational basis.

# Example:
# Create a simulation state.
state = cudaq.get_state(kernel)
# Return the amplitude of |0101> and |1010>, assuming this is a 4-qubit state.
amplitudes = state.amplitudes([[0,1,0,1], [1,0,1,0]])

amplitudes(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.State, arg0: list[str]) → list[complex]

Return the amplitudes of a list of states in computational basis.

# Example:
# Create a simulation state.
state = cudaq.get_state(kernel)
# Return the amplitudes of |0101> and |1010>, assuming this is a 4-qubit state.
amplitudes = state.amplitudes(['0101', '1010'])

dump()¶

dump(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.State) → None

Print the state to the console.

static from_data(*args, **kwargs)¶

Overloaded function.

from_data(arg0: numpy.ndarray) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.State

Return a state from data.

from_data(arg0: list[numpy.ndarray]) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.State

Return a state from matrix product state tensor data.

from_data(arg0: list[cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.Tensor]) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.State

Return a state from matrix product state tensor data.

from_data(arg0: list) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.State

Return a state from matrix product state tensor data (as CuPy ndarray).

from_data(arg0: object) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.State

Return a state from CuPy device array.

getTensor()¶

getTensor(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.State, idx: int = 0) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.Tensor

Return the idx tensor making up this state representation.

getTensors()¶

getTensors(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.State) → list[cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.Tensor]

Return all the tensors that comprise this state representation.

is_on_gpu()¶

is_on_gpu(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.State) → bool

Return True if this state is on the GPU.

num_qubits()¶

num_qubits(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.State) → int

Returns the number of qubits represented by this state.

overlap(*args, **kwargs)¶

Overloaded function.

overlap(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.State, arg0: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.State) → complex

Compute the overlap between the provided State’s.

overlap(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.State, arg0: numpy.ndarray) → complex

Compute the overlap between the provided State’s.

overlap(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.State, arg0: object) → complex

Compute overlap with general CuPy device array.

class cudaq.Tensor¶: The Tensor describes a pointer to simulation data as well as the rank and extents for that tensorial data it represents.

class cudaq.QuakeValue(mlirValue, pyKernel, size=None)¶

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 qvector. The QuakeValue can also hold kernel operations such as qubit allocations and measurements.

__add__(other)¶

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

__radd__(other)¶

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__(other)¶

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

__rsub__(other)¶

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__()¶

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__(other)¶

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

__rmul__(other)¶

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__(idx)¶

Return the element of self at the provided index.

Note

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

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

slice(startIdx, count)¶

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

Note

The underlying QuakeValue must be a list or veq.

Parameters:

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

Returns:

A new QuakeValue containing a slice of self from the start element to the start + count element.

Return type:

QuakeValue

class cudaq.qubit¶: The qubit is the primary unit of information in a quantum computer. Qubits can be created individually or as part of larger registers.

cudaq.qreg¶: alias of qvector

class cudaq.qvector¶: An owning, dynamically sized container for qubits. The semantics of the qvector follows that of a std::vector or list for qubits.

class cudaq.ComplexMatrix¶

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

__getitem__(*args, **kwargs)¶

Overloaded function.

__getitem__(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.ComplexMatrix, arg0: int, arg1: int) → complex

Return the matrix element at i, j.

__getitem__(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.ComplexMatrix, arg0: tuple[int, int]) → complex

Return the matrix element at i, j.

__str__()¶

__str__(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.ComplexMatrix) → str

Write this matrix to a string representation.

minimal_eigenvalue()¶

minimal_eigenvalue(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.ComplexMatrix) → complex

Return the lowest eigenvalue for this ComplexMatrix.

num_columns()¶

num_columns(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.ComplexMatrix) → int

Returns the number of columns in the matrix.

num_rows()¶

num_rows(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.ComplexMatrix) → int

Returns the number of rows in the matrix.

class cudaq.Schedule(steps: Iterable[Any], parameters: Iterable[str], get_value: Optional[Callable[[str, Any], numpy.complexfloating | complex | float | int]] = None)¶: Represents an iterator that produces all values needed for evaluating an operator expression at different time steps.

class cudaq.operator.integrator.BaseIntegrator(**kwargs)¶: An abstract wrapper around ODE integrator to ensure a common interface for master equation solver usage.

class cudaq.EvolveResult¶

Stores the execution data from an invocation of evolve().

expectation_values()¶

expectation_values(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.EvolveResult) → Optional[list[list[cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.ObserveResult]]]

Stores the expectation values, that is the results from the calls to observe(), at each step in the schedule produced by a call to evolve(), including the final expectation values. Each entry corresponds to one observable provided in the evolve() call. This property is only populated saving intermediate results was requested in the call to evolve(). This value will be None if no intermediate results were requested, or if no observables were specified in the call.

final_expectation_values()¶

final_expectation_values(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.EvolveResult) → Optional[list[cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.ObserveResult]]

Stores the final expectation values, that is the results produced by calls to observe(), triggered by a call to evolve(). Each entry corresponds to one observable provided in the evolve() call. This value will be None if no observables were specified in the call.

final_state()¶

final_state(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.EvolveResult) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.State

Stores the final state produced by a call to evolve(). Represent the state of a quantum system after time evolution under a set of operators, see the evolve() documentation for more detail.

intermediate_states()¶

intermediate_states(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.EvolveResult) → Optional[list[cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.State]]

Stores all intermediate states, meaning the state after each step in a defined schedule, produced by a call to evolve(), including the final state. This property is only populated if saving intermediate results was requested in the call to evolve().

class cudaq.AsyncEvolveResult¶

Stores the execution data from an invocation of evolve_async().

get()¶

get(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.AsyncEvolveResult) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.EvolveResult

Retrieve the evolution result from the asynchronous evolve execution .

class cudaq.SpinOperator(*args, **kwargs)¶

class cudaq.operator.expressions.OperatorSum(terms: Iterable[ProductOperator] = [])¶

Represents an operator expression consisting of a sum of terms, where each term is a product of elementary and scalar operators.

Operator expressions cannot be used within quantum kernels, but they provide methods to convert them to data types that can.

class cudaq.operator.expressions.ElementaryOperator(operator_id: str, degrees: Iterable[int])¶

Represents an elementary operator that acts on one or more degrees of freedom, and cannot be further simplified to be the product or sum of other operators. An elementary operator is defined as a function of zero or more complex-valued parameters using the ElementaryOperator.define() class method.

Operator expressions cannot be used within quantum kernels, but they provide methods to convert them to data types that can.

classmethod define(op_id: str, expected_dimensions: Sequence[int], create: Callable[[...], ndarray[Any, dtype[complexfloating]]]) → None¶

Adds the definition of an elementary operator with the given id to the class. After definition, an the defined elementary operator can be instantiated by providing the operator id as well as the degree(s) of freedom that it acts on.

An elementary operator is a parameterized object acting on certain degrees of freedom. To evaluate an operator, for example to compute its matrix, the level, that is the dimension, for each degree of freedom it acts on must be provided, as well as all additional parameters. Additional parameters must be provided in the form of keyword arguments.

Note: The dimensions passed during operator evaluation are automatically validated against the expected dimensions specified during definition - the create function does not need to do this.

Parameters:

op_id – A string that uniquely identifies the defined operator.
expected_dimensions – defines the number of levels, that is the dimension, for each degree of freedom in canonical (that is sorted) order. A negative or zero value for one (or more) of the expected dimensions indicates that the operator is defined for any dimension of the corresponding degree of freedom.
create – Takes any number of complex-valued arguments and returns the matrix representing the operator in canonical order. If the matrix can be defined for any number of levels for one or more degree of freedom, the create function must take an argument called dimension (or dim for short), if the operator acts on a single degree of freedom, and an argument called dimensions (or dims for short), if the operator acts on multiple degrees of freedom.

class cudaq.operator.expressions.ProductOperator(atomic_operators: Iterable[cudaq.operator.expressions.ElementaryOperator | cudaq.operator.expressions.ScalarOperator] = [])¶

Represents an operator expression consisting of a product of elementary and scalar operators.

Operator expressions cannot be used within quantum kernels, but they provide methods to convert them to data types that can.

class cudaq.operator.expressions.RydbergHamiltonian(atom_sites: Iterable[tuple[float, float]], amplitude: ScalarOperator, phase: ScalarOperator, delta_global: ScalarOperator, atom_filling: Optional[Iterable[int]] = [], delta_local: Optional[tuple[cudaq.operator.expressions.ScalarOperator, Iterable[float]]] = None)¶

Representation for the time-dependent Hamiltonian which is simulated by QuEra’s Aquila machine. Ref: https://docs.aws.amazon.com/braket/latest/developerguide/braket-quera-submitting-analog-program-aquila.html#braket-quera-ahs-program-schema

__init__(atom_sites: Iterable[tuple[float, float]], amplitude: ScalarOperator, phase: ScalarOperator, delta_global: ScalarOperator, atom_filling: Optional[Iterable[int]] = [], delta_local: Optional[tuple[cudaq.operator.expressions.ScalarOperator, Iterable[float]]] = None)¶

Instantiate an operator consumable by evolve API using the supplied parameters.

Parameters:

atom_sites – List of 2-d coordinates where the tweezers trap atoms.
amplitude – time and value points of driving amplitude, Omega(t).
phase – time and value points of driving phase, phi(t).
delta_global – time and value points of driving detuning, Delta_global(t).
atom_filling – Optional. Marks atoms that occupy the trap sites with 1, and empty sites with 0. If not provided, all are set to 1, i.e. filled.
delta_local – Optional. A tuple of time and value points of the time-dependent factor of the local detuning magnitude, Delta_local(t), and site-dependent factor of the local detuning magnitude, h_k, a dimensionless number between 0.0 and 1.0

class cudaq.operator.expressions.ScalarOperator(generator: Callable[[...], numpy.complexfloating | complex | float | int], parameter_info: Optional[Callable[[], Mapping[str, str]]] = None)¶

Represents a scalar operator defined as a function of zero or more complex-valued parameters.

Operator expressions cannot be used within quantum kernels, but they provide methods to convert them to data types that can.

class cudaq.operator.definitions.SpinOperator(*args, **kwargs)¶

spin.i(target: int) → ElementaryOperator¶

spin.x(target: int) → ElementaryOperator¶

spin.y(target: int) → ElementaryOperator¶

spin.z(target: int) → ElementaryOperator¶

class cudaq.operator.cudm_state.CuDensityMatState(data)¶

cudaq.operator.cudm_state.to_cupy_array(state)¶

cudaq.operator.cudm_state.coherent_state(N: int, alpha: float)¶

cudaq.operator.cudm_state.coherent_dm(N: int, alpha: float)¶

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.mlir._mlir_libs._quakeDialects.cudaq_runtime.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.mlir._mlir_libs._quakeDialects.cudaq_runtime.SampleResult) → Iterator[str]

Iterate through the SampleResult dictionary.

__len__()¶

__len__(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.SampleResult) → int

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

clear()¶

clear(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.SampleResult) → None

Clear out all metadata from self.

count()¶

count(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.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

deserialize()¶

deserialize(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.SampleResult, arg0: list[int]) → None

Deserialize this SampleResult from an existing vector of integers adhering to the implicit encoding.

dump()¶

dump(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.SampleResult) → None

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

expectation()¶

expectation(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.SampleResult, register_name: str = '__global__') → float

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

expectation_z()¶

expectation_z(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.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.mlir._mlir_libs._quakeDialects.cudaq_runtime.SampleResult, marginal_indices: list[int], \*, register_name: str = '__global__') → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.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.mlir._mlir_libs._quakeDialects.cudaq_runtime.SampleResult, register_name: str) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.SampleResult

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

get_sequential_data()¶

get_sequential_data(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.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.mlir._mlir_libs._quakeDialects.cudaq_runtime.SampleResult) → Iterator[tuple[str, int]]

Return the key/value pairs in this SampleResult dictionary.

most_probable()¶

most_probable(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.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.mlir._mlir_libs._quakeDialects.cudaq_runtime.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

serialize()¶

serialize(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.SampleResult) → list[int]

Serialize this SampleResult to a vector of integer encoding.

values()¶

values(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.SampleResult) → Iterator[int]

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 models a future-like type, 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.mlir._mlir_libs._quakeDialects.cudaq_runtime.AsyncSampleResult) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.SampleResult

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.mlir._mlir_libs._quakeDialects.cudaq_runtime.ObserveResult) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.SampleResult

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.mlir._mlir_libs._quakeDialects.cudaq_runtime.ObserveResult, sub_term: cudaq.SpinOperator) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.SampleResult

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

counts(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.ObserveResult, sub_term: object) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.SampleResult

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.mlir._mlir_libs._quakeDialects.cudaq_runtime.ObserveResult) → None

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

expectation(*args, **kwargs)¶

Overloaded function.

expectation(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.ObserveResult) → float

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

expectation(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.ObserveResult, sub_term: object) → 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

expectation_z(*args, **kwargs)¶

Overloaded function.

expectation_z(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.ObserveResult) → float

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

Note

expectation_z has been deprecated in favor of expectation.

expectation_z(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.ObserveResult, sub_term: object) → float

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

Note

expectation_z has been deprecated in favor of expectation.

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

get_spin()¶

get_spin(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.ObserveResult) → cudaq.SpinOperator

Return the SpinOperator corresponding to this ObserveResult.

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.mlir._mlir_libs._quakeDialects.cudaq_runtime.AsyncObserveResult) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.ObserveResult

Returns the ObserveResult from the asynchronous observe execution.

class cudaq.AsyncStateResult¶

A data-type containing the results of a call to get_state_async(). The AsyncStateResult models a future-like type, whose State 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.mlir._mlir_libs._quakeDialects.cudaq_runtime.AsyncStateResult) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.State

Return the State from the asynchronous get_state accessor execution.

class cudaq.OptimizationResult¶

Optimizers¶

class cudaq.optimizers.optimizer¶

class cudaq.optimizers.GradientDescent¶

static from_json()¶

from_json(arg0: str) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.optimizers.GradientDescent

Convert JSON string to optimizer

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.mlir._mlir_libs._quakeDialects.cudaq_runtime.optimizers.GradientDescent, dimensions: int, function: Callable) → tuple[float, list[float]]

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

requires_gradients()¶

requires_gradients(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.optimizers.GradientDescent) → bool

Returns whether the optimizer requires gradient.

to_json()¶

to_json(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.optimizers.GradientDescent) → str

Convert optimizer to JSON string

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

class cudaq.optimizers.COBYLA¶

static from_json()¶

from_json(arg0: str) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.optimizers.COBYLA

Convert JSON string to optimizer

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.mlir._mlir_libs._quakeDialects.cudaq_runtime.optimizers.COBYLA, dimensions: int, function: Callable) → tuple[float, list[float]]

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

requires_gradients()¶

requires_gradients(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.optimizers.COBYLA) → bool

Returns whether the optimizer requires gradient.

to_json()¶

to_json(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.optimizers.COBYLA) → str

Convert optimizer to JSON string

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

class cudaq.optimizers.NelderMead¶

static from_json()¶

from_json(arg0: str) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.optimizers.NelderMead

Convert JSON string to optimizer

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.mlir._mlir_libs._quakeDialects.cudaq_runtime.optimizers.NelderMead, dimensions: int, function: Callable) → tuple[float, list[float]]

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

requires_gradients()¶

requires_gradients(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.optimizers.NelderMead) → bool

Returns whether the optimizer requires gradient.

to_json()¶

to_json(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.optimizers.NelderMead) → str

Convert optimizer to JSON string

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

class cudaq.optimizers.LBFGS¶

static from_json()¶

from_json(arg0: str) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.optimizers.LBFGS

Convert JSON string to optimizer

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.mlir._mlir_libs._quakeDialects.cudaq_runtime.optimizers.LBFGS, dimensions: int, function: Callable) → tuple[float, list[float]]

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

requires_gradients()¶

requires_gradients(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.optimizers.LBFGS) → bool

Returns whether the optimizer requires gradient.

to_json()¶

to_json(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.optimizers.LBFGS) → str

Convert optimizer to JSON string

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.mlir._mlir_libs._quakeDialects.cudaq_runtime.gradients.gradient, parameter_vector: list[float], function: Callable, funcAtX: float) → list[float]

Compute the gradient of the provided parameter_vector with respect to its loss function, using the CentralDifference method.

static from_json()¶

from_json(arg0: str) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.gradients.CentralDifference

Convert JSON string to gradient

to_json()¶

to_json(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.gradients.CentralDifference) → str

Convert gradient to JSON string

class cudaq.gradients.ForwardDifference¶

compute()¶

compute(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.gradients.gradient, parameter_vector: list[float], function: Callable, funcAtX: float) → list[float]

Compute the gradient of the provided parameter_vector with respect to its loss function, using the ForwardDifference method.

static from_json()¶

from_json(arg0: str) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.gradients.ForwardDifference

Convert JSON string to gradient

to_json()¶

to_json(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.gradients.ForwardDifference) → str

Convert gradient to JSON string

class cudaq.gradients.ParameterShift¶

compute()¶

compute(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.gradients.gradient, parameter_vector: list[float], function: Callable, funcAtX: float) → list[float]

Compute the gradient of the provided parameter_vector with respect to its loss function, using the ParameterShift method.

static from_json()¶

from_json(arg0: str) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.gradients.ParameterShift

Convert JSON string to gradient

to_json()¶

to_json(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.gradients.ParameterShift) → str

Convert gradient to JSON string

Noisy Simulation¶

class cudaq.NoiseModel¶

The NoiseModel defines a set of KrausChannel’s applied to specific qubits after the invocation of specified quantum operations.

__init__()¶

__init__(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.NoiseModel) → None

Construct an empty noise model.

add_all_qubit_channel()¶

add_all_qubit_channel(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.NoiseModel, operator: str, channel: cudaq.KrausChannel, num_controls: int = 0) → None

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

Parameters:

operator (str) – The quantum operator to apply the noise channel to.
channel (cudaq.KrausChannel) – The KrausChannel to apply to the specified operator on any arbitrary qubits.
num_controls – Number of control bits. Default is 0 (no control bits).

add_channel(*args, **kwargs)¶

Overloaded function.

add_channel(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.NoiseModel, operator: str, qubits: list[int], channel: cudaq.KrausChannel) → None

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

Parameters:

operator (str) – The quantum operator to apply the noise channel to.
qubits (List[int]) – The qubit/s to apply the noise channel to.
channel (cudaq.KrausChannel) – The KrausChannel to apply to the specified operator on the specified qubits.

add_channel(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.NoiseModel, operator: str, pre: Callable[[list[int], list[float]], cudaq.KrausChannel]) → None

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

Parameters:

operator (str) – The quantum operator to apply the noise channel to.
pre (Callable) – The callback which takes qubits operands and gate parameters and returns a concrete KrausChannel to apply to the specified operator.

get_channels()¶

get_channels(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.NoiseModel, operator: str, qubits: list[int]) → list[cudaq.KrausChannel]

Return the KrausChannel’s that make up this noise model.

class cudaq.BitFlipChannel¶

Models the decoherence of the qubit state. Its constructor expects a float value, probability, representing the probability that the qubit flips from the 1-state to the 0-state, or vice versa. E.g, the probability of a random X-180 rotation being applied to the qubit.

The Kraus Channels are thereby defined to be:

K_0 = sqrt(1 - probability) * I

K_1 = sqrt(probability ) * X

The probability of the qubit remaining in the same state is therefore 1 - probability.

__init__()¶

__init__(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.BitFlipChannel, probability: float) → None

Initialize the BitFlipChannel with the provided probability.

class cudaq.PhaseFlipChannel¶

Models the decoherence of the qubit phase. Its constructor expects a float value, probability, representing the probability of a random Z-180 rotation being applied to the qubit.

The Kraus Channels are thereby defined to be:

K_0 = sqrt(1 - probability) * I

K_1 = sqrt(probability ) * Z

The probability of the qubit phase remaining untouched is therefore 1 - probability.

__init__()¶

__init__(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.PhaseFlipChannel, probability: float) → None

Initialize the PhaseFlipChannel with the provided probability.

class cudaq.DepolarizationChannel¶

Models the decoherence of the qubit state and phase into a mixture ” of the computational basis states, |0> and |1>.

The Kraus Channels are thereby defined to be:

K_0 = sqrt(1 - probability) * I

K_1 = sqrt(probability / 3) * X

K_2 = sqrt(probability / 3) * Y

K_3 = sqrt(probability / 3) * Z

where I, X, Y, Z are the 2x2 Pauli matrices.

The constructor expects a float value, probability, representing the probability the state decay will occur. The qubit will remain untouched, therefore, with a probability of 1 - probability. And the X,Y,Z operators will be applied with a probability of probability / 3.

For probability = 0.0, the channel will behave noise-free. For probability = 0.75, the channel will fully depolarize the state. For probability = 1.0, the channel will be uniform.

__init__()¶

__init__(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.DepolarizationChannel, probability: float) → None

Initialize the DepolarizationChannel with the provided probability.

class cudaq.AmplitudeDampingChannel¶

Models the dissipation of energy due to system interactions with the environment.

The Kraus Channels are thereby defined to be:

K_0 = sqrt(1 - probability) * I

K_1 = sqrt(probability) * 0.5 * (X + iY)

Its constructor expects a float value, probability, representing the probablity that the qubit will decay to its ground state. The probability of the qubit remaining in the same state is therefore 1 - probability.

__init__()¶

__init__(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.AmplitudeDampingChannel, probability: float) → None

Initialize the AmplitudeDampingChannel with the provided probability.

class cudaq.KrausChannel¶

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

__getitem__()¶

__getitem__(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.KrausChannel, index: int) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.KrausOperator

Return the KrausOperator at the given index in this KrausChannel.

append()¶

append(self: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.KrausChannel, arg0: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.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.

MPI Submodule¶

cudaq.mpi.initialize()¶

cudaq.mpi.initialize() → None

Initialize MPI if available.

cudaq.mpi.rank()¶

cudaq.mpi.rank() → int

Return the rank of this process.

cudaq.mpi.num_ranks()¶

cudaq.mpi.num_ranks() → int

Return the total number of ranks.

cudaq.mpi.all_gather(*args, **kwargs)¶

Overloaded function.

cudaq.mpi.all_gather(arg0: int, arg1: list[float]) → list[float]

Gather and scatter the local list of floating-point numbers, returning a concatenation of all lists across all ranks. The total global list size must be provided.

cudaq.mpi.all_gather(arg0: int, arg1: list[int]) → list[int]

Gather and scatter the local list of integers, returning a concatenation of all lists across all ranks. The total global list size must be provided.

cudaq.mpi.broadcast()¶

cudaq.mpi.broadcast(arg0: list[float], arg1: int, arg2: int) → list[float]

Broadcast an array from a process (rootRank) to all other processes. The size of broadcast array must be provided.

cudaq.mpi.is_initialized()¶

cudaq.mpi.is_initialized() → bool

Returns true if MPI has already been initialized.

cudaq.mpi.finalize()¶

cudaq.mpi.finalize() → None

Finalize MPI.

ORCA Submodule¶

cudaq.orca.sample(*args, **kwargs)¶

Overloaded function.

cudaq.orca.sample(input_state: list[int], loop_lengths: list[int], bs_angles: list[float], ps_angles: list[float], n_samples: int = 10000, qpu_id: int = 0) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.SampleResult

Performs Time Bin Interferometer (TBI) boson sampling experiments on ORCA’s backends

cudaq.orca.sample(input_state: list[int], loop_lengths: list[int], bs_angles: list[float], n_samples: int = 10000, qpu_id: int = 0) → cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.SampleResult

Performs Time Bin Interferometer (TBI) boson sampling experiments on ORCA’s backends