CUDA-Q Solvers C++ API

class operator_pool : public cudaqx::extension_point<operator_pool>

Interface for generating quantum operator pools used in quantum algorithms.

This class extends the extension_point template, allowing for runtime extensibility.

Subclassed by cudaq::solvers::qaoa_pool, cudaq::solvers::spin_complement_gsd, cudaq::solvers::uccsd

Public Functions

operator_pool() = default: Default constructor.

inline virtual ~operator_pool(): Virtual destructor to ensure proper cleanup of derived classes.

virtual std::vector<cudaq::spin_op> generate(const heterogeneous_map &config) const = 0

Generate a vector of spin operators based on the provided configuration.

Parameters:: config – A heterogeneous map containing configuration parameters for operator generation.
Returns:: A vector of cudaq::spin_op objects representing the generated operator pool.

class spin_complement_gsd : public cudaq::solvers::operator_pool : Test.

class uccsd : public cudaq::solvers::operator_pool : Test.

class qaoa_pool : public cudaq::solvers::operator_pool : Test.

struct atom: Represents an atom with a name and 3D coordinates.

class molecular_geometry

Represents the geometry of a molecule as a collection of atoms.

Public Functions

inline molecular_geometry(std::initializer_list<atom> &&args)

Constructor using initializer list.

Parameters:: args – Initializer list of atoms

inline molecular_geometry(const std::vector<atom> &args)

Constructor using vector of atoms.

Parameters:: args – Vector of atoms

inline std::size_t size() const

Get the number of atoms in the molecule.

Returns:: Size of the molecule

inline auto begin()

Get iterator to the beginning of atoms.

Returns:: Iterator to the beginning

inline auto end()

Get iterator to the end of atoms.

Returns:: Iterator to the end

inline auto begin() const

Get const iterator to the beginning of atoms.

Returns:: Const iterator to the beginning

inline auto end() const

Get const iterator to the end of atoms.

Returns:: Const iterator to the end

std::string name() const

Get the name of the molecule.

Returns:: Name of the molecule

Public Static Functions

static molecular_geometry from_xyz(const std::string &xyzFile)

Create a molecular geometry from an XYZ file.

Parameters:: xyzFile – Path to the XYZ file
Returns:: Molecular geometry object

struct molecular_hamiltonian

Represents a molecular Hamiltonian in both spin and fermionic forms.

Public Members

cudaq::spin_op hamiltonian: The molecular Hamiltonian represented as a spin operator.

cudaqx::tensor hpq

One-electron integrals tensor.

Represents the one-body terms in the second quantized Hamiltonian

cudaqx::tensor hpqrs

Two-electron integrals tensor.

Represents the two-body terms in the second quantized Hamiltonian

std::size_t n_electrons: Number of electrons in the molecule.

std::size_t n_orbitals: Number of orbitals (or spatial orbitals) in the basis set.

std::unordered_map<std::string, double> energies

Map of various energy contributions.

Keys may include “nuclear_repulsion”, “hf”, “mp2”, “ccsd”, etc.

struct molecule_options

Options for molecule creation and calculation.

Public Functions

void dump(): Dump the options to output.

Public Members

std::string driver = "RESTPySCFDriver": Driver for the quantum chemistry calculations default “RESTPySCFDriver”.

std::string fermion_to_spin = "jordan_wigner": Method for mapping fermionic operators to qubit operators default “jordan_wigner”.

std::string type = "gas_phase": Type of molecular system default “gas_phase”.

bool symmetry = false: Whether to use symmetry in calculations default false.

double memory = 4000.: Amount of memory to allocate for calculations (in MB) default 4000.0.

std::size_t cycles = 100: Maximum number of SCF cycles default 100.

std::string initguess = "minao": Initial guess method for SCF calculations default “minao”.

bool UR = false: Whether to use unrestricted calculations default false.

std::optional<std::size_t> nele_cas = std::nullopt: Number of electrons in the active space for CAS calculations default std::nullopt (not set)

std::optional<std::size_t> norb_cas = std::nullopt: Number of orbitals in the active space for CAS calculations default std::nullopt (not set)

bool MP2 = false: Whether to perform MP2 calculations default false.

bool natorb = false: Whether to use natural orbitals default false.

bool casci = false: Whether to perform CASCI calculations default false.

bool ccsd = false: Whether to perform CCSD calculations default false.

bool casscf = false: Whether to perform CASSCF calculations default false.

bool integrals_natorb = false: Whether to use natural orbitals for integrals default false.

bool integrals_casscf = false: Whether to use CASSCF orbitals for integrals default false.

std::optional<std::string> potfile = std::nullopt: Path to the potential file (if applicable) default std::nullopt (not set)

bool verbose = false: Whether to enable verbose output default false.

molecular_hamiltonian cudaq::solvers::create_molecule(const molecular_geometry &geometry, const std::string &basis, int spin, int charge, molecule_options options = molecule_options())

Create a molecular Hamiltonian.

Parameters:

geometry – Molecular geometry
basis – Basis set
spin – Spin of the molecule
charge – Charge of the molecule
options – Molecule options

Returns:

Molecular Hamiltonian

cudaq::spin_op cudaq::solvers::get_maxcut_hamiltonian(const cudaqx::graph &graph)

Generates a quantum Hamiltonian for the Maximum Cut problem.

This function constructs a spin Hamiltonian whose ground state corresponds to the maximum cut in the input graph. The Hamiltonian is constructed such that its ground state represents a partition of the graph’s vertices into two sets that maximizes the sum of weights of edges crossing between the sets.

The Hamiltonian takes the form: H = Σ_{(i,j)∈E} w_{ij}/2(Z_iZ_j - I) where:

E is the set of edges in the graph
w_{ij} is the weight of edge (i,j)
Z_i is the Pauli Z operator on qubit i
I is the identity operator

For an unweighted graph, all w_{ij} = 1.0

The resulting Hamiltonian has the following properties:

Each qubit represents a vertex in the graph
Z_i = +1 assigns vertex i to one partition
Z_i = -1 assigns vertex i to the other partition
The ground state energy corresponds to the negative of the maximum cut value

Note

The Hamiltonian is constructed to be symmetric under global spin flip, reflecting the symmetry of the MaxCut problem under swapping the partitions

Parameters:: graph – The input graph to find the maximum cut in
Returns:: cudaq::spin_op The quantum Hamiltonian for the MaxCut problem

cudaq::spin_op cudaq::solvers::get_clique_hamiltonian(const cudaqx::graph &graph, double penalty = 4.0)

Generates a quantum Hamiltonian for the Maximum Clique problem.

This function constructs a spin Hamiltonian whose ground state corresponds to the maximum clique in the input graph. The Hamiltonian consists of two terms:

A node term that rewards including nodes in the clique
A penalty term that enforces the clique constraint (all selected nodes must be connected)

The Hamiltonian takes the form: H = Σ_i w_i/2(Z_i - I) + p/4 Σ_{(i,j) ∉ E} (Z_iZ_j - Z_i - Z_j + I) where:

w_i is the weight of node i
p is the penalty strength
E is the set of edges in the graph

Note

The penalty parameter should be chosen large enough to ensure that invalid solutions (non-cliques) have higher energy than valid solutions

Parameters:

graph – The input graph to find the maximum clique in
penalty – The penalty strength for violating clique constraints (default: 4.0)

Returns:

cudaq::spin_op The quantum Hamiltonian for the Maximum Clique problem

cudaq::spin_op cudaq::solvers::one_particle_op(std::size_t numQubits, std::size_t p, std::size_t q, const std::string fermionCompiler = "jordan_wigner")

Create a one-particle operator.

Parameters:

numQubits – Number of qubits
p – First orbital index
q – Second orbital index
fermionCompiler – Fermion-to-qubit mapping method

Returns:

One-particle operator as a spin operator

using cudaq::ParameterizedKernel = std::function<void(std::vector<double>)>: Parameterized kernels for observe optimization must take on this signature - take a vector of double and return void.

using cudaq::optim::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 optimizable_function: An optimizable_function wraps a user-provided objective function to be optimized.

class optimizer : public cudaqx::extension_point<optimizer>

The 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.).

Subclassed by cudaq::optim::cobyla, cudaq::optim::lbfgs

Public Functions

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

inline virtual optimization_result optimize(std::size_t dim, const optimizable_function &opt_function): 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.

virtual optimization_result optimize(std::size_t dim, const optimizable_function &opt_function, const heterogeneous_map &options) = 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. Optionally provide optimizer options.

Public Members

std::vector<optimization_result> history: Return the optimization history, e.g. the value and parameters found for each iteration of the optimization.

class cobyla : public cudaq::optim::optimizer : The.

class lbfgs : public cudaq::optim::optimizer : The limited-memory Broyden-Fletcher-Goldfarb-Shanno gradient based black-box function optimizer.

class observe_gradient : public cudaqx::extension_point<observe_gradient, const ParameterizedKernel&, const spin_op&>

The observe_gradient provides an extension point for developers to inject custom gradient strategies to be used in global optimization of expectation values in typical quantum variational tasks.

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

Public Functions

inline observe_gradient(const ParameterizedKernel &functor, const spin_op &op): The constructor.

inline void compute(const std::vector<double> &x, std::vector<double> &dx, double expectationAtX, int inShots = -1): Compute the gradient at the given multi-dimensional point. The gradient vector is provided as a non-const reference, subtypes therefore should update the vector in place. This delegates to specific subtype implementations. It tracks the number of expectations that need to be computed, and executes them as a batch (e.g. allocates the state once, zeros the state between each iteration instead of deallocating).

Public Members

std::vector<observe_iteration> data: Storage for all data produced during gradient computation.

struct observe_iteration: Storage type for a single observe iteration. Keeps track of the parameters evaluated at, the result of the observation (shots data and expectations), and the type of the execution.

class central_difference : public cudaq::observe_gradient 

class forward_difference : public cudaq::observe_gradient 

class parameter_shift : public cudaq::observe_gradient 

enum class cudaq::observe_execution_type

Observe executions can be used for function evaluation or gradient evaluation. This enumeration allows us to distinguish these execution types.

Values:

enumerator function

enumerator gradient

struct vqe_result: A vqe_result encapsulates all the data produced by a standard variational quantum eigensolver execution. It provides the programmer with the optimal energy and parameters as well as a list of all execution data at each iteration.

template<typename QuantumKernel> static inline vqe_result cudaq::solvers::vqe(QuantumKernel &&kernel, const spin_op &hamiltonian, const std::string &optName, const std::string &gradName, const std::vector<double> &initial_parameters, heterogeneous_map options = heterogeneous_map()): Overloaded VQE function using string-based optimizer and gradient selection.

template<typename QuantumKernel> static inline vqe_result cudaq::solvers::vqe(QuantumKernel &&kernel, const spin_op &hamiltonian, const std::string &optName, const std::vector<double> &initial_parameters, heterogeneous_map options = heterogeneous_map()): Overloaded VQE function using string-based optimizer selection without gradient.

template<typename QuantumKernel> static inline vqe_result cudaq::solvers::vqe(QuantumKernel &&kernel, const spin_op &hamiltonian, const std::string &optName, observe_gradient &gradient, const std::vector<double> &initial_parameters, heterogeneous_map options = heterogeneous_map()): Overloaded VQE function using string-based optimizer and provided gradient object.

template<typename QuantumKernel> static inline vqe_result cudaq::solvers::vqe(QuantumKernel &&kernel, const spin_op &hamiltonian, optim::optimizer &optimizer, const std::string &gradName, const std::vector<double> &initial_parameters, heterogeneous_map options = heterogeneous_map()): Overloaded VQE function using provided optimizer and string-based gradient selection.

template<typename QuantumKernel> static inline vqe_result cudaq::solvers::vqe(QuantumKernel &&kernel, const spin_op &hamiltonian, optim::optimizer &optimizer, const std::vector<double> &initial_parameters, heterogeneous_map options = heterogeneous_map()): Overloaded VQE function using provided optimizer without gradient.

template<typename QuantumKernel> static inline vqe_result cudaq::solvers::vqe(QuantumKernel &&kernel, const spin_op &hamiltonian, optim::optimizer &optimizer, observe_gradient &gradient, const std::vector<double> &initial_parameters, heterogeneous_map options = heterogeneous_map())

Compute the minimal eigenvalue of the given Hamiltonian with VQE.

Given a quantum kernel of signature void(std::vector<double>), run the variational quantum eigensolver routine to compute the minimum eigenvalue of the specified hermitian spin_op.

Template Parameters:

QuantumKernel – Type of the quantum kernel

Parameters:

kernel – Quantum kernel to be optimized
hamiltonian – Spin operator representing the Hamiltonian
optimizer – Optimization algorithm to use
gradient – Gradient computation method
initial_parameters – Initial parameters for the optimization
options – Additional options for the VQE algorithm

Returns:

VQE result containing optimal energy, parameters, and iteration data

using cudaq::solvers::adapt::result = std::tuple<double, std::vector<double>, std::vector<cudaq::spin_op>>

Result type for ADAPT-VQE algorithm

Return:

Tuple containing:

Final energy (double)
Optimized parameters (vector of doubles)
Selected operators (vector of cudaq::spin_op)

static inline adapt::result cudaq::solvers::adapt_vqe(const cudaq::qkernel<void(cudaq::qvector<>&)> &initialState, const spin_op &H, const std::vector<spin_op> &poolList, const heterogeneous_map options = heterogeneous_map())

Run ADAPT-VQE algorithm with default optimizer.

Parameters:

initialState – Initial state preparation quantum kernel
H – Hamiltonian operator
poolList – Pool of operators
options – Additional options for the algorithm

Returns:

Result of the ADAPT-VQE algorithm

static inline adapt::result cudaq::solvers::adapt_vqe(const cudaq::qkernel<void(cudaq::qvector<>&)> &initialState, const spin_op &H, const std::vector<spin_op> &poolList, const optim::optimizer &optimizer, const heterogeneous_map options = heterogeneous_map())

Run ADAPT-VQE algorithm with custom optimizer.

Parameters:

initialState – Initial state preparation quantum kernel
H – Hamiltonian operator
poolList – Pool of operators
optimizer – Custom optimization algorithm
options – Additional options for the algorithm

Returns:

Result of the ADAPT-VQE algorithm

static inline adapt::result cudaq::solvers::adapt_vqe(const cudaq::qkernel<void(cudaq::qvector<>&)> &initialState, const spin_op &H, const std::vector<spin_op> &poolList, const optim::optimizer &optimizer, const std::string &gradient, const heterogeneous_map options = heterogeneous_map())

Run ADAPT-VQE algorithm with custom optimizer and gradient method.

Parameters:

initialState – Initial state preparation quantum kernel
H – Hamiltonian operator
poolList – Pool of operators
optimizer – Custom optimization algorithm
gradient – Gradient calculation method
options – Additional options for the algorithm

Returns:

Result of the ADAPT-VQE algorithm

using cudaq::solvers::stateprep::excitation_list = std::vector<std::vector<std::size_t>>: Represents a list of excitations.

std::tuple<excitation_list, excitation_list, excitation_list, excitation_list, excitation_list> cudaq::solvers::stateprep::get_uccsd_excitations(std::size_t numElectrons, std::size_t numQubits, std::size_t spin = 0)

Get UCCSD excitations for a given system.

Parameters:

numElectrons – Number of electrons in the system
numQubits – Number of qubits in the system
spin – Spin of the system

Returns:

Tuple containing five excitation lists

std::size_t cudaq::solvers::stateprep::get_num_uccsd_parameters(std::size_t numElectrons, std::size_t numQubits, std::size_t spin = 0)

Calculate the number of UCCSD parameters.

Parameters:

numElectrons – Number of electrons in the system
numQubits – Number of qubits in the system
spin – Spin of the system (default 0)

Returns:

Number of UCCSD parameters

void cudaq::solvers::stateprep::single_excitation(cudaq::qview<> qubits, double theta, std::size_t p_occ, std::size_t q_virt)

Perform a single excitation operation.

This function is a pure-device CUDA-Q quantum kernel. It cannot be invoked from host. It can only be invoked from other CUDA-Q kernel code.

Parameters:

qubits – Qubit register
theta – Rotation angle
p_occ – Occupied orbital index
q_virt – Virtual orbital index

void cudaq::solvers::stateprep::double_excitation(cudaq::qview<> qubits, double theta, std::size_t p_occ, std::size_t q_occ, std::size_t r_virt, std::size_t s_virt)

Perform a double excitation operation.

This function is a pure-device CUDA-Q quantum kernel. It cannot be invoked from host. It can only be invoked from other CUDA-Q kernel code.

Parameters:

qubits – Qubit register
theta – Rotation angle
p_occ – First occupied orbital index
q_occ – Second occupied orbital index
r_virt – First virtual orbital index
s_virt – Second virtual orbital index

void cudaq::solvers::stateprep::uccsd(cudaq::qview<> qubits, const std::vector<double> &thetas, std::size_t numElectrons, std::size_t spin)

Apply UCCSD ansatz to a qubit register.

This function is a pure-device CUDA-Q quantum kernel. It cannot be invoked from host. It can only be invoked from other CUDA-Q kernel code.

Parameters:

qubits – Qubit register
thetas – Vector of rotation angles
numElectrons – Number of electrons in the system
spin – Spin of the system

void cudaq::solvers::stateprep::uccsd(cudaq::qview<> qubits, const std::vector<double> &thetas, std::size_t numElectrons)

Apply UCCSD ansatz to a qubit vector.

This function is a pure-device CUDA-Q quantum kernel. It cannot be invoked from host. It can only be invoked from other CUDA-Q kernel code.

Parameters:

qubits – Qubit vector
thetas – Vector of rotation angles
numElectrons – Number of electrons in the system

struct qaoa_result

Result structure for QAOA optimization.

Public Members

double optimal_value = 0.0: The optimal value found by the QAOA algorithm.

std::vector<double> optimal_parameters: The optimal variational parameters that achieved the optimal value.

cudaq::sample_result optimal_config: The measurement results for the optimal circuit configuration.

qaoa_result cudaq::solvers::qaoa(const cudaq::spin_op &problemHamiltonian, const cudaq::spin_op &referenceHamiltonian, const optim::optimizer &optimizer, std::size_t numLayers, const std::vector<double> &initialParameters, const heterogeneous_map options = {})

Execute the Quantum Approximate Optimization Algorithm (QAOA) with custom mixing Hamiltonian.

Note

User can provide the following options - {“counterdiabatic”, true/false} to run Digitized-Counterdiabatic QAOA (adds Ry rotations after QAOA single layer)

Parameters:

problemHamiltonian – The cost Hamiltonian encoding the optimization problem
referenceHamiltonian – The mixing Hamiltonian for the QAOA evolution (typically X-rotation terms)
optimizer – The classical optimizer to use for parameter optimization
numLayers – The number of QAOA layers (p-value)
initialParameters – Initial guess for the variational parameters
options – Additional algorithm options passed as key-value pairs

Returns:

qaoa_result containing the optimization results

qaoa_result cudaq::solvers::qaoa(const cudaq::spin_op &problemHamiltonian, const optim::optimizer &optimizer, std::size_t numLayers, const std::vector<double> &initialParameters, const heterogeneous_map options = {})

Execute QAOA with default transverse field mixing Hamiltonian.

Note

User can provide the following options - {“counterdiabatic”, true/false} to run Digitized-Counterdiabatic QAOA (adds Ry rotations after QAOA single layer)

Parameters:

problemHamiltonian – The cost Hamiltonian encoding the optimization problem
optimizer – The classical optimizer to use for parameter optimization
numLayers – The number of QAOA layers (p-value)
initialParameters – Initial guess for the variational parameters
options – Additional algorithm options passed as key-value pairs

Returns:

qaoa_result containing the optimization results

qaoa_result cudaq::solvers::qaoa(const cudaq::spin_op &problemHamiltonian, std::size_t numLayers, const std::vector<double> &initialParameters, const heterogeneous_map options = {})

Execute QAOA with default optimizer and mixing Hamiltonian.

Note

User can provide the following options - {“counterdiabatic”, true/false} to run Digitized-Counterdiabatic QAOA (adds Ry rotations after QAOA single layer)

Parameters:

problemHamiltonian – The cost Hamiltonian encoding the optimization problem
numLayers – The number of QAOA layers (p-value)
initialParameters – Initial guess for the variational parameters be size 2*numLayers)
options – Additional algorithm options passed as key-value pairs

Returns:

qaoa_result containing the optimization results

qaoa_result cudaq::solvers::qaoa(const cudaq::spin_op &problemHamiltonian, const cudaq::spin_op &referenceHamiltonian, std::size_t numLayers, const std::vector<double> &initialParameters, const heterogeneous_map options = {})

Execute the Quantum Approximate Optimization Algorithm (QAOA) with custom mixing Hamiltonian.

Note

User can provide the following options - {“counterdiabatic”, true/false} to run Digitized-Counterdiabatic QAOA (adds Ry rotations after QAOA single layer)

Parameters:

problemHamiltonian – The cost Hamiltonian encoding the optimization problem
referenceHamiltonian – The mixing Hamiltonian for the QAOA evolution (typically X-rotation terms)
numLayers – The number of QAOA layers (p-value)
initialParameters – Initial guess for the variational parameters
options – Additional algorithm options passed as key-value pairs

Returns:

qaoa_result containing the optimization results

std::size_t cudaq::solvers::get_num_qaoa_parameters(const cudaq::spin_op &problemHamiltonian, const cudaq::spin_op &referenceHamiltonian, std::size_t numLayers, const heterogeneous_map options = {})

Calculate the number of variational parameters needed for QAOA with custom mixing Hamiltonian.

This function determines the total number of variational parameters required for QAOA execution based on the problem setup and options. When full_parameterization is true, an angle will be used for every term in both the problem and reference Hamiltonians. Otherwise, one angle per layer is used for each Hamiltonian.

Parameters:

problemHamiltonian – The cost Hamiltonian encoding the optimization problem
referenceHamiltonian – The mixing Hamiltonian for the QAOA evolution
numLayers – The number of QAOA layers (p-value)
options – Additional algorithm options:
- ”full_parameterization”: bool - Use individual angles for each Hamiltonian term
- ”counterdiabatic”: bool - Enable counterdiabatic QAOA variant, adds an Ry to every qubit in the system with its own angle to optimize.

Returns:

The total number of variational parameters needed

std::size_t cudaq::solvers::get_num_qaoa_parameters(const cudaq::spin_op &problemHamiltonian, std::size_t numLayers, const heterogeneous_map options = {})

Calculate the number of variational parameters needed for QAOA with default mixing Hamiltonian.

This function determines the total number of variational parameters required for QAOA execution using the default transverse field mixing Hamiltonian. When full_parameterization is true, an angle will be used for every term in both the problem and reference Hamiltonians. Otherwise, one angle per layer is used for each Hamiltonian.

Parameters:

problemHamiltonian – The cost Hamiltonian encoding the optimization problem
numLayers – The number of QAOA layers (p-value)
options – Additional algorithm options:
- ”full_parameterization”: bool - Use individual angles for each Hamiltonian term
- ”counterdiabatic”: bool - Enable counterdiabatic QAOA variant, adds an Ry to every qubit in the system with its own angle to optimize.

Returns:

The total number of variational parameters needed