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 diff --git a/docs/sphinx/components/solvers/introduction.rst b/docs/sphinx/components/solvers/introduction.rst index 3bd0c869..e858199e 100644 --- a/docs/sphinx/components/solvers/introduction.rst +++ b/docs/sphinx/components/solvers/introduction.rst @@ -495,12 +495,32 @@ 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 +* **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 + # Generate different operator pools gsd_ops = solvers.get_operator_pool( "spin_complement_gsd", @@ -513,6 +533,60 @@ 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 + + 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) + + 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 ^^^^^^^^^^^^^^^^^^^^^^