Make iterative refinement options as ENUM & ND level as a hyperparameters

Signed-off-by: yuwenchen95 <yuwchen@nvidia.com>

Author: yuwenchen95

cpp/include/cuopt/mathematical_optimization/constants.h

@@ -50,11 +50,10 @@
 #define CUOPT_POSTSOLVE_INFO                        "postsolve_info"
 #define CUOPT_BARRIER_PRESOLVE_BOUND_FREE_VARIABLES "barrier_presolve_bound_free_variables"
 #define CUOPT_BARRIER_ITERATIVE_REFINEMENT          "barrier_iterative_refinement"
-#define CUOPT_BARRIER_ITERATIVE_REFINEMENT_METHOD   "barrier_iterative_refinement_method"
 #define CUOPT_BARRIER_STEP_SCALE                    "barrier_step_scale"
 #define CUOPT_ELIMINATE_DENSE_COLUMNS               "eliminate_dense_columns"
 #define CUOPT_CUDSS_DETERMINISTIC                   "cudss_deterministic"
-#define CUOPT_CUDSS_ND_NLEVELS                      "cudss_nd_nlevels"
+#define CUOPT_CUDSS_HYPER_ND_NLEVELS                "cudss_hyper_nd_nlevels"
 #define CUOPT_PRESOLVE                              "presolve"
 #define CUOPT_MIP_PROBING                           "mip_probing"
 #define CUOPT_DUAL_POSTSOLVE                        "dual_postsolve"
@@ -240,8 +239,10 @@
 #define CUOPT_MIP_SCALING_ON           1
 #define CUOPT_MIP_SCALING_NO_OBJECTIVE 2
 
-#define CUOPT_BARRIER_ITERATIVE_REFINEMENT_OFF 0
-#define CUOPT_BARRIER_ITERATIVE_REFINEMENT_ON  1
+/* @brief Iterative refinement for barrier method */
+#define CUOPT_BARRIER_IR_OFF         0
+#define CUOPT_BARRIER_IR_GMRES       1
+#define CUOPT_BARRIER_IR_FIXED_POINT 2
 
 /* @brief Scalar problem attribute selectors
  * Passed as cuopt_int_t; the valid set depends on the accessor's value type. */

cpp/include/cuopt/mathematical_optimization/pdlp/solver_settings.hpp

@@ -304,8 +304,8 @@ class pdlp_solver_settings_t {
   i_t qcqp_ruiz_equilibration{-1};
   bool eliminate_dense_columns{true};
   pdlp_precision_t pdlp_precision{pdlp_precision_t::DefaultPrecision};
-  bool barrier_iterative_refinement{true};
-  i_t barrier_iterative_refinement_method{1};  // 0: fixed_point, 1: gmres (default)
+  // Iterative refinement for barrier method: 0: off, 1: gmres (default), 2: fixed_point
+  i_t barrier_iterative_refinement{barrier_iterative_refinement_t::GMRES};
   i_t barrier_soc_threshold{100};
   f_t barrier_step_scale{0.9};
   bool save_best_primal_so_far{false};

cpp/include/cuopt/mathematical_optimization/utilities/internals.hpp

@@ -142,5 +142,19 @@ enum presolver_t : int {
   PSLP    = CUOPT_PRESOLVE_PSLP
 };
 
+/**
+ * @brief Enum representing the iterative refinement method used by the barrier
+ * solver after each solve.
+ *
+ * Off: Disable iterative refinement.
+ * GMRES: Use restarted GMRES (default).
+ * FixedPoint: Use a fixed-point residual-correction loop.
+ */
+enum barrier_iterative_refinement_t : int {
+  Off        = CUOPT_BARRIER_IR_OFF,
+  GMRES      = CUOPT_BARRIER_IR_GMRES,
+  FixedPoint = CUOPT_BARRIER_IR_FIXED_POINT
+};
+
 }  // namespace mathematical_optimization
 }  // namespace cuopt

cpp/src/barrier/barrier.cu

@@ -2278,10 +2278,13 @@ int barrier_solver_t<i_t, f_t>::initial_point(iteration_data_t<i_t, f_t>& data)
       }
     } op(data);
 
-    if (settings.barrier_iterative_refinement) {
+    if (settings.barrier_iterative_refinement != barrier_iterative_refinement_t::Off) {
       const f_t ir_tol = data.has_sparse_cones() ? f_t(1e-12) : f_t(1e-8);
-      iterative_refinement<i_t, f_t, op_t>(
-        op, rhs, soln, ir_tol, settings.barrier_iterative_refinement_method);
+
+      const i_t internal_method =
+        (settings.barrier_iterative_refinement == barrier_iterative_refinement_t::FixedPoint) ? 0
+                                                                                              : 1;
+      iterative_refinement<i_t, f_t, op_t>(op, rhs, soln, ir_tol, internal_method);
     }
 
     for (i_t k = 0; k < lp.num_cols; k++) {
@@ -2904,15 +2907,15 @@ i_t barrier_solver_t<i_t, f_t>::gpu_compute_search_direction(iteration_data_t<i_
         data_.chol->solve(b, x);
       }
     } op(data);
-    if (settings.barrier_iterative_refinement) {
+    if (settings.barrier_iterative_refinement != barrier_iterative_refinement_t::Off) {
       raft::common::nvtx::range fun_scope("Barrier: iterative_refinement");
       const f_t ir_tol = data.has_sparse_cones() ? f_t(1e-12) : f_t(1e-8);
-      const f_t solve_err =
-        iterative_refinement<i_t, f_t, op_t>(op,
-                                             data.d_augmented_rhs_,
-                                             data.d_augmented_soln_,
-                                             ir_tol,
-                                             settings.barrier_iterative_refinement_method);
+
+      const i_t internal_method =
+        (settings.barrier_iterative_refinement == barrier_iterative_refinement_t::FixedPoint) ? 0
+                                                                                              : 1;
+      const f_t solve_err = iterative_refinement<i_t, f_t, op_t>(
+        op, data.d_augmented_rhs_, data.d_augmented_soln_, ir_tol, internal_method);
       if (solve_err > 1e-1) {
         settings.log.printf("|| Aug (dx, dy) - aug_rhs || %e after IR\n", solve_err);
       }
@@ -2982,7 +2985,8 @@ i_t barrier_solver_t<i_t, f_t>::gpu_compute_search_direction(iteration_data_t<i_
       // GMRES can handle large, potentially ill-conditioned systems better than simple Richardson
       // or classical iterative refinement, at the potential cost of higher computational work and
       // memory. This is only used on the pure Schur-complement (n_dense_columns == 0).
-      if (settings.barrier_iterative_refinement && data.n_dense_columns == 0) {
+      if (settings.barrier_iterative_refinement != barrier_iterative_refinement_t::Off &&
+          data.n_dense_columns == 0) {
         struct adat_op_t {
           adat_op_t(iteration_data_t<i_t, f_t>& data) : data_(data) {}
           iteration_data_t<i_t, f_t>& data_;
@@ -2998,8 +3002,12 @@ i_t barrier_solver_t<i_t, f_t>::gpu_compute_search_direction(iteration_data_t<i_
             data_.gpu_solve_adat(b, x);
           }
         } adat_op(data);
+
+        const i_t internal_method =
+          (settings.barrier_iterative_refinement == barrier_iterative_refinement_t::FixedPoint) ? 0
+                                                                                                : 1;
         const f_t adat_solve_err = iterative_refinement<i_t, f_t, adat_op_t>(
-          adat_op, data.d_h_, data.d_dy_, f_t(1e-8), settings.barrier_iterative_refinement_method);
+          adat_op, data.d_h_, data.d_dy_, f_t(1e-8), internal_method);
         if (adat_solve_err > 1e-1) {
           settings.log.printf("||ADAT*dy - h|| %e after IR\n", adat_solve_err);
         }

cpp/src/barrier/iterative_refinement.hpp

@@ -362,11 +362,8 @@ f_t iterative_refinement_gmres(T& op,
 }
 
 template <typename i_t, typename f_t, typename T>
-f_t iterative_refinement(T& op,
-                         const dense_vector_t<i_t, f_t>& b,
-                         dense_vector_t<i_t, f_t>& x,
-                         f_t tol    = 1e-8,
-                         i_t method = 1)
+f_t iterative_refinement(
+  T& op, const dense_vector_t<i_t, f_t>& b, dense_vector_t<i_t, f_t>& x, f_t tol, i_t method)
 {
   rmm::device_uvector<f_t> d_b(b.size(), op.data_.handle_ptr->get_stream());
   raft::copy(d_b.data(), b.data(), b.size(), op.data_.handle_ptr->get_stream());
@@ -382,11 +379,8 @@ f_t iterative_refinement(T& op,
 }
 
 template <typename i_t, typename f_t, typename T>
-f_t iterative_refinement(T& op,
-                         const rmm::device_uvector<f_t>& b,
-                         rmm::device_uvector<f_t>& x,
-                         f_t tol    = 1e-8,
-                         i_t method = 1)
+f_t iterative_refinement(
+  T& op, const rmm::device_uvector<f_t>& b, rmm::device_uvector<f_t>& x, f_t tol, i_t method)
 {
   return (method == 0) ? iterative_refinement_fixed_point<i_t, f_t, T>(op, b, x, tol)
                        : iterative_refinement_gmres<i_t, f_t, T>(op, b, x, tol);

cpp/src/dual_simplex/simplex_solver_settings.hpp

@@ -9,6 +9,7 @@
 
 #include <cuopt/mathematical_optimization/mip/diving_hyper_params.hpp>
 #include <cuopt/mathematical_optimization/mip/submip_hyper_params.hpp>
+#include <cuopt/mathematical_optimization/utilities/internals.hpp>
 
 #include <dual_simplex/logger.hpp>
 #include <math_optimization/types.hpp>
@@ -70,8 +71,7 @@ struct simplex_solver_settings_t {
       deterministic(false),
       barrier(false),
       eliminate_dense_columns(true),
-      barrier_iterative_refinement(true),
-      barrier_iterative_refinement_method(1),
+      barrier_iterative_refinement(barrier_iterative_refinement_t::GMRES),
       barrier_step_scale(0.9),
       barrier_soc_threshold(100),
       num_gpus(1),
@@ -166,11 +166,10 @@ struct simplex_solver_settings_t {
   i_t cudss_nd_nlevels;       // -1 automatic/unset, else METIS nested-dissection depth for cuDSS
   bool barrier;               // true to use barrier method, false to use dual simplex method
   bool deterministic;  // true to use B&B deterministic mode, false to use non-deterministic mode
-  bool eliminate_dense_columns;             // true to eliminate dense columns from A*D*A^T
-  bool barrier_iterative_refinement;        // true to use iterative refinement for barrier method
-  i_t barrier_iterative_refinement_method;  // 0: fixed_point, 1: gmres
-  f_t barrier_step_scale;                   // step scale for barrier method
-  i_t barrier_soc_threshold;  // SOC dimension above which rank-2 sparse scaling is used
+  bool eliminate_dense_columns;      // true to eliminate dense columns from A*D*A^T
+  i_t barrier_iterative_refinement;  // 0: off, 1: gmres (default), 2: fixed_point
+  f_t barrier_step_scale;            // step scale for barrier method
+  i_t barrier_soc_threshold;         // SOC dimension above which rank-2 sparse scaling is used
   int num_gpus;   // Number of GPUs to use (maximum of 2 gpus are supported at the moment)
   i_t folding;    // -1 automatic, 0 don't fold, 1 fold
   i_t augmented;  // -1 automatic, 0 to solve with ADAT, 1 to solve with augmented system

cpp/src/grpc/codegen/field_registry.yaml

@@ -496,8 +496,7 @@ pdlp_settings:
   - dual_postsolve:
       # C++ default is `true`; using proto3 `optional` so that a client that
       # omits this field gets the solver default rather than the proto3 zero
-      # (`false`). See also the matching `optional` markers on
-      # `barrier_iterative_refinement` (pdlp) and `probing` (mip).
+      # (`false`). See also the matching `optional` marker on `probing` (mip).
       field_num: 17
       type: bool
       optional: true
@@ -539,15 +538,6 @@ pdlp_settings:
       field_num: 27
       type: bool
       optional: true
-  - barrier_iterative_refinement:
-      # Whether the barrier method runs iterative refinement after each solve
-      # (see cpp/src/barrier/barrier.cu). C++ default is `true`. Declared as
-      # proto3 `optional` so that a client which omits this field preserves
-      # the solver default; without `optional`, the proto3 wire zero (`false`)
-      # would silently overwrite the C++ default.
-      field_num: 31
-      type: bool
-      optional: true
   - barrier_step_scale:
       # Step scale used by the barrier method primal/dual updates. Local-solve
       # binding restricts the range to [0.5, 0.9999] with default 0.9; see
@@ -565,7 +555,10 @@ pdlp_settings:
       optional: true
   # field_num 35-37 previously used by cudss_hybrid_mode/cudss_hybrid_execute_mode/
   # cudss_host_nthreads, removed — do not reuse these numbers.
-  - barrier_iterative_refinement_method:
+  # field_num 31 previously held `barrier_iterative_refinement` as a bool; that field
+  # was retired and the name reused below (field_num 38) for the merged int method,
+  # so the exposed parameter name is unchanged even though the wire field_num moved.
+  - barrier_iterative_refinement:
       field_num: 38
       type: int32
       optional: true
@@ -736,8 +729,7 @@ mip_settings:
       # C++ default is `true`; declared as proto3 `optional` so that a client
       # which omits this field preserves the solver default. Without
       # `optional`, the proto3 wire zero (`false`) would silently overwrite
-      # the C++ default. See also `dual_postsolve` and
-      # `barrier_iterative_refinement` in pdlp_settings.
+      # the C++ default. See also `dual_postsolve` in pdlp_settings.
       field_num: 29
       type: bool
       optional: true

cpp/src/grpc/codegen/generated/cuopt_remote_data.proto

@@ -191,11 +191,10 @@ message PDLPSolverSettings {
   bool save_best_primal_so_far = 28;
   bool first_primal_feasible = 29;
   optional int32 pdlp_precision = 30;
-  optional bool barrier_iterative_refinement = 31;
   optional double barrier_step_scale = 32;
   optional int32 postsolve_info = 33;
   optional int32 cudss_nd_nlevels = 34;
-  optional int32 barrier_iterative_refinement_method = 38;
+  optional int32 barrier_iterative_refinement = 38;
   PDLPWarmStartData warm_start_data = 50;
 }
 

cpp/src/grpc/codegen/generated/generated_pdlp_settings_to_proto.inc

@@ -33,11 +33,10 @@
   pb_settings->set_ordering(settings.ordering);
   pb_settings->set_barrier_dual_initial_point(settings.barrier_dual_initial_point);
   pb_settings->set_eliminate_dense_columns(settings.eliminate_dense_columns);
-  pb_settings->set_barrier_iterative_refinement(settings.barrier_iterative_refinement);
   pb_settings->set_barrier_step_scale(settings.barrier_step_scale);
   pb_settings->set_postsolve_info(settings.postsolve_info);
   pb_settings->set_cudss_nd_nlevels(settings.cudss_nd_nlevels);
-  pb_settings->set_barrier_iterative_refinement_method(settings.barrier_iterative_refinement_method);
+  pb_settings->set_barrier_iterative_refinement(settings.barrier_iterative_refinement);
   pb_settings->set_save_best_primal_so_far(settings.save_best_primal_so_far);
   pb_settings->set_first_primal_feasible(settings.first_primal_feasible);
   pb_settings->set_pdlp_precision(static_cast<int32_t>(settings.pdlp_precision));

cpp/src/grpc/codegen/generated/generated_proto_to_pdlp_settings.inc

@@ -73,9 +73,6 @@
   if (pb_settings.has_eliminate_dense_columns()) {
     settings.eliminate_dense_columns = pb_settings.eliminate_dense_columns();
   }
-  if (pb_settings.has_barrier_iterative_refinement()) {
-    settings.barrier_iterative_refinement = pb_settings.barrier_iterative_refinement();
-  }
   if (pb_settings.has_barrier_step_scale()) {
     settings.barrier_step_scale = pb_settings.barrier_step_scale();
   }
@@ -85,8 +82,8 @@
   if (pb_settings.has_cudss_nd_nlevels()) {
     settings.cudss_nd_nlevels = pb_settings.cudss_nd_nlevels();
   }
-  if (pb_settings.has_barrier_iterative_refinement_method()) {
-    settings.barrier_iterative_refinement_method = pb_settings.barrier_iterative_refinement_method();
+  if (pb_settings.has_barrier_iterative_refinement()) {
+    settings.barrier_iterative_refinement = pb_settings.barrier_iterative_refinement();
   }
   settings.save_best_primal_so_far = pb_settings.save_best_primal_so_far();
   settings.first_primal_feasible = pb_settings.first_primal_feasible();