From f455fe3ac14d601c2ec52a02eaf33431f3850614 Mon Sep 17 00:00:00 2001
From: bjyb <1091839467@qq.com>
Date: Wed, 20 Sep 2023 17:20:39 +0800
Subject: [PATCH] Update kmeans.cpp

---
 .../dbmind/db4ai/executor/kmeans/kmeans.cpp   | 49 +++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/src/gausskernel/dbmind/db4ai/executor/kmeans/kmeans.cpp b/src/gausskernel/dbmind/db4ai/executor/kmeans/kmeans.cpp
index 0b8933966..5946c1880 100644
--- a/src/gausskernel/dbmind/db4ai/executor/kmeans/kmeans.cpp
+++ b/src/gausskernel/dbmind/db4ai/executor/kmeans/kmeans.cpp
@@ -42,6 +42,12 @@ IDENTIFICATION
 /*
  * parameters that affect k-means (hyper-parameters)
  */
+
+/*KMeans is one of the top ten algorithms in data mining.
+In data mining practice, we often apply KMeans to various
+scenarios, because it is simple in principle, easy to implement
+and suitable for various data mining scenarios.*/
+
 typedef struct HyperparametersKMeans {
     ModelHyperparameters mhp;  // place-holder
     SeedingFunction seeding = KMEANS_RANDOM_SEED;
@@ -314,6 +320,14 @@ static bool deal_sample(bool const sample, std::mt19937_64 *prng, GSPoint *batch
     return false;
 }
 
+/*Function: compute_cost_and_weights
+Parameters: (list const * centroids, GS point const * points, uint32 _ tdimension,
+uint32_t const num_slots, double *cost)
+Return value: bool
+Given a set of centroids (as a PG list) and a set of points, this function 
+calculates the cost of the centroid set and their weights
+(the number of points assigned to each centroid).*/
+
 /*
  * given a set of centroids (as a PG list) and a set of points, this function computes
  * the cost of the set of centroids as well as their weights (number of points assigned
@@ -366,6 +380,12 @@ force_inline static void release_batch(GSPoint *batch, uint32_t const num_slots)
  * using a sum that provides higher precision (we could provide much higher precision at the cost
  * of allocating yet another array to keep correction terms for every dimension
  */
+/*Function: aggregate_ Point
+Formal parameters: (double * centroid_aggregation, double const * new_point,
+Uint32_ T const dimension)
+Return value: None
+Given the moving average of the centroid and new points, this will add new points to the set*/
+
 force_inline static void aggregate_point(double *centroid_aggregation, double const *new_point,
                                          uint32_t const dimension)
 {
@@ -380,6 +400,12 @@ force_inline static void aggregate_point(double *centroid_aggregation, double co
  * we assume that all slots in the batch are non-null (guaranteed by the upper call)
  * also, that the next set of centroids has been reset previous to the very first call
  */
+
+/*Function: update_ Centroids
+Formal parameters: (KMeansStateDescription * description, GSPoint * slots, uint32_t const num_slots,
+Uint32_ T const idx_ Current_ Centroids, uint32_ T const idx_ Next_ Centroids)
+Return value: None
+Update centroid*/
 static void update_centroids(KMeansStateDescription *description, GSPoint *slots, uint32_t const num_slots,
                              uint32_t const idx_current_centroids, uint32_t const idx_next_centroids)
 {
@@ -450,6 +476,13 @@ static void update_centroids(KMeansStateDescription *description, GSPoint *slots
 /*
  * updates the minimum bounding box to contain the new given point
  */
+/*Function: update_ Centroids
+Formal parameters: (double * const bbox_min, double * const bbox_max, double const * point,
+Uint32_ T const dimension)
+Return value: None
+Update the minimum bounding box to include the new given point*/
+
+
 force_inline static void update_bbox(double *const bbox_min, double *const bbox_max, double const *point,
                                      uint32_t const dimension)
 {
@@ -743,6 +776,11 @@ static List *one_data_pass(TrainModelState *pstate, KMeansStateDescription *stat
 /*
  * this sets the weights of a set of candidates to 1 (every point is the centroid of itself)
  */
+/*Function: reset_ Weights
+Formal parameters: (List const * centroids)
+Return value: None
+Initialize weights (each point has a centroid of 1)*/
+
 void reset_weights(List const *centroids)
 {
     ListCell const *current_centroid_cell = centroids ? centroids->head : nullptr;
@@ -983,6 +1021,12 @@ void reset_centroids(KMeansStateDescription *description, uint32_t const idx_cen
  * this produces the centroid by dividing the aggregate by the amount of points it got assigned
  * we assumed that population > 0
  */
+
+/*Function: finish_ Centroid
+Formal parameters: (double * centroid_aggregation, 
+uint32_t const dimension, double const population)
+Return value: None
+Generate centroid*/
 force_inline void finish_centroid(double *centroid_aggregation, uint32_t const dimension, double const population)
 {
     double local_correction = 0.;
@@ -992,6 +1036,11 @@ force_inline void finish_centroid(double *centroid_aggregation, uint32_t const d
     }
 }
 
+/*Function: merge_ Centroids
+Parameter: (KMeansStateDescription * description, uint32_t const idx_current_centroids,
+Uint32_ T const idx_ Next_ Centroids)
+Return value: None
+Merge centroids*/
 void merge_centroids(KMeansStateDescription *description, uint32_t const idx_current_centroids,
                      uint32_t const idx_next_centroids)
 {