Update LP/QP/MILP docs to cover 26.06 API additions#1339
Conversation
rg20
added
doc
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughExpanded cuOpt docs: added C problem write API and MPS file format constant; documented many solver parameter and method constants; added warm‑start/MIP‑start and MIP callback docs; extended lp-qp-milp settings; exposed Python Problem members and added SOCP (beta) docs. ChangesAPI Documentation Expansion
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
docs/cuopt/source/lp-qp-milp-settings.rst (1)
570-576: 💤 Low valueClarify the default value notation for strong branching simplex iteration limit.
The note says "By default there is no iteration limit" but does not explicitly mention that the implementation uses
-1to represent "no limit." For consistency with other parameters (e.g.,CUOPT_RANDOM_SEEDat line 660), consider stating the actual default value.♻️ Suggested clarification
-.. note:: By default there is no iteration limit for strong branching solves. +.. note:: The default value is ``-1`` (no iteration limit).🤖 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 `@docs/cuopt/source/lp-qp-milp-settings.rst` around lines 570 - 576, Update the documentation for CUOPT_MIP_STRONG_BRANCHING_SIMPLEX_ITERATION_LIMIT to explicitly state that the implementation uses -1 to denote "no limit" (e.g., "Default: -1 (no limit)"), mirroring the notation used for other parameters like CUOPT_RANDOM_SEED; edit the paragraph and the note text so readers see the concrete default value and its meaning.
🤖 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 `@docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rst`:
- Around line 46-49: Update the brief description so it accurately reflects
cuOptWriteProblem's purpose: change the sentence "Optimization problems can be
created or loaded via the following functions" to a phrase that includes writing
(for example, "Optimization problems can be created, loaded, or written via the
following functions") or split into two sentences separating creation/loading
from read/write operations; ensure both cuOptReadProblem and cuOptWriteProblem
are mentioned appropriately (e.g., "...loaded via cuOptReadProblem" and
"...written via cuOptWriteProblem") so the docstring precisely matches each
function's role.
In `@docs/cuopt/source/lp-qp-milp-settings.rst`:
- Around line 629-636: The docs for CUOPT_MIP_OBJECTIVE_STEP are incorrect: the
implementation treats objective_step as a 0/1 toggle (objective_step = 1 by
default) rather than a positive numeric step; update the text to state that
CUOPT_MIP_OBJECTIVE_STEP is a boolean-like flag (0 = disable, 1 = enable),
change the default in the note to 1 (enabled), and remove or reword any mention
of providing a positive step size to override detection so the wording matches
the implementation referenced in solver_settings.cu and solver_settings.hpp and
the objective_step field.
---
Nitpick comments:
In `@docs/cuopt/source/lp-qp-milp-settings.rst`:
- Around line 570-576: Update the documentation for
CUOPT_MIP_STRONG_BRANCHING_SIMPLEX_ITERATION_LIMIT to explicitly state that the
implementation uses -1 to denote "no limit" (e.g., "Default: -1 (no limit)"),
mirroring the notation used for other parameters like CUOPT_RANDOM_SEED; edit
the paragraph and the note text so readers see the concrete default value and
its meaning.
🪄 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: 4afe87cf-5eb8-4fda-8c04-6f8f5a8aec6c
📒 Files selected for processing (3)
docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rstdocs/cuopt/source/cuopt-python/lp-qp-milp/lp-qp-milp-api.rstdocs/cuopt/source/lp-qp-milp-settings.rst
- C API: add cuOptWriteProblem, warm start functions (cuOptSetInitialPrimalSolution, cuOptSetInitialDualSolution, cuOptAddMIPStart), MIP callback types and registration functions, file format constants, MIP determinism mode constants, barrier iterative refinement constants, CUOPT_TERMINATION_STATUS_WORK_LIMIT, CUOPT_METHOD_UNSET, and all previously missing parameter constants (work limit, random seed, presolve file, num GPUs, MIP symmetry, MIP determinism mode, cut types, branching settings, etc.) - Python API: expose NumVariables, NumConstraints, NumNZs, IsMIP properties - Settings: add descriptions for work limit, random seed, presolve file, primal/dual infeasibility tolerances, barrier iterative refinement, barrier step scale, MIP determinism mode, MIP symmetry, flow cover/implied bound/clique cuts, objective step, semi-continuous big-M, batch PDLP reliability branching, strong branching simplex limit Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- lp-qp-features.rst: add Second-Order Cone Programming beta section explaining SOCP support via quadratic constraints, auto barrier selection, constraints/limitations, and Python/C usage examples - lp-qp-milp-c-api.rst: add beta note to cuOptAddQuadraticConstraint section explaining SOCP auto-detection and sense restrictions - lp-qp-milp-api.rst: expose QuadraticExpression __le__, __ge__, __neg__ operators via special-members for SOCP constraint authoring - Update index titles in C and Python sections to include SOCP Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
/ok to test e99f396 |
rgsl888prabhu
left a comment
rgsl888prabhu
left a comment
There was a problem hiding this comment.
I would suggest to add few examples on SOCP to different APIs.
Restructure the combined LP/QP/MILP documentation into two distinct sections: - Continuous Optimization (LP, QP, SOCP/QCQP) with dedicated settings, C API, Python API, and examples pages - MIP with its own settings, C API, Python API, and examples pages Files are kept flat within existing lp-qp-milp/ directories. Old combined files remain on disk for reference but are removed from toctrees. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Fix RST title underline length warning in cuopt-python/lp-qp-milp/index.rst. Remove old combined LP/QP/MILP files that have been replaced by the split continuous/MIP documentation: - lp-qp-milp-settings.rst → continuous-settings.rst + mip-settings.rst - lp-qp-features.rst → continuous-features.rst - lp-qp-milp-c-api.rst → continuous-c-api.rst + mip-c-api.rst - lp-qp-example.rst → continuous-examples.rst - milp-examples.rst → mip-examples.rst - lp-qp-milp-api.rst → continuous-api.rst - lp-qp-milp-examples.rst → continuous-examples.rst + mip-examples.rst Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Split lp-qp-milp/ into separate domain directories: - cuopt-c/continuous/ — LP/QP/SOCP C API, settings, and examples - cuopt-c/mip/ — MIP C API, settings, and examples - cuopt-python/continuous/ — LP/QP/SOCP Python API and examples - cuopt-python/mip/ — MIP Python API and examples Parallel structure with cuopt-python/routing/ for consistency. Update all cross-references in settings, grpc, and parent index files. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
cuOpt reads quadratic constraints in QCQP format and converts to second-order cone form internally. Update the problem formulation, example comments, and C API note to reflect the actual user-facing API. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…neral QCQP cuOpt supports SOCP, not general QCQP. SOC constraints are specified via the quadratic constraint API (||u||_2 <= t written as u^T*u - t^2 <= 0), and cuOpt detects SOC structure internally. Make this distinction explicit and add a note that arbitrary quadratic constraints are not supported. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
|
||
| .. note:: | ||
| ``cuOptAddQuadraticConstraint`` enables **SOCP (beta)** support. SOC constraints are specified | ||
| as quadratic inequalities (e.g. ``u^T*u - t^2 <= 0`` for ``||u||_2 <= t``); cuOpt detects the |
There was a problem hiding this comment.
Rotated SOC format (u^T*u <= t * y, y >= 0, t >= 0) should be documented if supported.
There was a problem hiding this comment.
Done — the C API note now documents both standard and rotated second-order cones (e.g. x1^2 + x2^2 - x3*x4 <= 0).
|
|
||
| .. code-block:: text | ||
|
|
||
| Optimal solution found in 0.00 seconds |
There was a problem hiding this comment.
Do we have a way to test that the script produces exactly this output?
There was a problem hiding this comment.
I think so. @rgsl888prabhu I remember you had a way to test these.
There was a problem hiding this comment.
We run the tests to make sure they don't fail, but we provide sample output but we don't keep it synched with the response in the doc. Response is meant for reference to explain what to expect.
There was a problem hiding this comment.
ci/test_doc_examples.sh discovers and runs every examples/*.py (and builds/runs the C examples) as a smoke test (pass = exit 0); it does not yet assert exact printed output. All example outputs here were verified manually against a local build.
|
|
||
| .. note:: | ||
| The QP solver is not currently supported in third-party modeling languages. | ||
| The QP and SOCP solvers are not currently supported in third-party modeling languages. |
There was a problem hiding this comment.
QP is supported via JuMP, and I think this text may not age well since other interfaces will likely add support for socp quickly.
There was a problem hiding this comment.
Reworded to "SOCP is not yet supported in third-party modeling languages."
| ||u_i||_2 <= t_i (second-order cone constraints) | ||
| lb <= x <= ub | ||
|
|
||
| Because cuOpt does not accept cone constraints directly, SOC constraints are specified through the quadratic constraint API. Each SOC constraint ``||u||_2 <= t`` is expressed as the equivalent quadratic inequality ``u^T*u - t^2 <= 0``. cuOpt detects the SOC structure and converts to cone form internally before solving with the barrier method. |
There was a problem hiding this comment.
Mention rotated SOC if supported.
There was a problem hiding this comment.
Rotated second-order cone is supported through quadratic constraint API, we should also mention it.
There was a problem hiding this comment.
Done — rotated SOC is now documented with an example (Python, C, and MPS).
Add CVXPY (LP + QP), update JuMP to include QP support. Clarify AMPL and GAMS are LP-only. Use a table for clarity. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
We have some simple tests for building a socp problem in python and C, and the SOCP PR has been merged into the release branch and agent now should be able to read it. |
yuwenchen95
left a comment
yuwenchen95
left a comment
There was a problem hiding this comment.
Some files only document LP without QP and SOCP. We should also add QP and SOCP docs accordingly.
For socp, we should clarify that we are using quadratic constraints as the input format, and provide both standard soc and rotated soc examples under different APIs.
|
|
||
| minimize c^T*x | ||
| subject to A*x {<=, =, >=} b | ||
| ||u_i||_2 <= t_i (second-order cone constraints) |
There was a problem hiding this comment.
u_i, t_i are not defined in the problem formulation. We should write it as x \in K where K is second-order cone.
There was a problem hiding this comment.
Done — reformulated to lead with the quadratic-constraint form and use x_1..x_k cone indexing; u_i/t_i removed.
| ||u_i||_2 <= t_i (second-order cone constraints) | ||
| lb <= x <= ub | ||
|
|
||
| Because cuOpt does not accept cone constraints directly, SOC constraints are specified through the quadratic constraint API. Each SOC constraint ``||u||_2 <= t`` is expressed as the equivalent quadratic inequality ``u^T*u - t^2 <= 0``. cuOpt detects the SOC structure and converts to cone form internally before solving with the barrier method. |
There was a problem hiding this comment.
Rotated second-order cone is supported through quadratic constraint API, we should also mention it.
| ||u_i||_2 <= t_i (second-order cone constraints) | ||
| lb <= x <= ub | ||
|
|
||
| Because cuOpt does not accept cone constraints directly, SOC constraints are specified through the quadratic constraint API. Each SOC constraint ``||u||_2 <= t`` is expressed as the equivalent quadratic inequality ``u^T*u - t^2 <= 0``. cuOpt detects the SOC structure and converts to cone form internally before solving with the barrier method. |
There was a problem hiding this comment.
Replacing u_i, 't_i' with x indexing if possible.
There was a problem hiding this comment.
Done — now uses x_1..x_k indexing.
| x = problem.addVariable("x", lb=0) | ||
| y = problem.addVariable("y", lb=0) |
There was a problem hiding this comment.
Good to add another example for rotated soc.
There was a problem hiding this comment.
Added rotated-cone examples (Python and C/MPS). Note the cross term must be given symmetrically; see #1354.
| :titlesonly: | ||
|
|
||
| LP, QP and MILP <lp-qp-milp/index.rst> | ||
| Continuous Optimization <continuous/index.rst> |
There was a problem hiding this comment.
I think Convex Optimization or Continuous (Convex) Optimization would be better than Continuous Optimization, since we don't support nonconvex continuous optimization.
There was a problem hiding this comment.
Done — renamed to "Continuous (Convex) Optimization" in both the Python and C index pages.
| These constants are used as parameter names in the :c:func:`cuOptSetParameter`, :c:func:`cuOptGetParameter`, and similar functions. For more details on the available parameters, see the :doc:`Continuous Optimization settings <../../continuous-settings>` and :doc:`MIP settings <../../mip-settings>` sections. | ||
|
|
||
| .. LP/MIP parameter string constants | ||
| .. LP/QP parameter string constants |
There was a problem hiding this comment.
Should be renamed as Continuous
There was a problem hiding this comment.
Done — renamed the parameter-constants source comment to "Continuous"; the page already sits under the "Continuous Optimization (LP/QP/SOCP)" section.
There was a problem hiding this comment.
Continuous or add LP/QP/SOCP.
There was a problem hiding this comment.
Done — retitled to "LP/QP/SOCP C API Examples".
…CP MPS examples)
- Reframe SOCP section to lead with quadratic constraints
(x^T Q x + c^T x + alpha <= 0) that cuOpt translates into second-order
cones, per team guidance; note only certain (Q, c, alpha) combinations
are supported.
- Document both standard (Lorentz) and rotated cones with x-indexed cone
notation; fix the buggy addVariable(name=...) call.
- Add verified QP (qp_sample.mps) and SOCP (socp_sample.mps, standard +
rotated) MPS samples with captured output; generalize mps_file_example.c
header to LP/QP/SOCP.
- Rename Python/C index entries to "Continuous (Convex) Optimization";
fix C index "linear programming only" line; C examples title -> LP/QP/SOCP.
- Soften modeling-language note ("not yet supported"); state strong-branching
iteration-limit default (-1).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Ramakrishna Prabhu <ramakrishnap@nvidia.com>
|
/ok to test 2c4eb2a |
|
/ok to test d4c6918 |
Adds general_quadratic_example.{c,py} demonstrating a general convex quadratic
constraint (2x^2 + 2xy + 2y^2 <= 6): nonzero rhs and a cross term, with Q given
unsymmetrically (single off-diagonal entry) — cuOpt symmetrizes internally
(supported via NVIDIA#1361). Includes a linear row and uses MINIMIZE. Verified:
Optimal, objective -2, x=y=-1. CI builds/runs both.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Ramakrishna Prabhu <ramakrishnap@nvidia.com>
|
/ok to test 14fed6f |
The convex doc pages had RST title overlines/underlines shorter than the title text, which fail the Sphinx build under -W. Lengthen the rule lines to match. No content changes. make html now succeeds. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Ramakrishna Prabhu <ramakrishnap@nvidia.com>
|
/ok to test 93b6c49 |
|
/ok to test f7c868f |
|
/merge |
…ptive - Promote "Getting each objective right" to Step 1 (define the objectives), so the body reads as a clean workflow: define -> anchor (payoff table) -> scalarize -> sweep/collect/filter -> interpret. The opening (when this applies + core idea) stays as the conceptual preamble. - Replace specific method-name citations with the operation they perform, deferring exact calls to cuopt-numerical-optimization-api-python: "add it as a quadratic constraint" (was add_quadratic_constraint, which the merged NVIDIA#1339 docs supply via addConstraint); "carry the previous solve's PDLP warmstart data into the next" (was getWarmstartData -> set_pdlp_warm_start_data). Keeps the framing signal without binding to a changing API. Signed-off-by: cafzal <cameron.afzal@gmail.com>
6 participants
Uh oh!
There was an error while loading. Please reload this page.