UCCSD operator pool correction and integration in adapt simulator (#65)

# UCCSD operator pool correction and integration in adapt simulator
(Issue #28)
This PR fixes #28 .

## Problem
Adapt VQE did not provide correct results. The problem could be the
creation of the UCCSD operators pool.

## Changes
Changes so far have been applied to:
- The UCCSD operator pool 'generate' function.
- The Testing of the UCCSD operator pool, cpp and py files.
- Tested adap_vqe for final results.

## Additional notes 
Further testing is needed for making sure that adapt VQE works
correctly, especially in terms of molecules.

---------

Signed-off-by: kvmto <[email protected]>
Signed-off-by: Anna Gringauze <[email protected]>
Signed-off-by: Kevin Mato <[email protected]>
Signed-off-by: Melody Ren <[email protected]>
Co-authored-by: Anna Gringauze <[email protected]>
Co-authored-by: Ben Howe <[email protected]>
Co-authored-by: Melody Ren <[email protected]>

Author: 4 people

libs/solvers/include/cudaq/solvers/adapt.h

@@ -70,7 +70,23 @@ class adapt_impl : public extension_point<adapt_impl> {
   /// @param pool Pool of operators
   /// @param optimizer Optimization algorithm
   /// @param gradient Gradient calculation method
-  /// @param options Additional options for the algorithm
+  /// @param options Additional options for the algorithm. Supported Keys:
+  ///  - "max_iter" (int): Maximum number of iterations [default: 30]
+  ///  - "grad_norm_tolerance" (double): Convergence tolerance for gradient norm
+  ///  [default: 1e-5]
+  ///  - "grad_norm_diff_tolerance" (double): Tolerance for difference between
+  ///  gradient norms [default: 1e-5]
+  ///  - "threshold_energy" (double): Energy convergence threshold [default:
+  ///  1e-6]
+  ///  - "initial_theta" (double): Initial value for theta parameter [default:
+  ///  0.0]
+  ///  - "verbose" (bool): Enable detailed output logging [default: false]
+  ///  - "shots" (int): Number of measurement shots (-1 for exact simulation)
+  ///  [default: -1]
+  ///  - "dynamic_start" (string): Optimization mode for the theta parameters at
+  ///  each iteration.
+  ///      It can be either "warm", or "cold". [default: "cold"]
+  ///  - "tol" (double): Tolerance for optimization [default: 1e-12]
   /// @return Result of the ADAPT-VQE algorithm
   virtual result run(const cudaq::qkernel<void(cudaq::qvector<> &)> &initState,
                      const spin_op &H, const std::vector<spin_op> &pool,
@@ -88,7 +104,22 @@ class adapt_impl : public extension_point<adapt_impl> {
 /// @param initialState Initial state preparation quantum kernel
 /// @param H Hamiltonian operator
 /// @param poolList Pool of operators
-/// @param options Additional options for the algorithm
+/// @param options Additional options for the algorithm. Supported Keys:
+///  - "max_iter" (int): Maximum number of iterations [default: 30]
+///  - "grad_norm_tolerance" (double): Convergence tolerance for gradient norm
+///  [default: 1e-5]
+///  - "grad_norm_diff_tolerance" (double): Tolerance for difference between
+///  gradient norms [default: 1e-5]
+///  - "threshold_energy" (double): Energy convergence threshold [default: 1e-6]
+///  - "initial_theta" (double): Initial value for theta parameter [default:
+///  0.0]
+///  - "verbose" (bool): Enable detailed output logging [default: false]
+///  - "shots" (int): Number of measurement shots (-1 for exact simulation)
+///  [default: -1]
+///  - "dynamic_start" (string): Optimization mode for the theta parameters at
+///  each iteration.
+///      It can be either "warm", or "cold". [default: "cold"]
+///  - "tol" (double): Tolerance for optimization [default: 1e-12]
 /// @return Result of the ADAPT-VQE algorithm
 static inline adapt::result
 adapt_vqe(const cudaq::qkernel<void(cudaq::qvector<> &)> &initialState,
@@ -106,7 +137,22 @@ adapt_vqe(const cudaq::qkernel<void(cudaq::qvector<> &)> &initialState,
 /// @param H Hamiltonian operator
 /// @param poolList Pool of operators
 /// @param optimizer Custom optimization algorithm
-/// @param options Additional options for the algorithm
+/// @param options Additional options for the algorithm. Supported Keys:
+///  - "max_iter" (int): Maximum number of iterations [default: 30]
+///  - "grad_norm_tolerance" (double): Convergence tolerance for gradient norm
+///  [default: 1e-5]
+///  - "grad_norm_diff_tolerance" (double): Tolerance for difference between
+///  gradient norms [default: 1e-5]
+///  - "threshold_energy" (double): Energy convergence threshold [default: 1e-6]
+///  - "initial_theta" (double): Initial value for theta parameter [default:
+///  0.0]
+///  - "verbose" (bool): Enable detailed output logging [default: false]
+///  - "shots" (int): Number of measurement shots (-1 for exact simulation)
+///  [default: -1]
+///  - "dynamic_start" (string): Optimization mode for the theta parameters at
+///  each iteration.
+///      It can be either "warm", or "cold". [default: "cold"]
+///  - "tol" (double): Tolerance for optimization [default: 1e-12]
 /// @return Result of the ADAPT-VQE algorithm
 static inline adapt::result
 adapt_vqe(const cudaq::qkernel<void(cudaq::qvector<> &)> &initialState,
@@ -125,7 +171,22 @@ adapt_vqe(const cudaq::qkernel<void(cudaq::qvector<> &)> &initialState,
 /// @param poolList Pool of operators
 /// @param optimizer Custom optimization algorithm
 /// @param gradient Gradient calculation method
-/// @param options Additional options for the algorithm
+/// @param options Additional options for the algorithm. Supported Keys:
+///  - "max_iter" (int): Maximum number of iterations [default: 30]
+///  - "grad_norm_tolerance" (double): Convergence tolerance for gradient norm
+///  [default: 1e-5]
+///  - "grad_norm_diff_tolerance" (double): Tolerance for difference between
+///  gradient norms [default: 1e-5]
+///  - "threshold_energy" (double): Energy convergence threshold [default: 1e-6]
+///  - "initial_theta" (double): Initial value for theta parameter [default:
+///  0.0]
+///  - "verbose" (bool): Enable detailed output logging [default: false]
+///  - "shots" (int): Number of measurement shots (-1 for exact simulation)
+///  [default: -1]
+///  - "dynamic_start" (string): Optimization mode for the theta parameters at
+///  each iteration.
+///      It can be either "warm", or "cold". [default: "cold"]
+///  - "tol" (double): Tolerance for optimization [default: 1e-12]
 /// @return Result of the ADAPT-VQE algorithm
 static inline adapt::result
 adapt_vqe(const cudaq::qkernel<void(cudaq::qvector<> &)> &initialState,

libs/solvers/include/cudaq/solvers/operators/operator_pools/qaoa_operator_pool.h

@@ -12,16 +12,33 @@
 
 namespace cudaq::solvers {
 
-/// @brief Test
+/// @brief QAOA operator pool is a class with generates a pool
+/// of QAOA operators for use in quantum algorithms, like Adapt-QAOA.
+/// @details This class extends the operator_pool interface
+/// therefore inherits the extension_point template, allowing for
+/// runtime extensibility.
 class qaoa_pool : public operator_pool {
 public:
+  /// @brief Generate a vector of spin operators based on the provided
+  /// configuration.
+  /// @param config A heterogeneous map containing configuration parameters for
+  /// operator generation.
+  /// @return A vector of cudaq::spin_op objects representing the generated
+  /// operator pool.
   std::vector<cudaq::spin_op>
   generate(const heterogeneous_map &config) const override;
+
+  /// @brief Call to macro for defining the creator function for the qaoa_pool
+  /// extension
+  /// @details This function is used by the extension point mechanism to create
+  /// instances of the qaoa_pool class. The extension is registered with a name
   CUDAQ_EXTENSION_CUSTOM_CREATOR_FUNCTION_WITH_NAME(
       qaoa_pool, "qaoa", static std::unique_ptr<operator_pool> create() {
         return std::make_unique<qaoa_pool>();
       })
 };
+
+/// @brief Register the qaoa_pool extension type with the CUDA-Q framework
 CUDAQ_REGISTER_TYPE(qaoa_pool)
 
 } // namespace cudaq::solvers

libs/solvers/include/cudaq/solvers/operators/operator_pools/spin_complement_gsd.h

@@ -15,13 +15,31 @@ namespace cudaq::solvers {
 // adapted from
 // https://github.com/mayhallgroup/adapt-vqe/blob/master/src/operator_pools.py
 
-/// @brief Test
+/// @brief spin_complement_gsd operator pool is a class which generates a pool
+/// of operators with the spin complement ground state degeneracy method for use
+/// in quantum algorithms, like Adapt-VQE.
+/// @details This class extends the operator_pool interface
+/// therefore inherits extension_point template, allowing for
+/// runtime extensibility.
 class spin_complement_gsd : public operator_pool {
 
 public:
+  /// @brief Generate a vector of spin operators based on the provided
+  /// configuration.
+  /// @param config A heterogeneous map containing configuration parameters for
+  /// operator generation.
+  /// @return A vector of cudaq::spin_op objects representing the generated
+  /// operator pool.
   std::vector<cudaq::spin_op>
   generate(const heterogeneous_map &config) const override;
+
+  /// @brief Call to macro for defining the creator function for the
+  /// spin_complement_gsd extension
+  /// @details This function is used by the extension point mechanism to create
+  /// instances of the spin_complement_gsd class.
   CUDAQ_EXTENSION_CREATOR_FUNCTION(operator_pool, spin_complement_gsd)
 };
+/// @brief Register the spin_complement_gsd extension type with the CUDA-Q
+/// framework
 CUDAQ_REGISTER_TYPE(spin_complement_gsd)
 } // namespace cudaq::solvers

libs/solvers/include/cudaq/solvers/operators/operator_pools/uccsd_operator_pool.h

@@ -12,14 +12,32 @@
 
 namespace cudaq::solvers {
 
-/// @brief Test
+/// @brief UCCSD operator pool is a class with generates a pool
+/// of UCCSD operators for use in quantum algorithms, like Adapt-VQE.
+/// @details This class extends the operator_pool interface
+/// therefore inherits the extension_point template, allowing for
+/// runtime extensibility.
 class uccsd : public operator_pool {
 
 public:
+  /// @brief Generate a vector of spin operators based on the provided
+  /// configuration.
+  /// @details The UCCSD operator pool is generated with an imaginary factor 'i
+  /// in the coefficients of the operators, which simplifies the use for running
+  /// Adapt-VQE.
+  /// @param config A heterogeneous map containing configuration parameters for
+  /// operator generation.
+  /// @return A vector of cudaq::spin_op objects representing the generated
+  /// operator pool.
   std::vector<cudaq::spin_op>
   generate(const heterogeneous_map &config) const override;
+
+  /// @brief Call to macro for defining the creator function for an extension
+  /// @details This function is used by the extension point mechanism to create
+  /// instances of the uccsd class.
   CUDAQ_EXTENSION_CREATOR_FUNCTION(operator_pool, uccsd)
 };
+/// @brief Register the uccsd extension type with the CUDA-Q framework
 CUDAQ_REGISTER_TYPE(uccsd)
 
 } // namespace cudaq::solvers

libs/solvers/include/cudaq/solvers/vqe.h

@@ -37,7 +37,8 @@ struct vqe_result {
 /// @param optimizer Optimization algorithm to use
 /// @param gradient Gradient computation method
 /// @param initial_parameters Initial parameters for the optimization
-/// @param options Additional options for the VQE algorithm
+/// @param options Additional options for the VQE algorithm. Available options
+/// - "tol" (double): Tolerance for optimization [default: 1e-12]
 /// @return VQE result containing optimal energy, parameters, and iteration data
 template <typename QuantumKernel>
   requires std::invocable<QuantumKernel, std::vector<double>>