From 27e0eb09bb69ab49169d6669da7cdf300038c905 Mon Sep 17 00:00:00 2001 From: marwafar Date: Wed, 5 Nov 2025 22:32:05 +0000 Subject: [PATCH 1/4] add uccgsd to introduction.rst Signed-off-by: marwafar --- .../components/solvers/introduction.rst | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/docs/sphinx/components/solvers/introduction.rst b/docs/sphinx/components/solvers/introduction.rst index 3bd0c869..bd0cbb71 100644 --- a/docs/sphinx/components/solvers/introduction.rst +++ b/docs/sphinx/components/solvers/introduction.rst @@ -497,6 +497,7 @@ CUDA-QX provides several pre-built operator pools for ADAPT-VQE: * **spin_complement_gsd**: Spin-complemented generalized singles and doubles * **uccsd**: UCCSD operators +* **uccgsd**: UCC generalized singles and doubles * **qaoa**: QAOA mixer excitation operators .. code-block:: python @@ -513,6 +514,58 @@ CUDA-QX provides several pre-built operator pools for ADAPT-VQE: num_electrons=molecule.n_electrons ) + uccgsd_ops = solvers.get_operator_pool( + "uccgsd", + num_orbitals=molecule.n_orbitals + ) + +Available Ansatz +^^^^^^^^^^^^^^^^^^ + +CUDA-QX provides several state preparations ansatz for VQE. + +* **uccsd**: UCCSD operators +* **uccgsd**: UCC generalized singles and doubles + +.. code-block:: python + + # Using UCCSD ansatz + geometry = [('H', (0., 0., 0.)), ('H', (0., 0., .7474))] + molecule = solvers.create_molecule(geometry, 'sto-3g', 0, 0, casci=True) + + numQubits = molecule.n_orbitals * 2 + numElectrons = molecule.n_electrons + spin = 0 + + @cudaq.kernel + def ansatz(thetas: list[float]): + q = cudaq.qvector(numQubits) + for i in range(numElectrons): + x(q[i]) + solvers.stateprep.uccsd(q, thetas, numElectrons, spin) + + + # Using UCCGSD ansatz + geometry = [('H', (0., 0., 0.)), ('H', (0., 0., .7474))] + molecule = solvers.create_molecule(geometry, 'sto-3g', 0, 0, casci=True) + + numQubits = molecule.n_orbitals * 2 + numElectrons = molecule.n_electrons + + # Get grouped Pauli words and coefficients from UCCGSD pool + pauliWordsList, coefficientsList = solvers.stateprep.get_uccgsd_pauli_lists( + numQubits, only_singles=False, only_doubles=False) + + @cudaq.kernel + def ansatz(numQubits: int, numElectrons: int, thetas: list[float], + pauliWordsList: list[list[cudaq.pauli_word]], + coefficientsList: list[list[float]]): + q = cudaq.qvector(numQubits) + for i in range(numElectrons): + x(q[i]) + solvers.stateprep.uccgsd(q, thetas, pauliWordsList, coefficientsList) + + Algorithm Parameters ^^^^^^^^^^^^^^^^^^^^^^ From 03b56a88ab180ba004d3d4af527d6db4bbb9b99c Mon Sep 17 00:00:00 2001 From: marwafar Date: Mon, 10 Nov 2025 14:30:55 +0000 Subject: [PATCH 2/4] api Signed-off-by: marwafar --- docs/sphinx/api/solvers/cpp_api.rst | 3 +++ docs/sphinx/api/solvers/python_api.rst | 2 ++ 2 files changed, 5 insertions(+) diff --git a/docs/sphinx/api/solvers/cpp_api.rst b/docs/sphinx/api/solvers/cpp_api.rst index e363f396..fb40c647 100644 --- a/docs/sphinx/api/solvers/cpp_api.rst +++ b/docs/sphinx/api/solvers/cpp_api.rst @@ -6,6 +6,7 @@ CUDA-Q Solvers C++ API .. doxygenclass:: cudaq::solvers::spin_complement_gsd .. doxygenclass:: cudaq::solvers::uccsd +.. doxygenclass:: cudaq::solvers::uccgsd .. doxygenclass:: cudaq::solvers::qaoa_pool .. doxygenfunction:: cudaq::solvers::get_operator_pool @@ -67,6 +68,8 @@ CUDA-Q Solvers C++ API .. doxygenfunction:: cudaq::solvers::stateprep::double_excitation .. doxygenfunction:: cudaq::solvers::stateprep::uccsd(cudaq::qview<>, const std::vector&, std::size_t, std::size_t) .. doxygenfunction:: cudaq::solvers::stateprep::uccsd(cudaq::qview<>, const std::vector&, std::size_t) +.. doxygenfunction:: cudaq::solvers::stateprep::get_uccgsd_pauli_lists +.. doxygenfunction:: cudaq::solvers::stateprep::uccgsd(cudaq::qview<>, const std::vector&, const std::vector>&, const std::vector>&) .. doxygenstruct:: cudaq::solvers::qaoa_result diff --git a/docs/sphinx/api/solvers/python_api.rst b/docs/sphinx/api/solvers/python_api.rst index a737cdfe..8e82a1fd 100644 --- a/docs/sphinx/api/solvers/python_api.rst +++ b/docs/sphinx/api/solvers/python_api.rst @@ -27,6 +27,8 @@ CUDA-Q Solvers Python API .. autofunction:: cudaq_solvers.stateprep.double_excitation .. autofunction:: cudaq_solvers.stateprep.get_num_uccsd_parameters .. autofunction:: cudaq_solvers.stateprep.get_uccsd_excitations +.. autofunction:: cudaq_solvers.stateprep.get_uccgsd_pauli_lists +.. autofunction:: cudaq_solvers.stateprep.uccgsd .. autofunction:: cudaq_solvers.get_num_qaoa_parameters From 8d6bab3f4c3f7dac68a820d2d3f5546c1ee93b00 Mon Sep 17 00:00:00 2001 From: marwafar Date: Fri, 14 Nov 2025 01:19:53 +0000 Subject: [PATCH 3/4] add import cudaq_solvers as solvers Signed-off-by: marwafar --- docs/sphinx/components/solvers/introduction.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/sphinx/components/solvers/introduction.rst b/docs/sphinx/components/solvers/introduction.rst index bd0cbb71..46fbe875 100644 --- a/docs/sphinx/components/solvers/introduction.rst +++ b/docs/sphinx/components/solvers/introduction.rst @@ -502,6 +502,8 @@ CUDA-QX provides several pre-built operator pools for ADAPT-VQE: .. code-block:: python + import cudaq_solvers as solvers + # Generate different operator pools gsd_ops = solvers.get_operator_pool( "spin_complement_gsd", @@ -529,6 +531,8 @@ CUDA-QX provides several state preparations ansatz for VQE. .. code-block:: python + import cudaq_solvers as solvers + # Using UCCSD ansatz geometry = [('H', (0., 0., 0.)), ('H', (0., 0., .7474))] molecule = solvers.create_molecule(geometry, 'sto-3g', 0, 0, casci=True) From b02200a19aa174871d199c5c12b82741e0eee069 Mon Sep 17 00:00:00 2001 From: marwafar Date: Sat, 15 Nov 2025 00:49:46 +0000 Subject: [PATCH 4/4] add details about operator pools Signed-off-by: marwafar --- .../components/solvers/introduction.rst | 25 ++++++++++++++++--- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/docs/sphinx/components/solvers/introduction.rst b/docs/sphinx/components/solvers/introduction.rst index 46fbe875..e858199e 100644 --- a/docs/sphinx/components/solvers/introduction.rst +++ b/docs/sphinx/components/solvers/introduction.rst @@ -495,11 +495,28 @@ Available Operator Pools CUDA-QX provides several pre-built operator pools for ADAPT-VQE: -* **spin_complement_gsd**: Spin-complemented generalized singles and doubles -* **uccsd**: UCCSD operators -* **uccgsd**: UCC generalized singles and doubles +* **spin_complement_gsd**: Spin-complemented generalized singles and doubles. + This operator pool combines generalized excitations with enforced spin symmetry. It is + more powerful than UCCSD because its generalized operators capture more electron correlation, + and it is more reliable than both UCCSD and UCCGSD because its spin-complemented + construction prevents the unphysical "spin-symmetry breaking". +* **uccsd**: UCCSD operators. + The standard, chemically-inspired ansatz. Excitation Space + is Restricted. It only includes single and double excitations + where electrons move from a reference-occupied orbital (i) + to a reference-virtual orbital (a), + relative to the starting Hartree-Fock state. Excellent at capturing dynamic correlation + (short-range, instantaneous electron interactions). +* **uccgsd**: UCC generalized singles and doubles. + More expressive than UCCSD, as it includes all possible + single and double excitations, regardless of their occupied/virtual status in the reference state. + Capable of capturing both dynamic and static (strong) correlation + but at the cost of increased circuit depth and parameter count. * **qaoa**: QAOA mixer excitation operators - + It generates all possible single-qubit X and Y terms, along with all possible + two-qubit interaction terms (XX, YY, XY, YX, XZ, ZX, YZ, ZY) across every pair of qubits. + This pool offers a rich basis for constructing the mixer Hamiltonian for ADAPT-QAOA algorithms. + .. code-block:: python import cudaq_solvers as solvers