CUDA-Q C++ API¶

Quantum¶

constexpr std::size_t cudaq::dyn = ~0¶

template<std::size_t Levels> class qudit¶

The qudit models a general d-level quantum system. This type is templated on the number of levels d.

Public Functions

inline qudit()¶: Construct a qudit, will allocated a new unique index.

template<std::size_t N = dyn, std::size_t Levels = 2, typename = std::enable_if_t<(N > 0)>> class qreg¶

A qreg is a container for qudits. This container can be dynamic or compile-time-size specified. By default, the qreg is constructed as a dynamic register (vector-like) of qubits (2-level). This can be changed via the qreg type template parameters.

Public Types

using value_type = qudit<Levels>¶: Useful typedef indicating the underlying qudit type.

Public Functions

inline auto begin()¶: Iterator interface, begin.

inline value_type &operator[](const std::size_t idx)¶: Returns the qudit at idx.

inline qspan<dyn, Levels> front(std::size_t count)¶: Returns the [0, count) qudits.

inline value_type &front()¶: Returns the first qudit.

inline qspan<dyn, Levels> back(std::size_t count)¶: Returns the [count, size()) qudits.

inline value_type &back()¶: Returns the last qudit.

inline qspan<dyn, Levels> slice(std::size_t start, std::size_t size)¶: Returns the [start, start+size) qudits.

inline std::size_t size() const¶: Returns the number of contained qudits.

inline void clear()¶: Destroys all contained qudits. Postcondition: size() == 0.

template<std::size_t Levels = 2> class qvector¶

A qvector is an owning, dynamically sized container for qudits. The semantics of the qvector follows that of a std::vector for qudits. It is templated on the number of levels for the held qudits.

Public Types

using value_type = qudit<Levels>¶: Useful typedef indicating the underlying qudit type.

Public Functions

inline qvector(std::size_t size)¶: Construct a qvector with size qudits in the |0> state.

inline explicit qvector(const std::vector<complex> &vector, bool validate)¶: Construct a qvector from an input state vector. The number of qubits is determined by the size of the input vector. If validate is set, it will check the norm of input state vector.

inline explicit qvector(const state &state)¶: Construct a qvector from a pre-existing state. This state could be constructed with state::from_data or retrieved from an cudaq::get_state.

qvector(qvector const&) = delete¶: qvectors cannot be copied

qvector(qvector&&) = delete¶: qvectors cannot be moved

qvector &operator=(const qvector&) = delete¶: qvectors cannot be copy assigned.

inline auto begin()¶: Iterator interface, begin.

inline auto end()¶: Iterator interface, end.

inline value_type &operator[](const std::size_t idx)¶: Returns the qudit at idx.

inline qview<Levels> front(std::size_t count)¶: Returns the [0, count) qudits as a non-owning qview.

inline value_type &front()¶: Returns the first qudit.

inline qview<Levels> back(std::size_t count)¶: Returns the [count, size()) qudits as a non-owning qview

inline value_type &back()¶: Returns the last qudit.

inline qview<Levels> slice(std::size_t start, std::size_t size)¶: Returns the [start, start+size) qudits as a non-owning qview

inline std::size_t size() const¶: Returns the number of contained qudits.

inline void clear()¶: Destroys all contained qudits. Postcondition: size() == 0.

template<std::size_t N = dyn, std::size_t Levels = 2> class qspan¶

template<std::size_t Levels = 2> class qview¶

The qview represents a non-owning container of qudits.

Public Types

using value_type = qudit<Levels>¶: Useful typedef exposing the underlying qudit type that this qview contains.

using cudaq::qubit = qudit<2>¶

Common¶

class observe_result¶

The observe_result encapsulates all data generated from a cudaq”::”observe call. This includes all measurement counts from the execution of each ansatz + measure circuit, and the global expected value of the spin_op passed to observe.

Public Functions

inline observe_result(double e, const spin_op &H)¶: Constructor, takes the precomputed expectation value for <psi(x) | H | psi(x)> for the given spin_op.

inline observe_result(double e, const spin_op &H, sample_result counts)¶: Constructor, takes the precomputed expectation value for <psi(x) | H | psi(x)> for the given spin_op. If this execution was shots based, also provide the sample_result data containing counts for each term in H.

inline sample_result raw_data()¶

Return the raw counts data for all terms.

Returns:

inline operator double()¶: Conversion operator for this observe_result to double. Simply returns the precomputed expectation value for the given spin_op. This enables one to ignore the fine-grain sample_result data, and explicitly request the expected value: double exp = cudaq”::”observe(…); as opposed to cudaq”::”observe_data data = cudaq::observe(…); auto exp = data.expectation();.

inline double expectation()¶

Return the expected value for the provided spin_op.

Returns:

inline double expectation(const spin_op_term &term)¶: Return the expectation value for a sub-term in the provided spin_op.

inline sample_result counts(const spin_op_term &term)¶: Return the counts data for the given spin_op.

inline double id_coefficient()¶: Return the coefficient of the identity term. Assumes there is at more one identity term. Returns 0 if no identity term exists.

inline void dump()¶: Dump the counts data to standard out.

struct observe_options¶

Observe options to provide as an argument to the observe(), async_observe() functions.

Param shots:: number of shots to run for the given kernel, or -1 if not applicable.
Param noise:: noise model to use for the sample operation
Param num_trajectories:: is the optional number of trajectories to be used when computing the expectation values in the presence of noise. This parameter is only applied to simulation backends that support noisy simulation of trajectories.

template<typename QuantumKernel, typename ...Args, typename = std::enable_if_t<std::is_invocable_r_v<void, QuantumKernel, Args...>>> observe_result cudaq::observe(const observe_options &options, QuantumKernel &&kernel, const spin_op &H, Args&&... args)¶: Compute the expected value of H with respect to kernel(Args...). Specify the observation options.

template<typename QuantumKernel, typename ...Args, typename = std::enable_if_t<std::is_invocable_r_v<void, QuantumKernel, Args...>>> observe_result cudaq::observe(std::size_t shots, QuantumKernel &&kernel, const spin_op &H, Args&&... args)¶

Compute the expected value of H with respect to kernel(Args...). Specify the number of shots.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<typename QuantumKernel, typename ...Args, typename = std::enable_if_t<std::is_invocable_r_v<void, QuantumKernel, Args...>>> observe_result cudaq::observe(QuantumKernel &&kernel, const spin_op &H, Args&&... args)¶

Compute the expected value of H with respect to kernel(Args...).

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<typename QuantumKernel, typename SpinOpContainer, typename ...Args, typename = std::enable_if_t<std::is_invocable_r_v<void, QuantumKernel, Args...>>> std::vector<observe_result> cudaq::observe(QuantumKernel &&kernel, const SpinOpContainer &termList, Args&&... args)¶: Compute the expected value of every spin_op provided in SpinOpContainer (a range concept) with respect to kernel(Args...). Return a std::vector<observe_result>.

class ExecutionContext¶

The ExecutionContext is an abstraction to indicate how a CUDA-Q kernel should be executed.

Public Functions

inline ExecutionContext(const std::string n)¶

The Constructor, takes the name of the context.

Parameters:: n – The name of the context

inline ExecutionContext(const std::string n, std::size_t shots_)¶

The constructor, takes the name and the number of shots.

Parameters:

n – The name of the context
shots_ – The number of shots

Public Members

const std::string name¶: The name of the context ({basic, sampling, observe})

std::size_t shots = 0¶: The number of execution shots.

std::optional<cudaq::spin_op> spin¶: An optional spin operator.

sample_result result¶: Measurement counts for a CUDA-Q kernel invocation.

std::optional<double> expectationValue = std::nullopt¶: A computed expectation value.

std::optional<cudaq::optimization_result> optResult = std::nullopt¶: An optimization result.

bool hasConditionalsOnMeasureResults = false¶: The kernel being executed in this context has conditional statements on measure results.

const noise_model *noiseModel = nullptr¶: Noise model to apply to the current execution.

bool canHandleObserve = false¶: Flag to indicate if backend can handle spin_op observe task under this ExecutionContext.

bool asyncExec = false¶: Flag indicating that the current execution should occur asynchronously.

details::future futureResult¶: When execution asynchronously, store the expected results as a cudaq::future here.

async_result<sample_result> asyncResult¶: Construct a async_sample_result so as to pass across Python boundary.

std::unique_ptr<SimulationState> simulationState¶: Pointer to simulation-specific simulation data.

std::optional<std::map<std::vector<int>, std::complex<double>>> amplitudeMaps¶: A map of basis-state amplitudes.

std::optional<std::pair<const SimulationState*, const SimulationState*>> overlapComputeStates¶: List of pairs of states to compute the overlap.

std::optional<std::complex<double>> overlapResult¶: Overlap results.

Trace kernelTrace¶: When run under the tracer context, persist the traced quantum resources here.

std::string kernelName = ""¶: The name of the kernel being executed.

std::size_t batchIteration = 0¶: The current iteration for a batch execution, used by observe_n and sample_n.

std::size_t totalIterations = 0¶: For batch execution, the total number of batch iterations.

std::vector<std::string> registerNames¶: For mid-circuit measurements in library mode keep track of the register names.

std::vector<std::size_t> reorderIdx¶: A vector containing information about how to reorder the global register after execution. Empty means no reordering.

std::vector<char> invocationResultBuffer¶: A buffer containing the return value of a kernel invocation. Note: this is only needed for invocation not able to return a sample_result.

std::optional<std::size_t> numberTrajectories¶: The number of trajectories to be used for an expectation calculation on simulation backends that support trajectory simulation.

bool explicitMeasurements = false¶: Whether or not to simply concatenate measurements in execution order.

class future¶

The future type models the expected result of a CUDA-Q kernel execution under a specific execution context. This type is returned from asynchronous execution calls. It encapsulates the job-specific circuit execution identifiers, the name of the QPU the job executed on, and any extra configuration information needed to retrieve the results later from the server. This type can be persisted to file and read in later to retrieve execution results. It also optionally wraps a std::future<T> type, and in this case, persistence to file is not allowed, .get() must be invoked at some later point within the same runtime context.

Public Functions

future() = default¶: The constructor.

future(future&&) = default¶: move constructor

inline future(std::vector<Job> &_jobs, std::string &qpuNameIn, std::map<std::string, std::string> &config)¶: The constructor, takes all info required to be able to retrieve results at a later date, even after file persistence.

template<typename T> class async_result¶

the async_result type is a user facing, future-like type that is returned from CUDA-Q public asynchronous API functions. It wraps a details::future type, which can itself be constructed from a std::future or a collection of data pertinent to remote QPU REST invocation.

Public Functions

inline T get()¶: Return the asynchronously computed data, will wait until the data is ready.

using cudaq::async_sample_result = async_result<sample_result>¶: Return type for asynchronous sampling.

struct ExecutionResult¶

The ExecutionResult models the result of a typical quantum state sampling task. It will contain the observed measurement bit strings and corresponding number of times observed, as well as an expected value with respect to the Z…Z operator.

Public Functions

std::vector<std::size_t> serialize() const¶

Serialize this sample result to a vector of integers. Encoding: 1st element is size of the register name N, then next N represent register name, next is the number of bitstrings M, then for each bit string a triple {string mapped to long, bit string length, count}.

Returns:

void deserialize(std::vector<std::size_t> &data)¶

Deserialize a vector of integers to a ExecutionResult

Parameters:: data – The data with encoding discussed in the brief for serialize.

ExecutionResult() = default¶: Constructor.

ExecutionResult(CountsDictionary c)¶

Construct from a CountsDictionary, assumes registerName == global

Parameters:: c – the counts

ExecutionResult(std::string name)¶: Construct from a register name.

ExecutionResult(double expVal)¶: Construct from a precomputed expectation value.

ExecutionResult(CountsDictionary c, std::string name)¶

Construct from a CountsDictionary, specify the register name.

Parameters:

c – the counts
name – the register name

ExecutionResult(CountsDictionary c, double e)¶

Construct from a CountsDictionary and expected value.

Parameters:

c – The counts
e – The precomputed expected value

ExecutionResult(const ExecutionResult &other)¶

Copy constructor.

Parameters:: other –

ExecutionResult &operator=(const ExecutionResult &other)¶

Set this ExecutionResult equal to the provided one.

Parameters:: other –
Returns:

bool operator==(const ExecutionResult &result) const¶

Return true if the given ExecutionResult is the same as this one.

Parameters:: result –
Returns:

void appendResult(std::string bitString, std::size_t count)¶

Append the bitstring and count to this ExecutionResult

Parameters:

bitString –
count –

Public Members

std::string registerName = GlobalRegisterName¶: Register name for the classical bits.

std::vector<std::string> sequentialData¶: Sequential bit strings observed (not collated into a map)

class sample_result¶

The sample_result abstraction wraps a set of ExecutionResults for a single quantum kernel execution under the sampling or observation ExecutionContext. Each ExecutionResult is mapped to a register name, with a default ExecutionResult with name global representing the observed measurement results holistically for the quantum kernel.

Public Functions

sample_result() = default¶: Nullary constructor.

sample_result(ExecutionResult &&result)¶: The constructor, sets the global sample result.

sample_result(ExecutionResult &result)¶

The constructor, sets the global sample result.

Parameters:: result –

sample_result(std::vector<ExecutionResult> &results)¶: The constructor, appends all provided ExecutionResults.

sample_result(double preComputedExp, std::vector<ExecutionResult> &results)¶: The constructor, takes a precomputed expectation value and stores it with the __global__ ExecutionResult.

sample_result(const sample_result&) = default¶: Copy Constructor.

sample_result(sample_result&&) = default¶: Move constructor.

sample_result &operator=(sample_result &&counts) = default¶: Move assignment constructor.

~sample_result() = default¶: The destructor.

bool has_expectation(const std::string_view registerName = GlobalRegisterName) const¶: Return true if the ExecutionResult with the specified register name has a precomputed expectation value.

void append(ExecutionResult &result, bool concatenate = false)¶

Add another ExecutionResult to this sample_result.

Parameters:

result – Result to append
concatenate – If prior results are found, this concatenates the bitstrings.

std::vector<std::string> register_names() const¶

Return all register names. Can be used in tandem with sample_result::to_map(regName : string) to retrieve the counts for each register.

Returns:

sample_result &operator=(sample_result &counts) = default¶

Set this sample_result equal to the provided one.

Parameters:: counts –
Returns:

sample_result &operator+=(const sample_result &other)¶

Append all the data from other to this sample_result. Merge when necessary.

Parameters:: other –
Returns:

std::vector<std::size_t> serialize() const¶

Serialize this sample_result. See ExecutionResult::serialize() documentation for information.

Returns:

void deserialize(std::vector<std::size_t> &data)¶

Create this sample_result from the serialized data.

Parameters:: data –

bool operator==(const sample_result &counts) const¶

Return true if this sample_result is the same as the given one.

Parameters:: counts –
Returns:

double expectation(const std::string_view registerName = GlobalRegisterName) const¶

Return the expected value <Z…Z>

Returns:

double probability(std::string_view bitString, const std::string_view registerName = GlobalRegisterName) const¶

Return the probability of observing the given bit string.

Parameters:: bitString –
Returns:

std::string most_probable(const std::string_view registerName = GlobalRegisterName) const¶

Return the most probable bit string.

Parameters:: registerName –
Returns:

std::size_t count(std::string_view bitString, const std::string_view registerName = GlobalRegisterName) const¶

Return the number of times the given bitstring was observed.

Parameters:: bitString –
Returns:

std::size_t size(const std::string_view registerName = GlobalRegisterName) const noexcept¶

Return the number of observed bit strings.

Returns:

void dump() const¶: Dump this sample_result to standard out.

void dump(std::ostream &os) const¶: Dump this sample_result to the given output stream.

void clear()¶: Clear this sample_result.

CountsDictionary to_map(const std::string_view registerName = GlobalRegisterName) const¶

Extract the ExecutionResults as a std::unordered<string, size_t> map.

Parameters:: registerName –
Returns:

inline sample_result get_marginal(const std::vector<std::size_t> &&marginalIndices, const std::string_view registerName = GlobalRegisterName) const¶

Extract marginal counts, that is those counts for a subset of measured qubits.

Parameters:

marginalIndices – The qubit indices as an rvalue
registerName –

Returns:

sample_result get_marginal(const std::vector<std::size_t> &marginalIndices, const std::string_view registerName = GlobalRegisterName) const¶

Extract marginal counts, that is those counts for a subset of measured qubits.

Parameters:

marginalIndices – The qubit indices as an reference
registerName –

Returns:

void reorder(const std::vector<std::size_t> &index, const std::string_view registerName = GlobalRegisterName)¶

Reorder the bits in an ExecutionResult.

Parameters:

index – Vector of indices such that newBitStr(:)=oldBitStr(index(:))
registerName – register name to process (defaults to global)

CountsDictionary::iterator begin()¶

Range-based iterator begin function.

Returns:

CountsDictionary::iterator end()¶

Range-based iterator end function.

Returns:

CountsDictionary::const_iterator cbegin() const¶

Range-based constant iterator begin function.

Returns:

CountsDictionary::const_iterator cend() const¶

Range-based constant iterator end function.

Returns:

inline CountsDictionary::const_iterator begin() const¶

Range-based constant iterator begin function.

Returns:

inline CountsDictionary::const_iterator end() const¶

Range-based constant iterator end function.

Returns:

inline std::size_t get_total_shots() const¶: Get the total number of shots in the result.

Public Static Functions

static bool has_even_parity(std::string_view bitString)¶

Return true if the bit string has even parity.

Parameters:: bitString –
Returns:

struct sample_options¶

Sample options to provide to the sample() / async_sample() functions.

Param shots:: number of shots to run for the given kernel
Param noise:: noise model to use for the sample operation
Param explicit_measurements:: whether or not to form the global register based on user-supplied measurement order.

template<typename QuantumKernel, typename ...Args, typename = std::enable_if_t<std::is_invocable_r_v<void, QuantumKernel, Args...>>> sample_result cudaq::sample(const sample_options &options, QuantumKernel &&kernel, Args&&... args)¶

Sample the given quantum kernel expression and return the mapping of observed bit strings to corresponding number of times observed.

Given a quantum kernel with void return type, sample the corresponding quantum circuit generated by the kernel expression, returning the mapping of bits observed to number of times it was observed.

Parameters:

options – Sample options.
kernel – The kernel expression, must contain final measurements.
args – The variadic concrete arguments for evaluation of the kernel.

Returns:

The counts dictionary.

template<typename QuantumKernel, typename ...Args, typename = std::enable_if_t<std::is_invocable_r_v<void, QuantumKernel, Args...>>> auto cudaq::sample(std::size_t shots, QuantumKernel &&kernel, Args&&... args)¶

Sample the given quantum kernel expression and return the mapping of observed bit strings to corresponding number of times observed. Specify the number of shots.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Given a quantum kernel with void return type, sample the corresponding quantum circuit generated by the kernel expression, returning the mapping of bits observed to number of times it was observed.

Parameters:

shots – The number of samples to collect.
kernel – The kernel expression, must contain final measurements.
args – The variadic concrete arguments for evaluation of the kernel.

Returns:

The counts dictionary.

template<typename QuantumKernel, typename ...Args, typename = std::enable_if_t<std::is_invocable_r_v<void, QuantumKernel, Args...>>> sample_result cudaq::sample(QuantumKernel &&kernel, Args&&... args)¶

Sample the given quantum kernel expression and return the mapping of observed bit strings to corresponding number of times observed.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Given a quantum kernel with void return type, sample the corresponding quantum circuit generated by the kernel expression, returning the mapping of bits observed to number of times it was observed.

Parameters:

kernel – the kernel expression, must contain final measurements
args – the variadic concrete arguments for evaluation of the kernel.

Returns:

counts, The counts dictionary.

class SimulationState¶

The SimulationState interface provides and extension point for concrete circuit simulation sub-types to describe their underlying quantum state data in an efficient manner. The SimulationState provides a handle on the data for clients, with data remaining on GPU device or CPU memory. The primary goal of this type and its sub-types is to minimize data transfers for the state.

Subclassed by cudaq::CusvState< ScalarType >, cudaq::QPUState, cudaq::RemoteSimulationState, nvqir::MPSSimulationState, nvqir::TensorNetSimulationState

struct Tensor¶: Simulation states are made up of a vector of Tensors. Each tensor tracks its data pointer and the tensor extents.

enum class cudaq::SimulationState::precision¶

Runtime-known precision for the simulation data.

Values:

enumerator fp32¶

enumerator fp64¶

enum class cudaq::simulation_precision¶

Define an enumeration of possible simulation floating point precision types.

Values:

enumerator fp32¶

enumerator fp64¶

using cudaq::tensor = SimulationState::Tensor ¶

using cudaq::TensorStateData = std::vector<std::pair<const void*, std::vector<std::size_t>>>¶: Encapsulates a list of tensors (data pointer and dimensions).

using cudaq::state_data = std::variant<std::vector<std::complex<double>>, std::vector<std::complex<float>>, std::pair<std::complex<double>*, std::size_t>, std::pair<std::complex<float>*, std::size_t>, TensorStateData>¶: state_data is a variant type encoding different forms of user state vector data we support.

template<typename ScalarType> class CusvState : public cudaq::SimulationState ¶: CusvState provides an implementation of SimulationState that encapsulates the state data for the Custatevec Circuit Simulator. It attempts to keep the simulation data on GPU device and care is taken to ensure operations and comparisons with other states operate on compatible floating point element types.

class MPSSimulationState : public cudaq::SimulationState ¶

class TensorNetSimulationState : public cudaq::SimulationState ¶

class RemoteSimulationState : public cudaq::SimulationState ¶: Implementation of SimulationState for remote simulator backends.

class QPUState : public cudaq::SimulationState ¶: Implementation of SimulationState for quantum device backends. The state is represented by a quantum kernel. Quantum state contains all the information we need to replicate a call to kernel that created the state.

template<typename T> class RegisteredType¶: RegisteredType allows interface types to declare themselves as plugin interfaces. Used as follows class MyInterface : public RegisteredType<MyInterface> {…};.

class complex_matrix¶

This is a minimalist matrix container. It is two-dimensional. It owns its data. Elements are of type complex<double>. Typically, it will contain a two-by-two set of values.

Public Functions

value_type minimal_eigenvalue() const¶: Return the minimal eigenvalue for this matrix.

std::vector<value_type> eigenvalues() const¶: Return this matrix’s eigenvalues.

complex_matrix eigenvectors() const¶: Return the eigenvectors of this matrix. They are returned as the rows of a new matrix.

void set_zero()¶: Resets the matrix to all zero entries. Not needed after construction since the matrix will be initialized to zero.

complex_matrix exponential()¶: Matrix exponential, uses 20 terms of Taylor Series approximation.

complex_matrix power(int powers)¶: Matrix power.

complex_matrix adjoint()¶: Returns the conjugate transpose of a matrix.

complex_matrix::value_type operator[](const std::vector<std::size_t> &at) const¶: Operator to get the value at a particular index in the matrix.

complex_matrix::value_type &operator[](const std::vector<std::size_t> &at)¶: Operator to get the value at a particular index in the matrix.

complex_matrix::value_type operator()(std::size_t i, std::size_t j) const¶: Operator to get the value at a particular index in the matrix.

complex_matrix::value_type &operator()(std::size_t i, std::size_t j)¶: Operator to get the value at a particular index in the matrix.

std::string to_string() const¶: Returns a string representation of the matrix.

void dump() const¶: Print this matrix to the standard output stream.

void dump(std::ostream &os) const¶: Print this matrix to the given output stream.

Public Static Functions

static complex_matrix identity(const std::size_t rows)¶: Return a square identity matrix for the given size.

Friends

friend complex_matrix operator*(const complex_matrix&, const complex_matrix&)¶: Multiplication (cross-product) of two matrices.

friend std::vector<complex_matrix::value_type> operator*(const complex_matrix&, const std::vector<complex_matrix::value_type>&)¶: Right-side multiplication with a vector.

friend complex_matrix operator*(complex_matrix::value_type, const complex_matrix&)¶: Scalar Multiplication with matrices.

friend complex_matrix operator+(const complex_matrix&, const complex_matrix&)¶: Addition of two matrices.

friend complex_matrix operator-(const complex_matrix&, const complex_matrix&)¶: Subtraction of two matrices.

friend complex_matrix kronecker(const complex_matrix&, const complex_matrix&)¶: Kronecker of two matrices.

template<typename Iterable, typename T> friend complex_matrix kronecker(Iterable begin, Iterable end)¶: Kronecker a list of matrices. The list can be any container that has iterators defined.

class Trace¶: A trace is a circuit representation of the executed computation, as seen by the execution manager. (Here, a circuit is represented as a list of instructions on qudits). Since the execution manager cannot “see” control flow, the trace of a kernel with control flow represents a single execution path, and thus two calls to the same kernel might produce traces.

template<typename ElementType, typename = std::enable_if_t<std::is_integral_v<ElementType> && std::is_signed_v<ElementType>>> inline std::vector<ElementType> cudaq::range(ElementType N)¶: Return a vector of integers. The first element is zero, and the remaining elements are all values incremented by 1 to the total size value provided (exclusive).

template<typename ElementType, typename = std::enable_if_t<std::is_integral_v<ElementType> && std::is_signed_v<ElementType>>> inline std::vector<ElementType> cudaq::range(ElementType start, ElementType stop, ElementType step = 1)¶: Return a vector of integers. The first element is the user-specified start value. The remaining values are all values incremented by step (defaults to 1) until the stop value is reached (exclusive).

template<typename QuantumKernel, typename ...Args, typename = std::enable_if_t<std::is_invocable_v<QuantumKernel, Args...>>> std::string cudaq::draw(QuantumKernel &&kernel, Args&&... args)¶

Returns a drawing of the execution path, i.e., the trace, of the kernel. The drawing is a UTF-8 encoded string.

Usage:

#include <cudaq.h>
#include <cudaq/algorithms/draw.h>
#include <iostream>

auto bell_pair = []() __qpu__ {
    cudaq::qvector q(2);
    h(q[0]);
    x<cudaq::ctrl>(q[0], q[1]);
    mz(q);
};
...
std::cout << cudaq::draw(bell_pair);
/* Output:
     ╭───╮     
q0 : ┤ h ├──●──
     ╰───╯╭─┴─╮
q1 : ─────┤ x ├
          ╰───╯
*/

auto kernel = [](float angle) __qpu__ {
  cudaq::qvector q(1);
  h(q[0]);
  ry(angle, q[0]);
};
...
std::cout << cudaq::draw(kernel, 0.59);
/* Output:
     ╭───╮╭──────────╮
q0 : ┤ h ├┤ ry(0.59) ├
     ╰───╯╰──────────╯
*/      

Parameters:

kernel – The quantum callable with non-trivial function signature.
args – The arguments required for evaluation of the quantum kernel.

Returns:

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

template<typename QuantumKernel, typename ...Args> auto cudaq::get_state(QuantumKernel &&kernel, Args&&... args)¶: Return the state representation generated by the kernel at the given runtime arguments.

class Resources¶: The Resources type encodes information regarding the currently executing kernel’s resource usage. This includes number and type of quantum operation, circuit depth, etc.

using cudaq::complex_matrix::value_type = std::complex<double>¶

Noise Modeling¶

template<typename Channel, typename ...Args> void cudaq::apply_noise(Args&&... args)¶

This function is a type-safe injection of noise into a quantum kernel, occurring precisely at the call site of the function invocation. The function should be called inside CUDA-Q kernels (those annotated with __qpu__). The functionality is only supported for simulation targets, so it is automatically (and silently) stripped from any programs submitted to hardware targets.

Template Parameters:

Channel –

A subtype of cudaq::kraus_channel that implements/defines the desired noise mechanisms as Kraus channels (e.g. cudaq::depolarization2). If you want to use a custom cudaq::kraus_channel (i.e. not built-in to CUDA-Q), it must first be registered outside the kernel with cudaq::noise_model::register_channel(), like this:

struct my_custom_kraus_channel_subtype : public ::cudaq::kraus_channel {
  static constexpr std::size_t num_parameters = 1;
  static constexpr std::size_t num_targets = 1;

  my_custom_kraus_channel_subtype(const std::vector<cudaq::real> &params) {
      std::vector<cudaq::complex> k0v{std::sqrt(1 - params[0]), 0, 0,
                                      std::sqrt(1 - params[0])},
          k1v{0, std::sqrt(params[0]), std::sqrt(params[0]), 0};
      push_back(cudaq::kraus_op(k0v));
      push_back(cudaq::kraus_op(k1v));
      validateCompleteness();
      generateUnitaryParameters();
  }
  REGISTER_KRAUS_CHANNEL("my_custom_kraus_channel_subtype");
};

cudaq::noise_model noise;
noise.register_channel<my_custom_kraus_channel_subtype>();

Parameters:

args –

The precise argument pack depend on the concrete Channel being used. The arguments are a concatenated list of parameters and targets. For example, to apply a 2-qubit depolarization channel, which has num_parameters = 1 and num_targets = 2, one would write the call like this:

cudaq::qubit q, r;
cudaq::apply_noise<cudaq::depolarization2>(/*probability=*/0.1, q, r);

struct kraus_op¶

A kraus_op represents a single Kraus operation, described as a complex matrix of specific size. The matrix is represented here as a 1d array (specifically a std::vector).

Public Functions

kraus_op(const kraus_op&) = default¶: Copy constructor.

inline kraus_op(std::vector<cudaq::complex> d)¶: Constructor, initialize from vector data.

template<typename T> inline kraus_op(std::initializer_list<T> &&initList)¶: Constructor, initialize from initializer_list.

inline kraus_op &operator=(const kraus_op &other)¶: Set this kraus_op equal to the other.

inline kraus_op adjoint() const¶: Return the adjoint of this kraus_op.

Public Members

std::vector<cudaq::complex> data¶: Matrix data, represented as a 1d flattened.

std::size_t nRows = 0¶: The number of rows in the matrix.

std::size_t nCols = 0¶: The number of columns in the matrix NOTE we currently assume nRows == nCols.

const cudaq::simulation_precision precision = std::is_same_v<cudaq::real, float> ? cudaq::simulation_precision::fp32 : cudaq::simulation_precision::fp64 ¶: The precision of the underlying data.

class kraus_channel¶

A kraus_channel represents a quantum noise channel on specific qubits. The action of the noise channel is described by a vector of Kraus operations - matrices with size equal to 2**nQubits x 2**nQubits, where the number of qubits is the number of provided qubit indices at construction.

Subclassed by cudaq::amplitude_damping_channel, cudaq::bit_flip_channel, cudaq::depolarization2, cudaq::depolarization_channel, cudaq::pauli1, cudaq::pauli2, cudaq::phase_damping, cudaq::phase_flip_channel, cudaq::y_error

Public Functions

kraus_channel() = default¶: The nullary constructor.

kraus_channel(const kraus_channel &other)¶

The copy constructor.

Parameters:: other –

template<typename ...T> inline kraus_channel(std::initializer_list<T>&&... inputLists)¶: The constructor, initializes kraus_ops internally from the provided initializer_lists.

inline kraus_channel(const std::vector<kraus_op> &inOps)¶: The constructor, take qubits and channel kraus_ops as lvalue reference.

inline kraus_channel(std::vector<kraus_op> &&ops)¶: The constructor, take qubits and channel kraus_ops as rvalue reference.

std::size_t size() const¶: Return the number of kraus_ops that make up this channel.

bool empty() const¶: Return true if there are no ops in this channel.

kraus_op &operator[](const std::size_t idx)¶: Return the kraus_op at the given index.

kraus_channel &operator=(const kraus_channel &other)¶: Set this kraus_channel equal to the given one.

std::vector<kraus_op> get_ops() const¶: Return all kraus_ops in this channel.

void push_back(kraus_op op)¶: Add a kraus_op to this channel.

inline bool is_unitary_mixture() const¶: Returns whether or not this is a unitary mixture.

inline void generateUnitaryParameters()¶: Checks if Kraus ops have unitary representations and saves them if they do. Users should only need to call this if they have modified the Kraus ops and want to recompute these values.

Public Members

noise_model_type noise_type = noise_model_type::unknown ¶: Noise type enumeration.

std::vector<double> parameters¶: Noise parameter values.

std::vector<std::vector<std::complex<double>>> unitary_ops¶: If all Kraus ops are - when scaled - unitary, this holds the unitary versions of those ops. These values are always “double” regardless of whether cudaq::real is float or double.

std::vector<double> probabilities¶: If all Kraus ops are - when scaled - unitary, this holds the probabilities of those ops. These values are always “double” regardless of whether cudaq::real is float or double.

class amplitude_damping_channel : public cudaq::kraus_channel ¶

amplitude_damping_channel is a kraus_channel that automates the creation of the kraus_ops that make up a single-qubit amplitude damping error channel.

Subclassed by cudaq::amplitude_damping

Public Static Attributes

static constexpr std::size_t num_parameters = 1¶: Number of parameters. The one parameter is the probability that the error will occur.

static constexpr std::size_t num_targets = 1¶: Number of targets.

class bit_flip_channel : public cudaq::kraus_channel ¶

bit_flip_channel is a kraus_channel that automates the creation of the kraus_ops that make up a single-qubit bit flipping error channel.

Subclassed by cudaq::x_error

Public Static Attributes

static constexpr std::size_t num_parameters = 1¶: Number of parameters. The one parameter is the probability that the error will occur.

static constexpr std::size_t num_targets = 1¶: Number of targets.

class phase_flip_channel : public cudaq::kraus_channel ¶

phase_flip_channel is a kraus_channel that automates the creation of the kraus_ops that make up a single-qubit phase flip error channel.

Subclassed by cudaq::z_error

Public Static Attributes

static constexpr std::size_t num_parameters = 1¶: Number of parameters. The one parameter is the probability that the error will occur.

static constexpr std::size_t num_targets = 1¶: Number of targets.

class depolarization_channel : public cudaq::kraus_channel ¶

depolarization_channel is a kraus_channel that automates the creation of the kraus_ops that make up a single-qubit depolarization error channel.

Subclassed by cudaq::depolarization1

Public Static Attributes

static constexpr std::size_t num_parameters = 1¶: Number of parameters. The one parameter is the probability that the error will occur.

static constexpr std::size_t num_targets = 1¶: Number of targets.

class x_error : public cudaq::bit_flip_channel ¶: x_error is a Pauli error that applies the X operator when an error occurs. It is the same as bit_flip_channel.

class y_error : public cudaq::kraus_channel ¶

Y_error is a Pauli error that applies the Y operator when an error occurs.

Public Static Attributes

static constexpr std::size_t num_parameters = 1¶: Number of parameters. The one parameter is the probability that the error will occur.

static constexpr std::size_t num_targets = 1¶: Number of targets.

class z_error : public cudaq::phase_flip_channel ¶: z_error is a Pauli error that applies the Z operator when an error occurs. It is the same as phase_flip_channel.

class amplitude_damping : public cudaq::amplitude_damping_channel ¶: amplitude_damping is the same as amplitude_damping_channel.

class phase_damping : public cudaq::kraus_channel ¶

phase_damping is a kraus_channel that automates the creation of the kraus_ops that make up a single-qubit phase damping error channel.

Public Static Attributes

static constexpr std::size_t num_parameters = 1¶: Number of parameters. The one parameter is the probability that the error will occur.

static constexpr std::size_t num_targets = 1¶: Number of targets.

class pauli1 : public cudaq::kraus_channel ¶

A single-qubit Pauli error that applies either an X error, Y error, or Z error, with 3 probabilities specified as inputs.

Public Functions

inline pauli1(const std::vector<cudaq::real> &p)¶

Construct a single-qubit Pauli error Kraus channel.

Parameters:: p – Error probabilities for X, Y, and Z errors, respectively

Public Static Attributes

static constexpr std::size_t num_parameters = 3¶: Number of parameters. The 3 parameters are the probability that an X error, Y error, or Z error happens. Only 1 of the 3 possible errors will happen (at most).

static constexpr std::size_t num_targets = 1¶: Number of targets.

class pauli2 : public cudaq::kraus_channel ¶

A 2-qubit Pauli error that applies one of the following errors, with the probabilities specified as inputs. Possible errors: IX, IY, IZ, XI, XX, XY, XZ, YI, YX, YY, YZ, ZI, ZX, ZY, and ZZ.

Public Functions

inline pauli2(const std::vector<cudaq::real> &p)¶

Construct a 2-qubit Pauli error Kraus channel.

Parameters:: p – Error probabilities for the 2-qubit Pauli operators. The length of this vector must be 15. Note that since the probability of II is not specified, it is implied to by 1 - sum(p). Therefore, maximal mixing occurs when sum(p) = 0.9375.

Public Static Attributes

static constexpr std::size_t num_parameters = 15¶: Number of parameters. The 15 parameters are the probability that each one of the above errors will happen. Only 1 of the 15 possible errors will happen (at most).

static constexpr std::size_t num_targets = 2¶: Number of targets.

class depolarization1 : public cudaq::depolarization_channel ¶: depolarization1 is the same as depolarization_channel

class depolarization2 : public cudaq::kraus_channel ¶

A 2-qubit depolarization error that applies one of the following errors. Possible errors: IX, IY, IZ, XI, XX, XY, XZ, YI, YX, YY, YZ, ZI, ZX, ZY, and ZZ.

Public Functions

inline depolarization2(const real probability)¶

Construct a two qubit Kraus channel that applies a depolarization channel on either qubit independently.

Parameters:: probability – The probability of any depolarizing error happening in the 2 qubits. (Setting this to 1.0 ensures that “II” cannot happen; maximal mixing occurs at p = 0.9375.)

Public Static Attributes

static constexpr std::size_t num_parameters = 1¶: Number of parameters. The 1 parameter is the probability that each one of the 15 error possibilities list above will occur. Only 1 of the 15 possible errors will happen (at most).

static constexpr std::size_t num_targets = 2¶: Number of targets.

class noise_model¶

The noise_model type keeps track of a set of kraus_channels to be applied after the execution of quantum operations. Each quantum operation maps to a Kraus channel containing a number of kraus_ops to be applied to the density matrix representation of the state.

Public Types

using PredicateFuncTy = std::function<kraus_channel(const std::vector<std::size_t>&, const std::vector<double>&)>¶: Callback function type for noise channel. Given the qubit operands and gate parameters, this function should return a concrete noise channel.

template<typename T, typename ...Args> using requires_constructor = std::enable_if_t<std::is_constructible_v<T, Args...>>¶

SFINAE helper to enable a function only if T is constructible with Args....

Template Parameters:

T – The type to check
Args – The argument types required for construction.

Public Functions

noise_model()¶: default constructor

inline bool empty() const¶

Return true if there are no kraus_channels in this noise model.

Returns:

void add_channel(const std::string &quantumOp, const std::vector<std::size_t> &qubits, const kraus_channel &channel)¶: Add the Kraus channel to the specified one-qubit quantum operation. It applies to the quantumOp operation for the specified qubits in the kraus_channel.

void add_channel(const std::string &quantumOp, const PredicateFuncTy &pred)¶

Add the Kraus channel as a callback to the specified quantum operation.

Parameters:

quantumOp – Quantum operation that the noise channel applies to.
pred – Callback function that generates a noise channel.

template<typename KrausChannelT, typename = requires_constructor<KrausChannelT, const std::vector<cudaq::real>&>> inline void register_channel()¶: Register a Kraus channel. This must be called outside of a CUDA-Q kernel before the channel can be recognized inside a CUDA-Q kernel.

void add_all_qubit_channel(const std::string &quantumOp, const kraus_channel &channel, int numControls = 0)¶

Add the Kraus channel that applies to a quantum operation on any arbitrary qubits.

Parameters:

quantumOp – Quantum operation that the noise channel applies to.
channel – The Kraus channel to apply.
numControls – Number of control qubits for the gate. Default is 0 (gate without a control modifier).

template<typename ...QuantumOp> inline void add_channel(const std::vector<std::size_t> &qubits, const kraus_channel &channel)¶: Add the provided kraus_channel to all specified quantum operations.

template<typename ...QuantumOp> inline void add_channel(const PredicateFuncTy &pred)¶: Add the provided kraus_channel callback to all specified quantum operations.

template<typename ...QuantumOp> inline void add_all_qubit_channel(const kraus_channel &channel, int numControls = 0)¶: Add the provided kraus_channel to all specified quantum operations applying on arbitrary qubits.

std::vector<kraus_channel> get_channels(const std::string &quantumOp, const std::vector<std::size_t> &targetQubits, const std::vector<std::size_t> &controlQubits = {}, const std::vector<double> &params = {}) const¶: Return relevant kraus_channels on the specified qubits for.

template<typename QuantumOp> inline std::vector<kraus_channel> get_channels(const std::vector<std::size_t> &targetQubits, const std::vector<std::size_t> &controlQubits = {}, const std::vector<double> &params = {}) const¶: Get all kraus_channels on the given qubits.

enum class cudaq::noise_model_type¶

Values:

enumerator unknown¶

enumerator depolarization_channel¶

enumerator amplitude_damping_channel¶

enumerator bit_flip_channel¶

enumerator phase_flip_channel¶

enumerator x_error¶

enumerator y_error¶

enumerator z_error¶

enumerator amplitude_damping¶

enumerator phase_damping¶

enumerator pauli1¶

enumerator pauli2¶

enumerator depolarization1¶

enumerator depolarization2¶

Kernel Builder¶

template<typename ...Args> class kernel_builder : public cudaq::details::kernel_builder_base ¶

Public Functions

inline kernel_builder(std::vector<details::KernelBuilderType> &types)¶: The constructor, takes the input KernelBuilderTypes which is used to create the MLIR function type.

inline auto &getArguments()¶: Return the QuakeValue arguments.

inline bool isArgStdVec(std::size_t idx)¶: Return true if the argument to the kernel is a std::vector, false otherwise.

inline std::string name()¶: Return the name of this kernel.

inline std::size_t getNumParams()¶

Return the number of function arguments.

Returns:

inline QuakeValue qalloc()¶: Return a QuakeValue representing the allocated qubit.

inline QuakeValue qalloc(const std::size_t nQubits)¶: Return a QuakeValue representing the allocated QVec.

inline QuakeValue qalloc(QuakeValue size)¶: Return a QuakeValue representing the allocated Veq, size is from a pre-allocated size QuakeValue or BlockArgument.

inline QuakeValue qalloc(std::vector<std::complex<double>> &state)¶

Return a QuakeValue representing the allocated quantum register, initialized to the given state vector, state.

Note: input argument is a true reference here, the calling context has to own the data. Specifically, the builder object will capture variables by reference (implemented as a container of pointers for simplicity) but the builder does not create, own, or copy these vectors. This implies that if the captured vector goes out of scope before the kernel is invoked, the reference may contain garbage. This behavior is identical to a C++ lambda capture by reference.

inline QuakeValue constantVal(double val)¶: Return a QuakeValue representing the constant floating-point value.

inline void swap(const QuakeValue &first, const QuakeValue &second)¶: SWAP operation for swapping the quantum states of two qubits.

template<typename mod, typename = typename std::enable_if_t<std::is_same_v<mod, cudaq::ctrl>>> inline void swap(const QuakeValue &control, const QuakeValue &first, const QuakeValue &second)¶: SWAP operation for performing a Fredkin gate between two qubits, based on the state of input control qubit/s.

template<typename mod, typename = typename std::enable_if_t<std::is_same_v<mod, cudaq::ctrl>>> inline void swap(const std::vector<QuakeValue> &controls, const QuakeValue &first, const QuakeValue &second)¶: SWAP operation for performing a Fredkin gate between two qubits, based on the state of an input vector of controls.

class QuakeValue¶

A QuakeValue is meant to provide a thin wrapper around an mlir::Value instance. These QuakeValues represent handles to function arguments and return values from MLIR Operations, specifically Quake Dialect operations. The QuakeValue also exposes and algebraic API enabling one to negate, add, subtract, and multiply QuakeValues with each other as well as with primitive arithmetic types, e.g. double.

Public Functions

mlir::Value getValue() const¶: Return the actual MLIR Value.

QuakeValue(mlir::ImplicitLocOpBuilder &builder, mlir::Value v)¶: The constructor, takes the builder and the value to wrap.

QuakeValue(mlir::ImplicitLocOpBuilder &builder, double v)¶: The constructor, takes the builder and a constant double value, which will map to an arith::ConstantFloatOp Value.

void dump()¶: Dump the QuakeValue to standard out.

void dump(std::ostream&)¶: Dump the QuakeValue to the given output stream.

inline bool canValidateNumElements()¶: Return true if this QuakeValue of StdVecType can validate its number of unique elements. We cannot do this in the case of QuakeValue extractions within for loops where we do not know the bounds of the loop.

QuakeValue slice(const std::size_t startIdx, const std::size_t count)¶: For a subscriptable QuakeValue, extract a sub set of the elements starting at the given startIdx and including the following count elements.

QuakeValue size()¶: For a QuakeValue with type StdVec or Veq, return the size QuakeValue.

std::optional<std::size_t> constantSize()¶: Return the constant size of this QuakeValue if it is of Veq type.

bool isStdVec()¶

Return true if this QuakeValue is of type StdVec.

Returns:

std::size_t getRequiredElements()¶: For a QuakeValue of type StdVec, return the number of required elements, i.e. the number of unique extractions observed.

QuakeValue operator[](const std::size_t idx)¶: Return a new QuakeValue when the current value is indexed, specifically for QuakeValues of type StdVecType and VeqType.

QuakeValue operator[](const QuakeValue &idx)¶: Return a new QuakeValue when the current value is indexed, specifically for QuakeValues of type StdVecType and VeqType.

QuakeValue operator-() const¶: Return the negation of this QuakeValue.

QuakeValue operator*(const double)¶: Multiply this QuakeValue by the given double.

QuakeValue operator*(QuakeValue other)¶: Multiply this QuakeValue by the given QuakeValue.

QuakeValue operator/(const double)¶: Divide this QuakeValue by the given double.

QuakeValue operator/(QuakeValue other)¶: Divide this QuakeValue by the given QuakeValue.

QuakeValue operator+(const double)¶: Add this QuakeValue with the given double.

QuakeValue operator+(const int)¶: Add this QuakeValue with the given int.

QuakeValue operator+(QuakeValue other)¶: Add this QuakeValue with the given QuakeValue.

QuakeValue operator-(const double)¶: Subtract the given double from this QuakeValue.

QuakeValue operator-(const int)¶: Subtract the given int from this QuakeValue.

QuakeValue operator-(QuakeValue other)¶: Subtract the given QuakeValue from this QuakeValue.

QuakeValue inverse() const¶: Return the inverse (1/x) of this QuakeValue.

class kernel_builder_base¶

The kernel_builder_base provides a base type for the templated kernel builder so that we can get a single handle on an instance within the runtime.

Subclassed by cudaq::kernel_builder< Args >

Friends

friend std::ostream &operator<<(std::ostream &stream, const kernel_builder_base &builder)¶: Write the kernel_builder to the given output stream. This outputs the Quake representation.

class KernelBuilderType¶

The kernel_builder::Type allows us to track input C++ types representing the quake function argument types in a way that does not expose MLIR Type to the CUDA-Q code. This type keeps track of a functor that generates the MLIR Type in implementation code when create() is invoked.

Public Functions

KernelBuilderType(std::function<mlir::Type(mlir::MLIRContext *ctx)> &&f)¶: The constructor, take the Type generation functor.

mlir::Type create(mlir::MLIRContext *ctx)¶: Create the MLIR Type.

Algorithms¶

class optimizer¶

The cudaq::optimizer provides a high-level interface for general optimization of user-specified objective functions. This is meant to serve an interface for clients working with concrete subtypes providing specific optimization algorithms possibly delegating to third party libraries. This interface provides an optimize(…) method that takes the number of objective function input parameters (the dimension), and a user-specified objective function that takes the function input parameters as a immutable (const) vector<double> reference and a mutable vector<double> reference modeling the current iteration gradient vector (dF / dx_i, for all i parameters). This function must return a scalar double, the value of this function at the current input parameters. The optimizer also exposes a method for querying whether the current optimization strategy requires gradients or not. Parameterizing optimization strategies is left as a task for sub-types (things like initial parameters, max function evaluations, etc.).

cudaq::optimizers::cobyla opt;
assert(!opt.requiresGradients() && "Cobyla algo does not use gradients.");
auto [opt_val, opt_params] = opt.optimize(2,
              [&](const std::vector<double>& x, std::vector<double>& dx) {
                  ... use x, modify dx, return scalar double ...
              }
            );

Public Functions

virtual bool requiresGradients() = 0¶: Returns true if this optimization strategy requires gradients to achieve its optimization goals.

virtual optimization_result optimize(const int dim, optimizable_function &&opt_function) = 0¶: Run the optimization strategy defined by concrete sub-type implementations. Takes the number of variational parameters, and a custom objective function that takes the function input parameters as a immutable (const) vector<double> reference and a mutable vector<double> reference modeling the current iteration gradient vector (dF / dx_i, for all i parameters). This function must return a scalar double, the value of this function at the current input parameters.

class optimizable_function¶: An optimizable_function wraps a user-provided objective function to be optimized.

using cudaq::optimization_result = std::tuple<double, std::vector<double>>¶: Typedef modeling the result of an optimization strategy, a double representing the optimal value and the corresponding optimal parameters.

class state¶

The cudaq::state encapsulate backend simulation state vector or density matrix data.

Public Functions

inline explicit state(SimulationState *ptrToOwn)¶: The constructor, takes the simulation data and owns it.

state(const state &other) = default¶: Copy constructor (default)

state &operator=(state &&other)¶: Copy assignment.

std::complex<double> operator[](std::size_t idx) const¶: Convenience function for extracting from a known vector.

std::complex<double> operator()(std::size_t idx, std::size_t jdx) const¶: Convenience function for extracting from a known matrix.

std::complex<double> operator()(const std::initializer_list<std::size_t>&, std::size_t tensorIdx = 0) const¶: General extraction operator for state data.

tensor get_tensor(std::size_t tensorIdx = 0) const¶: Return the tensor at the given index for this state representation. For state-vector and density matrix simulation states, there is just one tensor with rank 1 or 2 respectively.

std::vector<tensor> get_tensors() const¶: Return all tensors that represent this simulation state.

std::size_t get_num_tensors() const¶: Return the number of tensors that represent this state.

std::size_t get_num_qubits() const¶: Return the number of qubits.

SimulationState::precision get_precision() const¶: Return the underlying floating point precision for this state.

bool is_on_gpu() const¶: Return true if this a state on the GPU.

template<typename ScalarType> inline void to_host(std::complex<ScalarType> *hostPtr, std::size_t numElements) const¶: Copy this state from device to.

void dump() const¶: Dump the state to standard out.

void dump(std::ostream &os) const¶: Dump the state to given output stream.

std::complex<double> overlap(const state &other)¶: Compute the overlap of this state with the other one. For state vectors (pure states), it is computed as |<this | other>|.

std::complex<double> amplitude(const std::vector<int> &basisState)¶: Return the amplitude of the given computational basis state.

std::vector<std::complex<double>> amplitudes(const std::vector<std::vector<int>> &basisStates)¶: Return the amplitudes of the given list of computational basis states.

Public Static Functions

static state from_data(const state_data &data)¶: Create a new state from user-provided data. The data can be host or device data.

class gradient¶

The cudaq::gradient represents a base type for all gradient strategies leveraged by variational algorithms.

The cudaq::gradient tracks a std::function with signature void(std::vector<double>) representing the parameterized kernel ansatz. For ansatzes that do not follow this signature, a separate Argument Mapper must be provided which takes std::vector<double> to a tuple of custom function arguments. All gradient subtypes should inherit the base class constructors (using gradient::gradient), but provide a concrete implementation of gradient::compute(). The compute method takes as input the current iteration parameters, a reference to the gradient vector which compute() must update, the cudaq::spin_op for this variational algorithm, and the expected value of the spin_op at the current iteration’s parameters. Subtypes can leverage the protected gradient::getExpectedValue() method to compute <psi(x) | H | psi(x)> at the provided set of variational parameters.

Subclassed by cudaq::gradients::central_difference, cudaq::gradients::forward_difference, cudaq::gradients::parameter_shift

Public Functions

inline gradient(std::function<void(std::vector<double>)> &&kernel)¶: Constructor, takes the quantum kernel with prescribed signature.

gradient() = default¶: Empty constructor.

template<typename KernelT, typename ArgsMapper> inline gradient(KernelT &kernel, ArgsMapper &&argsMapper)¶: Constructor, takes a callable with non-standard signature the Argument Mapper function object that maps the parameters to concrete arguments for the quantum kernel.

template<typename QuantumKernel, typename ...Args> inline void setArgs(QuantumKernel &kernel, Args&&... args)¶: Take the quantum kernel and concrete arguments for all arguments except the first std::vector<double> argument, which is used for the variational parameters for the gradient. Serialize and save those arguments into this object. (Useful for NVQC.)

template<typename QuantumKernel> inline void setKernel(QuantumKernel &kernel)¶: Set the kernel after the gradient has been constructed. Use of this function requires that the kernel ONLY accept the variational parameters. It cannot have any non-variational parameters.

template<typename KernelT, typename = std::enable_if_t<std::is_invocable_v<KernelT, std::vector<double>>>> inline gradient(KernelT &kernel)¶: Constructor, takes a callable that must have the prescribed call signature (void(std::vector<double>))

template<typename QuantumKernel, typename ArgsMapper> inline gradient(QuantumKernel &&kernel, ArgsMapper &&argsMapper)¶: Constructor, takes the quantum kernel with non-standard signature the Argument Mapper function object that maps the parameters to concrete arguments for the quantum kernel.

virtual void compute(const std::vector<double> &x, std::vector<double> &dx, const spin_op &h, double funcAtX) = 0¶: Compute the current iterations gradient vector and update the provided vector<double reference (dx).

virtual std::vector<double> compute(const std::vector<double> &x, const std::function<double(std::vector<double>)> &func, double funcAtX) = 0¶: Compute the gradient vector for the provided objective function, func, at the given set of parameters, x.

virtual std::unique_ptr<cudaq::gradient> clone() = 0¶: Clone the object. Must be implemented by derived classes.

class central_difference : public cudaq::gradient ¶

Public Functions

inline virtual std::unique_ptr<cudaq::gradient> clone() override¶: Clone the object. Must be implemented by derived classes.

inline virtual void compute(const std::vector<double> &x, std::vector<double> &dx, const spin_op &h, double exp_h) override¶: Compute the current iterations gradient vector and update the provided vector<double reference (dx).

inline virtual std::vector<double> compute(const std::vector<double> &x, const std::function<double(std::vector<double>)> &func, double funcAtX) override¶: Compute the central_difference gradient for the arbitrary function, func, passed in by the user.

inline gradient(std::function<void(std::vector<double>)> &&kernel)¶: Constructor, takes the quantum kernel with prescribed signature.

gradient() = default¶: Empty constructor.

template<typename KernelT, typename ArgsMapper> inline gradient(KernelT &kernel, ArgsMapper &&argsMapper)¶: Constructor, takes a callable with non-standard signature the Argument Mapper function object that maps the parameters to concrete arguments for the quantum kernel.

template<typename KernelT, typename = std::enable_if_t<std::is_invocable_v<KernelT, std::vector<double>>>> inline gradient(KernelT &kernel)¶: Constructor, takes a callable that must have the prescribed call signature (void(std::vector<double>))

template<typename QuantumKernel, typename ArgsMapper> inline gradient(QuantumKernel &&kernel, ArgsMapper &&argsMapper)¶: Constructor, takes the quantum kernel with non-standard signature the Argument Mapper function object that maps the parameters to concrete arguments for the quantum kernel.

class parameter_shift : public cudaq::gradient ¶

Public Functions

inline virtual std::unique_ptr<cudaq::gradient> clone() override¶: Clone the object. Must be implemented by derived classes.

inline virtual void compute(const std::vector<double> &x, std::vector<double> &dx, const spin_op &h, double exp_h) override¶: Compute the current iterations gradient vector and update the provided vector<double reference (dx).

inline virtual std::vector<double> compute(const std::vector<double> &x, const std::function<double(std::vector<double>)> &func, double funcAtX) override¶: Compute the parameter_shift gradient for the arbitrary function, func, passed in by the user.

inline gradient(std::function<void(std::vector<double>)> &&kernel)¶: Constructor, takes the quantum kernel with prescribed signature.

gradient() = default¶: Empty constructor.

template<typename KernelT, typename ArgsMapper> inline gradient(KernelT &kernel, ArgsMapper &&argsMapper)¶: Constructor, takes a callable with non-standard signature the Argument Mapper function object that maps the parameters to concrete arguments for the quantum kernel.

template<typename KernelT, typename = std::enable_if_t<std::is_invocable_v<KernelT, std::vector<double>>>> inline gradient(KernelT &kernel)¶: Constructor, takes a callable that must have the prescribed call signature (void(std::vector<double>))

template<typename QuantumKernel, typename ArgsMapper> inline gradient(QuantumKernel &&kernel, ArgsMapper &&argsMapper)¶: Constructor, takes the quantum kernel with non-standard signature the Argument Mapper function object that maps the parameters to concrete arguments for the quantum kernel.

class forward_difference : public cudaq::gradient ¶

Compute the first order forward difference approximation for the gradient.

Public Functions

inline virtual std::unique_ptr<cudaq::gradient> clone() override¶: Clone the object. Must be implemented by derived classes.

inline virtual void compute(const std::vector<double> &x, std::vector<double> &dx, const spin_op &h, double funcAtX) override¶: Compute the forward_difference gradient.

inline virtual std::vector<double> compute(const std::vector<double> &x, const std::function<double(std::vector<double>)> &func, double funcAtX) override¶: Compute the forward_difference gradient for the arbitrary function, func, passed in by the user.

inline gradient(std::function<void(std::vector<double>)> &&kernel)¶: Constructor, takes the quantum kernel with prescribed signature.

gradient() = default¶: Empty constructor.

template<typename KernelT, typename ArgsMapper> inline gradient(KernelT &kernel, ArgsMapper &&argsMapper)¶: Constructor, takes a callable with non-standard signature the Argument Mapper function object that maps the parameters to concrete arguments for the quantum kernel.

template<typename KernelT, typename = std::enable_if_t<std::is_invocable_v<KernelT, std::vector<double>>>> inline gradient(KernelT &kernel)¶: Constructor, takes a callable that must have the prescribed call signature (void(std::vector<double>))

template<typename QuantumKernel, typename ArgsMapper> inline gradient(QuantumKernel &&kernel, ArgsMapper &&argsMapper)¶: Constructor, takes the quantum kernel with non-standard signature the Argument Mapper function object that maps the parameters to concrete arguments for the quantum kernel.

Platform¶

class QPU : public cudaq::registry::RegisteredType<QPU>¶

A CUDA-Q QPU is an abstraction on the quantum processing unit which executes quantum kernel expressions. The QPU exposes certain information about the QPU being targeting, such as the number of available qubits, the logical ID for this QPU in a set of available QPUs, and its qubit connectivity. The QPU keeps track of an execution queue for enqueuing asynchronous tasks that execute quantum kernel expressions. The QPU also tracks the client-provided execution context to enable quantum kernel related tasks such as sampling and observation.

This type is meant to be subtyped by concrete quantum_platform subtypes.

Subclassed by cudaq::BaseRemoteRESTQPU, cudaq::BaseRemoteSimulatorQPU, cudaq::OrcaRemoteRESTQPU

Public Functions

inline QPU()¶: The constructor, initializes the execution queue.

inline QPU(std::size_t _qpuId)¶: The constructor, sets the current QPU Id and initializes the execution queue

QPU(QPU&&) = default¶: Move constructor.

virtual ~QPU() = default¶: The destructor.

inline void setId(std::size_t _qpuId)¶: Set the current QPU Id.

inline std::thread::id getExecutionThreadId() const¶: Get id of the thread this QPU’s queue executes on.

inline std::size_t getNumQubits()¶: Return the number of qubits.

inline auto getConnectivity()¶: Return the qubit connectivity.

inline virtual bool isSimulator()¶: Is this QPU a simulator ?

inline virtual bool supportsConditionalFeedback()¶: Return whether this QPU has conditional feedback support.

inline virtual bool supportsExplicitMeasurements()¶: Return whether this QPU supports explicit measurements.

inline virtual RemoteCapabilities getRemoteCapabilities() const¶: Return the remote capabilities for this platform.

inline virtual void setShots(int _nShots)¶: Base class handling of shots is do-nothing, subclasses can handle as they wish

inline virtual bool isEmulated()¶: Is this a local emulator of a remote QPU?

virtual void enqueue(QuantumTask &task) = 0¶: Enqueue a quantum task on the asynchronous execution queue.

virtual void setExecutionContext(ExecutionContext *context) = 0¶: Set the execution context, meant for subtype specification.

virtual void resetExecutionContext() = 0¶: Reset the execution context, meant for subtype specification.

virtual KernelThunkResultType launchKernel(const std::string &name, KernelThunkType kernelFunc, void *args, std::uint64_t, std::uint64_t, const std::vector<void*> &rawArgs) = 0¶: Launch the kernel with given name (to extract its Quake representation). The raw function pointer is also provided, as are the runtime arguments, as a struct-packed void pointer and its corresponding size.

inline virtual void launchKernel(const std::string &name, const std::vector<void*> &rawArgs)¶: Launch the kernel with given name and argument arrays.

inline virtual void launchSerializedCodeExecution(const std::string &name, cudaq::SerializedCodeExecutionContext &serializeCodeExecutionObject)¶: Launch serialized code for remote execution. Subtypes that support this should override this function.

inline virtual void onRandomSeedSet(std::size_t seed)¶: Notify the QPU that a new random seed value is set. By default do nothing, let subclasses override.

class BaseRemoteRESTQPU : public cudaq::QPU ¶: Subclassed by cudaq::FermioniqBaseQPU, cudaq::PasqalBaseQPU, cudaq::QuEraBaseQPU

class BaseRemoteSimulatorQPU : public cudaq::QPU ¶: Subclassed by cudaq::BaseNvcfSimulatorQPU

class BaseNvcfSimulatorQPU : public cudaq::BaseRemoteSimulatorQPU ¶: Implementation of base QPU subtype that submits simulation request to NVCF.

class FermioniqBaseQPU : public cudaq::BaseRemoteRESTQPU ¶: The FermioniqBaseQPU is a QPU that allows users to.

class OrcaRemoteRESTQPU : public cudaq::QPU ¶: The OrcaRemoteRESTQPU is a subtype of QPU that enables the execution of CUDA-Q kernels on remotely hosted quantum computing services via a REST Client / Server interaction. This type is meant to be general enough to support any remotely hosted service. Moreover, this QPU handles launching kernels under the Execution Context that includes sampling via synchronous client invocations.

class PasqalBaseQPU : public cudaq::BaseRemoteRESTQPU ¶: The PasqalBaseQPU is a QPU that allows users to submit kernels to the Pasqal machine.

class QuEraBaseQPU : public cudaq::BaseRemoteRESTQPU ¶: The QuEraBaseQPU is a QPU that allows users to.

class quantum_platform¶

The quantum_platform corresponds to a specific quantum architecture. The quantum_platform exposes a public API for programmers to query specific information about the targeted QPU(s) (e.g. number of qubits, qubit connectivity, etc.). This type is meant to be subclassed for concrete realizations of quantum platforms, which are intended to populate this platformQPUs member of this base class.

Public Functions

std::optional<QubitConnectivity> connectivity()¶: Fetch the connectivity info.

std::size_t get_num_qubits()¶: Get the number of qubits for the current QPU.

inline virtual bool supports_task_distribution() const¶: Return true if this platform exposes multiple QPUs and supports parallel distribution of quantum tasks.

std::size_t get_num_qubits(std::size_t qpu_id)¶: Get the number of qubits for the QPU with ID qpu_id.

inline std::optional<int> get_shots()¶: Getter for the shots. This will be deprecated once set_shots and clear_shots are removed.

inline virtual void set_shots(int numShots)¶: Setter for the shots.

inline virtual void clear_shots()¶: Reset shots.

void set_exec_ctx(cudaq::ExecutionContext *ctx, std::size_t qpu_id = 0)¶: Specify the execution context for this platform.

inline ExecutionContext *get_exec_ctx() const¶: Return the current execution context.

void reset_exec_ctx(std::size_t qpu_id = 0)¶: Reset the execution context for this platform.

inline std::size_t num_qpus() const¶: Get the number of QPUs available with this platform.

bool is_simulator(const std::size_t qpu_id = 0) const¶: Return whether this platform is simulating the architecture.

bool supports_conditional_feedback(const std::size_t qpu_id = 0) const¶: Return whether the QPU has conditional feedback support.

bool supports_explicit_measurements(const std::size_t qpu_id = 0) const¶: Return whether the QPU supports explicit measurements.

inline std::string name() const¶: The name of the platform, which also corresponds to the name of the platform file.

std::size_t get_current_qpu()¶: Get the ID of the current QPU.

void set_current_qpu(const std::size_t device_id)¶: Set the current QPU via its device ID.

bool is_remote(const std::size_t qpuId = 0)¶: Return true if the QPU is remote.

bool is_emulated(const std::size_t qpuId = 0) const¶: Return true if QPU is locally emulating a remote QPU.

void set_noise(const noise_model *model)¶: Set the noise model for future invocations of quantum kernels.

const noise_model *get_noise()¶: Return the current noise model or nullptr if none set.

RemoteCapabilities get_remote_capabilities(const std::size_t qpuId = 0) const¶: Get the remote capabilities (only applicable for remote platforms)

void reset_noise()¶: Turn off any noise models.

std::future<sample_result> enqueueAsyncTask(const std::size_t qpu_id, KernelExecutionTask &t)¶: Enqueue an asynchronous sampling task.

void enqueueAsyncTask(const std::size_t qpu_id, std::function<void()> &f)¶: Enqueue a general task that runs on the specified QPU.

void launchVQE(const std::string kernelName, const void *kernelArgs, cudaq::gradient *gradient, const cudaq::spin_op &H, cudaq::optimizer &optimizer, const int n_params, const std::size_t shots)¶: Launch a VQE operation on the platform.

inline virtual void setTargetBackend(const std::string &name)¶

Set the target backend, by default do nothing, let subclasses override.

Parameters:: name –

virtual void onRandomSeedSet(std::size_t seed)¶: Called by the runtime to notify that a new random seed value is set.

void resetLogStream()¶: Turn off any custom logging stream.

std::ostream *getLogStream()¶: Get the stream for info logging.

void setLogStream(std::ostream &logStream)¶: Set the info logging stream.

Public Static Functions

static std::vector<std::string> list_platforms()¶: List all available platforms.

struct RemoteCapabilities¶

A structure of boolean fields to indicate whether a given remote server has specific capabilities.

Public Functions

inline RemoteCapabilities(bool initValue)¶: Constructor that broadcasts initValue to all fields.

Public Members

bool stateOverlap = false¶: True if the remote can perform state overlap operations.

bool serializedCodeExec = false¶: True if the remote can perform serialized code execution (raw Python commands).

bool vqe = false¶: True if the remote can perform an entire VQE operation without and back-and-forth client/server communications.

bool isRemoteSimulator = false¶: True if execution is performed on a remote simulator - i.e. IR generation (including synthesis) and execution are performed in different processes.

class SerializedCodeExecutionContext¶: The SerializedCodeExecutionContext is an abstraction to indicate how a serialized code should be executed.

using cudaq::QuantumTask = std::function<void()>¶: The QuantumTask is ultimately what gets added to the execution queue. It is meant to wrap any Sampling or Observe task with an appropriate std::promise instance being provided and set.

using cudaq::QubitConnectivity = std::vector<QubitEdge>¶

using cudaq::QubitEdge = std::pair<std::size_t, std::size_t>¶: Typedefs for defining the connectivity structure of a QPU.

using cudaq::KernelExecutionTask = std::function<sample_result()>¶: A sampling tasks takes no input arguments and returns a sample_result instance.

struct KernelThunkResultType¶: A kernel may return results dynamically if the size of the result is not a constant at compile-time.

using cudaq::KernelThunkType = KernelThunkResultType (*)(void*, bool)¶: The universal signature of a kernel thunk.

Utilities¶

using cudaq::complex = std::complex<real>¶

using cudaq::real = double¶

inline std::vector<std::size_t> cudaq::range(std::size_t N)¶: Return a vector of unsigned integers. The first element is zero, and the remaining elements are all values incremented by 1 to the total size value provided (exclusive).

Namespaces¶

namespace cudaq¶

int cudaq::num_available_gpus()¶: The number of available GPUs.

void cudaq::set_random_seed(std::size_t seed)¶: Set a seed for any random number generators used in backend simulations.

void cudaq::set_noise(const cudaq::noise_model &model)¶: Set a custom noise model for simulation. The caller must also call cudaq::unset_noise before model gets deallocated or goes out of scope.

void cudaq::unset_noise()¶: Remove an existing noise model from simulation.

namespace details¶

namespace registry¶

namespace mpi¶

void cudaq::mpi::initialize()¶: Initialize MPI if available. This function is a no-op if there CUDA-Q has not been built against MPI.

void cudaq::mpi::initialize(int argc, char **argv)¶: Initialize MPI if available. This function is a no-op if there CUDA-Q has not been built against MPI. Takes program arguments as input.

bool cudaq::mpi::is_initialized()¶: Return true if MPI is already initialized, false otherwise.

void cudaq::mpi::finalize()¶: Finalize MPI. This function is a no-op if there CUDA-Q has not been built against MPI.

int cudaq::mpi::rank()¶: Return the rank of the calling process.

int cudaq::mpi::num_ranks()¶: Return the number of MPI ranks.

void cudaq::mpi::all_gather(std::vector<double> &global, const std::vector<double> &local)¶

Gather all vector data (floating point numbers) locally into the provided global vector.

Global vector must be sized to fit all vector elements coming from individual ranks.

void cudaq::mpi::all_gather(std::vector<int> &global, const std::vector<int> &local)¶

Gather all vector data (integers) locally into the provided global vector.

Global vector must be sized to fit all vector elements coming from individual ranks.

template<typename T, typename Func> T cudaq::mpi::all_reduce(const T&, const Func&)¶

template<typename T, typename BinaryFunction> T cudaq::mpi::all_reduce(const T &localValue, const BinaryFunction &function)¶: Reduce all values across ranks with the specified binary function.

void cudaq::mpi::broadcast(std::vector<double> &data, int rootRank)¶: Broadcast a vector from a process (rootRank) to all other processes.

void cudaq::mpi::broadcast(std::string &data, int rootRank)¶: Broadcast a string from a process (rootRank) to all other processes.

namespace orca¶

cudaq::sample_result cudaq::orca::sample(std::vector<std::size_t> &input_state, std::vector<std::size_t> &loop_lengths, std::vector<double> &bs_angles, int n_samples = 10000, std::size_t qpu_id = 0)¶

cudaq::sample_result cudaq::orca::sample(std::vector<std::size_t> &input_state, std::vector<std::size_t> &loop_lengths, std::vector<double> &bs_angles, std::vector<double> &ps_angles, int n_samples = 10000, std::size_t qpu_id = 0)¶: Implementation of the sample method of the cudaq::orca namespace.

async_sample_result cudaq::orca::sample_async(std::vector<std::size_t> &input_state, std::vector<std::size_t> &loop_lengths, std::vector<double> &bs_angles, int n_samples = 10000, std::size_t qpu_id = 0)¶

async_sample_result cudaq::orca::sample_async(std::vector<std::size_t> &input_state, std::vector<std::size_t> &loop_lengths, std::vector<double> &bs_angles, std::vector<double> &ps_angles, int n_samples = 10000, std::size_t qpu_id = 0)¶