refactor(builder): remove additional_swap_tries and rename swap_tries to improve_tries

- Remove obsolete additional_swap_tries parameter across C++ and Python
- Rename swap_tries to improve_tries for consistency with improve_k/improve_eps
- Clean up EvenRegularGraphBuilder constructor overloads
- Update C++ benchmarks, unit/regression tests, Python bindings, and documentation

Author: Neiko2002

cpp/API.md

@@ -128,8 +128,7 @@ DynamicExplorationGraph build_from_data(
     uint8_t improve_k = 0,
     float improve_eps = 0.001f,
     uint8_t max_path_length = 5,
-    uint32_t swap_tries = 0,
-    uint32_t additional_swap_tries = 0,
+    uint32_t improve_tries = 0,
     size_t thread_count = 0,
     uint32_t seed = 42,
     function<void(BuilderStatus&)> callback = nullptr
@@ -176,14 +175,13 @@ public:
     EvenRegularGraphBuilder(
         DynamicExplorationGraph& graph,
         mt19937& rnd,
-        OptimizationTarget target = OptimizationTarget::StreamingData,
+        OptimizationTarget target = OptimizationTarget::LowLID,
         uint8_t extend_k = 0,
         float extend_eps = 0.1f,
         uint8_t improve_k = 0,
         float improve_eps = 0.001f,
         uint8_t max_path_length = 5,
-        uint32_t swap_tries = 0,
-        uint32_t additional_swap_tries = 0
+        uint32_t improve_tries = 0
     );
 
     // --- Entry Queue Management ---

cpp/bench/include/build.h

@@ -63,8 +63,7 @@ inline void create_graph(
     const deglib::cpu::InstructionSet instruction = deglib::cpu::InstructionSet::Auto
 ) {
     auto rnd = std::mt19937(7);
-    const uint32_t swap_tries = 0;
-    const uint32_t additional_swap_tries = 0;
+    const uint32_t improve_tries = 0;
 
     const auto dims = repository.dims();
     const uint32_t max_vertex_count = uint32_t(repository.size());
@@ -76,7 +75,7 @@ inline void create_graph(
 
     auto graph = deglib::graph::SizeBoundedGraph(max_vertex_count, k, feature_space);
 
-    auto builder = deglib::builder::EvenRegularGraphBuilder(graph, rnd, lid, k_ext, eps_ext, k_opt, eps_opt, i_opt, swap_tries, additional_swap_tries);
+    auto builder = deglib::builder::EvenRegularGraphBuilder(graph, rnd, lid, k_ext, eps_ext, k_opt, eps_opt, i_opt, improve_tries);
     builder.setThreadCount(thread_count);
     builder.setBatchSize(10, 10);
 
@@ -166,7 +165,7 @@ inline void optimize_graph(
     const uint32_t scale = 1
 ) {
     auto rnd = std::mt19937(7);
-    auto builder = deglib::builder::EvenRegularGraphBuilder(graph, rnd, deglib::builder::OptimizationTarget::LowLID, 0, 0, k_opt, eps_opt, i_opt, 1, 0);
+    auto builder = deglib::builder::EvenRegularGraphBuilder(graph, rnd, deglib::builder::OptimizationTarget::LowLID, 0, 0, k_opt, eps_opt, i_opt, 1);
 
     auto initial_avg_edge_weight = deglib::analysis::calc_avg_edge_weight(graph, scale);
     log("Optimizing graph with initial AEW {:.2f}\n", initial_avg_edge_weight);

cpp/bench/src/bench_edge_optimization.cpp

@@ -123,7 +123,7 @@ void run_edge_optimization_benchmark(
     log("\n=== Optimizing Graph Edges (in memory) ===\n");
     auto rnd = std::mt19937(7);
     auto builder = deglib::builder::EvenRegularGraphBuilder(
-        graph, rnd, deglib::builder::OptimizationTarget::LowLID, 0, 0, config.k_opt, config.eps_opt, config.max_path_length, 1, 0
+        graph, rnd, deglib::builder::OptimizationTarget::LowLID, 0, 0, config.k_opt, config.eps_opt, config.max_path_length, 1
     );
 
     auto start = std::chrono::steady_clock::now();

cpp/deglib/include/deglib/builder.h

@@ -217,8 +217,7 @@ class EvenRegularGraphBuilder {
     const uint8_t improve_k_;               // k value for improving the graph
     const float improve_eps_;               // eps value for improving the graph
     const uint8_t max_path_length_;         // max amount of changes before canceling an improvement try
-    const uint32_t swap_tries_;             // number of improvement attempts per build step
-    const uint32_t additional_swap_tries_;  // additional improvement attempts after a successful improvement
+    const uint32_t improve_tries_;          // number of improvement attempts per build step
 
     std::mt19937& rnd_;                   // Reference to a random number generator used for randomized operations
     deglib::graph::MutableGraph& graph_;  // Reference to the mutable graph being built and optimized
@@ -252,32 +251,29 @@ class EvenRegularGraphBuilder {
      * @param improve_k Number of neighbors to consider when improving the graph.
      * @param improve_eps Epsilon value for neighbor search during graph improvement.
      * @param max_path_length Maximum number of edge swaps in a single improvement attempt (default: 5).
-     * @param swap_tries Number of improvement attempts per build step (default: 0).
-     * @param additional_swap_tries Additional improvement attempts after a successful improvement (default: 0).
+     * @param improve_tries Number of improvement attempts per build step (default: 0).
      *
      * This constructor initializes the builder with the provided parameters and sets up internal
      * batching and threading parameters for efficient graph construction and optimization.
      */
     EvenRegularGraphBuilder(
         deglib::graph::MutableGraph& graph,
         std::mt19937& rnd,
-        const OptimizationTarget optimization_target,
-        const uint8_t extend_k,
-        const float extend_eps,
-        const uint8_t improve_k,
-        const float improve_eps,
+        const OptimizationTarget optimization_target = OptimizationTarget::LowLID,
+        const uint8_t extend_k = 0,
+        const float extend_eps = 0.1f,
+        const uint8_t improve_k = 0,
+        const float improve_eps = 0.001f,
         const uint8_t max_path_length = 5,
-        const uint32_t swap_tries = 0,
-        const uint32_t additional_swap_tries = 0
+        const uint32_t improve_tries = 0
     )
         : optimizationTarget_(optimization_target),
           extend_k_(extend_k),
           extend_eps_(extend_eps),
           improve_k_(improve_k),
           improve_eps_(improve_eps),
           max_path_length_(max_path_length),
-          swap_tries_(swap_tries),
-          additional_swap_tries_(additional_swap_tries),
+          improve_tries_(improve_tries),
           rnd_(rnd),
           graph_(graph),
           build_status_() {
@@ -286,29 +282,6 @@ class EvenRegularGraphBuilder {
         extend_batch_size = extend_thread_count * extend_thread_task_count * extend_thread_task_size;
     }
 
-    /**
-     * @brief Constructs an EvenRegularGraphBuilder with default parameters for streaming data.
-     *
-     * @param graph Reference to a MutableGraph object to be built and optimized.
-     * @param rnd Reference to a random number generator (std::mt19937) used for randomized operations.
-     * @param swaps Number of improvement attempts per build step (used for both swap_tries and additional_swap_tries).
-     *
-     * This constructor is a convenience overload for quickly creating a builder for streaming data
-     * with default extension and improvement parameters.
-     */
-    EvenRegularGraphBuilder(deglib::graph::MutableGraph& graph, std::mt19937& rnd, const uint32_t swaps)
-        : EvenRegularGraphBuilder(graph, rnd, OptimizationTarget::StreamingData, graph.getEdgesPerVertex(), 0.1f, 0, 0.0f, 5, swaps, swaps) {}
-
-    /**
-     * @brief Constructs an EvenRegularGraphBuilder with default parameters and a single swap attempt.
-     *
-     * @param graph Reference to a MutableGraph object to be built and optimized.
-     * @param rnd Reference to a random number generator (std::mt19937) used for randomized operations.
-     *
-     * This constructor is a convenience overload for quickly creating a builder with minimal configuration.
-     */
-    EvenRegularGraphBuilder(deglib::graph::MutableGraph& graph, std::mt19937& rnd) : EvenRegularGraphBuilder(graph, rnd, 1) {}
-
     /**
      * @brief Constructs an EvenRegularGraphBuilder wrapping a DynamicExplorationGraph facade.
      *
@@ -317,14 +290,13 @@ class EvenRegularGraphBuilder {
     EvenRegularGraphBuilder(
         deglib::DynamicExplorationGraph& graph,
         std::mt19937& rnd,
-        const OptimizationTarget optimization_target,
-        const uint8_t extend_k,
-        const float extend_eps,
-        const uint8_t improve_k,
-        const float improve_eps,
+        const OptimizationTarget optimization_target = OptimizationTarget::LowLID,
+        const uint8_t extend_k = 0,
+        const float extend_eps = 0.1f,
+        const uint8_t improve_k = 0,
+        const float improve_eps = 0.001f,
         const uint8_t max_path_length = 5,
-        const uint32_t swap_tries = 0,
-        const uint32_t additional_swap_tries = 0
+        const uint32_t improve_tries = 0
     )
         : EvenRegularGraphBuilder(
               check_and_get_mutable_graph(graph),
@@ -335,21 +307,9 @@ class EvenRegularGraphBuilder {
               improve_k,
               improve_eps,
               max_path_length,
-              swap_tries,
-              additional_swap_tries
+              improve_tries
           ) {}
 
-    /**
-     * @brief Constructs an EvenRegularGraphBuilder wrapping a DynamicExplorationGraph with default parameters for streaming data.
-     */
-    EvenRegularGraphBuilder(deglib::DynamicExplorationGraph& graph, std::mt19937& rnd, const uint32_t swaps)
-        : EvenRegularGraphBuilder(check_and_get_mutable_graph(graph), rnd, swaps) {}
-
-    /**
-     * @brief Constructs an EvenRegularGraphBuilder wrapping a DynamicExplorationGraph with default parameters and a single swap attempt.
-     */
-    EvenRegularGraphBuilder(deglib::DynamicExplorationGraph& graph, std::mt19937& rnd) : EvenRegularGraphBuilder(check_and_get_mutable_graph(graph), rnd, 1) {}
-
   private:
     static deglib::graph::MutableGraph& check_and_get_mutable_graph(deglib::DynamicExplorationGraph& graph) {
         if (!graph.isMutable()) {
@@ -1494,12 +1454,11 @@ class EvenRegularGraphBuilder {
 
             // try to improve the graph
             if (graph_.size() > edge_per_vertex && improve_k_ > 0) {
-                for (int64_t swap_try = 0; swap_try < int64_t(this->swap_tries_); swap_try++) {
+                for (uint32_t try_idx = 0; try_idx < this->improve_tries_; try_idx++) {
                     this->build_status_.tries++;
 
                     if (this->improveEdges()) {
                         this->build_status_.improved++;
-                        swap_try -= this->additional_swap_tries_;
                     }
                 }
             }
@@ -1539,8 +1498,7 @@ class EvenRegularGraphBuilder {
  * @param improve_k Number of neighbors to consider during improvement (default: 0).
  * @param improve_eps Epsilon value for neighbor search during improvement (default: 0.001f).
  * @param max_path_length Maximum number of edge swaps in a single improvement (default: 5).
- * @param swap_tries Number of improvement attempts per build step (default: 0).
- * @param additional_swap_tries Additional improvement attempts after successful improvement (default: 0).
+ * @param improve_tries Number of improvement attempts per build step (default: 0).
  * @param thread_count Number of threads for construction (0 = single-threaded / default).
  * @param seed Random seed for deterministic construction (default: 42).
  * @param callback Optional progress callback invoked during build.
@@ -1559,8 +1517,7 @@ DynamicExplorationGraph build_from_data(
     const uint8_t improve_k = 0,
     const float improve_eps = 0.001f,
     const uint8_t max_path_length = 5,
-    const uint32_t swap_tries = 0,
-    const uint32_t additional_swap_tries = 0,
+    const uint32_t improve_tries = 0,
     const size_t thread_count = 0,
     const uint32_t seed = 42,
     std::function<void(deglib::builder::BuilderStatus&)> callback = nullptr
@@ -1582,7 +1539,7 @@ DynamicExplorationGraph build_from_data(
 
     std::mt19937 rng(seed);
     auto builder = EvenRegularGraphBuilder(
-        graph, rng, optimization_target, extend_k, extend_eps, improve_k, improve_eps, max_path_length, swap_tries, additional_swap_tries
+        graph, rng, optimization_target, extend_k, extend_eps, improve_k, improve_eps, max_path_length, improve_tries
     );
 
     if (thread_count > 0) {

cpp/deglib/include/deglib/optimization.h

@@ -170,7 +170,7 @@ inline uint32_t prune_non_rng_edges_iterative(deglib::graph::MutableGraph& graph
 inline void optimize_edges(deglib::graph::MutableGraph& graph, const uint8_t k_opt, const float eps_opt, const uint8_t i_opt, const uint32_t iterations) {
     auto rnd = std::mt19937(7);
 
-    auto builder = deglib::builder::EvenRegularGraphBuilder(graph, rnd, deglib::builder::StreamingData, 0, 0.0f, k_opt, eps_opt, i_opt, 1, 0);
+    auto builder = deglib::builder::EvenRegularGraphBuilder(graph, rnd, deglib::builder::StreamingData, 0, 0.0f, k_opt, eps_opt, i_opt, 1);
 
     auto start = std::chrono::steady_clock::now();
     uint64_t duration_ms = 0;

cpp/test/src/common/test_helpers.h

@@ -448,8 +448,7 @@ inline static void run_integration_test(
     const uint8_t improve_k = 0;
     const float improve_eps = 0.0f;
     const uint8_t max_path_length = 5;
-    const uint32_t swap_tries = 0;
-    const uint32_t additional_swap_tries = 0;
+    const uint32_t improve_tries = 0;
     const uint32_t thread_count = 1;
 
     // Build DEG Graph using the specified metric feature space
@@ -462,7 +461,7 @@ inline static void run_integration_test(
 
     std::mt19937 rng(1337);
     deglib::builder::EvenRegularGraphBuilder builder(
-        graph, rng, optimization_target, extend_k, extend_eps, improve_k, improve_eps, max_path_length, swap_tries, additional_swap_tries
+        graph, rng, optimization_target, extend_k, extend_eps, improve_k, improve_eps, max_path_length, improve_tries
     );
     builder.setThreadCount(thread_count);
 
@@ -530,11 +529,10 @@ inline static std::vector<uint32_t> build_graph_for_determinism(
     const uint8_t improve_k = 0;
     const float improve_eps = 0.0f;
     const uint8_t max_path_length = 5;
-    const uint32_t swap_tries = 0;
-    const uint32_t additional_swap_tries = 0;
+    const uint32_t improve_tries = 0;
 
     deglib::builder::EvenRegularGraphBuilder builder(
-        graph, rng, optimization_target, extend_k, extend_eps, improve_k, improve_eps, max_path_length, swap_tries, additional_swap_tries
+        graph, rng, optimization_target, extend_k, extend_eps, improve_k, improve_eps, max_path_length, improve_tries
     );
     builder.setThreadCount(1);
 
@@ -662,8 +660,7 @@ inline static void run_regression_test(
     const uint8_t improve_k = 0;
     const float improve_eps = 0.0f;
     const uint8_t max_path_length = 5;
-    const uint32_t swap_tries = 0;
-    const uint32_t additional_swap_tries = 0;
+    const uint32_t improve_tries = 0;
 
     // Build DEG Graph using the specified metric feature space
     const deglib::distances::FloatSpace feature_space =
@@ -675,7 +672,7 @@ inline static void run_regression_test(
 
     std::mt19937 rng(1337);
     deglib::builder::EvenRegularGraphBuilder builder(
-        graph, rng, optimization_target, extend_k, extend_eps, improve_k, improve_eps, max_path_length, swap_tries, additional_swap_tries
+        graph, rng, optimization_target, extend_k, extend_eps, improve_k, improve_eps, max_path_length, improve_tries
     );
     builder.setThreadCount(thread_count);
     auto t_build_start = std::chrono::high_resolution_clock::now();

cpp/test/src/regression/optimization/flas/test_fast_linear_assignment_sorter_regression.cpp

@@ -86,11 +86,10 @@ static double build_deg_graph(
     const uint8_t improve_k = 0;
     const float improve_eps = 0.0f;
     const uint8_t max_path_length = 5;
-    const uint32_t swap_tries = 0;
-    const uint32_t additional_swap_tries = 0;
+    const uint32_t improve_tries = 0;
 
     deglib::builder::EvenRegularGraphBuilder builder(
-        graph, rng, optimization_target, extend_k, extend_eps, improve_k, improve_eps, max_path_length, swap_tries, additional_swap_tries
+        graph, rng, optimization_target, extend_k, extend_eps, improve_k, improve_eps, max_path_length, improve_tries
     );
     builder.setThreadCount(thread_count);
 

cpp/test/src/regression/test_builder_regression.cpp

@@ -48,7 +48,7 @@ TEST(DeglibBuilderRegression, DynamicGraph_vs_SizeBoundedGraph_100k_Benchmark) {
         std::mt19937 rng(1337);
         deglib::builder::EvenRegularGraphBuilder builder(
             graph, rng, deglib::builder::OptimizationTarget::LowLID, extend_k, extend_eps, /*improve_k=*/0, /*improve_eps=*/0.0f,
-            /*max_path_length=*/5, /*swap_tries=*/0, /*additional_swap_tries=*/0
+            /*max_path_length=*/5, /*improve_tries=*/0
         );
         builder.setThreadCount(thread_count);
 

cpp/test/src/unit/test_builder.cpp

@@ -526,8 +526,7 @@ TEST(EvenRegularGraphBuilder, BuildGraphWithCustomParameters) {
         4,      // improve_k
         0.15f,  // improve_eps
         5,      // max_path_length
-        2,      // swap_tries
-        1       // additional_swap_tries
+        2       // improve_tries
     );
 
     // Create feature vectors
@@ -783,7 +782,7 @@ TEST(BuilderBuildFromData, CustomLabelsAndThreads) {
 
     auto graph = deglib::builder::build_from_data(
         std::span<const float>(dataset), dims, std::span<const uint32_t>(custom_labels), edges_per_vertex, deglib::distances::Metric::FP32_L2,
-        deglib::builder::OptimizationTarget::StreamingData, 0, 0.2f, 0, 0.001f, 5, 0, 0, 2, 123, callback
+        deglib::builder::OptimizationTarget::StreamingData, 0, 0.2f, 0, 0.001f, 5, 0, 2, 123, callback
     );
 
     EXPECT_EQ(graph.size(), num_vectors);

docs/tutorials/building_graphs.rst

@@ -124,12 +124,9 @@ Improvement & Deletion Parameters (Used after Deletions or during Continuous Ref
    * - ``max_path_length``
      - ``5``
      - Maximum number of consecutive edge swaps in a single improvement sequence.
-   * - ``swap_tries``
+   * - ``improve_tries``
      - ``0``
      - Number of improvement attempts executed per build step.
-   * - ``additional_swap_tries``
-     - ``0``
-     - Extra improvement attempts executed immediately after a successful edge swap.
 
 .. note::