Expose diving hyper parameters

[nguidotti]

Similar to #993, this PR exposes the diving hyper parameters to cuopt_cli and to the public API in order to be easier to tune. They are hidden by default in cuopt_cli.

Checklist

• I am familiar with the Contributing Guidelines.
• Testing
  • New or existing tests cover these changes
  • Added tests
  • Created an issue to follow-up
  • NA
• Documentation
  • The documentation is up to date with these changes
  • Added new documentation
  • NA

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR centralizes MIP diving hyperparameters into a templated mip_diving_hyper_params_t, exposes them via solver settings, switches diving-type logging to a runtime show_type flag, updates strategy enablement and worker allocation to use the new type, and adds debug logs in diving heuristics.

Changes

Diving Heuristic Parameters

Layer / File(s)	Summary
Diving parameter contract definition cpp/include/cuopt/linear_programming/constants.h, cpp/include/cuopt/linear_programming/mip/diving_hyper_params.hpp	New templated mip_diving_hyper_params_t<i_t,f_t> with flags for line-search/pseudocost/guided/coefficient diving, min_node_depth, node_limit, backtrack_limit (i_t), iteration_limit_factor (f_t), and show_type logging flag. String macros added for parameter keys.
Public settings integration & heuristics template cpp/include/cuopt/linear_programming/mip/heuristics_hyper_params.hpp, cpp/include/cuopt/linear_programming/mip/solver_settings.hpp, cpp/tests/mip/heuristics_hyper_params_test.cu	mip_heuristics_hyper_params_t converted to template <i_t,f_t>; mip_solver_settings_t exposes mip_diving_hyper_params_t<i_t,f_t> diving_params; tests updated to instantiate templated type.
Simplex diving settings replacement cpp/src/dual_simplex/simplex_solver_settings.hpp	Removed in-header diving_heuristics_settings_t and changed simplex_solver_settings_t::diving_settings to mip_diving_hyper_params_t<i_t,f_t>.
Diving heuristics utilities cpp/src/branch_and_bound/diving_heuristics.hpp	Added feasible_solution_symbol(search_strategy_t, bool log_diving_type) mapping symbols (collapsed or per-strategy) and is_search_strategy_enabled(search_strategy_t, const mip_diving_hyper_params_t<i_t,f_t>&) that enables strategies by non-zero numeric fields (BEST_FIRST always enabled).
Worker and pseudo-costs refactor cpp/src/branch_and_bound/pseudo_costs.hpp, cpp/src/branch_and_bound/worker.hpp	Removed include from pseudo_costs.hpp and added forward declarations; worker.hpp now includes diving heuristics utilities, removed header-local enable helper, and updated bfs_worker_t::calculate_num_diving_workers to accept const mip_diving_hyper_params_t& and use is_search_strategy_enabled().
Branch-and-bound logging and search integration cpp/src/branch_and_bound/branch_and_bound.cpp	Replaced compile-time symbol mapping with runtime show_type flag; add_feasible_solution() threads show_type into debug logging and reporting; best_first_search_with() copies diving settings, disables/re-enables guided diving based on incumbent and recalculates worker counts.
Configuration registration and wiring cpp/src/math_optimization/solver_settings.cu, cpp/src/mip_heuristics/solver.cu	Registered new float and numeric diving hyperparameters (including iteration_limit_factor, per-strategy toggles, min_node_depth, node_limit, backtrack_limit) and bool show_type in solver param catalog; mip_solver_t::run_solver() wires context.settings.diving_params into branch_and_bound_settings.diving_settings.
Diving heuristics debug instrumentation cpp/src/branch_and_bound/diving_heuristics.cpp	Added log.debug() messages in pseudocost_diving and guided_diving reporting selected branch variable, its value, rounding direction, and computed score.

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Expose diving hyper parameters' directly matches the main objective of the PR: exposing diving hyperparameters to the public API and cuopt_cli.
Description check	✅ Passed	The description clearly explains the PR's purpose: exposing diving hyperparameters to cuopt_cli and public API for easier tuning, following a similar approach to #993.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

cpp/include/cuopt/linear_programming/mip/diving_hyper_params.hpp (1)

8-8: ⚡ Quick win

Use a macro guard here instead of only #pragma once.

The new C++ header does not follow the repository header-guard convention. Please add a normal #define guard and keep #pragma once only if you want it as a secondary optimization.

As per coding guidelines, "Use #define guards on C++ headers".

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@cpp/include/cuopt/linear_programming/mip/diving_hyper_params.hpp` at line 8,
The header currently only has `#pragma once`; add a standard include guard macro
around the file to follow project convention: introduce a unique macro like
CPP_INCLUDE_CUOPT_LINEAR_PROGRAMMING_MIP_DIVING_HYPER_PARAMS_HPP (or similar
uppercase, path-based name) with `#ifndef ... `#define` ...` at the top and a
matching `#endif` at the bottom of diving_hyper_params.hpp, keeping `#pragma
once` if you want it as a secondary optimization; ensure the macro name is
unique and consistent with other headers.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@cpp/src/branch_and_bound/branch_and_bound.cpp`:
- Around line 1758-1760: The code unconditionally sets
diving_settings.guided_diving = 1 before calling
worker->calculate_num_diving_workers(...), overwriting the caller's intended
mode; change this to preserve and reuse the original mode by assigning
diving_settings.guided_diving = settings_.diving_settings.guided_diving (so
guided_diving keeps -1 for automatic or 1 for enabled) before invoking
worker->calculate_num_diving_workers.

In `@cpp/src/branch_and_bound/diving_heuristics.hpp`:
- Around line 42-43: The declaration of is_search_strategy_enabled in
diving_heuristics.hpp uses the type mip_diving_hyper_params_t but the header
doesn't directly include the header that defines that type; make the header
self-contained by adding an `#include` for the header that introduces
mip_diving_hyper_params_t (the file that defines the mip_diving_hyper_params_t
type) to diving_heuristics.hpp so the declaration compiles without relying on
transitive includes.

In `@cpp/src/math_optimization/solver_settings.cu`:
- Around line 118-119: The registration passes
&mip_settings.diving_params.iteration_limit_factor (declared as double in
diving_hyper_params.hpp) into a parameter_info_t<f_t> (used by
solver_settings_t<int, float>), causing a double* vs float* mismatch; fix by
changing the type of iteration_limit_factor in diving_hyper_params.hpp to f_t so
it matches parameter_info_t<f_t>, or alternatively add a specialized
registration path that accepts a double-typed parameter (i.e., a
parameter_info_t<double> entry) for
CUOPT_MIP_HYPER_DIVING_ITERATION_LIMIT_FACTOR and ensure solver_settings
registration logic handles that specialization.

---

Nitpick comments:
In `@cpp/include/cuopt/linear_programming/mip/diving_hyper_params.hpp`:
- Line 8: The header currently only has `#pragma once`; add a standard include
guard macro around the file to follow project convention: introduce a unique
macro like CPP_INCLUDE_CUOPT_LINEAR_PROGRAMMING_MIP_DIVING_HYPER_PARAMS_HPP (or
similar uppercase, path-based name) with `#ifndef ... `#define` ...` at the top
and a matching `#endif` at the bottom of diving_hyper_params.hpp, keeping
`#pragma once` if you want it as a secondary optimization; ensure the macro name
is unique and consistent with other headers.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 877a2203-2924-4ddf-bcb2-d88a2e40efd0

📥 Commits

Reviewing files that changed from the base of the PR and between fa67d5e and fc1ab19.

📒 Files selected for processing (11)

• cpp/include/cuopt/linear_programming/constants.h
• cpp/include/cuopt/linear_programming/mip/diving_hyper_params.hpp
• cpp/include/cuopt/linear_programming/mip/solver_settings.hpp
• cpp/src/branch_and_bound/branch_and_bound.cpp
• cpp/src/branch_and_bound/diving_heuristics.cpp
• cpp/src/branch_and_bound/diving_heuristics.hpp
• cpp/src/branch_and_bound/pseudo_costs.hpp
• cpp/src/branch_and_bound/worker.hpp
• cpp/src/dual_simplex/simplex_solver_settings.hpp
• cpp/src/math_optimization/solver_settings.cu
• cpp/src/mip_heuristics/solver.cu

[coderabbitai]

♻️ Duplicate comments (1)

cpp/src/branch_and_bound/branch_and_bound.cpp (1)

1755-1761: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Preserve the original guided-diving mode when re-enabling.

Line 1758 hardcodes diving_settings.guided_diving = 1, but the original setting might have been -1 (automatic) rather than 1 (enabled). Restoring the original value from settings_.diving_settings.guided_diving preserves the caller's intended mode.

Suggested fix

-        diving_settings.guided_diving = 1;
+        diving_settings.guided_diving = settings_.diving_settings.guided_diving;

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@cpp/src/branch_and_bound/branch_and_bound.cpp` around lines 1755 - 1761, The
code currently forces diving_settings.guided_diving = 1 when re-enabling guided
diving; instead restore the original mode from
settings_.diving_settings.guided_diving so automatic (-1) vs enabled (1) is
preserved. Update the block that checks diving_worker_pool_.size() and
settings_.diving_settings.guided_diving to assign diving_settings.guided_diving
= settings_.diving_settings.guided_diving (not literal 1) before calling
worker->calculate_num_diving_workers(bfs_worker_pool_.size(),
diving_worker_pool_.size(), diving_settings), keeping the
has_solver_space_incumbent() check unchanged.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Duplicate comments:
In `@cpp/src/branch_and_bound/branch_and_bound.cpp`:
- Around line 1755-1761: The code currently forces diving_settings.guided_diving
= 1 when re-enabling guided diving; instead restore the original mode from
settings_.diving_settings.guided_diving so automatic (-1) vs enabled (1) is
preserved. Update the block that checks diving_worker_pool_.size() and
settings_.diving_settings.guided_diving to assign diving_settings.guided_diving
= settings_.diving_settings.guided_diving (not literal 1) before calling
worker->calculate_num_diving_workers(bfs_worker_pool_.size(),
diving_worker_pool_.size(), diving_settings), keeping the
has_solver_space_incumbent() check unchanged.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 69c1430e-729e-4b5e-ab18-aa8abd5151ec

📥 Commits

Reviewing files that changed from the base of the PR and between fc1ab19 and c385de1.

📒 Files selected for processing (10)

• cpp/include/cuopt/linear_programming/constants.h
• cpp/include/cuopt/linear_programming/mip/diving_hyper_params.hpp
• cpp/include/cuopt/linear_programming/mip/heuristics_hyper_params.hpp
• cpp/include/cuopt/linear_programming/mip/solver_settings.hpp
• cpp/src/branch_and_bound/branch_and_bound.cpp
• cpp/src/branch_and_bound/diving_heuristics.hpp
• cpp/src/branch_and_bound/worker.hpp
• cpp/src/dual_simplex/simplex_solver_settings.hpp
• cpp/src/math_optimization/solver_settings.cu
• cpp/tests/mip/heuristics_hyper_params_test.cu

✅ Files skipped from review due to trivial changes (1)

• cpp/src/math_optimization/solver_settings.cu

🚧 Files skipped from review as they are similar to previous changes (5)

• cpp/src/branch_and_bound/diving_heuristics.hpp
• cpp/include/cuopt/linear_programming/mip/solver_settings.hpp
• cpp/include/cuopt/linear_programming/constants.h
• cpp/src/dual_simplex/simplex_solver_settings.hpp
• cpp/src/branch_and_bound/worker.hpp

[coderabbitai]

🧹 Nitpick comments (2)

cpp/include/cuopt/linear_programming/mip/diving_hyper_params.hpp (2)

22-26: ⚡ Quick win

Add per-member documentation for heuristic enable flags.

The tri-state semantics (-1 automatic, 0 disabled, 1 enabled) are documented only in a single-line comment. For a public API, consider adding inline documentation for each flag explaining what "automatic" mode does for that specific heuristic.

📝 Example documentation pattern

-  // -1 automatic, 0 disabled, 1 enabled
-  i_t line_search_diving = -1;
+  /// Enable line-search diving heuristic: -1 (automatic, enabled based on problem characteristics), 0 (disabled), 1 (enabled).
+  i_t line_search_diving = -1;

As per coding guidelines, public C++ headers should document algorithm parameters clearly.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@cpp/include/cuopt/linear_programming/mip/diving_hyper_params.hpp` around
lines 22 - 26, Add inline Doxygen-style comments for each public member
(line_search_diving, pseudocost_diving, guided_diving, coefficient_diving) that
state the tri-state semantics (-1 = automatic, 0 = disabled, 1 = enabled) and
briefly explain what "automatic" chooses for that specific heuristic (e.g.,
select based on problem size/LP relaxation info, use historical pseudocosts,
enable guided branching when strong inference exists, or pick coefficient-based
rules respectively). Place these short comments immediately above each member
declaration in diving_hyper_params.hpp so the public API documents behavior
per-flag.

---

12-21: ⚡ Quick win

Document template parameters.

The template parameters i_t and f_t are not documented. Consider adding @tparam tags to clarify expected types and constraints (e.g., i_t must be a signed integer type to support the -1 automatic mode).

📝 Suggested documentation enhancement

 /**
  * `@brief` Tuning knobs for the dual-simplex diving heuristics used in MIP B&B.
  *
+ * `@tparam` i_t  Signed integer type for counts, limits, and tri-state flags.
+ * `@tparam` f_t  Floating-point type for scaling factors.
+ *
  * Used directly as simplex_solver_settings_t::diving_settings and copied into

As per coding guidelines, public C++ headers should document parameters and types for API clarity.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@cpp/include/cuopt/linear_programming/mip/diving_hyper_params.hpp` around
lines 12 - 21, Add Doxygen `@tparam` documentation for the template parameters on
the mip_diving_hyper_params_t template: document i_t as the integer index/size
type (must be a signed integer type because -1 is used for "automatic" mode) and
document f_t as the floating-point type used for numeric thresholds/weights
(e.g., double/float). Place the `@tparam` entries in the existing comment block
immediately above the template<typename i_t, typename f_t> struct
mip_diving_hyper_params_t so the API docs clearly state the expected types and
any constraints.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@cpp/include/cuopt/linear_programming/mip/diving_hyper_params.hpp`:
- Around line 22-26: Add inline Doxygen-style comments for each public member
(line_search_diving, pseudocost_diving, guided_diving, coefficient_diving) that
state the tri-state semantics (-1 = automatic, 0 = disabled, 1 = enabled) and
briefly explain what "automatic" chooses for that specific heuristic (e.g.,
select based on problem size/LP relaxation info, use historical pseudocosts,
enable guided branching when strong inference exists, or pick coefficient-based
rules respectively). Place these short comments immediately above each member
declaration in diving_hyper_params.hpp so the public API documents behavior
per-flag.
- Around line 12-21: Add Doxygen `@tparam` documentation for the template
parameters on the mip_diving_hyper_params_t template: document i_t as the
integer index/size type (must be a signed integer type because -1 is used for
"automatic" mode) and document f_t as the floating-point type used for numeric
thresholds/weights (e.g., double/float). Place the `@tparam` entries in the
existing comment block immediately above the template<typename i_t, typename
f_t> struct mip_diving_hyper_params_t so the API docs clearly state the expected
types and any constraints.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: c64e4a8f-3405-47c1-a6e9-11eff3ac628b

📥 Commits

Reviewing files that changed from the base of the PR and between c385de1 and 1da6200.

📒 Files selected for processing (2)

• cpp/include/cuopt/linear_programming/mip/diving_hyper_params.hpp
• cpp/src/branch_and_bound/diving_heuristics.hpp

🚧 Files skipped from review as they are similar to previous changes (1)

• cpp/src/branch_and_bound/diving_heuristics.hpp

[nguidotti]

/merge