[Docs] Add uccgsd to doc (#340)

In this PR:
We update the doc and add details about uccgsd implemented in #319

---------

Signed-off-by: marwafar <[email protected]>
Co-authored-by: Ben Howe <[email protected]>

Author: marwafar

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<double>&, std::size_t, std::size_t)
 .. doxygenfunction:: cudaq::solvers::stateprep::uccsd(cudaq::qview<>, const std::vector<double>&, std::size_t)
+.. doxygenfunction:: cudaq::solvers::stateprep::get_uccgsd_pauli_lists
+.. doxygenfunction:: cudaq::solvers::stateprep::uccgsd(cudaq::qview<>, const std::vector<double>&, const std::vector<std::vector<cudaq::pauli_word>>&, const std::vector<std::vector<double>>&)
 
 
 .. doxygenstruct:: cudaq::solvers::qaoa_result

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
 

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
 ^^^^^^^^^^^^^^^^^^^^^^