Add docstring and comments for hessian related function

Author: longhongc

Diff for: ifopt_core/include/ifopt/constraint_set.h

@@ -107,8 +107,43 @@ class ConstraintSet : public Component {
   virtual void FillJacobianBlock(std::string var_set,
                                  Jacobian& jac_block) const = 0;
 
-
+  /**
+   * @brief  The second-order derivatives (Hessians) for these constraints and variables.
+   *
+   * This function returns a pair containing two vectors. The first vector holds
+   * the indices of the corresponding constraints or costs, while the second vector
+   * contains the Hessian matrices as sparse representations.
+   *
+   * Assuming @c n constraints or costs and @c m variables, each Hessian matrix
+   * in the second vector has dimensions m x m, representing the second-order
+   * derivatives of a specific constraint or cost function with respect to the
+   * optimization variables.
+   *
+   * This function only combines the user-defined Hessians from
+   * FillHessianTriplets().
+   */
   RowIndicesHessiansPair GetHessians() const final;
+
+  /**
+   * @brief Set individual Hessians corresponding to each constraint or cost function.
+   * @param var_set_list  The full set of variables involved in Hessian computation.
+   * @param hessian_row_index_list  Indices of the corresponding constraints or costs.
+   * @param triplets_list  Nonzero elements of each Hessian, stored as triplets.
+   *
+   * This function provides the second-order derivatives (Hessians) of constraints
+   * or costs with respect to the optimization variables. Unlike the Jacobian, Hessians
+   * involve cross-derivatives between different variable sets, so the full variable
+   * set is provided.
+   *
+   * The Hessians are stored efficiently in triplet form to minimize memory usage,
+   * as Hessian matrices are typically much sparser than Jacobians. Each entry in
+   * @c triplets_list corresponds to a specific constraint or cost function, with
+   * its nonzero elements stored as Eigen triplets.
+   *
+   * If a constraint or cost does not require a Hessian, it should simply be omitted
+   * from @c hessian_row_index_list and @c triplets_list. The missing entries will
+   * be treated as empty Hessians.
+   */
   virtual void FillHessianTriplets(std::vector<std::string> var_set_list,
                                    std::vector<int>& hessian_row_index_list,
                                    std::vector<HessianTriplet>& triplets_list) const

Diff for: ifopt_core/include/ifopt/problem.h

@@ -218,16 +218,61 @@ class Problem {
   Jacobian GetJacobianOfCosts() const;
 
   /**
-   * @brief Extracts those entries from total hessian (combination of hessian from cost and constraints) that are not zero.
+   * @brief Computes the nonzero entries of the total Hessian after applying scaling factors.
+   *
+   * This function extracts the nonzero elements from the total Hessian, which is
+   * the combination of the Hessians from both cost functions and constraints, and
+   * applies the appropriate scaling factors.
+   *
+   * The Hessian of the cost function is multiplied by @c obj_factor, while the
+   * Hessians of the constraints are weighted by their corresponding Lagrange
+   * multipliers in @c lambda.
+   *
    * @param [in]  x  The current values of the optimization variables.
-   * @param [in]  obj_factor  The scaling multiplier for the hessian of the objective function(cost).
-   * @param [in]  lambda  Lagrange Multipliers of the constraints.
-   * @param [out] values  The nonzero derivatives ordered by Eigen::RowMajor.
+   * @param [in]  obj_factor  The scaling multiplier for the Hessian of the objective function (cost).
+   * @param [in]  lambda  The Lagrange multipliers for the constraints.
+   * @param [out] values  The nonzero second-order derivatives, ordered in @c Eigen::RowMajor format.
    */
   void EvalNonzerosOfHessian(const double* x, double obj_factor, const double* lambda, double* values);
 
+  /**
+   * @brief Computes the full Hessian by summing the Hessians of costs and constraints.
+   *
+   * This function returns the total Hessian, which combines the second-order
+   * derivatives of both cost functions and constraints with respect to the
+   * optimization variables.
+   *
+   * The primary purpose of this function is to determine the structure of the
+   * overall Hessian, including the number and positions of nonzero elements.
+   * The resulting matrix is stored in sparse format for efficiency.
+   */
   Hessian GetTotalHessian() const;
+
+  /**
+   * @brief The sparse-matrix representation of the Hessians of the constraints.
+   *
+   * This function returns a pair of vectors, where the first vector contains
+   * the indices of the corresponding constraints, and the second vector holds
+   * the Hessian matrices in sparse format.
+   *
+   * Each Hessian matrix represents the second-order derivatives of a constraint
+   * with respect to the optimization variables. The Hessians are stored sparsely
+   * to optimize memory usage, as they are typically very sparse.
+   */
   RowIndicesHessiansPair GetHessianOfConstraints() const;
+
+
+  /**
+   * @brief The sparse-matrix representation of the Hessians of the cost functions.
+   *
+   * This function returns a pair of vectors, where the first vector contains
+   * the indices of the corresponding cost functions, and the second vector holds
+   * the Hessian matrices in sparse format.
+   *
+   * Each Hessian matrix represents the second-order derivatives of a cost function
+   * with respect to the optimization variables. The Hessians are stored sparsely
+   * to optimize memory usage, as they are typically very sparse.
+   */
   RowIndicesHessiansPair GetHessianOfCosts() const;
 
   /**

Diff for: ifopt_core/test/ifopt/test_vars_constr_cost.h

@@ -149,6 +149,9 @@ class ExConstraint : public ConstraintSet {
                            std::vector<int>& hessian_row_index_list,
                            std::vector<HessianTriplet>& triplets_list) const override
   {
+    // only the upper triangular elements need to be provided, as the Hessian
+    // is symmetric and internally only these values are used.
+
     // only 1 constraint in this problem
     HessianTriplet constraint1_triplets;
     for (int i = 0; i < (int)var_set_list.size(); ++i) {
@@ -188,6 +191,8 @@ class ExCost : public CostTerm {
                            std::vector<int>& hessian_row_index_list,
                            std::vector<HessianTriplet>& triplets_list) const override
   {
+    // only the upper triangular elements need to be provided, as the Hessian
+    // is symmetric and internally only these values are used.
     HessianTriplet cost_triplets;
     for (int i = 0; i < (int)var_set_list.size(); ++i) {
       const std::string& var_set = var_set_list[i];