Introduce an early stop threshold for Kmeans (#4894)

Summary:
Basically speaking, the feature allows kmeans iterations to stop once the improvement in an error becomes marginal.

Pull Request resolved: #4894

Reviewed By: limqiying

Differential Revision: D95987848

Pulled By: alibeklfc

fbshipit-source-id: 4422d08c9e04880cbef84093f0c4ae714dff254c

Author: alexanderguzhva

faiss/Clustering.cpp

@@ -569,7 +569,12 @@ void Clustering::train_encoded(
             if (i > 0) {
                 float prev_obj =
                         iteration_stats[iteration_stats.size() - 2].obj;
-                if (obj == prev_obj) {
+
+                double change = (prev_obj == 0)
+                        ? std::numeric_limits<double>::max()
+                        : std::abs(prev_obj - obj) / std::abs(prev_obj);
+
+                if (change >= 0 && change <= early_stop_threshold) {
                     if (verbose) {
                         printf("\n  Converged at iteration %d: "
                                "objective did not change\n",

faiss/Clustering.h

@@ -69,6 +69,12 @@ struct ClusteringParameters {
     /// Only used when init_method = AFK_MC2.
     /// Longer chains give better approximation but are slower.
     uint16_t afkmc2_chain_length = 50;
+
+    /// Early stop threshold, the range is [0, 1].
+    /// The value of 0 implies a default Faiss behavior,
+    /// so the training process stops only if an error
+    /// is unchanged from the previous iteration.
+    double early_stop_threshold = 0.0;
 };
 
 struct ClusteringIterationStats {