Expose GPU heuristics tuning parameters via config files

cpp/cuopt_cli.cpp

@@ -90,11 +90,13 @@ inline cuopt::init_logger_t dummy_logger(
 int run_single_file(const std::string& file_path,
                     const std::string& initial_solution_file,
                     bool solve_relaxation,
-                    const std::map<std::string, std::string>& settings_strings)
+                    const std::map<std::string, std::string>& settings_strings,
+                    const std::string& params_file = "")
 {
   cuopt::linear_programming::solver_settings_t<int, double> settings;
 
   try {
+    if (!params_file.empty()) { settings.load_parameters_from_file(params_file); }
     for (auto& [key, val] : settings_strings) {
       settings.set_parameter_from_string(key, val);
     }
@@ -258,6 +260,16 @@ int set_cuda_module_loading(int argc, char* argv[])
  */
 int main(int argc, char* argv[])
 {
+  // Handle --show-hyper-params before argparse so no other args are required
+  for (int i = 1; i < argc; ++i) {
+    std::string arg = argv[i];
+    if (arg == "--show-hyper-params") {
+      cuopt::linear_programming::solver_settings_t<int, double> settings;
+      settings.dump_parameters_to_file("/dev/stdout", true);
+      return 0;
+    }
+  }
+
   if (set_cuda_module_loading(argc, argv) != 0) { return 1; }
 
   // Get the version string from the version_config.hpp file
@@ -286,6 +298,15 @@ int main(int argc, char* argv[])
     .default_value(true)
     .implicit_value(true);
 
+  program.add_argument("--params-file")
+    .help("path to parameter config file (key = value format, supports all parameters)")
+    .default_value(std::string(""));
+
+  program.add_argument("--show-hyper-params")
+    .help("print hyper-parameters in config-file format and exit")
+    .default_value(false)
+    .implicit_value(true);
+
   std::map<std::string, std::string> arg_name_to_param_name;
 
   // Register --pdlp-precision with string-to-int mapping so that it flows
@@ -311,37 +332,39 @@ int main(int argc, char* argv[])
       std::string arg_name = param_name_to_arg_name(param.param_name);
       // handle duplicate parameters appearing in MIP and LP settings
       if (arg_name_to_param_name.count(arg_name) == 0) {
-        program.add_argument(arg_name.c_str()).default_value(param.default_value);
+        auto& arg = program.add_argument(arg_name.c_str()).default_value(param.default_value);
+        if (param.is_hyperparameter) { arg.hidden(); }
         arg_name_to_param_name[arg_name] = param.param_name;
       }
     }
 
     for (auto& param : double_params) {
       std::string arg_name = param_name_to_arg_name(param.param_name);
-      // handle duplicate parameters appearing in MIP and LP settings
       if (arg_name_to_param_name.count(arg_name) == 0) {
-        program.add_argument(arg_name.c_str()).default_value(param.default_value);
+        auto& arg = program.add_argument(arg_name.c_str()).default_value(param.default_value);
+        if (param.is_hyperparameter) { arg.hidden(); }
         arg_name_to_param_name[arg_name] = param.param_name;
       }
     }
 
     for (auto& param : bool_params) {
       std::string arg_name = param_name_to_arg_name(param.param_name);
       if (arg_name_to_param_name.count(arg_name) == 0) {
-        program.add_argument(arg_name.c_str()).default_value(param.default_value);
+        auto& arg = program.add_argument(arg_name.c_str()).default_value(param.default_value);
+        if (param.is_hyperparameter) { arg.hidden(); }
         arg_name_to_param_name[arg_name] = param.param_name;
       }
     }
 
     for (auto& param : string_params) {
       std::string arg_name = param_name_to_arg_name(param.param_name);
-      // handle duplicate parameters appearing in MIP and LP settings
       if (arg_name_to_param_name.count(arg_name) == 0) {
-        program.add_argument(arg_name.c_str()).default_value(param.default_value);
+        auto& arg = program.add_argument(arg_name.c_str()).default_value(param.default_value);
+        if (param.is_hyperparameter) { arg.hidden(); }
         arg_name_to_param_name[arg_name] = param.param_name;
       }
-    }  // done with solver settings
-  }
+    }
+  }  // done with solver settings
 
   // Parse arguments
   try {
@@ -392,5 +415,8 @@ int main(int argc, char* argv[])
     RAFT_CUDA_TRY(cudaSetDevice(0));
   }
 
-  return run_single_file(file_name, initial_solution_file, solve_relaxation, settings_strings);
+  const auto params_file = program.get<std::string>("--params-file");
+
+  return run_single_file(
+    file_name, initial_solution_file, solve_relaxation, settings_strings, params_file);
 }

cpp/include/cuopt/linear_programming/constants.h

@@ -77,6 +77,25 @@
 #define CUOPT_RANDOM_SEED                     "random_seed"
 #define CUOPT_PDLP_PRECISION                  "pdlp_precision"
 
+/* @brief MIP heuristic hyper-parameter names */
+#define CUOPT_POPULATION_SIZE               "population_size"
+#define CUOPT_NUM_CPUFJ_THREADS             "num_cpufj_threads"
+#define CUOPT_PRESOLVE_TIME_RATIO           "presolve_time_ratio"
+#define CUOPT_PRESOLVE_MAX_TIME             "presolve_max_time"
+#define CUOPT_ROOT_LP_TIME_RATIO            "root_lp_time_ratio"
+#define CUOPT_ROOT_LP_MAX_TIME              "root_lp_max_time"
+#define CUOPT_RINS_TIME_LIMIT               "rins_time_limit"
+#define CUOPT_RINS_MAX_TIME_LIMIT           "rins_max_time_limit"
+#define CUOPT_RINS_FIX_RATE                 "rins_fix_rate"
+#define CUOPT_STAGNATION_TRIGGER            "stagnation_trigger"
+#define CUOPT_MAX_ITERS_WITHOUT_IMPROVEMENT "max_iterations_without_improvement"
+#define CUOPT_INITIAL_INFEASIBILITY_WEIGHT  "initial_infeasibility_weight"
+#define CUOPT_N_OF_MINIMUMS_FOR_EXIT        "n_of_minimums_for_exit"
+#define CUOPT_ENABLED_RECOMBINERS           "enabled_recombiners"
+#define CUOPT_CYCLE_DETECTION_LENGTH        "cycle_detection_length"
+#define CUOPT_RELAXED_LP_TIME_LIMIT         "relaxed_lp_time_limit"
+#define CUOPT_RELATED_VARS_TIME_LIMIT       "related_vars_time_limit"
+
 /* @brief MIP determinism mode constants */
 #define CUOPT_MODE_OPPORTUNISTIC 0
 #define CUOPT_MODE_DETERMINISTIC 1

cpp/include/cuopt/linear_programming/mip/heuristics_hyper_params.hpp

@@ -0,0 +1,40 @@
+/* clang-format off */
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/* clang-format on */
+
+#pragma once
+
+namespace cuopt::linear_programming {
+
+/**
+ * @brief Tuning knobs for MIP GPU heuristics.
+ *
+ * All fields carry their actual defaults. A config file only needs to list
+ * the knobs being changed; omitted keys keep the values shown here.
+ * These are registered in the unified parameter framework via solver_settings_t
+ * and can be loaded from a config file with load_parameters_from_file().
+ */
+struct mip_heuristics_hyper_params_t {
+  int population_size                    = 32;      // max solutions in pool
+  int num_cpufj_threads                  = 8;       // parallel CPU FJ climbers
+  double presolve_time_ratio             = 0.1;     // fraction of total time for presolve
+  double presolve_max_time               = 60.0;    // hard cap on presolve seconds
+  double root_lp_time_ratio              = 0.1;     // fraction of total time for root LP
+  double root_lp_max_time                = 15.0;    // hard cap on root LP seconds
+  double rins_time_limit                 = 3.0;     // per-call RINS sub-MIP time
+  double rins_max_time_limit             = 20.0;    // ceiling for RINS adaptive time budget
+  double rins_fix_rate                   = 0.5;     // RINS variable fix rate
+  int stagnation_trigger                 = 3;       // FP loops w/o improvement before recombination
+  int max_iterations_without_improvement = 8;       // diversity step depth after stagnation
+  double initial_infeasibility_weight    = 1000.0;  // constraint violation penalty seed
+  int n_of_minimums_for_exit             = 7000;    // FJ baseline local-minima exit threshold
+  int enabled_recombiners                = 15;      // bitmask: 1=BP 2=FP 4=LS 8=SubMIP
+  int cycle_detection_length             = 30;      // FP assignment cycle ring buffer
+  double relaxed_lp_time_limit           = 1.0;     // base relaxed LP time cap in heuristics
+  double related_vars_time_limit         = 30.0;    // time for related-variable structure build
+};
+
+}  // namespace cuopt::linear_programming

cpp/include/cuopt/linear_programming/mip/solver_settings.hpp

@@ -10,6 +10,7 @@
 #include <vector>
 
 #include <cuopt/linear_programming/constants.h>
+#include <cuopt/linear_programming/mip/heuristics_hyper_params.hpp>
 #include <cuopt/linear_programming/pdlp/pdlp_hyper_params.cuh>
 #include <cuopt/linear_programming/utilities/internals.hpp>
 
@@ -134,6 +135,8 @@ class mip_solver_settings_t {
   // TODO check with Akif and Alice
   pdlp_hyper_params::pdlp_hyper_params_t hyper_params;
 
+  mip_heuristics_hyper_params_t heuristic_params;
+
  private:
   std::vector<internals::base_solution_callback_t*> mip_callbacks_;
 

cpp/include/cuopt/linear_programming/solver_settings.hpp

@@ -96,6 +96,9 @@ class solver_settings_t {
   const std::vector<parameter_info_t<std::string>>& get_string_parameters() const;
   const std::vector<std::string> get_parameter_names() const;
 
+  void load_parameters_from_file(const std::string& path);
+  bool dump_parameters_to_file(const std::string& path, bool hyperparameters_only = true) const;
+
  private:
   pdlp_solver_settings_t<i_t, f_t> pdlp_settings;
   mip_solver_settings_t<i_t, f_t> mip_settings;

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

@@ -79,37 +79,71 @@ class base_solution_t {
 
 template <typename T>
 struct parameter_info_t {
-  parameter_info_t(std::string_view param_name, T* value, T min, T max, T def)
-    : param_name(param_name), value_ptr(value), min_value(min), max_value(max), default_value(def)
+  parameter_info_t(std::string_view param_name,
+                   T* value,
+                   T min,
+                   T max,
+                   T def,
+                   bool is_hyperparameter  = false,
+                   const char* description = "")
+    : param_name(param_name),
+      value_ptr(value),
+      min_value(min),
+      max_value(max),
+      default_value(def),
+      is_hyperparameter(is_hyperparameter),
+      description(description)
   {
   }
   std::string param_name;
   T* value_ptr;
   T min_value;
   T max_value;
   T default_value;
+  bool is_hyperparameter;
+  const char* description;
 };
 
 template <>
 struct parameter_info_t<bool> {
-  parameter_info_t(std::string_view name, bool* value, bool def)
-    : param_name(name), value_ptr(value), default_value(def)
+  parameter_info_t(std::string_view name,
+                   bool* value,
+                   bool def,
+                   bool is_hyperparameter  = false,
+                   const char* description = "")
+    : param_name(name),
+      value_ptr(value),
+      default_value(def),
+      is_hyperparameter(is_hyperparameter),
+      description(description)
   {
   }
   std::string param_name;
   bool* value_ptr;
   bool default_value;
+  bool is_hyperparameter;
+  const char* description;
 };
 
 template <>
 struct parameter_info_t<std::string> {
-  parameter_info_t(std::string_view name, std::string* value, std::string def)
-    : param_name(name), value_ptr(value), default_value(def)
+  parameter_info_t(std::string_view name,
+                   std::string* value,
+                   std::string def,
+                   bool is_hyperparameter  = false,
+                   const char* description = "")
+    : param_name(name),
+      value_ptr(value),
+      default_value(def),
+      is_hyperparameter(is_hyperparameter),
+      description(description)
   {
   }
   std::string param_name;
   std::string* value_ptr;
   std::string default_value;
+  bool is_hyperparameter;
+  const char* description;
 };
 
 /**