From c9f7a658c1eebd6f1023544a99a15430e429cef9 Mon Sep 17 00:00:00 2001 From: Rajesh Gandham Date: Fri, 29 May 2026 10:22:45 -0400 Subject: [PATCH 01/13] Update LP/QP/MILP docs to cover 26.06 API additions - 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 --- .../cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rst | 83 +++++++++- .../lp-qp-milp/lp-qp-milp-api.rst | 2 +- docs/cuopt/source/lp-qp-milp-settings.rst | 143 ++++++++++++++++++ 3 files changed, 226 insertions(+), 2 deletions(-) diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rst b/docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rst index ea9bf30925..17a41554cf 100644 --- a/docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rst +++ b/docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rst @@ -43,9 +43,10 @@ An optimization problem is represented via a `cuOptOptimizationProblem` .. doxygentypedef:: cuOptOptimizationProblem -Optimization problems can be created via five different functions +Optimization problems can be created or loaded via the following functions .. doxygenfunction:: cuOptReadProblem +.. doxygenfunction:: cuOptWriteProblem .. doxygenfunction:: cuOptCreateProblem .. doxygenfunction:: cuOptCreateRangedProblem .. doxygenfunction:: cuOptCreateQuadraticProblem @@ -101,6 +102,13 @@ This constant may be used to represent infinity in the :c:func:`cuOptCreateProbl .. doxygendefine:: CUOPT_INFINITY +File Format Constants +--------------------- + +These constants are used to specify the output file format in :c:func:`cuOptWriteProblem`. + +.. doxygendefine:: CUOPT_FILE_FORMAT_MPS + Querying an optimization problem -------------------------------- @@ -171,6 +179,7 @@ These constants are used as parameter names in the :c:func:`cuOptSetParameter`, .. doxygendefine:: CUOPT_DUAL_INFEASIBLE_TOLERANCE .. doxygendefine:: CUOPT_ITERATION_LIMIT .. doxygendefine:: CUOPT_TIME_LIMIT +.. doxygendefine:: CUOPT_WORK_LIMIT .. doxygendefine:: CUOPT_NODE_LIMIT .. doxygendefine:: CUOPT_PDLP_SOLVER_MODE .. doxygendefine:: CUOPT_METHOD @@ -186,6 +195,8 @@ These constants are used as parameter names in the :c:func:`cuOptSetParameter`, .. doxygendefine:: CUOPT_MIP_SCALING .. doxygendefine:: CUOPT_MIP_HEURISTICS_ONLY .. doxygendefine:: CUOPT_MIP_PRESOLVE +.. doxygendefine:: CUOPT_MIP_DETERMINISM_MODE +.. doxygendefine:: CUOPT_MIP_SYMMETRY .. doxygendefine:: CUOPT_PRESOLVE .. doxygendefine:: CUOPT_MIP_PROBING .. doxygendefine:: CUOPT_LOG_TO_CONSOLE @@ -197,11 +208,33 @@ These constants are used as parameter names in the :c:func:`cuOptSetParameter`, .. doxygendefine:: CUOPT_ELIMINATE_DENSE_COLUMNS .. doxygendefine:: CUOPT_CUDSS_DETERMINISTIC .. doxygendefine:: CUOPT_BARRIER_DUAL_INITIAL_POINT +.. doxygendefine:: CUOPT_BARRIER_ITERATIVE_REFINEMENT +.. doxygendefine:: CUOPT_BARRIER_STEP_SCALE .. doxygendefine:: CUOPT_DUAL_POSTSOLVE .. doxygendefine:: CUOPT_SOLUTION_FILE .. doxygendefine:: CUOPT_NUM_CPU_THREADS +.. doxygendefine:: CUOPT_NUM_GPUS .. doxygendefine:: CUOPT_USER_PROBLEM_FILE +.. doxygendefine:: CUOPT_PRESOLVE_FILE +.. doxygendefine:: CUOPT_RANDOM_SEED .. doxygendefine:: CUOPT_PDLP_PRECISION +.. doxygendefine:: CUOPT_MIP_RELIABILITY_BRANCHING +.. doxygendefine:: CUOPT_MIP_CUT_PASSES +.. doxygendefine:: CUOPT_MIP_MIXED_INTEGER_ROUNDING_CUTS +.. doxygendefine:: CUOPT_MIP_MIXED_INTEGER_GOMORY_CUTS +.. doxygendefine:: CUOPT_MIP_KNAPSACK_CUTS +.. doxygendefine:: CUOPT_MIP_FLOW_COVER_CUTS +.. doxygendefine:: CUOPT_MIP_IMPLIED_BOUND_CUTS +.. doxygendefine:: CUOPT_MIP_CLIQUE_CUTS +.. doxygendefine:: CUOPT_MIP_STRONG_CHVATAL_GOMORY_CUTS +.. doxygendefine:: CUOPT_MIP_REDUCED_COST_STRENGTHENING +.. doxygendefine:: CUOPT_MIP_OBJECTIVE_STEP +.. doxygendefine:: CUOPT_MIP_CUT_CHANGE_THRESHOLD +.. doxygendefine:: CUOPT_MIP_CUT_MIN_ORTHOGONALITY +.. doxygendefine:: CUOPT_MIP_BATCH_PDLP_STRONG_BRANCHING +.. doxygendefine:: CUOPT_MIP_BATCH_PDLP_RELIABILITY_BRANCHING +.. doxygendefine:: CUOPT_MIP_STRONG_BRANCHING_SIMPLEX_ITERATION_LIMIT +.. doxygendefine:: CUOPT_MIP_SEMICONTINUOUS_BIG_M .. _pdlp-solver-mode-constants: @@ -239,6 +272,53 @@ These constants are used to configure `CUOPT_METHOD` via :c:func:`cuOptSetIntege .. doxygendefine:: CUOPT_METHOD_PDLP .. doxygendefine:: CUOPT_METHOD_DUAL_SIMPLEX .. doxygendefine:: CUOPT_METHOD_BARRIER +.. doxygendefine:: CUOPT_METHOD_UNSET + +.. _mip-determinism-mode-constants: + +MIP Determinism Mode Constants +------------------------------ + +These constants are used to configure `CUOPT_MIP_DETERMINISM_MODE` via :c:func:`cuOptSetIntegerParameter`. + +.. doxygendefine:: CUOPT_MODE_OPPORTUNISTIC +.. doxygendefine:: CUOPT_MODE_DETERMINISTIC + +.. _barrier-iterative-refinement-constants: + +Barrier Iterative Refinement Constants +--------------------------------------- + +These constants are used to configure `CUOPT_BARRIER_ITERATIVE_REFINEMENT` via :c:func:`cuOptSetIntegerParameter`. + +.. doxygendefine:: CUOPT_BARRIER_ITERATIVE_REFINEMENT_OFF +.. doxygendefine:: CUOPT_BARRIER_ITERATIVE_REFINEMENT_ON + + +Warm Start and MIP Start +------------------------ + +The following functions set initial solution hints for the solver. + +For LP problems solved with PDLP, primal and dual warm start vectors may be provided: + +.. doxygenfunction:: cuOptSetInitialPrimalSolution +.. doxygenfunction:: cuOptSetInitialDualSolution + +For MIP problems, one or more primal solution hints (MIP starts) may be provided: + +.. doxygenfunction:: cuOptAddMIPStart + +MIP Solution Callbacks +----------------------- + +The following callback types and functions allow monitoring and injecting solutions during a MIP solve. + +.. doxygentypedef:: cuOptMIPGetSolutionCallback +.. doxygentypedef:: cuOptMIPSetSolutionCallback + +.. doxygenfunction:: cuOptSetMIPGetSolutionCallback +.. doxygenfunction:: cuOptSetMIPSetSolutionCallback Solving an LP or MIP @@ -290,4 +370,5 @@ These constants define the termination status received from the :c:func:`cuOptGe .. doxygendefine:: CUOPT_TERMINATION_STATUS_PRIMAL_FEASIBLE .. doxygendefine:: CUOPT_TERMINATION_STATUS_FEASIBLE_FOUND .. doxygendefine:: CUOPT_TERMINATION_STATUS_CONCURRENT_LIMIT +.. doxygendefine:: CUOPT_TERMINATION_STATUS_WORK_LIMIT .. doxygendefine:: CUOPT_TERMINATION_STATUS_UNBOUNDED_OR_INFEASIBLE diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/lp-qp-milp-api.rst b/docs/cuopt/source/cuopt-python/lp-qp-milp/lp-qp-milp-api.rst index 609e11b34b..4d1c0cf14d 100644 --- a/docs/cuopt/source/cuopt-python/lp-qp-milp/lp-qp-milp-api.rst +++ b/docs/cuopt/source/cuopt-python/lp-qp-milp/lp-qp-milp-api.rst @@ -5,7 +5,7 @@ LP, QP and MILP API Reference .. autoclass:: cuopt.linear_programming.problem.Problem :members: :undoc-members: - :exclude-members: reset_solved_values, populate_solution, dict_to_object, NumNZs, NumVariables, NumConstraints, IsMIP, get_incumbent_values, get_pdlp_warm_start_data, getQcsr + :exclude-members: reset_solved_values, populate_solution, dict_to_object, get_incumbent_values, get_pdlp_warm_start_data, getQcsr .. autoclass:: cuopt.linear_programming.problem.Variable :members: diff --git a/docs/cuopt/source/lp-qp-milp-settings.rst b/docs/cuopt/source/lp-qp-milp-settings.rst index 985204e1b2..bbfcc61c17 100644 --- a/docs/cuopt/source/lp-qp-milp-settings.rst +++ b/docs/cuopt/source/lp-qp-milp-settings.rst @@ -556,3 +556,146 @@ Set this value to 0 to disable batched PDLP strong branching. Set this value to 1 to enable batched PDLP strong branching. .. note:: The default value is ``0`` (disabled). This setting is ignored if the problem is not a MIP problem. + +Batch PDLP Reliability Branching +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_BATCH_PDLP_RELIABILITY_BRANCHING`` controls whether to use batched PDLP for reliability branching evaluations. +When enabled, candidate variables for reliability branching are evaluated simultaneously using a single batched PDLP solve. +Set this value to 0 to disable. +Set this value to 1 to enable. + +.. note:: The default value is ``0`` (disabled). + +Strong Branching Simplex Iteration Limit +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_STRONG_BRANCHING_SIMPLEX_ITERATION_LIMIT`` controls the maximum number of simplex iterations allowed per candidate during strong branching. +Reducing this value speeds up strong branching at the cost of less accurate candidate evaluations. + +.. note:: By default there is no iteration limit for strong branching solves. + +MIP Determinism Mode +^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_DETERMINISM_MODE`` controls whether the MIP solver runs in opportunistic or deterministic mode. + +* ``0`` (``CUOPT_MODE_OPPORTUNISTIC``): Opportunistic mode — results may vary between runs due to parallelism (default). +* ``1`` (``CUOPT_MODE_DETERMINISTIC``): Deterministic mode — guarantees reproducible results across runs with the same number of threads. + +.. note:: The default value is ``0`` (opportunistic). + +MIP Symmetry +^^^^^^^^^^^^^ + +``CUOPT_MIP_SYMMETRY`` controls symmetry detection and handling in the MIP solver. + +* ``-1``: Automatic (default) — cuOpt decides based on problem characteristics. +* ``0``: Disable symmetry handling. +* ``1``: Enable symmetry handling. + +.. note:: The default value is ``-1`` (automatic). + +Flow Cover Cuts +^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_FLOW_COVER_CUTS`` controls whether to use flow cover cuts. +Set this value to ``-1`` (automatic) to let the solver decide. +Set this value to ``0`` to disable flow cover cuts. +Set this value to ``1`` to enable flow cover cuts. + +.. note:: The default value is ``-1`` (automatic). + +Implied Bound Cuts +^^^^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_IMPLIED_BOUND_CUTS`` controls whether to use implied bound cuts. +Set this value to ``-1`` (automatic) to let the solver decide. +Set this value to ``0`` to disable implied bound cuts. +Set this value to ``1`` to enable implied bound cuts. + +.. note:: The default value is ``-1`` (automatic). + +Clique Cuts +^^^^^^^^^^^^ + +``CUOPT_MIP_CLIQUE_CUTS`` controls whether to use clique cuts. +Set this value to ``-1`` (automatic) to let the solver decide. +Set this value to ``0`` to disable clique cuts. +Set this value to ``1`` to enable clique cuts. + +.. note:: The default value is ``-1`` (automatic). + +Objective Step +^^^^^^^^^^^^^^^ + +``CUOPT_MIP_OBJECTIVE_STEP`` controls the minimum discrete step size used to tighten the dual bound when all integer variables have integer objective coefficients. +When the objective value can only change in multiples of a known step size, cuOpt uses this information to close the gap faster. +Set this value to ``0`` to disable this tightening (default) or provide a positive step size to override automatic detection. + +.. note:: The default value is ``0`` (disabled). When set to ``0``, cuOpt will automatically detect an objective step when possible. + +Semi-Continuous Big-M +^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_SEMICONTINUOUS_BIG_M`` controls the Big-M coefficient used when linearizing semi-continuous variable constraints. +A semi-continuous variable is either zero or takes a value in the range ``[lower_bound, upper_bound]``. +Set this to a positive value that is at least as large as the upper bound of any semi-continuous variable in the problem. + +.. note:: By default cuOpt derives the Big-M from the variable's upper bound. + +Work Limit +^^^^^^^^^^ + +``CUOPT_WORK_LIMIT`` controls the work limit after which the solver will stop and return the current solution. +Work units are a machine-independent measure of solver effort. If set along with the time limit or iteration limit, cuOpt will stop when the first limit is hit. + +.. note:: By default there is no work limit. + +Random Seed +^^^^^^^^^^^^ + +``CUOPT_RANDOM_SEED`` controls the random seed used by the solver. Setting a fixed seed enables reproducible results when running in deterministic mode. + +.. note:: By default the random seed is set automatically. + +Presolve File +^^^^^^^^^^^^^^ + +``CUOPT_PRESOLVE_FILE`` controls the name of a file where cuOpt should write presolve information. + +.. note:: The default value is ``""`` and no presolve file is written. + +Primal Infeasibility Tolerance +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_PRIMAL_INFEASIBLE_TOLERANCE`` controls the tolerance used to detect primal infeasibility in PDLP. +A certificate of primal infeasibility is accepted when the primal infeasibility residual falls below this threshold. + +.. note:: The default value is ``1e-8``. + +Dual Infeasibility Tolerance +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_DUAL_INFEASIBLE_TOLERANCE`` controls the tolerance used to detect dual infeasibility (unboundedness) in PDLP. +A certificate of dual infeasibility is accepted when the dual infeasibility residual falls below this threshold. + +.. note:: The default value is ``1e-8``. + +Barrier Iterative Refinement +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_BARRIER_ITERATIVE_REFINEMENT`` controls whether iterative refinement is applied after each barrier iteration to improve solution accuracy. + +* ``0`` (``CUOPT_BARRIER_ITERATIVE_REFINEMENT_OFF``): Disable iterative refinement (default). +* ``1`` (``CUOPT_BARRIER_ITERATIVE_REFINEMENT_ON``): Enable iterative refinement. + +.. note:: The default value is ``0`` (off). + +Barrier Step Scale +^^^^^^^^^^^^^^^^^^^ + +``CUOPT_BARRIER_STEP_SCALE`` controls the scaling factor applied to the step size in the barrier method. +Values less than 1 result in more conservative (shorter) steps; values greater than 1 result in more aggressive steps. + +.. note:: By default cuOpt selects the step scale automatically. From 6229e3b5eddd7cf05c23762d14fa770be373dc31 Mon Sep 17 00:00:00 2001 From: Rajesh Gandham Date: Fri, 29 May 2026 10:35:35 -0400 Subject: [PATCH 02/13] Add a note to determinism --- docs/cuopt/source/lp-qp-milp-settings.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/cuopt/source/lp-qp-milp-settings.rst b/docs/cuopt/source/lp-qp-milp-settings.rst index bbfcc61c17..28fd4f3105 100644 --- a/docs/cuopt/source/lp-qp-milp-settings.rst +++ b/docs/cuopt/source/lp-qp-milp-settings.rst @@ -581,10 +581,12 @@ MIP Determinism Mode ``CUOPT_MIP_DETERMINISM_MODE`` controls whether the MIP solver runs in opportunistic or deterministic mode. * ``0`` (``CUOPT_MODE_OPPORTUNISTIC``): Opportunistic mode — results may vary between runs due to parallelism (default). -* ``1`` (``CUOPT_MODE_DETERMINISTIC``): Deterministic mode — guarantees reproducible results across runs with the same number of threads. +* ``1`` (``CUOPT_MODE_DETERMINISTIC``): Deterministic mode — improves reproducibility across runs with the same number of threads. .. note:: The default value is ``0`` (opportunistic). +.. warning:: Deterministic mode is experimental. It improves reproducibility in many cases but does not yet guarantee fully deterministic results in all scenarios. + MIP Symmetry ^^^^^^^^^^^^^ From 4c26638d6cdda0a7453602f8fd80584796591f8b Mon Sep 17 00:00:00 2001 From: Rajesh Gandham Date: Fri, 29 May 2026 12:10:43 -0400 Subject: [PATCH 03/13] Add SOCP (beta) documentation for 26.06 - 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 --- .../cuopt/source/cuopt-c/lp-qp-milp/index.rst | 6 +-- .../cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rst | 8 +++- .../source/cuopt-python/lp-qp-milp/index.rst | 12 ++--- .../lp-qp-milp/lp-qp-milp-api.rst | 1 + docs/cuopt/source/lp-qp-features.rst | 45 +++++++++++++++++-- 5 files changed, 59 insertions(+), 13 deletions(-) diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/index.rst b/docs/cuopt/source/cuopt-c/lp-qp-milp/index.rst index 57de6053a5..3dade721fc 100644 --- a/docs/cuopt/source/cuopt-c/lp-qp-milp/index.rst +++ b/docs/cuopt/source/cuopt-c/lp-qp-milp/index.rst @@ -1,12 +1,12 @@ Linear Programming ================== -This section contains details on the cuOpt LP/QP/MILP C API. +This section contains details on the cuOpt LP/QP/MILP/SOCP C API. .. toctree:: :maxdepth: 3 - :caption: LP/QP/MILP - :name: LP/QP/MILP + :caption: LP/QP/MILP/SOCP + :name: LP/QP/MILP/SOCP :titlesonly: lp-qp-milp-c-api.rst diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rst b/docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rst index 17a41554cf..ad7d1128a2 100644 --- a/docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rst +++ b/docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rst @@ -57,12 +57,18 @@ Optimization problems can be created or loaded via the following functions Prefer ``cuOptCreateProblem`` or ``cuOptCreateRangedProblem`` followed by ``cuOptSetQuadraticObjective`` (and ``cuOptAddQuadraticConstraint`` for QCQP). -For QP and QCQP models, the quadratic objective and constraints may be specified +For QP and QCQP/SOCP models, the quadratic objective and constraints may be specified after creating a linear problem: .. doxygenfunction:: cuOptSetQuadraticObjective .. doxygenfunction:: cuOptAddQuadraticConstraint +.. note:: + ``cuOptAddQuadraticConstraint`` also enables **Second-Order Cone Programming (SOCP)** + support **(beta)**. When one or more quadratic constraints are present, cuOpt automatically + converts them to second-order cone form and selects the barrier solver. Only ``CUOPT_LESS_THAN`` + and ``CUOPT_GREATER_THAN`` sense is supported; equality quadratic constraints are not supported. + A optimization problem must be destroyed with the following function .. doxygenfunction:: cuOptDestroyProblem diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/index.rst b/docs/cuopt/source/cuopt-python/lp-qp-milp/index.rst index e7fb2f6445..eff941e763 100644 --- a/docs/cuopt/source/cuopt-python/lp-qp-milp/index.rst +++ b/docs/cuopt/source/cuopt-python/lp-qp-milp/index.rst @@ -1,13 +1,13 @@ -============================================================================== -Linear Programming, Quadratic Programming and Mixed Integer Linear Programming -============================================================================== +============================================================================================================= +Linear Programming, Quadratic Programming, Mixed Integer Linear Programming, and Second-Order Cone Programming +============================================================================================================= -This section contains details on the cuOpt linear programming, quadratic programming and mixed integer linear programming Python API. +This section contains details on the cuOpt linear programming, quadratic programming, mixed integer linear programming, and second-order cone programming Python API. .. toctree:: :maxdepth: 3 - :caption: LP, QP and MILP - :name: LP, QP and MILP + :caption: LP, QP, MILP, and SOCP + :name: LP, QP, MILP, and SOCP :titlesonly: lp-qp-milp-api.rst diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/lp-qp-milp-api.rst b/docs/cuopt/source/cuopt-python/lp-qp-milp/lp-qp-milp-api.rst index 4d1c0cf14d..7af291d2ff 100644 --- a/docs/cuopt/source/cuopt-python/lp-qp-milp/lp-qp-milp-api.rst +++ b/docs/cuopt/source/cuopt-python/lp-qp-milp/lp-qp-milp-api.rst @@ -19,6 +19,7 @@ LP, QP and MILP API Reference .. autoclass:: cuopt.linear_programming.problem.QuadraticExpression :members: :undoc-members: + :special-members: __le__, __ge__, __neg__ .. autoclass:: cuopt.linear_programming.problem.Constraint :members: diff --git a/docs/cuopt/source/lp-qp-features.rst b/docs/cuopt/source/lp-qp-features.rst index bf9ff574c6..9656f47bcc 100644 --- a/docs/cuopt/source/lp-qp-features.rst +++ b/docs/cuopt/source/lp-qp-features.rst @@ -1,6 +1,6 @@ -================== -LP/QP Features -================== +======================== +LP/QP/SOCP Features +======================== Availability ------------- @@ -73,6 +73,45 @@ where Q is a symmetric positive semidefinite matrix. Please note that the Q matr See :ref:`simple-qp-example-python` for an example of how to create a QP problem with the Python Modeling API. See :ref:`simple-qp-example-c` for an example of how to create a QP problem with the C API. +Second-Order Cone Programming (Beta) +-------------------------------------- + +.. note:: SOCP support is **beta** in this release. The API is functional but has not been fully hardened for all problem types and edge cases. + +cuOpt supports Second-Order Cone Programming (SOCP) problems — problems with quadratic constraints of the form: + +.. code-block:: text + + minimize c^T*x + subject to A*x {<=, =, >=} b + ||Ax + b||_2 <= c^T*x + d (second-order cone constraints) + lb <= x <= ub + +SOCP constraints are specified as quadratic constraints using ``<=`` or ``>=`` comparisons on a ``QuadraticExpression``. cuOpt automatically converts these quadratic constraints to second-order cone form internally. + +When any quadratic constraint is present, cuOpt automatically selects the barrier method and disables presolve optimizations that apply only to linear problems. + +**Constraints:** + +- Only ``<=`` and ``>=`` sense is supported for quadratic constraints. Equality quadratic constraints are not supported. +- The right-hand side of a quadratic constraint must be zero when the constraint is intended as a SOC constraint. +- Each second-order cone must have dimension at least 2. + +**Python example:** + +.. code-block:: python + + x = problem.addVariable("x", lb=0) + y = problem.addVariable("y", lb=0) + z = problem.addVariable("z", lb=0) + + # ||[x, y]||_2 <= z written as x*x + y*y - z*z <= 0 + problem.addConstraint(x*x + y*y - z*z <= 0, name="soc") + +**C API:** Use :c:func:`cuOptAddQuadraticConstraint` to add quadratic constraints. The solver automatically detects and handles SOC structure. + +.. note:: SOCP problems always use the barrier solver regardless of the ``CUOPT_METHOD`` setting. + Warm Start ----------- From 262b5e4c87694dd76069be601574c59c76245336 Mon Sep 17 00:00:00 2001 From: Rajesh Gandham Date: Fri, 29 May 2026 12:20:28 -0400 Subject: [PATCH 04/13] Fix intro sentence to include writing in C API RST Co-Authored-By: Claude Sonnet 4.6 --- docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rst b/docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rst index ad7d1128a2..f4e7aaf0aa 100644 --- a/docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rst +++ b/docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rst @@ -43,7 +43,7 @@ An optimization problem is represented via a `cuOptOptimizationProblem` .. doxygentypedef:: cuOptOptimizationProblem -Optimization problems can be created or loaded via the following functions +Optimization problems can be created, loaded, or written via the following functions .. doxygenfunction:: cuOptReadProblem .. doxygenfunction:: cuOptWriteProblem From e99f3962972eb6749306fda34a395b2d2e1c1342 Mon Sep 17 00:00:00 2001 From: Rajesh Gandham Date: Fri, 29 May 2026 12:56:23 -0400 Subject: [PATCH 05/13] Fix CUOPT_MIP_OBJECTIVE_STEP docs: 0/1 toggle, default 1 (enabled) Co-Authored-By: Claude Sonnet 4.6 --- docs/cuopt/source/lp-qp-milp-settings.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/cuopt/source/lp-qp-milp-settings.rst b/docs/cuopt/source/lp-qp-milp-settings.rst index 28fd4f3105..2de147018c 100644 --- a/docs/cuopt/source/lp-qp-milp-settings.rst +++ b/docs/cuopt/source/lp-qp-milp-settings.rst @@ -631,11 +631,13 @@ Set this value to ``1`` to enable clique cuts. Objective Step ^^^^^^^^^^^^^^^ -``CUOPT_MIP_OBJECTIVE_STEP`` controls the minimum discrete step size used to tighten the dual bound when all integer variables have integer objective coefficients. -When the objective value can only change in multiples of a known step size, cuOpt uses this information to close the gap faster. -Set this value to ``0`` to disable this tightening (default) or provide a positive step size to override automatic detection. +``CUOPT_MIP_OBJECTIVE_STEP`` controls whether cuOpt automatically detects and exploits discrete step structure in the objective to tighten the dual bound. +When all integer variables have integer objective coefficients, the objective value can only change in multiples of a known step size; enabling this setting allows cuOpt to use that information to close the gap faster. -.. note:: The default value is ``0`` (disabled). When set to ``0``, cuOpt will automatically detect an objective step when possible. +* ``0``: Disable objective step detection. +* ``1``: Enable objective step detection (default). + +.. note:: The default value is ``1`` (enabled). Semi-Continuous Big-M ^^^^^^^^^^^^^^^^^^^^^^ From 59e13f89b94e5c5eb8bf3c4de9a5161d3d9387f6 Mon Sep 17 00:00:00 2001 From: Rajesh Gandham Date: Fri, 29 May 2026 16:20:11 -0400 Subject: [PATCH 06/13] Split LP/QP/SOCP and MIP docs into separate sections 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 --- docs/cuopt/source/continuous-features.rst | 225 ++++++++++ docs/cuopt/source/continuous-settings.rst | 405 ++++++++++++++++++ docs/cuopt/source/cuopt-c/index.rst | 2 +- .../cuopt-c/lp-qp-milp/continuous-c-api.rst | 324 ++++++++++++++ .../lp-qp-milp/continuous-examples.rst | 214 +++++++++ .../cuopt/source/cuopt-c/lp-qp-milp/index.rst | 27 +- .../source/cuopt-c/lp-qp-milp/mip-c-api.rst | 74 ++++ .../cuopt-c/lp-qp-milp/mip-examples.rst | 162 +++++++ docs/cuopt/source/cuopt-cli/quick-start.rst | 2 +- docs/cuopt/source/cuopt-grpc/examples.rst | 9 +- docs/cuopt/source/cuopt-grpc/quick-start.rst | 2 +- docs/cuopt/source/cuopt-python/index.rst | 6 +- .../lp-qp-milp/continuous-api.rst | 46 ++ .../lp-qp-milp/continuous-examples.rst | 153 +++++++ .../source/cuopt-python/lp-qp-milp/index.rst | 24 +- .../cuopt-python/lp-qp-milp/mip-api.rst | 26 ++ .../cuopt-python/lp-qp-milp/mip-examples.rst | 78 ++++ .../cuopt-server/examples/lp-examples.rst | 4 +- .../source/cuopt-server/server-api/index.rst | 3 +- docs/cuopt/source/faq.rst | 2 +- docs/cuopt/source/index.rst | 2 +- docs/cuopt/source/mip-settings.rst | 369 ++++++++++++++++ docs/cuopt/source/transition.rst | 2 +- 23 files changed, 2128 insertions(+), 33 deletions(-) create mode 100644 docs/cuopt/source/continuous-features.rst create mode 100644 docs/cuopt/source/continuous-settings.rst create mode 100644 docs/cuopt/source/cuopt-c/lp-qp-milp/continuous-c-api.rst create mode 100644 docs/cuopt/source/cuopt-c/lp-qp-milp/continuous-examples.rst create mode 100644 docs/cuopt/source/cuopt-c/lp-qp-milp/mip-c-api.rst create mode 100644 docs/cuopt/source/cuopt-c/lp-qp-milp/mip-examples.rst create mode 100644 docs/cuopt/source/cuopt-python/lp-qp-milp/continuous-api.rst create mode 100644 docs/cuopt/source/cuopt-python/lp-qp-milp/continuous-examples.rst create mode 100644 docs/cuopt/source/cuopt-python/lp-qp-milp/mip-api.rst create mode 100644 docs/cuopt/source/cuopt-python/lp-qp-milp/mip-examples.rst create mode 100644 docs/cuopt/source/mip-settings.rst diff --git a/docs/cuopt/source/continuous-features.rst b/docs/cuopt/source/continuous-features.rst new file mode 100644 index 0000000000..487cdf4dfc --- /dev/null +++ b/docs/cuopt/source/continuous-features.rst @@ -0,0 +1,225 @@ +======================== +LP/QP/SOCP Features +======================== + +Availability +------------- + +The Linear Programming (LP), Quadratic Programming (QP), and Second-Order Cone Programming (SOCP) solvers can be accessed in the following ways: + +- **Third-Party Modeling Languages**: cuOpt's LP solver can be called directly from the following third-party modeling languages. This allows you to leverage GPU acceleration while maintaining your existing optimization workflow in these modeling languages. + + Supported modeling languages: + - AMPL + - GAMS + - PuLP + - JuMP + +.. note:: + The QP and SOCP solvers are not currently supported in third-party modeling languages. + +- **C API**: A native C API that provides direct low-level access to cuOpt's LP/QP/SOCP capabilities, enabling integration into any application or system that can interface with C. + +- **Python SDK**: A Python package that provides direct access to cuOpt's LP/QP/SOCP capabilities through a simple, intuitive API. This allows for seamless integration into Python applications and workflows. For more information, see :doc:`cuopt-python/quick-start`. + +- **As a Self-Hosted Service**: cuOpt's LP/QP solver can be deployed as a self-hosted service in your own infrastructure, enabling you to maintain full control while integrating it into your existing systems. + +Each option provide the same powerful linear optimization capabilities while offering flexibility in deployment and integration. + +Variable Bounds +--------------- + +Lower and upper bounds can be applied to each variable. If no variable bounds are specified, the default bounds are ``[-inf,+inf]``. + +Constraints +----------- + +The constraint matrix is specified in `Compressed Sparse Row (CSR) format `_. + +There are two ways to specify constraints to the LP solver: + +1. Using row_type and right-hand side: + + Constraints can be specified in the form: + + A*x {<=, =, >=} b + + where A is the constraint matrix in CSR format, x is the variable vector, and b is the right-hand side vector. The relationship {<=, =, >=} is specified via the ``row_type`` parameter. + +2. Using constraint bounds: + + Alternatively, constraints can be specified as two-sided inequalities: + + lb <= A*x <= ub + + where lb and ub are vectors of lower and upper bounds respectively. This form allows specifying both bounds on a single constraint. + + +Quadratic Programming +--------------------- + +cuOpt supports problems with quadratic objectives of the form: + +.. code-block:: text + + minimize x^T*Q*x + c^T*x + subject to A*x {<=, =, >=} b + lb <= x <= ub + +where Q is a symmetric positive semidefinite matrix. Please note that the Q matrix is specified without the 1/2 factor that may be used by other solvers. + +.. note:: Currently, barrier is the only method that supports QPs. + +See :ref:`simple-qp-example-python` for an example of how to create a QP problem with the Python Modeling API. +See :ref:`simple-qp-example-c` for an example of how to create a QP problem with the C API. + +Second-Order Cone Programming (Beta) +-------------------------------------- + +.. note:: SOCP support is **beta** in this release. The API is functional but has not been fully hardened for all problem types and edge cases. + +cuOpt supports Second-Order Cone Programming (SOCP) problems — problems with quadratic constraints of the form: + +.. code-block:: text + + minimize c^T*x + subject to A*x {<=, =, >=} b + ||Ax + b||_2 <= c^T*x + d (second-order cone constraints) + lb <= x <= ub + +SOCP constraints are specified as quadratic constraints using ``<=`` or ``>=`` comparisons on a ``QuadraticExpression``. cuOpt automatically converts these quadratic constraints to second-order cone form internally. + +When any quadratic constraint is present, cuOpt automatically selects the barrier method and disables presolve optimizations that apply only to linear problems. + +**Constraints:** + +- Only ``<=`` and ``>=`` sense is supported for quadratic constraints. Equality quadratic constraints are not supported. +- The right-hand side of a quadratic constraint must be zero when the constraint is intended as a SOC constraint. +- Each second-order cone must have dimension at least 2. + +**Python example:** + +.. code-block:: python + + x = problem.addVariable("x", lb=0) + y = problem.addVariable("y", lb=0) + z = problem.addVariable("z", lb=0) + + # ||[x, y]||_2 <= z written as x*x + y*y - z*z <= 0 + problem.addConstraint(x*x + y*y - z*z <= 0, name="soc") + +**C API:** Use :c:func:`cuOptAddQuadraticConstraint` to add quadratic constraints. The solver automatically detects and handles SOC structure. + +.. note:: SOCP problems always use the barrier solver regardless of the ``CUOPT_METHOD`` setting. + +Warm Start +----------- + +A warm starts allow a user to provide an initial solution to help PDLP converge faster. The initial ``primal`` and ``dual`` solutions can be specified by the user. + +Alternatively, previously run solutions can be used to warm start a new solve to decrease solve time. :ref:`Examples ` are shared on the self-hosted page. + +PDLP Solver Mode +---------------- +Users can control how the solver will operate by specifying the PDLP solver mode. The mode choice can drastically impact how fast a specific problem will be solved. Users are encouraged to test different modes to see which one fits the best their problem. + + +Method +------ + +**Concurrent**: The default method for solving linear programs. When concurrent is selected, cuOpt runs three algorithms in parallel: PDLP on the GPU, barrier (interior-point) on the GPU, and dual simplex on the CPU. A solution is returned from the algorithm that finishes first. + +**PDLP**: Primal-Dual Hybrid Gradient for Linear Program is an algorithm for solving large-scale linear programming problems on the GPU. PDLP does not attempt any matrix factorizations during the course of the solve. Select this method if your LP is so large that factorization will not fit into memory. By default PDLP solves to low relative tolerance and the solutions it returns do not lie at a vertex of the feasible region. Enable crossover to obtain a highly accurate basic solution from a PDLP solution. + +.. note:: + PDLP solves to 1e-4 relative accuracy by default. + +**Barrier**: The barrier method (also known as interior-point method) solves linear and quadratic programs using a primal-dual predictor-corrector algorithm. This method uses GPU-accelerated sparse Cholesky and sparse LDLT solves via cuDSS, and GPU-accelerated sparse matrix-vector and matrix-matrix operations via cuSparse. Barrier is particularly effective for large-scale problems and can automatically apply techniques like folding, dualization, and dense column elimination to improve performance. This method solves the linear systems at each iteration using the augmented system or the normal equations (ADAT). Enable crossover to obtain a highly accurate basic solution from a barrier solution. + +.. note:: + Barrier solves to 1e-8 relative accuracy by default. + +**Dual Simplex**: Dual simplex is the simplex method applied to the dual of the linear program. Dual simplex requires the basis factorization of linear program fit into memory. Select this method if your LP is small to medium sized, or if you require a high-quality basic solution. + +.. note:: + Dual Simplex solves to 1e-6 absolute accuracy by default. + + +Crossover +--------- + +Crossover allows you to obtain a high-quality basic solution from the results of a PDLP or barrier solve. When enabled, crossover converts the PDLP or barrier solution to a vertex solution (basic solution) with high accuracy. More details can be found :ref:`here `. + +.. note:: + Crossover is not supported for QP problems. + +Presolve +-------- + +Presolve procedure is applied to the problem before the solver is called. It can be used to reduce the problem size and improve solve time. cuOpt supports presolve reductions using PSLP or Papilo for linear programming (LP) problems. For LP problems, PSLP presolve is always enabled by default. Users can manually select to disable presolve by setting this parameter to 0, enable Papilo presolve by setting this parameter to 1, or enable PSLP presolve by setting this parameter to 2. +Furthermore, for LP problems with Papilo presolver, when the dual solution is not needed, additional presolve procedures can be applied to further improve solve times. This is achieved by turning off dual postsolve with the ``CUOPT_DUAL_POSTSOLVE`` setting. + + +Logging +------- + +The ``CUOPT_LOG_FILE`` parameter can be set to write detailed solver logs for LP/QP problems. This parameter is available in all APIs that allow setting solver parameters except the cuOpt service. For the service, see the logging callback below. + +Logging Callback in the Service +------------------------------- + +In the cuOpt service API, the ``log_file`` value in ``solver_configs`` is ignored. + +If however you set the ``solver_logs`` flag on the ``/cuopt/request`` REST API call, users can fetch the log file content from the webserver at ``/cuopt/logs/{id}``. Using the logging callback feature through the cuOpt client is shown in :ref:`Examples ` on the self-hosted page. + + +Infeasibility Detection +----------------------- + +The PDLP solver includes the option to detect infeasible problems. If the infeasibilty detection is enabled in solver settings, PDLP will abort as soon as it concludes the problem is infeasible. + +.. note:: + Infeasibility detection is always enabled for dual simplex. + +Time Limit +---------- + +The user may specify a time limit to the solver. By default the solver runs until a solution is found or the problem is determined to be infeasible or unbounded. + +.. note:: + + Note that ``time_limit`` applies only to solve time inside the LP solver. This does not include time for network transfer, validation of input, and other operations that occur outside the solver. The overhead associated with these operations are usually small compared to the solve time. + + +.. _batch-mode: + +Batch Mode +---------- + +Users can submit a set of problems which will be solved in a batch. Problems will be solved at the same time in parallel to fully utilize the GPU. Checkout :ref:`self-hosted client ` example in thin client. + +.. warning:: Deprecated + + LP batch mode (Python ``cuopt.linear_programming.BatchSolve``, server requests + with a list of LP problems, and multi-file ``cuopt_sh`` LP submissions) is + deprecated and will be removed in a future release. Prefer sequential + ``cuopt.linear_programming.Solve`` calls, or implement your own parallelism + (for example with ``concurrent.futures``). Existing batch APIs still run in + parallel today; callers may see a ``DeprecationWarning`` or a deprecation + message in server ``warnings``. + +PDLP Precision Modes +-------------------- + +By default, PDLP operates in the native precision of the problem type (FP64 for double-precision problems). The ``pdlp_precision`` parameter provides several modes: + +- **single**: Run PDLP internally in FP32, with automatic conversion of inputs and outputs. FP32 uses half the memory and allows PDHG iterations to be on average twice as fast, but may require more iterations to converge. Compatible with crossover (solution is converted back to FP64 before crossover) and concurrent mode (PDLP runs in FP32 while other solvers run in FP64). +- **mixed**: Use mixed precision SpMV during PDHG iterations. The constraint matrix is stored in FP32 while vectors and compute type remain in FP64, improving SpMV performance with limited impact on convergence. Convergence checking and restart logic always use the full FP64 matrix. +- **double**: Explicitly run in FP64 (same as default for double-precision problems). + +.. note:: The default precision is the native type of the problem (FP64 for double). + +Multi-GPU Mode +-------------- + +Users can use multiple GPUs to solve a problem by specifying the ``num_gpus`` parameter. The feature is restricted to LP problems that uses concurrent mode and supports up to 2 GPUs at the moment. Using this mode will run PDLP and barrier in parallel on different GPUs to avoid sharing single GPU resources. diff --git a/docs/cuopt/source/continuous-settings.rst b/docs/cuopt/source/continuous-settings.rst new file mode 100644 index 0000000000..cbb1d4630c --- /dev/null +++ b/docs/cuopt/source/continuous-settings.rst @@ -0,0 +1,405 @@ +================================================ +Continuous Optimization Settings (LP, QP, SOCP) +================================================ + + +This page describes the parameter settings available for cuOpt's LP, QP, and SOCP solvers. These parameters are set as :ref:`parameter constants ` in case of C API and in case of Server Thin client as raw strings. Please refer to examples in :doc:`C ` and :doc:`Server Thin client ` for more details. + +.. note:: + When setting parameters in thin client solver settings, remove ``CUOPT_`` from the parameter name and convert to lowercase. For example, ``CUOPT_TIME_LIMIT`` would be set as ``time_limit``. + +Common Parameters +----------------- + +We begin by describing parameters common to both the MILP and LP solvers + + +Time Limit +^^^^^^^^^^ +``CUOPT_TIME_LIMIT`` controls the time limit in seconds after which the solver will stop and return the current solution. +For performance reasons, cuOpt does not constantly checks for time limit. Thus, the solver +may run slightly over the limit. If set along with the iteration limit, cuOpt will stop when +the first limit (iteration or time) is hit. + + +.. note:: By default there is no time limit. So cuOpt will run until it finds an optimal solution, + or proves the problem is infeasible or unbounded. + + + +Log to Console +^^^^^^^^^^^^^^ +``CUOPT_LOG_TO_CONSOLE`` controls whether cuOpt should log information to the console during a solve. +If true, a logging info is written to the console, if false no logging info is written to the console (logs may still be written to a file.) + +.. note:: The default value is true. + +Log File +^^^^^^^^ +``CUOPT_LOG_FILE`` controls the name of a log file where cuOpt should write information about the solve. + +.. note:: The default value is ``""`` and no log file is written. This setting is ignored by the cuOpt service, use the log callback feature instead. + +Solution File +^^^^^^^^^^^^^ +``CUOPT_SOLUTION_FILE`` controls the name of a file where cuOpt should write the solution. + +.. note:: The default value is ``""`` and no solution file is written. This setting is ignored by the cuOpt service. + +User Problem File +^^^^^^^^^^^^^^^^^ +``CUOPT_USER_PROBLEM_FILE`` controls the name of a file where cuOpt should write the user problem. + +.. note:: The default value is ``""`` and no user problem file is written. This setting is ignored by the cuOpt service. + +Num CPU Threads +^^^^^^^^^^^^^^^ +``CUOPT_NUM_CPU_THREADS`` controls the number of CPU threads used in the LP and MIP solvers. Set this to a small value to limit +the amount of CPU resources cuOpt uses. Set this to a large value to improve solve times for CPU +parallel parts of the solvers. + +.. note:: By default the number of CPU threads is automatically determined based on the number of CPU cores. + +Presolve +^^^^^^^^ +``CUOPT_PRESOLVE`` controls which presolver to use for presolve reductions. +cuOpt provides presolve reductions for linear programming (LP) problems using either PSLP or Papilo, and for mixed-integer programming (MIP) problems using Papilo. By default, Papilo presolve is always enabled for MIP problems. For LP problems, PSLP presolve is always enabled by default. You can explicitly control the presolver by setting this parameter to 0 (disable presolve), 1 (Papilo), or 2 (PSLP). + +Dual Postsolve +^^^^^^^^^^^^^^ +``CUOPT_DUAL_POSTSOLVE`` controls whether dual postsolve is enabled when using Papilo presolver for LP problems. Disabling dual postsolve can improve solve time at the expense of not having +access to the dual solution. Enabled by default for LP when Papilo presolve is selected. This is not relevant for MIP problems. + +Linear Programming +------------------ + +We now describe the parameter settings used to control cuOpt's Linear Programming solvers + +Method +^^^^^^ + +``CUOPT_METHOD`` controls the method to solve the linear programming problem. Four methods are available: + +* ``Concurrent``: Use PDLP, dual simplex, and barrier in parallel (default). +* ``PDLP``: Use the PDLP method. +* ``Dual Simplex``: Use the dual simplex method. +* ``Barrier``: Use the barrier (interior-point) method. + +.. note:: The default method is ``Concurrent``. + +Default accuracy for each method: + +* PDLP solves to 1e-4 relative accuracy by default. +* Barrier solves to 1e-8 relative accuracy by default. +* Dual Simplex solves to 1e-6 absolute accuracy by default. + +C API users should use the constants defined in :ref:`method-constants` for this parameter. + +Server Thin client users should use the :class:`cuopt_sh_client.SolverMethod` for this parameter. + +PDLP Solver Mode +^^^^^^^^^^^^^^^^ + +``CUOPT_PDLP_SOLVER_MODE`` controls the mode under which PDLP should operate. The mode will change the way the +PDLP internally optimizes the problem. The mode choice can drastically impact how fast a +specific problem will be solved. Users are encouraged to test different modes to see which one +fits the best their problem. By default, the solver uses ``Stable3``, the best +overall mode from our experiments. For now, only three modes are available: ``Stable3``, +``Methodical1``, and ``Fast1``. + +For now, we do not offer a mechanism to know upfront which solver mode will be the best +for a specific problem. + +C API users should use the constants defined in :ref:`pdlp-solver-mode-constants` for this parameter. + +Server Thin client users should use the :class:`cuopt_sh_client.PDLPSolverMode` for this parameter. + +Iteration Limit +^^^^^^^^^^^^^^^ + +``CUOPT_ITERATION_LIMIT`` controls the iteration limit after which the solver will stop and return the current solution. +For performance reasons, cuOpt's does not constantly checks for iteration limit, thus, +the solver might run a few extra iterations over the limit. If set along with the time limit, +cuOpt will stop at the first limit (iteration or time) reached. + +.. note:: By default there is no iteration limit. So, cuOpt will run until it finds an optimal solution, + or proves the problem is infeasible or unbounded. + + +Number of GPUs +^^^^^^^^^^^^^^ + +``CUOPT_NUM_GPUS`` controls the number of GPUs to use for the solve. This setting is only relevant for LP problems that uses concurrent mode and supports up to 2 GPUs at the moment. Using this mode will run PDLP and barrier in parallel on different GPUs to avoid sharing single GPU resources. + + +Infeasibility Detection +^^^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_INFEASIBILITY_DETECTION`` controls whether PDLP should detect infeasibility. Note that infeasibility detection in PDLP +is not always accurate. Some problems detected as infeasible may converge under a different tolerance factor. +Detecting infeasibility consumes both more runtime and memory. The added runtime is between 3% and 7%, +the added memory consumption is between 10% and 20%. + +.. note:: By default PDLP will not detect infeasibility. Dual simplex will always detect infeasibility + regardless of this setting. + +Strict Infeasibility +^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_STRICT_INFEASIBILITY`` controls the strict infeasibility mode in PDLP. When true if either the current or the average solution +is detected as infeasible, PDLP will stop. When false both the current and average solution need to be +detected as infeasible for PDLP to stop. + +.. note:: The default value is false. + +.. _crossover: + +Crossover +^^^^^^^^^ + +``CUOPT_CROSSOVER`` controls whether PDLP or barrier should crossover to a basic solution after an optimal solution is found. +Changing this value has a significant impact on accuracy and runtime. +By default the solutions provided by PDLP and barrier do not lie at a vertex and thus may have many variables that lie +between their bounds. Enabling crossover allows the user to obtain a high-quality basic solution +that lies at a vertex of the feasible region. If n is the number of variables, and m is the number of +constraints, n - m variables will be on their bounds in a basic solution. + +.. note:: The default value is false. + +Save Best Primal So Far +^^^^^^^^^^^^^^^^^^^^^^^ +``CUOPT_SAVE_BEST_PRIMAL_SOLUTION`` controls whether PDLP should save the best primal solution so far +With this parameter set to true, PDLP +* Will always prioritize a primal feasible to a non primal feasible +* If a new primal feasible is found, the one with the best primal objective will be kept +* If no primal feasible was found, the one with the lowest primal residual will be kept +* If two have the same primal residual, the one with the best objective will be kept + +.. note:: The default value is false. + +First Primal Feasible +^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_FIRST_PRIMAL_FEASIBLE`` controls whether PDLP should stop when the first primal feasible solution is found. + +.. note:: The default value is false. + +Per Constraint Residual +^^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_PER_CONSTRAINT_RESIDUAL`` controls whether PDLP should compute the primal & dual residual per constraint instead of globally. + +.. note:: The default value is false. + +PDLP Precision +^^^^^^^^^^^^^^ + +``CUOPT_PDLP_PRECISION`` controls the precision mode used by the PDLP solver. The following modes are +available: + +- **default** (-1): Use the native precision of the problem type (FP64 for double-precision problems). +- **single** (0): Run PDLP internally in FP32 (float). Inputs are converted from FP64 to FP32 before + solving and outputs are converted back to FP64. FP32 uses half the memory and allows PDHG iterations + to be on average twice as fast, but may require more iterations to converge due to reduced numerical + accuracy. Compatible with crossover (solution is converted back to FP64 before crossover runs) and + concurrent mode (the PDLP leg runs in FP32 while Dual Simplex and Barrier run in FP64). +- **double** (1): Explicitly run in FP64 (same as default for double-precision problems). +- **mixed** (2): Use mixed precision sparse matrix-vector products (SpMV) during PDHG iterations. The + constraint matrix and its transpose are stored in FP32 while vectors and the compute type remain in + FP64, improving SpMV performance. Convergence checking and restart logic always use the + full FP64 matrix, so this mode does not reduce overall memory usage. This provides a middle ground + between full FP64 and FP32: faster PDHG iterations with limited impact on convergence. + +.. note:: The default value is 0 (default precision). + +Barrier Solver Settings +^^^^^^^^^^^^^^^^^^^^^^^^ + +The following settings control the behavior of the barrier (interior-point) method: + +Folding +""""""" + +``CUOPT_FOLDING`` controls whether to fold the linear program. Folding can reduce problem size by exploiting symmetry in the problem. + +* ``-1``: Automatic (default) - cuOpt decides whether to fold based on problem characteristics +* ``0``: Disable folding +* ``1``: Force folding to run + +.. note:: The default value is ``-1`` (automatic). + +Dualize +""""""" + +``CUOPT_DUALIZE`` controls whether to dualize the linear program in presolve. Dualizing can improve solve time for problems, with inequality constraints, where there are more constraints than variables. + +* ``-1``: Automatic (default) - cuOpt decides whether to dualize based on problem characteristics +* ``0``: Don't attempt to dualize +* ``1``: Force dualize + +.. note:: The default value is ``-1`` (automatic). + +Ordering +"""""""" + +``CUOPT_ORDERING`` controls the ordering algorithm used by cuDSS for sparse factorizations. The ordering can significantly impact solver run time. + +* ``-1``: Automatic (default) - cuOpt selects the best ordering +* ``0``: cuDSS default ordering +* ``1``: AMD (Approximate Minimum Degree) ordering + +.. note:: The default value is ``-1`` (automatic). + +Augmented System +"""""""""""""""" + +``CUOPT_AUGMENTED`` controls which linear system to solve in the barrier method. + +* ``-1``: Automatic (default) - cuOpt selects the best linear system to solve +* ``0``: Solve the ADAT system (normal equations) +* ``1``: Solve the augmented system + +.. note:: The default value is ``-1`` (automatic). The augmented system may be more stable for some problems, while ADAT may be faster for others. + +Eliminate Dense Columns +"""""""""""""""""""""""" + +``CUOPT_ELIMINATE_DENSE_COLUMNS`` controls whether to eliminate dense columns from the constraint matrix before solving. Eliminating dense columns can improve performance by reducing fill-in during factorization. +However, extra solves must be performed at each iteration. + +* ``true``: Eliminate dense columns (default) +* ``false``: Don't eliminate dense columns + +This setting only has an effect when the ADAT (normal equation) system is solved. + +.. note:: The default value is ``true``. + +cuDSS Deterministic Mode +""""""""""""""""""""""""" + +``CUOPT_CUDSS_DETERMINISTIC`` controls whether cuDSS operates in deterministic mode. Deterministic mode ensures reproducible results across runs but may be slower. + +* ``true``: Use deterministic mode +* ``false``: Use non-deterministic mode (default) + +.. note:: The default value is ``false``. Enable deterministic mode if reproducibility is more important than performance. + +Dual Initial Point +"""""""""""""""""" + +``CUOPT_BARRIER_DUAL_INITIAL_POINT`` controls the method used to compute the dual initial point for the barrier solver. The choice of initial point will affect the number of iterations performed by barrier. + +* ``-1``: Automatic (default) - cuOpt selects the best method +* ``0``: Use an initial point from a heuristic approach based on the paper "On Implementing Mehrotra's Predictor–Corrector Interior-Point Method for Linear Programming" (SIAM J. Optimization, 1992) by Lustig, Martsten, Shanno. +* ``1``: Use an initial point from solving a least squares problem that minimizes the norms of the dual variables and reduced costs while statisfying the dual equality constraints. + +.. note:: The default value is ``-1`` (automatic). + +Absolute Primal Tolerance +^^^^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_ABSOLUTE_PRIMAL_TOLERANCE`` controls the absolute primal tolerance used in the primal feasibility check. +Changing this value might have a significant impact on accuracy and runtime if the relative part +(the right-hand side vector b L2 norm) is close to, or equal to, 0. + + +The primal feasibility condition is computed as follows:: + + primal_feasiblity < absolute_primal_tolerance + relative_primal_tolerance * l2_norm(b) + +Default value is ``1e-4``. + + +Relative Primal Tolerance +^^^^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_RELATIVE_PRIMAL_TOLERANCE`` controls the relative primal tolerance used in PDLP's primal feasibility check. +Changing this value has a significant impact on accuracy and runtime. +The primal feasibility condition is computed as follows:: + + primal_feasiblity < absolute_primal_tolerance + relative_primal_tolerance * l2_norm(b) + +.. note:: The default value is ``1e-4``. + +Absolute Dual Tolerance +^^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_ABSOLUTE_DUAL_TOLERANCE`` controls the absolute dual tolerance used in PDLP's dual feasibility check. +Changing this value might have a significant impact on accuracy and runtime if the relative part +(the objective vector L2 norm) is close to, or equal to, 0. + +The dual feasibility condition is computed as follows:: + + dual_feasiblity < absolute_dual_tolerance + relative_dual_tolerance * l2_norm(c) + +.. note:: The default value is ``1e-4``. + +Relative Dual Tolerance +^^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_RELATIVE_DUAL_TOLERANCE`` controls the relative dual tolerance used in PDLP's dual feasibility check. +Changing this value has a significant impact on accuracy and runtime. +The dual feasibility condition is computed as follows:: + + dual_feasiblity < absolute_dual_tolerance + relative_dual_tolerance * l2_norm(c) + +.. note:: The default value is ``1e-4``. + + +Absolute Gap Tolerance +^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_ABSOLUTE_GAP_TOLERANCE`` controls the absolute gap tolerance used in PDLP's duality gap check. +Changing this value might have a significant impact on accuracy and runtime if the relative part ``(|primal_objective| + |dual_objective|)`` is close to, or equal to, 0. + +The duality gap is computed as follows:: + + duality_gap < absolute_gap_tolerance + relative_gap_tolerance * (|primal_objective| + |dual_objective|) + +.. note:: The default value is ``1e-4``. + + +Relative Gap Tolerance +^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_RELATIVE_GAP_TOLERANCE`` controls the relative gap tolerance used in PDLP's duality gap check. +Changing this value has a significant impact on accuracy and runtime. +The duality gap is computed as follows:: + + duality_gap < absolute_gap_tolerance + relative_gap_tolerance * (|primal_objective| + |dual_objective|) + +.. note:: The default value is ``1e-4``. + +Primal Infeasibility Tolerance +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_PRIMAL_INFEASIBLE_TOLERANCE`` controls the tolerance used to detect primal infeasibility in PDLP. +A certificate of primal infeasibility is accepted when the primal infeasibility residual falls below this threshold. + +.. note:: The default value is ``1e-8``. + +Dual Infeasibility Tolerance +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_DUAL_INFEASIBLE_TOLERANCE`` controls the tolerance used to detect dual infeasibility (unboundedness) in PDLP. +A certificate of dual infeasibility is accepted when the dual infeasibility residual falls below this threshold. + +.. note:: The default value is ``1e-8``. + +Barrier Iterative Refinement +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_BARRIER_ITERATIVE_REFINEMENT`` controls whether iterative refinement is applied after each barrier iteration to improve solution accuracy. + +* ``0`` (``CUOPT_BARRIER_ITERATIVE_REFINEMENT_OFF``): Disable iterative refinement (default). +* ``1`` (``CUOPT_BARRIER_ITERATIVE_REFINEMENT_ON``): Enable iterative refinement. + +.. note:: The default value is ``0`` (off). + +Barrier Step Scale +^^^^^^^^^^^^^^^^^^^ + +``CUOPT_BARRIER_STEP_SCALE`` controls the scaling factor applied to the step size in the barrier method. +Values less than 1 result in more conservative (shorter) steps; values greater than 1 result in more aggressive steps. + +.. note:: By default cuOpt selects the step scale automatically. diff --git a/docs/cuopt/source/cuopt-c/index.rst b/docs/cuopt/source/cuopt-c/index.rst index 9f424cdcb9..6b8aed243b 100644 --- a/docs/cuopt/source/cuopt-c/index.rst +++ b/docs/cuopt/source/cuopt-c/index.rst @@ -17,4 +17,4 @@ NVIDIA cuOpt supports a C API for GPU-accelerated optimization that enables user :name: LP, QP and MILP Optimization :titlesonly: - LP, QP and MILP + Continuous Optimization and MIP diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/continuous-c-api.rst b/docs/cuopt/source/cuopt-c/lp-qp-milp/continuous-c-api.rst new file mode 100644 index 0000000000..ac4e21173e --- /dev/null +++ b/docs/cuopt/source/cuopt-c/lp-qp-milp/continuous-c-api.rst @@ -0,0 +1,324 @@ +cuOpt LP/QP/SOCP C API Reference +======================================== + +This section contains the cuOpt LP/QP/SOCP C API reference. For MIP-specific functions and callbacks, see :doc:`mip-c-api`. + +Integer and Floating-Point Types +--------------------------------- + +cuOpt may be built with 32 or 64 bit integer and floating-point types. The C API uses a `typedef` for floating point and integer types to abstract the size of these types. + +.. doxygentypedef:: cuopt_int_t +.. doxygentypedef:: cuopt_float_t + +You may use the following functions to determine the number of bytes used to represent these types in your build + +.. doxygenfunction:: cuOptGetIntSize +.. doxygenfunction:: cuOptGetFloatSize + +Version Information +------------------- + +You may use the following function to get the version of the cuOpt library + +.. doxygenfunction:: cuOptGetVersion + +Status Codes +------------ + +Every function in the C API returns a status code that indicates success or failure. The following status codes are defined + +.. doxygendefine:: CUOPT_SUCCESS +.. doxygendefine:: CUOPT_INVALID_ARGUMENT +.. doxygendefine:: CUOPT_MPS_FILE_ERROR +.. doxygendefine:: CUOPT_MPS_PARSE_ERROR +.. doxygendefine:: CUOPT_VALIDATION_ERROR +.. doxygendefine:: CUOPT_OUT_OF_MEMORY +.. doxygendefine:: CUOPT_RUNTIME_ERROR + +Optimization Problem +-------------------- + +An optimization problem is represented via a `cuOptOptimizationProblem` + +.. doxygentypedef:: cuOptOptimizationProblem + +Optimization problems can be created, loaded, or written via the following functions + +.. doxygenfunction:: cuOptReadProblem +.. doxygenfunction:: cuOptWriteProblem +.. doxygenfunction:: cuOptCreateProblem +.. doxygenfunction:: cuOptCreateRangedProblem +.. doxygenfunction:: cuOptCreateQuadraticProblem +.. doxygenfunction:: cuOptCreateQuadraticRangedProblem + +.. note:: + ``cuOptCreateQuadraticProblem`` and ``cuOptCreateQuadraticRangedProblem`` are deprecated. + Prefer ``cuOptCreateProblem`` or ``cuOptCreateRangedProblem`` followed by + ``cuOptSetQuadraticObjective`` (and ``cuOptAddQuadraticConstraint`` for QCQP). + +For QP and QCQP/SOCP models, the quadratic objective and constraints may be specified +after creating a linear problem: + +.. doxygenfunction:: cuOptSetQuadraticObjective +.. doxygenfunction:: cuOptAddQuadraticConstraint + +.. note:: + ``cuOptAddQuadraticConstraint`` also enables **Second-Order Cone Programming (SOCP)** + support **(beta)**. When one or more quadratic constraints are present, cuOpt automatically + converts them to second-order cone form and selects the barrier solver. Only ``CUOPT_LESS_THAN`` + and ``CUOPT_GREATER_THAN`` sense is supported; equality quadratic constraints are not supported. + +A optimization problem must be destroyed with the following function + +.. doxygenfunction:: cuOptDestroyProblem + +Certain constants are needed to define an optimization problem. These constants are described below. + +Objective Sense Constants +------------------------- + +These constants are used to define the objective sense in the :c:func:`cuOptCreateProblem` and :c:func:`cuOptCreateRangedProblem` functions. + +.. doxygendefine:: CUOPT_MINIMIZE +.. doxygendefine:: CUOPT_MAXIMIZE + +Constraint Sense Constants +-------------------------- + +These constants are used to define the constraint sense in the :c:func:`cuOptCreateProblem` and :c:func:`cuOptCreateRangedProblem` functions. + +.. doxygendefine:: CUOPT_LESS_THAN +.. doxygendefine:: CUOPT_GREATER_THAN +.. doxygendefine:: CUOPT_EQUAL + +Variable Type Constants +----------------------- + +These constants are used to define the the variable type in the :c:func:`cuOptCreateProblem` and :c:func:`cuOptCreateRangedProblem` functions. + +.. doxygendefine:: CUOPT_CONTINUOUS +.. doxygendefine:: CUOPT_INTEGER +.. doxygendefine:: CUOPT_SEMI_CONTINUOUS + +Infinity Constant +----------------- + +This constant may be used to represent infinity in the :c:func:`cuOptCreateProblem` and :c:func:`cuOptCreateRangedProblem` functions. + +.. doxygendefine:: CUOPT_INFINITY + +File Format Constants +--------------------- + +These constants are used to specify the output file format in :c:func:`cuOptWriteProblem`. + +.. doxygendefine:: CUOPT_FILE_FORMAT_MPS + +Querying an optimization problem +-------------------------------- + +The following functions may be used to get information about an `cuOptimizationProblem` + +.. doxygenfunction:: cuOptGetNumConstraints +.. doxygenfunction:: cuOptGetNumVariables +.. doxygenfunction:: cuOptGetObjectiveSense +.. doxygenfunction:: cuOptGetObjectiveOffset +.. doxygenfunction:: cuOptGetObjectiveCoefficients +.. doxygenfunction:: cuOptGetNumNonZeros +.. doxygenfunction:: cuOptGetConstraintMatrix +.. doxygenfunction:: cuOptGetConstraintSense +.. doxygenfunction:: cuOptGetConstraintRightHandSide +.. doxygenfunction:: cuOptGetConstraintLowerBounds +.. doxygenfunction:: cuOptGetConstraintUpperBounds +.. doxygenfunction:: cuOptGetVariableLowerBounds +.. doxygenfunction:: cuOptGetVariableUpperBounds +.. doxygenfunction:: cuOptGetVariableTypes +.. doxygenfunction:: cuOptIsMIP + + +Solver Settings +--------------- + +Settings are used to configure the LP/MIP solvers. All settings are stored in a `cuOptSolverSettings` object. + + +.. doxygentypedef:: cuOptSolverSettings + +A `cuOptSolverSettings` object is created with `cuOptCreateSolverSettings` + +.. doxygenfunction:: cuOptCreateSolverSettings + +When you are done with a solve you should destroy a `cuOptSolverSettings` object with + +.. doxygenfunction:: cuOptDestroySolverSettings + + +Setting Parameters +------------------ +The following functions are used to set and get parameters. You can find more details on the available parameters in the :doc:`Continuous Optimization settings <../../continuous-settings>` section. + +.. doxygenfunction:: cuOptSetParameter +.. doxygenfunction:: cuOptGetParameter +.. doxygenfunction:: cuOptSetIntegerParameter +.. doxygenfunction:: cuOptGetIntegerParameter +.. doxygenfunction:: cuOptSetFloatParameter +.. doxygenfunction:: cuOptGetFloatParameter + +.. _parameter-constants: + +Parameter Constants +------------------- + +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/QP parameter string constants +.. doxygendefine:: CUOPT_ABSOLUTE_DUAL_TOLERANCE +.. doxygendefine:: CUOPT_RELATIVE_DUAL_TOLERANCE +.. doxygendefine:: CUOPT_ABSOLUTE_PRIMAL_TOLERANCE +.. doxygendefine:: CUOPT_RELATIVE_PRIMAL_TOLERANCE +.. doxygendefine:: CUOPT_ABSOLUTE_GAP_TOLERANCE +.. doxygendefine:: CUOPT_RELATIVE_GAP_TOLERANCE +.. doxygendefine:: CUOPT_INFEASIBILITY_DETECTION +.. doxygendefine:: CUOPT_STRICT_INFEASIBILITY +.. doxygendefine:: CUOPT_PRIMAL_INFEASIBLE_TOLERANCE +.. doxygendefine:: CUOPT_DUAL_INFEASIBLE_TOLERANCE +.. doxygendefine:: CUOPT_ITERATION_LIMIT +.. doxygendefine:: CUOPT_TIME_LIMIT +.. doxygendefine:: CUOPT_PDLP_SOLVER_MODE +.. doxygendefine:: CUOPT_METHOD +.. doxygendefine:: CUOPT_PER_CONSTRAINT_RESIDUAL +.. doxygendefine:: CUOPT_SAVE_BEST_PRIMAL_SO_FAR +.. doxygendefine:: CUOPT_FIRST_PRIMAL_FEASIBLE +.. doxygendefine:: CUOPT_LOG_FILE +.. doxygendefine:: CUOPT_PRESOLVE +.. doxygendefine:: CUOPT_LOG_TO_CONSOLE +.. doxygendefine:: CUOPT_CROSSOVER +.. doxygendefine:: CUOPT_FOLDING +.. doxygendefine:: CUOPT_AUGMENTED +.. doxygendefine:: CUOPT_DUALIZE +.. doxygendefine:: CUOPT_ORDERING +.. doxygendefine:: CUOPT_ELIMINATE_DENSE_COLUMNS +.. doxygendefine:: CUOPT_CUDSS_DETERMINISTIC +.. doxygendefine:: CUOPT_BARRIER_DUAL_INITIAL_POINT +.. doxygendefine:: CUOPT_BARRIER_ITERATIVE_REFINEMENT +.. doxygendefine:: CUOPT_BARRIER_STEP_SCALE +.. doxygendefine:: CUOPT_DUAL_POSTSOLVE +.. doxygendefine:: CUOPT_SOLUTION_FILE +.. doxygendefine:: CUOPT_NUM_CPU_THREADS +.. doxygendefine:: CUOPT_NUM_GPUS +.. doxygendefine:: CUOPT_USER_PROBLEM_FILE +.. doxygendefine:: CUOPT_PDLP_PRECISION + +.. _pdlp-solver-mode-constants: + +PDLP Solver Mode Constants +-------------------------- + +These constants are used to configure `CUOPT_PDLP_SOLVER_MODE` via :c:func:`cuOptSetIntegerParameter`. + +.. doxygendefine:: CUOPT_PDLP_SOLVER_MODE_STABLE1 +.. doxygendefine:: CUOPT_PDLP_SOLVER_MODE_STABLE2 +.. doxygendefine:: CUOPT_PDLP_SOLVER_MODE_STABLE3 +.. doxygendefine:: CUOPT_PDLP_SOLVER_MODE_METHODICAL1 +.. doxygendefine:: CUOPT_PDLP_SOLVER_MODE_FAST1 + +.. _pdlp-precision-constants: + +PDLP Precision Constants +------------------------ + +These constants are used to configure `CUOPT_PDLP_PRECISION` via :c:func:`cuOptSetIntegerParameter`. + +.. doxygendefine:: CUOPT_PDLP_DEFAULT_PRECISION +.. doxygendefine:: CUOPT_PDLP_SINGLE_PRECISION +.. doxygendefine:: CUOPT_PDLP_DOUBLE_PRECISION +.. doxygendefine:: CUOPT_PDLP_MIXED_PRECISION + +.. _method-constants: + +Method Constants +---------------- + +These constants are used to configure `CUOPT_METHOD` via :c:func:`cuOptSetIntegerParameter`. + +.. doxygendefine:: CUOPT_METHOD_CONCURRENT +.. doxygendefine:: CUOPT_METHOD_PDLP +.. doxygendefine:: CUOPT_METHOD_DUAL_SIMPLEX +.. doxygendefine:: CUOPT_METHOD_BARRIER +.. doxygendefine:: CUOPT_METHOD_UNSET + +.. _barrier-iterative-refinement-constants: + +Barrier Iterative Refinement Constants +--------------------------------------- + +These constants are used to configure `CUOPT_BARRIER_ITERATIVE_REFINEMENT` via :c:func:`cuOptSetIntegerParameter`. + +.. doxygendefine:: CUOPT_BARRIER_ITERATIVE_REFINEMENT_OFF +.. doxygendefine:: CUOPT_BARRIER_ITERATIVE_REFINEMENT_ON + + +Warm Start +---------- + +For LP problems solved with PDLP, primal and dual warm start vectors may be provided: + +.. doxygenfunction:: cuOptSetInitialPrimalSolution +.. doxygenfunction:: cuOptSetInitialDualSolution + +.. note:: + For MIP warm start (MIP starts), see :doc:`mip-c-api`. + + +Solving an LP or MIP +-------------------- + +LP and MIP solves are performed by calling the `cuOptSolve` function + +.. doxygenfunction:: cuOptSolve + + +Solution +-------- + +The output of a solve is a `cuOptSolution` object. + +.. doxygentypedef:: cuOptSolution + +The following functions may be used to access information from a `cuOptSolution` + +.. doxygenfunction:: cuOptGetTerminationStatus +.. doxygenfunction:: cuOptGetErrorStatus +.. doxygenfunction:: cuOptGetErrorString +.. doxygenfunction:: cuOptGetPrimalSolution +.. doxygenfunction:: cuOptGetObjectiveValue +.. doxygenfunction:: cuOptGetSolveTime +.. doxygenfunction:: cuOptGetMIPGap +.. doxygenfunction:: cuOptGetSolutionBound +.. doxygenfunction:: cuOptGetDualSolution +.. doxygenfunction:: cuOptGetDualObjectiveValue +.. doxygenfunction:: cuOptGetReducedCosts + +When you are finished with a `cuOptSolution` object you should destory it with + +.. doxygenfunction:: cuOptDestroySolution + +Termination Status Constants +---------------------------- + +These constants define the termination status received from the :c:func:`cuOptGetTerminationStatus` function. + +.. LP/MIP termination status constants +.. doxygendefine:: CUOPT_TERMINATION_STATUS_NO_TERMINATION +.. doxygendefine:: CUOPT_TERMINATION_STATUS_OPTIMAL +.. doxygendefine:: CUOPT_TERMINATION_STATUS_INFEASIBLE +.. doxygendefine:: CUOPT_TERMINATION_STATUS_UNBOUNDED +.. doxygendefine:: CUOPT_TERMINATION_STATUS_ITERATION_LIMIT +.. doxygendefine:: CUOPT_TERMINATION_STATUS_TIME_LIMIT +.. doxygendefine:: CUOPT_TERMINATION_STATUS_NUMERICAL_ERROR +.. doxygendefine:: CUOPT_TERMINATION_STATUS_PRIMAL_FEASIBLE +.. doxygendefine:: CUOPT_TERMINATION_STATUS_FEASIBLE_FOUND +.. doxygendefine:: CUOPT_TERMINATION_STATUS_CONCURRENT_LIMIT +.. doxygendefine:: CUOPT_TERMINATION_STATUS_WORK_LIMIT +.. doxygendefine:: CUOPT_TERMINATION_STATUS_UNBOUNDED_OR_INFEASIBLE diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/continuous-examples.rst b/docs/cuopt/source/cuopt-c/lp-qp-milp/continuous-examples.rst new file mode 100644 index 0000000000..1bfb1156c1 --- /dev/null +++ b/docs/cuopt/source/cuopt-c/lp-qp-milp/continuous-examples.rst @@ -0,0 +1,214 @@ +==================== +LP/QP C API Examples +==================== + + +Example With Data +----------------- + +This example demonstrates how to use the LP solver in C. More details on the API can be found in :doc:`C API `. + +The example code is available at ``examples/cuopt-c/lp/simple_lp_example.c`` (:download:`download `): + +.. literalinclude:: examples/simple_lp_example.c + :language: c + :linenos: + +It is necessary to have the path for include and library dirs ready, if you know the paths, please add them to the path variables directly. Otherwise, run the following commands to find the path and assign it to the path variables. +The following commands are for Linux and might fail in cases where the cuopt library is not installed or there are multiple cuopt libraries in the system. + +If you have built it locally, libcuopt.so will be in the build directory ``cpp/build`` and include directoy would be ``cpp/include``. + +.. code-block:: bash + + # Find the cuopt header file and assign to INCLUDE_PATH + INCLUDE_PATH=$(find / -name "cuopt_c.h" -path "*/linear_programming/*" -printf "%h\n" | sed 's/\/linear_programming//' 2>/dev/null) + # Find the libcuopt library and assign to LIBCUOPT_LIBRARY_PATH + LIBCUOPT_LIBRARY_PATH=$(find / -name "libcuopt.so" 2>/dev/null) + + +Build and run the example + +.. code-block:: bash + + # Build and run the example + gcc -I $INCLUDE_PATH -L $LIBCUOPT_LIBRARY_PATH -o simple_lp_example simple_lp_example.c -lcuopt + ./simple_lp_example + + + +You should see the following output: + +.. code-block:: bash + :caption: Output + + Creating and solving simple LP problem... + Solving a problem with 2 constraints 2 variables (0 integers) and 4 nonzeros + Objective offset 0.000000 scaling_factor 1.000000 + Running concurrent + + Dual simplex finished in 0.00 seconds + Iter Primal Obj. Dual Obj. Gap Primal Res. Dual Res. Time + 0 +0.00000000e+00 +0.00000000e+00 0.00e+00 0.00e+00 2.00e-01 0.011s + PDLP finished + Concurrent time: 0.013s + Solved with dual simplex + Status: Optimal Objective: -3.60000000e-01 Iterations: 1 Time: 0.013s + + Results: + -------- + Termination status: Optimal (1) + Solve time: 0.000013 seconds + Objective value: -0.360000 + + Primal Solution: Solution variables + x1 = 1.800000 + x2 = 0.000000 + + Test completed successfully! + + +Example With MPS File +--------------------- + +This example demonstrates how to use the cuOpt linear programming solver in C to solve an MPS file. + +The same ``cuOptReadProblem`` call also accepts **LP** format files. The +format is dispatched from the filename extension (case-insensitive): +``.lp`` / ``.lp.gz`` / ``.lp.bz2`` → LP parser; ``.mps`` / ``.qps`` and +their ``.gz`` / ``.bz2`` variants → MPS parser. Unknown extensions are +rejected. See :ref:`lp-file-example-c` for an LP counterpart. + +The example code is available at ``examples/cuopt-c/lp/mps_file_example.c`` (:download:`download `): + +.. literalinclude:: examples/mps_file_example.c + :language: c + :linenos: + +It is necessary to have the path for include and library dirs ready, if you know the paths, please add them to the path variables directly. Otherwise, run the following commands to find the path and assign it to the path variables. +The following commands are for Linux and might fail in cases where the cuopt library is not installed or there are multiple cuopt libraries in the system. + +If you have built it locally, libcuopt.so will be in the build directory ``cpp/build`` and include directoy would be ``cpp/include``. + +.. code-block:: bash + + # Find the cuopt header file and assign to INCLUDE_PATH + INCLUDE_PATH=$(find / -name "cuopt_c.h" -path "*/linear_programming/*" -printf "%h\n" | sed 's/\/linear_programming//' 2>/dev/null) + # Find the libcuopt library and assign to LIBCUOPT_LIBRARY_PATH + LIBCUOPT_LIBRARY_PATH=$(find / -name "libcuopt.so" 2>/dev/null) + +A sample MPS file (:download:`download sample.mps `): + +.. literalinclude:: examples/sample.mps + :language: text + :linenos: + +Build and run the example + +.. code-block:: bash + + # Build and run the example + gcc -I $INCLUDE_PATH -L $LIBCUOPT_LIBRARY_PATH -o mps_file_example mps_file_example.c -lcuopt + ./mps_file_example sample.mps + + +You should see the following output: + +.. code-block:: bash + :caption: Output + + Reading and solving MPS file: sample.mps + Solving a problem with 2 constraints 2 variables (0 integers) and 4 nonzeros + Objective offset 0.000000 scaling_factor 1.000000 + Running concurrent + + Dual simplex finished in 0.00 seconds + Iter Primal Obj. Dual Obj. Gap Primal Res. Dual Res. Time + 0 +0.00000000e+00 +0.00000000e+00 0.00e+00 0.00e+00 2.00e-01 0.012s + PDLP finished + Concurrent time: 0.014s + Solved with dual simplex + Status: Optimal Objective: -3.60000000e-01 Iterations: 1 Time: 0.014s + + Results: + -------- + Number of variables: 2 + Termination status: Optimal (1) + Solve time: 0.000014 seconds + Objective value: -0.360000 + + Primal Solution: First 10 solution variables (or fewer if less exist): + x1 = 1.800000 + x2 = 0.000000 + + Solver completed successfully! + + +.. _lp-file-example-c: + +Example With LP File +-------------------- + +``cuOptReadProblem`` also accepts LP format files. The same function is +used — it dispatches on the file extension (case-insensitive): +``.lp`` / ``.lp.gz`` / ``.lp.bz2`` → LP parser; ``.mps`` / ``.qps`` and +their ``.gz`` / ``.bz2`` variants → MPS parser; unknown extensions are +rejected. See the ``read_lp`` declaration in +``cuopt/linear_programming/io/parser.hpp`` for the supported subset of +the LP format. + +The example code is available at ``examples/cuopt-c/lp/lp_file_example.c`` (:download:`download `): + +.. literalinclude:: examples/lp_file_example.c + :language: c + :linenos: + +A sample LP file (:download:`download sample.lp `), +equivalent to the MPS sample above: + +.. literalinclude:: examples/sample.lp + :language: text + :linenos: + +Build and run the example + +.. code-block:: bash + + gcc -I $INCLUDE_PATH -L $LIBCUOPT_LIBRARY_PATH -o lp_file_example lp_file_example.c -lcuopt + ./lp_file_example sample.lp + +The output matches the MPS example above (same problem, same objective = -0.36). + + +.. _simple-qp-example-c: + +Simple Quadratic Programming Example +------------------------------------ + +This example demonstrates how to use the cuOpt C API for quadratic programming. + +The example code is available at ``examples/cuopt-c/lp/simple_qp_example.c`` (:download:`download `): + +.. literalinclude:: examples/simple_qp_example.c + :language: c + :linenos: + +Build and run the example + +.. code-block:: bash + + # Build and run the example + gcc -I $INCLUDE_PATH -L $LIBCUOPT_LIBRARY_PATH -o simple_qp_example simple_qp_example.c -lcuopt + ./simple_qp_example + +You should see the following output: + +.. code-block:: bash + :caption: Output + + Creating and solving simple QP problem... + Status: Optimal + Objective value: 0.500000 + x = 0.500000 + y = 0.500000 + Test completed successfully! diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/index.rst b/docs/cuopt/source/cuopt-c/lp-qp-milp/index.rst index 3dade721fc..17b7369bf1 100644 --- a/docs/cuopt/source/cuopt-c/lp-qp-milp/index.rst +++ b/docs/cuopt/source/cuopt-c/lp-qp-milp/index.rst @@ -1,15 +1,24 @@ -Linear Programming -================== +Continuous Optimization and MIP +================================ -This section contains details on the cuOpt LP/QP/MILP/SOCP C API. +This section contains details on the cuOpt LP/QP/SOCP/MILP C API. .. toctree:: :maxdepth: 3 - :caption: LP/QP/MILP/SOCP - :name: LP/QP/MILP/SOCP + :caption: Continuous Optimization (LP/QP/SOCP) + :name: LP/QP/SOCP C API :titlesonly: - lp-qp-milp-c-api.rst - ../../lp-qp-milp-settings.rst - lp-qp-example.rst - milp-examples.rst + continuous-c-api.rst + ../../continuous-settings.rst + continuous-examples.rst + +.. toctree:: + :maxdepth: 3 + :caption: Mixed Integer Programming (MIP) + :name: MIP C API + :titlesonly: + + mip-c-api.rst + ../../mip-settings.rst + mip-examples.rst diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/mip-c-api.rst b/docs/cuopt/source/cuopt-c/lp-qp-milp/mip-c-api.rst new file mode 100644 index 0000000000..1870b8d5ec --- /dev/null +++ b/docs/cuopt/source/cuopt-c/lp-qp-milp/mip-c-api.rst @@ -0,0 +1,74 @@ +cuOpt MIP C API Reference +========================= + +This section contains the cuOpt MIP C API reference. Functions for problem creation, solver settings, solving, and inspecting solutions are shared with LP/QP/SOCP and documented in :doc:`continuous-c-api`. + +Warm Start and MIP Start +------------------------ + +For LP problems solved with PDLP, see :doc:`continuous-c-api` for primal and dual warm start. + +For MIP problems, one or more primal solution hints (MIP starts) may be provided: + +.. doxygenfunction:: cuOptAddMIPStart + +MIP Solution Callbacks +----------------------- + +The following callback types and functions allow monitoring and injecting solutions during a MIP solve. + +.. doxygentypedef:: cuOptMIPGetSolutionCallback +.. doxygentypedef:: cuOptMIPSetSolutionCallback + +.. doxygenfunction:: cuOptSetMIPGetSolutionCallback +.. doxygenfunction:: cuOptSetMIPSetSolutionCallback + +.. _mip-parameter-constants: + +MIP Parameter Constants +----------------------- + +These constants configure MIP-specific solver behavior. Use them with :c:func:`cuOptSetParameter`, :c:func:`cuOptSetIntegerParameter`, or :c:func:`cuOptSetFloatParameter`. For shared parameters (time limit, logging, presolve, etc.), see :ref:`parameter-constants` in the continuous API reference. + +.. doxygendefine:: CUOPT_NODE_LIMIT +.. doxygendefine:: CUOPT_WORK_LIMIT +.. doxygendefine:: CUOPT_RANDOM_SEED +.. doxygendefine:: CUOPT_PRESOLVE_FILE +.. doxygendefine:: CUOPT_MIP_ABSOLUTE_TOLERANCE +.. doxygendefine:: CUOPT_MIP_RELATIVE_TOLERANCE +.. doxygendefine:: CUOPT_MIP_INTEGRALITY_TOLERANCE +.. doxygendefine:: CUOPT_MIP_ABSOLUTE_GAP +.. doxygendefine:: CUOPT_MIP_RELATIVE_GAP +.. doxygendefine:: CUOPT_MIP_SCALING +.. doxygendefine:: CUOPT_MIP_HEURISTICS_ONLY +.. doxygendefine:: CUOPT_MIP_PRESOLVE +.. doxygendefine:: CUOPT_MIP_DETERMINISM_MODE +.. doxygendefine:: CUOPT_MIP_SYMMETRY +.. doxygendefine:: CUOPT_MIP_PROBING +.. doxygendefine:: CUOPT_MIP_RELIABILITY_BRANCHING +.. doxygendefine:: CUOPT_MIP_CUT_PASSES +.. doxygendefine:: CUOPT_MIP_MIXED_INTEGER_ROUNDING_CUTS +.. doxygendefine:: CUOPT_MIP_MIXED_INTEGER_GOMORY_CUTS +.. doxygendefine:: CUOPT_MIP_KNAPSACK_CUTS +.. doxygendefine:: CUOPT_MIP_FLOW_COVER_CUTS +.. doxygendefine:: CUOPT_MIP_IMPLIED_BOUND_CUTS +.. doxygendefine:: CUOPT_MIP_CLIQUE_CUTS +.. doxygendefine:: CUOPT_MIP_STRONG_CHVATAL_GOMORY_CUTS +.. doxygendefine:: CUOPT_MIP_REDUCED_COST_STRENGTHENING +.. doxygendefine:: CUOPT_MIP_OBJECTIVE_STEP +.. doxygendefine:: CUOPT_MIP_CUT_CHANGE_THRESHOLD +.. doxygendefine:: CUOPT_MIP_CUT_MIN_ORTHOGONALITY +.. doxygendefine:: CUOPT_MIP_BATCH_PDLP_STRONG_BRANCHING +.. doxygendefine:: CUOPT_MIP_BATCH_PDLP_RELIABILITY_BRANCHING +.. doxygendefine:: CUOPT_MIP_STRONG_BRANCHING_SIMPLEX_ITERATION_LIMIT +.. doxygendefine:: CUOPT_MIP_SEMICONTINUOUS_BIG_M + +.. _mip-determinism-mode-constants: + +MIP Determinism Mode Constants +------------------------------ + +These constants are used to configure `CUOPT_MIP_DETERMINISM_MODE` via :c:func:`cuOptSetIntegerParameter`. + +.. doxygendefine:: CUOPT_MODE_OPPORTUNISTIC +.. doxygendefine:: CUOPT_MODE_DETERMINISTIC diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/mip-examples.rst b/docs/cuopt/source/cuopt-c/lp-qp-milp/mip-examples.rst new file mode 100644 index 0000000000..0d925677a6 --- /dev/null +++ b/docs/cuopt/source/cuopt-c/lp-qp-milp/mip-examples.rst @@ -0,0 +1,162 @@ +MILP C API Examples +=================== + + +Example With Data +----------------- + +This example demonstrates how to use the MILP solver in C. More details on the API can be found in :doc:`MIP C API `. + +The example code is available at ``../lp-milp/examples/simple_milp_example.c`` (:download:`download `): + +.. literalinclude:: examples/simple_milp_example.c + :language: c + :linenos: + +It is necessary to have the path for include and library dirs ready, if you know the paths, please add them to the path variables directly. Otherwise, run the following commands to find the path and assign it to the path variables. +The following commands are for Linux and might fail in cases where the cuopt library is not installed or there are multiple cuopt libraries in the system. + +If you have built it locally, libcuopt.so will be in the build directory ``cpp/build`` and include directoy would be ``cpp/include``. + +.. code-block:: bash + + # Find the cuopt header file and assign to INCLUDE_PATH + INCLUDE_PATH=$(find / -name "cuopt_c.h" -path "*/linear_programming/*" -printf "%h\n" | sed 's/\/linear_programming//' 2>/dev/null) + # Find the libcuopt library and assign to LIBCUOPT_LIBRARY_PATH + LIBCUOPT_LIBRARY_PATH=$(find / -name "libcuopt.so" 2>/dev/null) + + +Build and run the example + +.. code-block:: bash + + # Build and run the example + gcc -I $INCLUDE_PATH -L $LIBCUOPT_LIBRARY_PATH -o simple_milp_example simple_milp_example.c -lcuopt + ./simple_milp_example + + + +You should see the following output: + +.. code-block:: bash + :caption: Output + + Creating and solving simple LP problem... + Solving a problem with 2 constraints 2 variables (1 integers) and 4 nonzeros + Objective offset 0.000000 scaling_factor 1.000000 + After trivial presolve updated 2 constraints 2 variables + Running presolve! + After trivial presolve updated 2 constraints 2 variables + Solving LP root relaxation + Scaling matrix. Maximum column norm 1.046542e+00 + Dual Simplex Phase 1 + Dual feasible solution found. + Dual Simplex Phase 2 + Iter Objective Primal Infeas Perturb Time + 1 -2.00000000e-01 1.46434160e+00 0.00e+00 0.00 + + Root relaxation solution found in 2 iterations and 0.00s + Root relaxation objective -2.00000000e-01 + + Optimal solution found at root node. Objective -2.0000000000000001e-01. Time 0.00. + B&B added a solution to population, solution queue size 0 with objective -0.2 + Solution objective: -0.200000 , relative_mip_gap 0.000000 solution_bound -0.200000 presolve_time 0.041144 total_solve_time 0.000000 max constraint violation 0.000000 max int violation 0.000000 max var bounds violation 0.000000 nodes 0 simplex_iterations 0 + + Results: + -------- + Termination status: Optimal (1) + Solve time: 0.000000 seconds + Objective value: -0.200000 + + Solution: + x1 = 1.000000 + x2 = 0.000000 + + Test completed successfully! + + +Example With MPS File +--------------------- + +This example demonstrates how to use the cuOpt solver in C to solve an MPS file. + +The example code is available at ``examples/milp_mps_example.c`` (:download:`download `): + +.. literalinclude:: examples/milp_mps_example.c + :language: c + :linenos: + +It is necessary to have the path for include and library dirs ready, if you know the paths, please add them to the path variables directly. Otherwise, run the following commands to find the path and assign it to the path variables. +The following commands are for Linux and might fail in cases where the cuopt library is not installed or there are multiple cuopt libraries in the system. + +If you have built it locally, libcuopt.so will be in the build directory ``cpp/build`` and include directoy would be ``cpp/include``. + +.. code-block:: bash + + # Find the cuopt header file and assign to INCLUDE_PATH + INCLUDE_PATH=$(find / -name "cuopt_c.h" -path "*/linear_programming/*" -printf "%h\n" | sed 's/\/linear_programming//' 2>/dev/null) + # Find the libcuopt library and assign to LIBCUOPT_LIBRARY_PATH + LIBCUOPT_LIBRARY_PATH=$(find / -name "libcuopt.so" 2>/dev/null) + +A sample MILP MPS file (:download:`download mip_sample.mps `): + +.. literalinclude:: examples/mip_sample.mps + :language: text + :linenos: + +Build and run the example + +.. code-block:: bash + + # Build and run the example + gcc -I $INCLUDE_PATH -L $LIBCUOPT_LIBRARY_PATH -o milp_mps_example milp_mps_example.c -lcuopt + ./milp_mps_example mip_sample.mps + + +You should see the following output: + +.. code-block:: bash + :caption: Output + + Reading and solving MPS file: sample.mps + Solving a problem with 3 constraints 2 variables (2 integers) and 6 nonzeros + Objective offset 0.000000 scaling_factor 1.000000 + After trivial presolve updated 3 constraints 2 variables + Running presolve! + After trivial presolve updated 3 constraints 2 variables + Solving LP root relaxation + Scaling matrix. Maximum column norm 1.225464e+00 + Dual Simplex Phase 1 + Dual feasible solution found. + Dual Simplex Phase 2 + Iter Objective Primal Infeas Perturb Time + 1 -3.04000000e+01 7.57868205e+00 0.00e+00 0.00 + + Root relaxation solution found in 3 iterations and 0.00s + Root relaxation objective -3.01818182e+01 + + Strong branching on 2 fractional variables + | Explored | Unexplored | Objective | Bound | Depth | Iter/Node | Gap | Time + 0 1 +inf -3.018182e+01 1 0.0e+00 - 0.00 + B 3 1 -2.700000e+01 -2.980000e+01 2 6.7e-01 10.4% 0.00 + B&B added a solution to population, solution queue size 0 with objective -27 + B 4 0 -2.800000e+01 -2.980000e+01 2 7.5e-01 6.4% 0.00 + B&B added a solution to population, solution queue size 1 with objective -28 + Explored 4 nodes in 0.00s. + Absolute Gap 0.000000e+00 Objective -2.8000000000000004e+01 Lower Bound -2.8000000000000004e+01 + Optimal solution found. + Generated fast solution in 0.136067 seconds with objective -28.000000 + Solution objective: -28.000000 , relative_mip_gap 0.000000 solution_bound -28.000000 presolve_time 0.039433 total_solve_time 0.000000 max constraint violation 0.000000 max int violation 0.000000 max var bounds violation 0.000000 nodes 4 simplex_iterations 3 + + Results: + -------- + Number of variables: 2 + Termination status: Optimal (1) + Solve time: 0.000000 seconds + Objective value: -28.000000 + + Solution: + x1 = 4.000000 + x2 = 0.000000 + + Solver completed successfully! diff --git a/docs/cuopt/source/cuopt-cli/quick-start.rst b/docs/cuopt/source/cuopt-cli/quick-start.rst index c6012fe918..d020bed043 100644 --- a/docs/cuopt/source/cuopt-cli/quick-start.rst +++ b/docs/cuopt/source/cuopt-cli/quick-start.rst @@ -23,4 +23,4 @@ This will display the complete list of command-line arguments and their usage: :language: text :linenos: -Please refer to :doc:`../lp-qp-milp-settings` for more details on default values and other options. +Please refer to :doc:`../continuous-settings` and :doc:`../mip-settings` for more details on default values and other options. diff --git a/docs/cuopt/source/cuopt-grpc/examples.rst b/docs/cuopt/source/cuopt-grpc/examples.rst index 730db5f612..a17816fb48 100644 --- a/docs/cuopt/source/cuopt-grpc/examples.rst +++ b/docs/cuopt/source/cuopt-grpc/examples.rst @@ -27,15 +27,16 @@ Where to find examples Python (LP / QP / MILP) ----------------------- -* :doc:`../cuopt-python/lp-qp-milp/lp-qp-milp-examples` — runnable Python samples (LP, QP, MILP). With ``CUOPT_REMOTE_HOST`` and ``CUOPT_REMOTE_PORT`` set on the client, solves go to the remote server automatically. +* :doc:`../cuopt-python/lp-qp-milp/continuous-examples` — runnable Python samples (LP, QP). With ``CUOPT_REMOTE_HOST`` and ``CUOPT_REMOTE_PORT`` set on the client, solves go to the remote server automatically. +* :doc:`../cuopt-python/lp-qp-milp/mip-examples` — runnable Python samples (MILP). With ``CUOPT_REMOTE_HOST`` and ``CUOPT_REMOTE_PORT`` set on the client, solves go to the remote server automatically. C API (LP / QP / MILP) ---------------------- -* :doc:`../cuopt-c/lp-qp-milp/lp-qp-example` — LP and QP C examples. -* :doc:`../cuopt-c/lp-qp-milp/milp-examples` — MILP C examples. +* :doc:`../cuopt-c/lp-qp-milp/continuous-examples` — LP and QP C examples. +* :doc:`../cuopt-c/lp-qp-milp/mip-examples` — MILP C examples. - Compile and run these programs with the same exports in the shell; ``solve_lp`` / ``solve_mip`` use gRPC when both remote variables are set (see :doc:`../cuopt-c/lp-qp-milp/lp-qp-milp-c-api` for API reference). + Compile and run these programs with the same exports in the shell; ``solve_lp`` / ``solve_mip`` use gRPC when both remote variables are set (see :doc:`../cuopt-c/lp-qp-milp/continuous-c-api` for API reference). ``cuopt_cli`` ------------- diff --git a/docs/cuopt/source/cuopt-grpc/quick-start.rst b/docs/cuopt/source/cuopt-grpc/quick-start.rst index b3c0ca2cc1..360447a0da 100644 --- a/docs/cuopt/source/cuopt-grpc/quick-start.rst +++ b/docs/cuopt/source/cuopt-grpc/quick-start.rst @@ -143,7 +143,7 @@ To solve **locally** with the same file: More options (time limits, relaxation): :doc:`../cuopt-cli/quick-start` and :doc:`examples`. -**C API** — With the same environment variables set, call ``solve_lp`` / ``solve_mip`` as in :doc:`../cuopt-c/lp-qp-milp/lp-qp-milp-c-api`. +**C API** — With the same environment variables set, call ``solve_lp`` / ``solve_mip`` as in :doc:`../cuopt-c/lp-qp-milp/continuous-c-api`. More patterns (MPS variants, custom gRPC): :doc:`examples`. diff --git a/docs/cuopt/source/cuopt-python/index.rst b/docs/cuopt/source/cuopt-python/index.rst index 49b805a801..b39a8d5d79 100644 --- a/docs/cuopt/source/cuopt-python/index.rst +++ b/docs/cuopt/source/cuopt-python/index.rst @@ -26,8 +26,8 @@ This section contains details on the cuOpt Python package. .. toctree:: :maxdepth: 3 - :caption: Linear Programming, Quadratic Programming and Mixed Integer Linear Programming - :name: LP, QP and MILP API + :caption: Continuous Optimization and MIP + :name: Continuous Optimization and MIP Python API :titlesonly: - LP, QP and MILP + Continuous Optimization and MIP diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/continuous-api.rst b/docs/cuopt/source/cuopt-python/lp-qp-milp/continuous-api.rst new file mode 100644 index 0000000000..e0a4fb672c --- /dev/null +++ b/docs/cuopt/source/cuopt-python/lp-qp-milp/continuous-api.rst @@ -0,0 +1,46 @@ +============================= +LP, QP and SOCP API Reference +============================= + +.. autoclass:: cuopt.linear_programming.problem.Problem + :members: + :undoc-members: + :exclude-members: reset_solved_values, populate_solution, dict_to_object, get_incumbent_values, get_pdlp_warm_start_data, getQcsr + +.. autoclass:: cuopt.linear_programming.problem.Variable + :members: + :undoc-members: + :exclude-members: + +.. autoclass:: cuopt.linear_programming.problem.LinearExpression + :members: + :undoc-members: + +.. autoclass:: cuopt.linear_programming.problem.QuadraticExpression + :members: + :undoc-members: + :special-members: __le__, __ge__, __neg__ + +.. autoclass:: cuopt.linear_programming.problem.Constraint + :members: + :undoc-members: + :exclude-members: compute_slack + +.. autoclass:: cuopt.linear_programming.solver_settings.SolverSettings + :members: + :undoc-members: + :exclude-members: to_base_type, toDict + +.. autoclass:: cuopt.linear_programming.problem.CType + :members: + :member-order: bysource + :undoc-members: + :exclude-members: capitalize, casefold, center, count, encode, endswith, expandtabs, find, format, format_map, index, isalnum, isalpha, isascii, isdecimal, isdigit, isidentifier, islower, isnumeric, isprintable, isspace, istitle, isupper, join, ljust, lower, lstrip, maketrans, partition, removeprefix, removesuffix, replace, rfind, rindex, rjust, rpartition, rsplit, rstrip, split, splitlines, startswith, strip, swapcase, title, translate, upper, zfill + +.. autoclass:: cuopt.linear_programming.problem.sense + :members: + :member-order: bysource + :undoc-members: + :exclude-members: __new__, __init__, _generate_next_value_, as_integer_ratio, bit_count, bit_length, conjugate, denominator, from_bytes, imag, is_integer, numerator, real, to_bytes + +.. autofunction:: cuopt.linear_programming.io.Read diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/continuous-examples.rst b/docs/cuopt/source/cuopt-python/lp-qp-milp/continuous-examples.rst new file mode 100644 index 0000000000..e4ad75f4e7 --- /dev/null +++ b/docs/cuopt/source/cuopt-python/lp-qp-milp/continuous-examples.rst @@ -0,0 +1,153 @@ +======================== +LP, QP and SOCP Examples +======================== + +This section contains examples of how to use the cuOpt LP, QP, and SOCP Python API. + +.. note:: + + The examples in this section are not exhaustive. They are provided to help you get started with the cuOpt LP, QP, and SOCP Python API. For more examples, please refer to the `cuopt-examples GitHub repository `_. + + +Simple Linear Programming Example +--------------------------------- + +:download:`simple_lp_example.py ` + +.. literalinclude:: examples/simple_lp_example.py + :language: python + :linenos: + +The response is as follows: + +.. code-block:: text + + Optimal solution found in 0.01 seconds + x = 10.0 + y = 0.0 + Objective value = 10.0 + + +.. _simple-qp-example-python: + +Simple Quadratic Programming Example +------------------------------------ + +:download:`simple_qp_example.py ` + +.. literalinclude:: examples/simple_qp_example.py + :language: python + :linenos: + +The response is as follows: + +.. code-block:: text + + Optimal solution found in 0.01 seconds + x = 0.5 + y = 0.5 + Objective value = 0.5 + + +Advanced Example: Production Planning +------------------------------------- + +:download:`production_planning_example.py ` + +.. literalinclude:: examples/production_planning_example.py + :language: python + :linenos: + +The response is as follows: + +.. code-block:: text + + === Production Planning Solution === + + Status: Optimal + Solve time: 0.09 seconds + Product A production: 36.0 units + Product B production: 28.000000000000004 units + Total profit: $2640.00 + +Working with Expressions and Constraints +---------------------------------------- + +:download:`expressions_constraints_example.py ` + +.. literalinclude:: examples/expressions_constraints_example.py + :language: python + :linenos: + +The response is as follows: + +.. code-block:: text + + === Expression Example Results === + x = 0.0 + y = 50.0 + z = 99.99999999999999 + Objective value = 399.99999999999994 + +Working with Quadratic objective matrix +--------------------------------------- + +:download:`qp_matrix_example.py ` + +.. literalinclude:: examples/qp_matrix_example.py + :language: python + :linenos: + +The response is as follows: + +.. code-block:: text + + Optimal solution found in 0.16 seconds + p1 = 30.770728122083014 + p2 = 65.38350784293876 + p3 = 53.84576403497824 + Minimized cost = 1153.8461538953868 + +Inspecting the Problem Solution +------------------------------- + +:download:`solution_example.py ` + +.. literalinclude:: examples/solution_example.py + :language: python + :linenos: + +The response is as follows: + +.. code-block:: text + + Optimal solution found in 0.02 seconds + Objective: 9.0 + x = 1.0, ReducedCost = 0.0 + y = 3.0, ReducedCost = 0.0 + z = 0.0, ReducedCost = 2.999999858578644 + c1 DualValue = 1.0000000592359144 + c2 DualValue = 1.0000000821854418 + +Working with PDLP Warmstart Data +-------------------------------- + +Warmstart data allows to restart PDLP with a previous solution context. This should be used when you solve a new problem which is similar to the previous one. + +.. note:: + Warmstart data is only available for Linear Programming (LP) problems, not for Mixed Integer Linear Programming (MILP) problems. + +:download:`pdlp_warmstart_example.py ` + +.. literalinclude:: examples/pdlp_warmstart_example.py + :language: python + :linenos: + +The response is as follows: + +.. code-block:: text + + Optimal solution found in 0.01 seconds + x = 25.000000000639382 + y = 0.0 + Objective value = 50.000000001278764 diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/index.rst b/docs/cuopt/source/cuopt-python/lp-qp-milp/index.rst index eff941e763..8967f82a22 100644 --- a/docs/cuopt/source/cuopt-python/lp-qp-milp/index.rst +++ b/docs/cuopt/source/cuopt-python/lp-qp-milp/index.rst @@ -1,14 +1,22 @@ -============================================================================================================= -Linear Programming, Quadratic Programming, Mixed Integer Linear Programming, and Second-Order Cone Programming -============================================================================================================= +Continuous Optimization and MIP Python API +========================================== -This section contains details on the cuOpt linear programming, quadratic programming, mixed integer linear programming, and second-order cone programming Python API. +This section contains details on the cuOpt LP/QP/SOCP/MILP Python API. .. toctree:: :maxdepth: 3 - :caption: LP, QP, MILP, and SOCP - :name: LP, QP, MILP, and SOCP + :caption: Continuous Optimization (LP/QP/SOCP) + :name: LP/QP/SOCP Python API :titlesonly: - lp-qp-milp-api.rst - lp-qp-milp-examples.rst + continuous-api.rst + continuous-examples.rst + +.. toctree:: + :maxdepth: 3 + :caption: Mixed Integer Programming (MIP) + :name: MIP Python API + :titlesonly: + + mip-api.rst + mip-examples.rst diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/mip-api.rst b/docs/cuopt/source/cuopt-python/lp-qp-milp/mip-api.rst new file mode 100644 index 0000000000..c84707a2f7 --- /dev/null +++ b/docs/cuopt/source/cuopt-python/lp-qp-milp/mip-api.rst @@ -0,0 +1,26 @@ +================ +MIP API Reference +================ + +MIP uses the same Python API classes as LP/QP/SOCP — see :doc:`continuous-api` for the full class reference. The following are particularly relevant for MIP problems. + +Variable Types +-------------- + +Use :class:`~cuopt.linear_programming.problem.VType` to declare integer and semi-continuous variables: + +.. autoclass:: cuopt.linear_programming.problem.VType + :members: + :member-order: bysource + :undoc-members: + :exclude-members: capitalize, casefold, center, count, encode, endswith, expandtabs, find, format, format_map, index, isalnum, isalpha, isascii, isdecimal, isdigit, isidentifier, islower, isnumeric, isprintable, isspace, istitle, isupper, join, ljust, lower, lstrip, maketrans, partition, removeprefix, removesuffix, replace, rfind, rindex, rjust, rpartition, rsplit, rstrip, split, splitlines, startswith, strip, swapcase, title, translate, upper, zfill + +MIP Start +--------- + +:class:`~cuopt.linear_programming.problem.Problem` supports providing initial feasible solutions (MIP starts) to help the solver find good solutions faster. Use ``Problem.addMIPStart`` to add one or more primal solution hints before calling ``solve()``. + +MIP Solution Callbacks +----------------------- + +:class:`~cuopt.linear_programming.solver_settings.SolverSettings` supports callbacks to monitor incumbent solutions found during the MIP solve. Use ``SolverSettings.set_mip_solution_callback`` to register a callback that receives each new incumbent solution. diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/mip-examples.rst b/docs/cuopt/source/cuopt-python/lp-qp-milp/mip-examples.rst new file mode 100644 index 0000000000..a0e7b56644 --- /dev/null +++ b/docs/cuopt/source/cuopt-python/lp-qp-milp/mip-examples.rst @@ -0,0 +1,78 @@ +============ +MIP Examples +============ + +This section contains examples of how to use the cuOpt MIP Python API. + +.. note:: + + The examples in this section are not exhaustive. They are provided to help you get started with the cuOpt mixed integer linear programming Python API. For more examples, please refer to the `cuopt-examples GitHub repository `_. + + +Mixed Integer Linear Programming Example +---------------------------------------- + +:download:`simple_milp_example.py ` + +.. literalinclude:: examples/simple_milp_example.py + :language: python + :linenos: + +The response is as follows: + +.. code-block:: text + + Optimal solution found in 0.00 seconds + x = 36.0 + y = 40.99999999999999 + Objective value = 303.0 + + +Semi-continuous Variable Example +-------------------------------- + +:download:`semi_continuous_example.py ` + +.. literalinclude:: examples/semi_continuous_example.py + :language: python + :linenos: + +The response is as follows: + +.. code-block:: text + + Optimal solution found in 0.00 seconds + x = 0.0 + y = 1.0 + Objective value = 0.0 + + +Working with Incumbent Solutions +-------------------------------- + +Incumbent solutions are intermediate feasible solutions found during the MIP solving process. They represent the best integer-feasible solution discovered so far and can be accessed through callback functions. + +.. note:: + Incumbent solutions are only available for Mixed Integer Programming (MIP) problems, not for pure Linear Programming (LP) problems. + +:download:`incumbent_solutions_example.py ` + +.. literalinclude:: examples/incumbent_solutions_example.py + :language: python + :linenos: + +The response is as follows: + +.. code-block:: text + + Optimal solution found. + Incumbent 1: x=36.0 y=41.0 cost: 303.00 + Solution objective: 303.000000 , relative_mip_gap 0.000000 solution_bound 303.000000 presolve_time 0.103659 total_solve_time 0.173678 max constraint violation 0.000000 max int violation 0.000000 max var bounds violation 0.000000 nodes 0 simplex_iterations 2 + + === Final Results === + Problem status: Optimal + Solve time: 0.17 seconds + Final solution: x=36.0 y=41.0 + Final objective value: 303.00 + + Total incumbent solutions found: 1 diff --git a/docs/cuopt/source/cuopt-server/examples/lp-examples.rst b/docs/cuopt/source/cuopt-server/examples/lp-examples.rst index 964d99680c..9dd1483732 100644 --- a/docs/cuopt/source/cuopt-server/examples/lp-examples.rst +++ b/docs/cuopt/source/cuopt-server/examples/lp-examples.rst @@ -274,7 +274,7 @@ Use a :class:`~cuopt.linear_programming.data_model.DataModel` built with :func:`~cuopt.linear_programming.io.Read` as input to ``get_LP_solve``; the client dispatches on the file extension (``.mps`` / ``.qps`` vs ``.lp``, including ``.gz`` / ``.bz2`` compressed variants). For solver settings see -:doc:`LP/QP/MILP parameters <../../lp-qp-milp-settings>`. +:doc:`LP/QP/SOCP parameters <../../continuous-settings>` and :doc:`MIP parameters <../../mip-settings>`. MPS format ~~~~~~~~~~ @@ -431,7 +431,7 @@ In the case of batch mode, you can send a bunch of ``mps`` files at once, and ac .. note:: LP batch mode is deprecated; see :ref:`Batch Mode ` in - :doc:`../../lp-qp-features`. + :doc:`../../continuous-features`. .. note:: Batch mode is not available for MILP problems. diff --git a/docs/cuopt/source/cuopt-server/server-api/index.rst b/docs/cuopt/source/cuopt-server/server-api/index.rst index 23340843ba..ce17698dcb 100644 --- a/docs/cuopt/source/cuopt-server/server-api/index.rst +++ b/docs/cuopt/source/cuopt-server/server-api/index.rst @@ -12,4 +12,5 @@ This section contains details on Server options supported and open-api specifica server-cli.rst ../../open-api.rst - ../../lp-qp-milp-settings.rst + ../../continuous-settings.rst + ../../mip-settings.rst diff --git a/docs/cuopt/source/faq.rst b/docs/cuopt/source/faq.rst index 69a34dc179..02f38a0f4c 100644 --- a/docs/cuopt/source/faq.rst +++ b/docs/cuopt/source/faq.rst @@ -366,7 +366,7 @@ Linear Programming FAQs .. dropdown:: How small and how many problems can I give when using the batch mode? LP batch mode is deprecated; see :ref:`Batch Mode ` in - :doc:`lp-qp-features`. + :doc:`continuous-features`. The batch mode allows solving many LPs in parallel to try to fully utilize the GPU when LP problems are too small. Using H100 SXM, the problem should be of at least 1K elements, and giving more than 100 LPs will usually not increase performance. diff --git a/docs/cuopt/source/index.rst b/docs/cuopt/source/index.rst index 6f8ae3ba2c..7ec6e3335b 100644 --- a/docs/cuopt/source/index.rst +++ b/docs/cuopt/source/index.rst @@ -19,7 +19,7 @@ NVIDIA cuOpt :name: Features routing-features.rst - lp-qp-features.rst + continuous-features.rst milp-features.rst ========================== diff --git a/docs/cuopt/source/mip-settings.rst b/docs/cuopt/source/mip-settings.rst new file mode 100644 index 0000000000..f767aaf4d9 --- /dev/null +++ b/docs/cuopt/source/mip-settings.rst @@ -0,0 +1,369 @@ +============ +MIP Settings +============ + + +This page describes the parameter settings available for cuOpt's MIP solver. These parameters are set as :ref:`parameter constants ` in case of C API and in case of Server Thin client as raw strings. Please refer to examples in :doc:`C ` and :doc:`Server Thin client ` for more details. + +.. note:: + When setting parameters in thin client solver settings, remove ``CUOPT_`` from the parameter name and convert to lowercase. For example, ``CUOPT_TIME_LIMIT`` would be set as ``time_limit``. + +Common Parameters +----------------- + +We begin by describing parameters common to both the MILP and LP solvers + + +Time Limit +^^^^^^^^^^ +``CUOPT_TIME_LIMIT`` controls the time limit in seconds after which the solver will stop and return the current solution. +For performance reasons, cuOpt does not constantly checks for time limit. Thus, the solver +may run slightly over the limit. If set along with the iteration limit, cuOpt will stop when +the first limit (iteration or time) is hit. + + +.. note:: By default there is no time limit. So cuOpt will run until it finds an optimal solution, + or proves the problem is infeasible or unbounded. + + + +Log to Console +^^^^^^^^^^^^^^ +``CUOPT_LOG_TO_CONSOLE`` controls whether cuOpt should log information to the console during a solve. +If true, a logging info is written to the console, if false no logging info is written to the console (logs may still be written to a file.) + +.. note:: The default value is true. + +Log File +^^^^^^^^ +``CUOPT_LOG_FILE`` controls the name of a log file where cuOpt should write information about the solve. + +.. note:: The default value is ``""`` and no log file is written. This setting is ignored by the cuOpt service, use the log callback feature instead. + +Solution File +^^^^^^^^^^^^^ +``CUOPT_SOLUTION_FILE`` controls the name of a file where cuOpt should write the solution. + +.. note:: The default value is ``""`` and no solution file is written. This setting is ignored by the cuOpt service. + +User Problem File +^^^^^^^^^^^^^^^^^ +``CUOPT_USER_PROBLEM_FILE`` controls the name of a file where cuOpt should write the user problem. + +.. note:: The default value is ``""`` and no user problem file is written. This setting is ignored by the cuOpt service. + +Num CPU Threads +^^^^^^^^^^^^^^^ +``CUOPT_NUM_CPU_THREADS`` controls the number of CPU threads used in the LP and MIP solvers. Set this to a small value to limit +the amount of CPU resources cuOpt uses. Set this to a large value to improve solve times for CPU +parallel parts of the solvers. + +.. note:: By default the number of CPU threads is automatically determined based on the number of CPU cores. + +Presolve +^^^^^^^^ +``CUOPT_PRESOLVE`` controls which presolver to use for presolve reductions. +cuOpt provides presolve reductions for linear programming (LP) problems using either PSLP or Papilo, and for mixed-integer programming (MIP) problems using Papilo. By default, Papilo presolve is always enabled for MIP problems. For LP problems, PSLP presolve is always enabled by default. You can explicitly control the presolver by setting this parameter to 0 (disable presolve), 1 (Papilo), or 2 (PSLP). + +Probing +^^^^^^^ +``CUOPT_MIP_PROBING`` toggles the probing-cache step of cuOpt's internal MIP presolve. The probing pass evaluates variable fixings to discover implications used later by branch-and-bound and the rounding heuristics. It is enabled by default (``true``); set it to ``false`` to skip probing while leaving the rest of presolve in place. Setting ``CUOPT_PRESOLVE=0`` already turns off the entire presolve pipeline, so ``CUOPT_MIP_PROBING`` only matters when presolve is otherwise enabled. Probing is also skipped in deterministic mode and on LP-only solves. + +Dual Postsolve +^^^^^^^^^^^^^^ +``CUOPT_DUAL_POSTSOLVE`` controls whether dual postsolve is enabled when using Papilo presolver for LP problems. Disabling dual postsolve can improve solve time at the expense of not having +access to the dual solution. Enabled by default for LP when Papilo presolve is selected. This is not relevant for MIP problems. + +Mixed Integer Linear Programming +--------------------------------- + +We now describe parameter settings for the MILP solvers + + +Heuristics only +^^^^^^^^^^^^^^^ + +``CUOPT_MIP_HEURISTICS_ONLY`` controls if only the GPU heuristics should be run for the MIP problem. When set to true, only the primal +bound is improved via the GPU. When set to false, both the GPU and CPU are used and +the dual bound is improved on the CPU. + +.. note:: The default value is false. + +Scaling +^^^^^^^ + +``CUOPT_MIP_SCALING`` controls if scaling should be applied to the MIP problem. + +* ``0``: Scaling is off. +* ``1``: Scaling is on. +* ``2``: Scaling is not applied to the objective (default). + +Absolute Tolerance +^^^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_ABSOLUTE_TOLERANCE`` controls the MIP absolute tolerance. + +.. note:: The default value is ``1e-6``. + +Relative Tolerance +^^^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_RELATIVE_TOLERANCE`` controls the MIP relative tolerance. + +.. note:: The default value is ``1e-12``. + + +Integrality Tolerance +^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_INTEGRALITY_TOLERANCE`` controls the MIP integrality tolerance. A variable is considered to be integral, if +it is within the integrality tolerance of an integer. + +.. note:: The default value is ``1e-5``. + +Absolute MIP Gap +^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_ABSOLUTE_GAP`` controls the absolute tolerance used to terminate the MIP solve. The solve terminates when:: + + Best Objective - Dual Bound <= absolute tolerance + +when minimizing or + + Dual Bound - Best Objective <= absolute tolerance + +when maximizing. + +.. note:: The default value is ``1e-10``. + +Relative MIP Gap +^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_RELATIVE_GAP`` controls the relative tolerance used to terminate the MIP solve. The solve terminates when:: + + abs(Best Objective - Dual Bound) / abs(Best Objective) <= relative tolerance + +If the Best Objective and the Dual Bound are both zero the gap is zero. If the best objective value is zero, the +gap is infinity. + +.. note:: The default value is ``1e-4``. + + +Node Limit +^^^^^^^^^^ + +``CUOPT_NODE_LIMIT`` controls the maximum number of branch-and-bound nodes the MILP solver will explore before stopping and returning the current best feasible solution (if any). If set along with the time limit, cuOpt stops at whichever limit is hit first. + +.. note:: By default there is no node limit. The setting only affects MILP; + it is ignored for LP and QP. + +Cut Passes +^^^^^^^^^^ + +``CUOPT_MIP_CUT_PASSES`` controls the number of cut passes to run. Set this value to 0 to disable cuts. Set this value to larger numbers to perform more cut passes. + +.. note:: The default value is ``10``. + +Mixed Integer Rounding Cuts +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_MIXED_INTEGER_ROUNDING_CUTS`` controls whether to use mixed integer rounding cuts. +The default value of ``-1`` (automatic) means that the solver will decide whether to use mixed integer rounding cuts based on the problem characteristics. +Set this value to 1 to enable mixed integer rounding cuts. +Set this value to 0 to disable mixed integer rounding cuts. + +.. note:: The default value is ``-1`` (automatic). + +Mixed Integer Gomory Cuts +^^^^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_MIXED_INTEGER_GOMORY_CUTS`` controls whether to use mixed integer Gomory cuts. +The default value of ``-1`` (automatic) means that the solver will decide whether to use mixed integer Gomory cuts based on the problem characteristics. +Set this value to 1 to enable mixed integer Gomory cuts. +Set this value to 0 to disable mixed integer Gomory cuts. + +.. note:: The default value is ``-1`` (automatic). + +Strong Chvatal-Gomory Cuts +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_STRONG_CHVATAL_GOMORY_CUTS`` controls whether to use strong Chvatal-Gomory cuts. +The default value of ``-1`` (automatic) means that the solver will decide whether to use strong Chvatal-Gomory cuts based on the problem characteristics. +Set this value to 1 to enable strong Chvatal Gomory cuts. +Set this value to 0 to disable strong Chvatal Gomory cuts. + +.. note:: The default value is ``-1`` (automatic). + +Knapsack Cuts +^^^^^^^^^^^^^ + +``CUOPT_MIP_KNAPSACK_CUTS`` controls whether to use knapsack cuts. +The default value of ``-1`` (automatic) means that the solver will decide whether to use knapsack cuts based on the problem characteristics. +Set this value to 1 to enable knapsack cuts. +Set this value to 0 to disable knapsack cuts. + +.. note:: The default value is ``-1`` (automatic). + + +Cut Change Threshold +^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_CUT_CHANGE_THRESHOLD`` controls the threshold for the improvement in the dual bound per cut pass. +Larger values require the dual bound to improve significantly in each cut pass. +Set this value to 0 to allow the cut passes to continue even if the dual bound does not improve. + +.. note:: The default value is ``1e-3``. + +Cut Min Orthogonality +^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_CUT_MIN_ORTHOGONALITY`` controls the minimum orthogonality required for a cut to be added to the LP relaxation. +Set this value close to 1, to require all cuts be close to orthogonal to each other. +Set this value close to zero to allow more cuts to be added to the LP relaxation. + +.. note:: The default value is ``0.5``. + +Reduced Cost Strengthening +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_REDUCED_COST_STRENGTHENING`` controls whether to use reduced-cost strengthening. +When enabled, the solver will use integer feasible solutions to strengthen the bounds of integer variables. +The default value of ``-1`` (automatic) means that the solver will decide whether to use reduced-cost strengthening based on the problem characteristics. +Set this value to 0 to disable reduced-cost strengthening. +Set this value to 1 to perform reduced-cost strengthening during the root cut passes. +Set this value to 2 to perform reduced-cost strengthening during the root cut passes and after strong branching. + +.. note:: The default value is ``-1`` (automatic). + +Reliability Branching +^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_RELIABILITY_BRANCHING`` controls the reliability branching mode. +The default value of ``-1`` (automatic) means that the solver will decide whether to use reliability branching, and the reliability branching factor, based on the problem characteristics. +Set this value to 0 to disable reliability branching. +Set this value to k > 0, to enable reliability branching. A variable will be considered reliable if it has been branched on k times. + +.. note:: The default value is ``-1`` (automatic). + +Batch PDLP Strong Branching +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_BATCH_PDLP_STRONG_BRANCHING`` controls whether to use batched PDLP over Dual Simplex during strong branching at the root. +When enabled, the solver evaluates multiple branching candidates simultaneously in a single batched PDLP solve rather than solving them in parallel using Dual Simplex. This can significantly reduce the time spent in strong branching if Dual Simplex is struggling. +Set this value to 0 to disable batched PDLP strong branching. +Set this value to 1 to enable batched PDLP strong branching. + +.. note:: The default value is ``0`` (disabled). This setting is ignored if the problem is not a MIP problem. + +Batch PDLP Reliability Branching +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_BATCH_PDLP_RELIABILITY_BRANCHING`` controls whether to use batched PDLP for reliability branching evaluations. +When enabled, candidate variables for reliability branching are evaluated simultaneously using a single batched PDLP solve. +Set this value to 0 to disable. +Set this value to 1 to enable. + +.. note:: The default value is ``0`` (disabled). + +Strong Branching Simplex Iteration Limit +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_STRONG_BRANCHING_SIMPLEX_ITERATION_LIMIT`` controls the maximum number of simplex iterations allowed per candidate during strong branching. +Reducing this value speeds up strong branching at the cost of less accurate candidate evaluations. + +.. note:: By default there is no iteration limit for strong branching solves. + +MIP Determinism Mode +^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_DETERMINISM_MODE`` controls whether the MIP solver runs in opportunistic or deterministic mode. + +* ``0`` (``CUOPT_MODE_OPPORTUNISTIC``): Opportunistic mode — results may vary between runs due to parallelism (default). +* ``1`` (``CUOPT_MODE_DETERMINISTIC``): Deterministic mode — improves reproducibility across runs with the same number of threads. + +.. note:: The default value is ``0`` (opportunistic). + +.. warning:: Deterministic mode is experimental. It improves reproducibility in many cases but does not yet guarantee fully deterministic results in all scenarios. + +MIP Symmetry +^^^^^^^^^^^^^ + +``CUOPT_MIP_SYMMETRY`` controls symmetry detection and handling in the MIP solver. + +* ``-1``: Automatic (default) — cuOpt decides based on problem characteristics. +* ``0``: Disable symmetry handling. +* ``1``: Enable symmetry handling. + +.. note:: The default value is ``-1`` (automatic). + +Flow Cover Cuts +^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_FLOW_COVER_CUTS`` controls whether to use flow cover cuts. +Set this value to ``-1`` (automatic) to let the solver decide. +Set this value to ``0`` to disable flow cover cuts. +Set this value to ``1`` to enable flow cover cuts. + +.. note:: The default value is ``-1`` (automatic). + +Implied Bound Cuts +^^^^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_IMPLIED_BOUND_CUTS`` controls whether to use implied bound cuts. +Set this value to ``-1`` (automatic) to let the solver decide. +Set this value to ``0`` to disable implied bound cuts. +Set this value to ``1`` to enable implied bound cuts. + +.. note:: The default value is ``-1`` (automatic). + +Clique Cuts +^^^^^^^^^^^^ + +``CUOPT_MIP_CLIQUE_CUTS`` controls whether to use clique cuts. +Set this value to ``-1`` (automatic) to let the solver decide. +Set this value to ``0`` to disable clique cuts. +Set this value to ``1`` to enable clique cuts. + +.. note:: The default value is ``-1`` (automatic). + +Objective Step +^^^^^^^^^^^^^^^ + +``CUOPT_MIP_OBJECTIVE_STEP`` controls whether cuOpt automatically detects and exploits discrete step structure in the objective to tighten the dual bound. +When all integer variables have integer objective coefficients, the objective value can only change in multiples of a known step size; enabling this setting allows cuOpt to use that information to close the gap faster. + +* ``0``: Disable objective step detection. +* ``1``: Enable objective step detection (default). + +.. note:: The default value is ``1`` (enabled). + +Semi-Continuous Big-M +^^^^^^^^^^^^^^^^^^^^^^ + +``CUOPT_MIP_SEMICONTINUOUS_BIG_M`` controls the Big-M coefficient used when linearizing semi-continuous variable constraints. +A semi-continuous variable is either zero or takes a value in the range ``[lower_bound, upper_bound]``. +Set this to a positive value that is at least as large as the upper bound of any semi-continuous variable in the problem. + +.. note:: By default cuOpt derives the Big-M from the variable's upper bound. + +Work Limit +^^^^^^^^^^ + +``CUOPT_WORK_LIMIT`` controls the work limit after which the solver will stop and return the current solution. +Work units are a machine-independent measure of solver effort. If set along with the time limit or iteration limit, cuOpt will stop when the first limit is hit. + +.. note:: By default there is no work limit. + +Random Seed +^^^^^^^^^^^^ + +``CUOPT_RANDOM_SEED`` controls the random seed used by the solver. Setting a fixed seed enables reproducible results when running in deterministic mode. + +.. note:: By default the random seed is set automatically. + +Presolve File +^^^^^^^^^^^^^^ + +``CUOPT_PRESOLVE_FILE`` controls the name of a file where cuOpt should write presolve information. + +.. note:: The default value is ``""`` and no presolve file is written. diff --git a/docs/cuopt/source/transition.rst b/docs/cuopt/source/transition.rst index 3c6e0aa9c6..3a92982609 100644 --- a/docs/cuopt/source/transition.rst +++ b/docs/cuopt/source/transition.rst @@ -16,7 +16,7 @@ Parameter/option statuses are listed below, they express how each of these optio **Removed** - These features were deprecated in a previous release and completely removed in this one. -For all solver_configs fields, see the LP/QP/MILP settings guide :doc:`lp-qp-milp-settings` or the service openapi spec :doc:`open-api`. +For all solver_configs fields, see the :doc:`continuous-settings` and :doc:`mip-settings` guides or the service openapi spec :doc:`open-api`. Changes to solver_configs.tolerances ------------------------------------ From 3b3df2ea700eb1db5c1f2b599afdb89c44e65c72 Mon Sep 17 00:00:00 2001 From: Rajesh Gandham Date: Fri, 29 May 2026 16:26:13 -0400 Subject: [PATCH 07/13] Fix Python index title underline and remove old combined doc files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../cuopt-c/lp-qp-milp/lp-qp-example.rst | 214 ------ .../cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rst | 380 ---------- .../cuopt-c/lp-qp-milp/milp-examples.rst | 162 ---- .../source/cuopt-python/lp-qp-milp/index.rst | 2 +- .../lp-qp-milp/lp-qp-milp-api.rst | 52 -- .../lp-qp-milp/lp-qp-milp-examples.rst | 221 ------ docs/cuopt/source/lp-qp-features.rst | 225 ------ docs/cuopt/source/lp-qp-milp-settings.rst | 705 ------------------ 8 files changed, 1 insertion(+), 1960 deletions(-) delete mode 100644 docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-example.rst delete mode 100644 docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rst delete mode 100644 docs/cuopt/source/cuopt-c/lp-qp-milp/milp-examples.rst delete mode 100644 docs/cuopt/source/cuopt-python/lp-qp-milp/lp-qp-milp-api.rst delete mode 100644 docs/cuopt/source/cuopt-python/lp-qp-milp/lp-qp-milp-examples.rst delete mode 100644 docs/cuopt/source/lp-qp-features.rst delete mode 100644 docs/cuopt/source/lp-qp-milp-settings.rst diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-example.rst b/docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-example.rst deleted file mode 100644 index d4b981719c..0000000000 --- a/docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-example.rst +++ /dev/null @@ -1,214 +0,0 @@ -==================== -LP/QP C API Examples -==================== - - -Example With Data ------------------ - -This example demonstrates how to use the LP solver in C. More details on the API can be found in :doc:`C API `. - -The example code is available at ``examples/cuopt-c/lp/simple_lp_example.c`` (:download:`download `): - -.. literalinclude:: examples/simple_lp_example.c - :language: c - :linenos: - -It is necessary to have the path for include and library dirs ready, if you know the paths, please add them to the path variables directly. Otherwise, run the following commands to find the path and assign it to the path variables. -The following commands are for Linux and might fail in cases where the cuopt library is not installed or there are multiple cuopt libraries in the system. - -If you have built it locally, libcuopt.so will be in the build directory ``cpp/build`` and include directoy would be ``cpp/include``. - -.. code-block:: bash - - # Find the cuopt header file and assign to INCLUDE_PATH - INCLUDE_PATH=$(find / -name "cuopt_c.h" -path "*/linear_programming/*" -printf "%h\n" | sed 's/\/linear_programming//' 2>/dev/null) - # Find the libcuopt library and assign to LIBCUOPT_LIBRARY_PATH - LIBCUOPT_LIBRARY_PATH=$(find / -name "libcuopt.so" 2>/dev/null) - - -Build and run the example - -.. code-block:: bash - - # Build and run the example - gcc -I $INCLUDE_PATH -L $LIBCUOPT_LIBRARY_PATH -o simple_lp_example simple_lp_example.c -lcuopt - ./simple_lp_example - - - -You should see the following output: - -.. code-block:: bash - :caption: Output - - Creating and solving simple LP problem... - Solving a problem with 2 constraints 2 variables (0 integers) and 4 nonzeros - Objective offset 0.000000 scaling_factor 1.000000 - Running concurrent - - Dual simplex finished in 0.00 seconds - Iter Primal Obj. Dual Obj. Gap Primal Res. Dual Res. Time - 0 +0.00000000e+00 +0.00000000e+00 0.00e+00 0.00e+00 2.00e-01 0.011s - PDLP finished - Concurrent time: 0.013s - Solved with dual simplex - Status: Optimal Objective: -3.60000000e-01 Iterations: 1 Time: 0.013s - - Results: - -------- - Termination status: Optimal (1) - Solve time: 0.000013 seconds - Objective value: -0.360000 - - Primal Solution: Solution variables - x1 = 1.800000 - x2 = 0.000000 - - Test completed successfully! - - -Example With MPS File ---------------------- - -This example demonstrates how to use the cuOpt linear programming solver in C to solve an MPS file. - -The same ``cuOptReadProblem`` call also accepts **LP** format files. The -format is dispatched from the filename extension (case-insensitive): -``.lp`` / ``.lp.gz`` / ``.lp.bz2`` → LP parser; ``.mps`` / ``.qps`` and -their ``.gz`` / ``.bz2`` variants → MPS parser. Unknown extensions are -rejected. See :ref:`lp-file-example-c` for an LP counterpart. - -The example code is available at ``examples/cuopt-c/lp/mps_file_example.c`` (:download:`download `): - -.. literalinclude:: examples/mps_file_example.c - :language: c - :linenos: - -It is necessary to have the path for include and library dirs ready, if you know the paths, please add them to the path variables directly. Otherwise, run the following commands to find the path and assign it to the path variables. -The following commands are for Linux and might fail in cases where the cuopt library is not installed or there are multiple cuopt libraries in the system. - -If you have built it locally, libcuopt.so will be in the build directory ``cpp/build`` and include directoy would be ``cpp/include``. - -.. code-block:: bash - - # Find the cuopt header file and assign to INCLUDE_PATH - INCLUDE_PATH=$(find / -name "cuopt_c.h" -path "*/linear_programming/*" -printf "%h\n" | sed 's/\/linear_programming//' 2>/dev/null) - # Find the libcuopt library and assign to LIBCUOPT_LIBRARY_PATH - LIBCUOPT_LIBRARY_PATH=$(find / -name "libcuopt.so" 2>/dev/null) - -A sample MPS file (:download:`download sample.mps `): - -.. literalinclude:: examples/sample.mps - :language: text - :linenos: - -Build and run the example - -.. code-block:: bash - - # Build and run the example - gcc -I $INCLUDE_PATH -L $LIBCUOPT_LIBRARY_PATH -o mps_file_example mps_file_example.c -lcuopt - ./mps_file_example sample.mps - - -You should see the following output: - -.. code-block:: bash - :caption: Output - - Reading and solving MPS file: sample.mps - Solving a problem with 2 constraints 2 variables (0 integers) and 4 nonzeros - Objective offset 0.000000 scaling_factor 1.000000 - Running concurrent - - Dual simplex finished in 0.00 seconds - Iter Primal Obj. Dual Obj. Gap Primal Res. Dual Res. Time - 0 +0.00000000e+00 +0.00000000e+00 0.00e+00 0.00e+00 2.00e-01 0.012s - PDLP finished - Concurrent time: 0.014s - Solved with dual simplex - Status: Optimal Objective: -3.60000000e-01 Iterations: 1 Time: 0.014s - - Results: - -------- - Number of variables: 2 - Termination status: Optimal (1) - Solve time: 0.000014 seconds - Objective value: -0.360000 - - Primal Solution: First 10 solution variables (or fewer if less exist): - x1 = 1.800000 - x2 = 0.000000 - - Solver completed successfully! - - -.. _lp-file-example-c: - -Example With LP File --------------------- - -``cuOptReadProblem`` also accepts LP format files. The same function is -used — it dispatches on the file extension (case-insensitive): -``.lp`` / ``.lp.gz`` / ``.lp.bz2`` → LP parser; ``.mps`` / ``.qps`` and -their ``.gz`` / ``.bz2`` variants → MPS parser; unknown extensions are -rejected. See the ``read_lp`` declaration in -``cuopt/linear_programming/io/parser.hpp`` for the supported subset of -the LP format. - -The example code is available at ``examples/cuopt-c/lp/lp_file_example.c`` (:download:`download `): - -.. literalinclude:: examples/lp_file_example.c - :language: c - :linenos: - -A sample LP file (:download:`download sample.lp `), -equivalent to the MPS sample above: - -.. literalinclude:: examples/sample.lp - :language: text - :linenos: - -Build and run the example - -.. code-block:: bash - - gcc -I $INCLUDE_PATH -L $LIBCUOPT_LIBRARY_PATH -o lp_file_example lp_file_example.c -lcuopt - ./lp_file_example sample.lp - -The output matches the MPS example above (same problem, same objective = -0.36). - - -.. _simple-qp-example-c: - -Simple Quadratic Programming Example ------------------------------------- - -This example demonstrates how to use the cuOpt C API for quadratic programming. - -The example code is available at ``examples/cuopt-c/lp/simple_qp_example.c`` (:download:`download `): - -.. literalinclude:: examples/simple_qp_example.c - :language: c - :linenos: - -Build and run the example - -.. code-block:: bash - - # Build and run the example - gcc -I $INCLUDE_PATH -L $LIBCUOPT_LIBRARY_PATH -o simple_qp_example simple_qp_example.c -lcuopt - ./simple_qp_example - -You should see the following output: - -.. code-block:: bash - :caption: Output - - Creating and solving simple QP problem... - Status: Optimal - Objective value: 0.500000 - x = 0.500000 - y = 0.500000 - Test completed successfully! diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rst b/docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rst deleted file mode 100644 index f4e7aaf0aa..0000000000 --- a/docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rst +++ /dev/null @@ -1,380 +0,0 @@ -cuOpt LP/QP/MILP C API Reference -======================================== - -This section contains the cuOpt LP/QP/MILP C API reference. - -Integer and Floating-Point Types ---------------------------------- - -cuOpt may be built with 32 or 64 bit integer and floating-point types. The C API uses a `typedef` for floating point and integer types to abstract the size of these types. - -.. doxygentypedef:: cuopt_int_t -.. doxygentypedef:: cuopt_float_t - -You may use the following functions to determine the number of bytes used to represent these types in your build - -.. doxygenfunction:: cuOptGetIntSize -.. doxygenfunction:: cuOptGetFloatSize - -Version Information -------------------- - -You may use the following function to get the version of the cuOpt library - -.. doxygenfunction:: cuOptGetVersion - -Status Codes ------------- - -Every function in the C API returns a status code that indicates success or failure. The following status codes are defined - -.. doxygendefine:: CUOPT_SUCCESS -.. doxygendefine:: CUOPT_INVALID_ARGUMENT -.. doxygendefine:: CUOPT_MPS_FILE_ERROR -.. doxygendefine:: CUOPT_MPS_PARSE_ERROR -.. doxygendefine:: CUOPT_VALIDATION_ERROR -.. doxygendefine:: CUOPT_OUT_OF_MEMORY -.. doxygendefine:: CUOPT_RUNTIME_ERROR - -Optimization Problem --------------------- - -An optimization problem is represented via a `cuOptOptimizationProblem` - -.. doxygentypedef:: cuOptOptimizationProblem - -Optimization problems can be created, loaded, or written via the following functions - -.. doxygenfunction:: cuOptReadProblem -.. doxygenfunction:: cuOptWriteProblem -.. doxygenfunction:: cuOptCreateProblem -.. doxygenfunction:: cuOptCreateRangedProblem -.. doxygenfunction:: cuOptCreateQuadraticProblem -.. doxygenfunction:: cuOptCreateQuadraticRangedProblem - -.. note:: - ``cuOptCreateQuadraticProblem`` and ``cuOptCreateQuadraticRangedProblem`` are deprecated. - Prefer ``cuOptCreateProblem`` or ``cuOptCreateRangedProblem`` followed by - ``cuOptSetQuadraticObjective`` (and ``cuOptAddQuadraticConstraint`` for QCQP). - -For QP and QCQP/SOCP models, the quadratic objective and constraints may be specified -after creating a linear problem: - -.. doxygenfunction:: cuOptSetQuadraticObjective -.. doxygenfunction:: cuOptAddQuadraticConstraint - -.. note:: - ``cuOptAddQuadraticConstraint`` also enables **Second-Order Cone Programming (SOCP)** - support **(beta)**. When one or more quadratic constraints are present, cuOpt automatically - converts them to second-order cone form and selects the barrier solver. Only ``CUOPT_LESS_THAN`` - and ``CUOPT_GREATER_THAN`` sense is supported; equality quadratic constraints are not supported. - -A optimization problem must be destroyed with the following function - -.. doxygenfunction:: cuOptDestroyProblem - -Certain constants are needed to define an optimization problem. These constants are described below. - -Objective Sense Constants -------------------------- - -These constants are used to define the objective sense in the :c:func:`cuOptCreateProblem` and :c:func:`cuOptCreateRangedProblem` functions. - -.. doxygendefine:: CUOPT_MINIMIZE -.. doxygendefine:: CUOPT_MAXIMIZE - -Constraint Sense Constants --------------------------- - -These constants are used to define the constraint sense in the :c:func:`cuOptCreateProblem` and :c:func:`cuOptCreateRangedProblem` functions. - -.. doxygendefine:: CUOPT_LESS_THAN -.. doxygendefine:: CUOPT_GREATER_THAN -.. doxygendefine:: CUOPT_EQUAL - -Variable Type Constants ------------------------ - -These constants are used to define the the variable type in the :c:func:`cuOptCreateProblem` and :c:func:`cuOptCreateRangedProblem` functions. - -.. doxygendefine:: CUOPT_CONTINUOUS -.. doxygendefine:: CUOPT_INTEGER -.. doxygendefine:: CUOPT_SEMI_CONTINUOUS - -Infinity Constant ------------------ - -This constant may be used to represent infinity in the :c:func:`cuOptCreateProblem` and :c:func:`cuOptCreateRangedProblem` functions. - -.. doxygendefine:: CUOPT_INFINITY - -File Format Constants ---------------------- - -These constants are used to specify the output file format in :c:func:`cuOptWriteProblem`. - -.. doxygendefine:: CUOPT_FILE_FORMAT_MPS - -Querying an optimization problem --------------------------------- - -The following functions may be used to get information about an `cuOptimizationProblem` - -.. doxygenfunction:: cuOptGetNumConstraints -.. doxygenfunction:: cuOptGetNumVariables -.. doxygenfunction:: cuOptGetObjectiveSense -.. doxygenfunction:: cuOptGetObjectiveOffset -.. doxygenfunction:: cuOptGetObjectiveCoefficients -.. doxygenfunction:: cuOptGetNumNonZeros -.. doxygenfunction:: cuOptGetConstraintMatrix -.. doxygenfunction:: cuOptGetConstraintSense -.. doxygenfunction:: cuOptGetConstraintRightHandSide -.. doxygenfunction:: cuOptGetConstraintLowerBounds -.. doxygenfunction:: cuOptGetConstraintUpperBounds -.. doxygenfunction:: cuOptGetVariableLowerBounds -.. doxygenfunction:: cuOptGetVariableUpperBounds -.. doxygenfunction:: cuOptGetVariableTypes -.. doxygenfunction:: cuOptIsMIP - - -Solver Settings ---------------- - -Settings are used to configure the LP/MIP solvers. All settings are stored in a `cuOptSolverSettings` object. - - -.. doxygentypedef:: cuOptSolverSettings - -A `cuOptSolverSettings` object is created with `cuOptCreateSolverSettings` - -.. doxygenfunction:: cuOptCreateSolverSettings - -When you are done with a solve you should destroy a `cuOptSolverSettings` object with - -.. doxygenfunction:: cuOptDestroySolverSettings - - -Setting Parameters ------------------- -The following functions are used to set and get parameters. You can find more details on the available parameters in the :doc:`LP/MILP settings <../../lp-qp-milp-settings>` section. - -.. doxygenfunction:: cuOptSetParameter -.. doxygenfunction:: cuOptGetParameter -.. doxygenfunction:: cuOptSetIntegerParameter -.. doxygenfunction:: cuOptGetIntegerParameter -.. doxygenfunction:: cuOptSetFloatParameter -.. doxygenfunction:: cuOptGetFloatParameter - -.. _parameter-constants: - -Parameter Constants -------------------- - -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:`LP/MILP settings <../../lp-qp-milp-settings>` section. - -.. LP/MIP parameter string constants -.. doxygendefine:: CUOPT_ABSOLUTE_DUAL_TOLERANCE -.. doxygendefine:: CUOPT_RELATIVE_DUAL_TOLERANCE -.. doxygendefine:: CUOPT_ABSOLUTE_PRIMAL_TOLERANCE -.. doxygendefine:: CUOPT_RELATIVE_PRIMAL_TOLERANCE -.. doxygendefine:: CUOPT_ABSOLUTE_GAP_TOLERANCE -.. doxygendefine:: CUOPT_RELATIVE_GAP_TOLERANCE -.. doxygendefine:: CUOPT_INFEASIBILITY_DETECTION -.. doxygendefine:: CUOPT_STRICT_INFEASIBILITY -.. doxygendefine:: CUOPT_PRIMAL_INFEASIBLE_TOLERANCE -.. doxygendefine:: CUOPT_DUAL_INFEASIBLE_TOLERANCE -.. doxygendefine:: CUOPT_ITERATION_LIMIT -.. doxygendefine:: CUOPT_TIME_LIMIT -.. doxygendefine:: CUOPT_WORK_LIMIT -.. doxygendefine:: CUOPT_NODE_LIMIT -.. doxygendefine:: CUOPT_PDLP_SOLVER_MODE -.. doxygendefine:: CUOPT_METHOD -.. doxygendefine:: CUOPT_PER_CONSTRAINT_RESIDUAL -.. doxygendefine:: CUOPT_SAVE_BEST_PRIMAL_SO_FAR -.. doxygendefine:: CUOPT_FIRST_PRIMAL_FEASIBLE -.. doxygendefine:: CUOPT_LOG_FILE -.. doxygendefine:: CUOPT_MIP_ABSOLUTE_TOLERANCE -.. doxygendefine:: CUOPT_MIP_RELATIVE_TOLERANCE -.. doxygendefine:: CUOPT_MIP_INTEGRALITY_TOLERANCE -.. doxygendefine:: CUOPT_MIP_ABSOLUTE_GAP -.. doxygendefine:: CUOPT_MIP_RELATIVE_GAP -.. doxygendefine:: CUOPT_MIP_SCALING -.. doxygendefine:: CUOPT_MIP_HEURISTICS_ONLY -.. doxygendefine:: CUOPT_MIP_PRESOLVE -.. doxygendefine:: CUOPT_MIP_DETERMINISM_MODE -.. doxygendefine:: CUOPT_MIP_SYMMETRY -.. doxygendefine:: CUOPT_PRESOLVE -.. doxygendefine:: CUOPT_MIP_PROBING -.. doxygendefine:: CUOPT_LOG_TO_CONSOLE -.. doxygendefine:: CUOPT_CROSSOVER -.. doxygendefine:: CUOPT_FOLDING -.. doxygendefine:: CUOPT_AUGMENTED -.. doxygendefine:: CUOPT_DUALIZE -.. doxygendefine:: CUOPT_ORDERING -.. doxygendefine:: CUOPT_ELIMINATE_DENSE_COLUMNS -.. doxygendefine:: CUOPT_CUDSS_DETERMINISTIC -.. doxygendefine:: CUOPT_BARRIER_DUAL_INITIAL_POINT -.. doxygendefine:: CUOPT_BARRIER_ITERATIVE_REFINEMENT -.. doxygendefine:: CUOPT_BARRIER_STEP_SCALE -.. doxygendefine:: CUOPT_DUAL_POSTSOLVE -.. doxygendefine:: CUOPT_SOLUTION_FILE -.. doxygendefine:: CUOPT_NUM_CPU_THREADS -.. doxygendefine:: CUOPT_NUM_GPUS -.. doxygendefine:: CUOPT_USER_PROBLEM_FILE -.. doxygendefine:: CUOPT_PRESOLVE_FILE -.. doxygendefine:: CUOPT_RANDOM_SEED -.. doxygendefine:: CUOPT_PDLP_PRECISION -.. doxygendefine:: CUOPT_MIP_RELIABILITY_BRANCHING -.. doxygendefine:: CUOPT_MIP_CUT_PASSES -.. doxygendefine:: CUOPT_MIP_MIXED_INTEGER_ROUNDING_CUTS -.. doxygendefine:: CUOPT_MIP_MIXED_INTEGER_GOMORY_CUTS -.. doxygendefine:: CUOPT_MIP_KNAPSACK_CUTS -.. doxygendefine:: CUOPT_MIP_FLOW_COVER_CUTS -.. doxygendefine:: CUOPT_MIP_IMPLIED_BOUND_CUTS -.. doxygendefine:: CUOPT_MIP_CLIQUE_CUTS -.. doxygendefine:: CUOPT_MIP_STRONG_CHVATAL_GOMORY_CUTS -.. doxygendefine:: CUOPT_MIP_REDUCED_COST_STRENGTHENING -.. doxygendefine:: CUOPT_MIP_OBJECTIVE_STEP -.. doxygendefine:: CUOPT_MIP_CUT_CHANGE_THRESHOLD -.. doxygendefine:: CUOPT_MIP_CUT_MIN_ORTHOGONALITY -.. doxygendefine:: CUOPT_MIP_BATCH_PDLP_STRONG_BRANCHING -.. doxygendefine:: CUOPT_MIP_BATCH_PDLP_RELIABILITY_BRANCHING -.. doxygendefine:: CUOPT_MIP_STRONG_BRANCHING_SIMPLEX_ITERATION_LIMIT -.. doxygendefine:: CUOPT_MIP_SEMICONTINUOUS_BIG_M - -.. _pdlp-solver-mode-constants: - -PDLP Solver Mode Constants --------------------------- - -These constants are used to configure `CUOPT_PDLP_SOLVER_MODE` via :c:func:`cuOptSetIntegerParameter`. - -.. doxygendefine:: CUOPT_PDLP_SOLVER_MODE_STABLE1 -.. doxygendefine:: CUOPT_PDLP_SOLVER_MODE_STABLE2 -.. doxygendefine:: CUOPT_PDLP_SOLVER_MODE_STABLE3 -.. doxygendefine:: CUOPT_PDLP_SOLVER_MODE_METHODICAL1 -.. doxygendefine:: CUOPT_PDLP_SOLVER_MODE_FAST1 - -.. _pdlp-precision-constants: - -PDLP Precision Constants ------------------------- - -These constants are used to configure `CUOPT_PDLP_PRECISION` via :c:func:`cuOptSetIntegerParameter`. - -.. doxygendefine:: CUOPT_PDLP_DEFAULT_PRECISION -.. doxygendefine:: CUOPT_PDLP_SINGLE_PRECISION -.. doxygendefine:: CUOPT_PDLP_DOUBLE_PRECISION -.. doxygendefine:: CUOPT_PDLP_MIXED_PRECISION - -.. _method-constants: - -Method Constants ----------------- - -These constants are used to configure `CUOPT_METHOD` via :c:func:`cuOptSetIntegerParameter`. - -.. doxygendefine:: CUOPT_METHOD_CONCURRENT -.. doxygendefine:: CUOPT_METHOD_PDLP -.. doxygendefine:: CUOPT_METHOD_DUAL_SIMPLEX -.. doxygendefine:: CUOPT_METHOD_BARRIER -.. doxygendefine:: CUOPT_METHOD_UNSET - -.. _mip-determinism-mode-constants: - -MIP Determinism Mode Constants ------------------------------- - -These constants are used to configure `CUOPT_MIP_DETERMINISM_MODE` via :c:func:`cuOptSetIntegerParameter`. - -.. doxygendefine:: CUOPT_MODE_OPPORTUNISTIC -.. doxygendefine:: CUOPT_MODE_DETERMINISTIC - -.. _barrier-iterative-refinement-constants: - -Barrier Iterative Refinement Constants ---------------------------------------- - -These constants are used to configure `CUOPT_BARRIER_ITERATIVE_REFINEMENT` via :c:func:`cuOptSetIntegerParameter`. - -.. doxygendefine:: CUOPT_BARRIER_ITERATIVE_REFINEMENT_OFF -.. doxygendefine:: CUOPT_BARRIER_ITERATIVE_REFINEMENT_ON - - -Warm Start and MIP Start ------------------------- - -The following functions set initial solution hints for the solver. - -For LP problems solved with PDLP, primal and dual warm start vectors may be provided: - -.. doxygenfunction:: cuOptSetInitialPrimalSolution -.. doxygenfunction:: cuOptSetInitialDualSolution - -For MIP problems, one or more primal solution hints (MIP starts) may be provided: - -.. doxygenfunction:: cuOptAddMIPStart - -MIP Solution Callbacks ------------------------ - -The following callback types and functions allow monitoring and injecting solutions during a MIP solve. - -.. doxygentypedef:: cuOptMIPGetSolutionCallback -.. doxygentypedef:: cuOptMIPSetSolutionCallback - -.. doxygenfunction:: cuOptSetMIPGetSolutionCallback -.. doxygenfunction:: cuOptSetMIPSetSolutionCallback - - -Solving an LP or MIP --------------------- - -LP and MIP solves are performed by calling the `cuOptSolve` function - -.. doxygenfunction:: cuOptSolve - - -Solution --------- - -The output of a solve is a `cuOptSolution` object. - -.. doxygentypedef:: cuOptSolution - -The following functions may be used to access information from a `cuOptSolution` - -.. doxygenfunction:: cuOptGetTerminationStatus -.. doxygenfunction:: cuOptGetErrorStatus -.. doxygenfunction:: cuOptGetErrorString -.. doxygenfunction:: cuOptGetPrimalSolution -.. doxygenfunction:: cuOptGetObjectiveValue -.. doxygenfunction:: cuOptGetSolveTime -.. doxygenfunction:: cuOptGetMIPGap -.. doxygenfunction:: cuOptGetSolutionBound -.. doxygenfunction:: cuOptGetDualSolution -.. doxygenfunction:: cuOptGetDualObjectiveValue -.. doxygenfunction:: cuOptGetReducedCosts - -When you are finished with a `cuOptSolution` object you should destory it with - -.. doxygenfunction:: cuOptDestroySolution - -Termination Status Constants ----------------------------- - -These constants define the termination status received from the :c:func:`cuOptGetTerminationStatus` function. - -.. LP/MIP termination status constants -.. doxygendefine:: CUOPT_TERMINATION_STATUS_NO_TERMINATION -.. doxygendefine:: CUOPT_TERMINATION_STATUS_OPTIMAL -.. doxygendefine:: CUOPT_TERMINATION_STATUS_INFEASIBLE -.. doxygendefine:: CUOPT_TERMINATION_STATUS_UNBOUNDED -.. doxygendefine:: CUOPT_TERMINATION_STATUS_ITERATION_LIMIT -.. doxygendefine:: CUOPT_TERMINATION_STATUS_TIME_LIMIT -.. doxygendefine:: CUOPT_TERMINATION_STATUS_NUMERICAL_ERROR -.. doxygendefine:: CUOPT_TERMINATION_STATUS_PRIMAL_FEASIBLE -.. doxygendefine:: CUOPT_TERMINATION_STATUS_FEASIBLE_FOUND -.. doxygendefine:: CUOPT_TERMINATION_STATUS_CONCURRENT_LIMIT -.. doxygendefine:: CUOPT_TERMINATION_STATUS_WORK_LIMIT -.. doxygendefine:: CUOPT_TERMINATION_STATUS_UNBOUNDED_OR_INFEASIBLE diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/milp-examples.rst b/docs/cuopt/source/cuopt-c/lp-qp-milp/milp-examples.rst deleted file mode 100644 index a6d446d4b3..0000000000 --- a/docs/cuopt/source/cuopt-c/lp-qp-milp/milp-examples.rst +++ /dev/null @@ -1,162 +0,0 @@ -MILP C API Examples -=================== - - -Example With Data ------------------ - -This example demonstrates how to use the MILP solver in C. More details on the API can be found in :doc:`C API `. - -The example code is available at ``../lp-milp/examples/simple_milp_example.c`` (:download:`download `): - -.. literalinclude:: examples/simple_milp_example.c - :language: c - :linenos: - -It is necessary to have the path for include and library dirs ready, if you know the paths, please add them to the path variables directly. Otherwise, run the following commands to find the path and assign it to the path variables. -The following commands are for Linux and might fail in cases where the cuopt library is not installed or there are multiple cuopt libraries in the system. - -If you have built it locally, libcuopt.so will be in the build directory ``cpp/build`` and include directoy would be ``cpp/include``. - -.. code-block:: bash - - # Find the cuopt header file and assign to INCLUDE_PATH - INCLUDE_PATH=$(find / -name "cuopt_c.h" -path "*/linear_programming/*" -printf "%h\n" | sed 's/\/linear_programming//' 2>/dev/null) - # Find the libcuopt library and assign to LIBCUOPT_LIBRARY_PATH - LIBCUOPT_LIBRARY_PATH=$(find / -name "libcuopt.so" 2>/dev/null) - - -Build and run the example - -.. code-block:: bash - - # Build and run the example - gcc -I $INCLUDE_PATH -L $LIBCUOPT_LIBRARY_PATH -o simple_milp_example simple_milp_example.c -lcuopt - ./simple_milp_example - - - -You should see the following output: - -.. code-block:: bash - :caption: Output - - Creating and solving simple LP problem... - Solving a problem with 2 constraints 2 variables (1 integers) and 4 nonzeros - Objective offset 0.000000 scaling_factor 1.000000 - After trivial presolve updated 2 constraints 2 variables - Running presolve! - After trivial presolve updated 2 constraints 2 variables - Solving LP root relaxation - Scaling matrix. Maximum column norm 1.046542e+00 - Dual Simplex Phase 1 - Dual feasible solution found. - Dual Simplex Phase 2 - Iter Objective Primal Infeas Perturb Time - 1 -2.00000000e-01 1.46434160e+00 0.00e+00 0.00 - - Root relaxation solution found in 2 iterations and 0.00s - Root relaxation objective -2.00000000e-01 - - Optimal solution found at root node. Objective -2.0000000000000001e-01. Time 0.00. - B&B added a solution to population, solution queue size 0 with objective -0.2 - Solution objective: -0.200000 , relative_mip_gap 0.000000 solution_bound -0.200000 presolve_time 0.041144 total_solve_time 0.000000 max constraint violation 0.000000 max int violation 0.000000 max var bounds violation 0.000000 nodes 0 simplex_iterations 0 - - Results: - -------- - Termination status: Optimal (1) - Solve time: 0.000000 seconds - Objective value: -0.200000 - - Solution: - x1 = 1.000000 - x2 = 0.000000 - - Test completed successfully! - - -Example With MPS File ---------------------- - -This example demonstrates how to use the cuOpt solver in C to solve an MPS file. - -The example code is available at ``examples/milp_mps_example.c`` (:download:`download `): - -.. literalinclude:: examples/milp_mps_example.c - :language: c - :linenos: - -It is necessary to have the path for include and library dirs ready, if you know the paths, please add them to the path variables directly. Otherwise, run the following commands to find the path and assign it to the path variables. -The following commands are for Linux and might fail in cases where the cuopt library is not installed or there are multiple cuopt libraries in the system. - -If you have built it locally, libcuopt.so will be in the build directory ``cpp/build`` and include directoy would be ``cpp/include``. - -.. code-block:: bash - - # Find the cuopt header file and assign to INCLUDE_PATH - INCLUDE_PATH=$(find / -name "cuopt_c.h" -path "*/linear_programming/*" -printf "%h\n" | sed 's/\/linear_programming//' 2>/dev/null) - # Find the libcuopt library and assign to LIBCUOPT_LIBRARY_PATH - LIBCUOPT_LIBRARY_PATH=$(find / -name "libcuopt.so" 2>/dev/null) - -A sample MILP MPS file (:download:`download mip_sample.mps `): - -.. literalinclude:: examples/mip_sample.mps - :language: text - :linenos: - -Build and run the example - -.. code-block:: bash - - # Build and run the example - gcc -I $INCLUDE_PATH -L $LIBCUOPT_LIBRARY_PATH -o milp_mps_example milp_mps_example.c -lcuopt - ./milp_mps_example mip_sample.mps - - -You should see the following output: - -.. code-block:: bash - :caption: Output - - Reading and solving MPS file: sample.mps - Solving a problem with 3 constraints 2 variables (2 integers) and 6 nonzeros - Objective offset 0.000000 scaling_factor 1.000000 - After trivial presolve updated 3 constraints 2 variables - Running presolve! - After trivial presolve updated 3 constraints 2 variables - Solving LP root relaxation - Scaling matrix. Maximum column norm 1.225464e+00 - Dual Simplex Phase 1 - Dual feasible solution found. - Dual Simplex Phase 2 - Iter Objective Primal Infeas Perturb Time - 1 -3.04000000e+01 7.57868205e+00 0.00e+00 0.00 - - Root relaxation solution found in 3 iterations and 0.00s - Root relaxation objective -3.01818182e+01 - - Strong branching on 2 fractional variables - | Explored | Unexplored | Objective | Bound | Depth | Iter/Node | Gap | Time - 0 1 +inf -3.018182e+01 1 0.0e+00 - 0.00 - B 3 1 -2.700000e+01 -2.980000e+01 2 6.7e-01 10.4% 0.00 - B&B added a solution to population, solution queue size 0 with objective -27 - B 4 0 -2.800000e+01 -2.980000e+01 2 7.5e-01 6.4% 0.00 - B&B added a solution to population, solution queue size 1 with objective -28 - Explored 4 nodes in 0.00s. - Absolute Gap 0.000000e+00 Objective -2.8000000000000004e+01 Lower Bound -2.8000000000000004e+01 - Optimal solution found. - Generated fast solution in 0.136067 seconds with objective -28.000000 - Solution objective: -28.000000 , relative_mip_gap 0.000000 solution_bound -28.000000 presolve_time 0.039433 total_solve_time 0.000000 max constraint violation 0.000000 max int violation 0.000000 max var bounds violation 0.000000 nodes 4 simplex_iterations 3 - - Results: - -------- - Number of variables: 2 - Termination status: Optimal (1) - Solve time: 0.000000 seconds - Objective value: -28.000000 - - Solution: - x1 = 4.000000 - x2 = 0.000000 - - Solver completed successfully! diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/index.rst b/docs/cuopt/source/cuopt-python/lp-qp-milp/index.rst index 8967f82a22..7b928b408d 100644 --- a/docs/cuopt/source/cuopt-python/lp-qp-milp/index.rst +++ b/docs/cuopt/source/cuopt-python/lp-qp-milp/index.rst @@ -1,5 +1,5 @@ Continuous Optimization and MIP Python API -========================================== +============================================ This section contains details on the cuOpt LP/QP/SOCP/MILP Python API. diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/lp-qp-milp-api.rst b/docs/cuopt/source/cuopt-python/lp-qp-milp/lp-qp-milp-api.rst deleted file mode 100644 index 7af291d2ff..0000000000 --- a/docs/cuopt/source/cuopt-python/lp-qp-milp/lp-qp-milp-api.rst +++ /dev/null @@ -1,52 +0,0 @@ -============================= -LP, QP and MILP API Reference -============================= - -.. autoclass:: cuopt.linear_programming.problem.Problem - :members: - :undoc-members: - :exclude-members: reset_solved_values, populate_solution, dict_to_object, get_incumbent_values, get_pdlp_warm_start_data, getQcsr - -.. autoclass:: cuopt.linear_programming.problem.Variable - :members: - :undoc-members: - :exclude-members: - -.. autoclass:: cuopt.linear_programming.problem.LinearExpression - :members: - :undoc-members: - -.. autoclass:: cuopt.linear_programming.problem.QuadraticExpression - :members: - :undoc-members: - :special-members: __le__, __ge__, __neg__ - -.. autoclass:: cuopt.linear_programming.problem.Constraint - :members: - :undoc-members: - :exclude-members: compute_slack - -.. autoclass:: cuopt.linear_programming.solver_settings.SolverSettings - :members: - :undoc-members: - :exclude-members: to_base_type, toDict - -.. autoclass:: cuopt.linear_programming.problem.VType - :members: - :member-order: bysource - :undoc-members: - :exclude-members: capitalize, casefold, center, count, encode, endswith, expandtabs, find, format, format_map, index, isalnum, isalpha, isascii, isdecimal, isdigit, isidentifier, islower, isnumeric, isprintable, isspace, istitle, isupper, join, ljust, lower, lstrip, maketrans, partition, removeprefix, removesuffix, replace, rfind, rindex, rjust, rpartition, rsplit, rstrip, split, splitlines, startswith, strip, swapcase, title, translate, upper, zfill - -.. autoclass:: cuopt.linear_programming.problem.CType - :members: - :member-order: bysource - :undoc-members: - :exclude-members: capitalize, casefold, center, count, encode, endswith, expandtabs, find, format, format_map, index, isalnum, isalpha, isascii, isdecimal, isdigit, isidentifier, islower, isnumeric, isprintable, isspace, istitle, isupper, join, ljust, lower, lstrip, maketrans, partition, removeprefix, removesuffix, replace, rfind, rindex, rjust, rpartition, rsplit, rstrip, split, splitlines, startswith, strip, swapcase, title, translate, upper, zfill - -.. autoclass:: cuopt.linear_programming.problem.sense - :members: - :member-order: bysource - :undoc-members: - :exclude-members: __new__, __init__, _generate_next_value_, as_integer_ratio, bit_count, bit_length, conjugate, denominator, from_bytes, imag, is_integer, numerator, real, to_bytes - -.. autofunction:: cuopt.linear_programming.io.Read diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/lp-qp-milp-examples.rst b/docs/cuopt/source/cuopt-python/lp-qp-milp/lp-qp-milp-examples.rst deleted file mode 100644 index 8237a560df..0000000000 --- a/docs/cuopt/source/cuopt-python/lp-qp-milp/lp-qp-milp-examples.rst +++ /dev/null @@ -1,221 +0,0 @@ -======================== -LP, QP and MILP Examples -======================== - -This section contains examples of how to use the cuOpt linear programming, quadratic programming and mixed integer linear programming Python API. - -.. note:: - - The examples in this section are not exhaustive. They are provided to help you get started with the cuOpt linear programming, quadratic programming and mixed integer linear programming Python API. For more examples, please refer to the `cuopt-examples GitHub repository `_. - - -Simple Linear Programming Example ---------------------------------- - -:download:`simple_lp_example.py ` - -.. literalinclude:: examples/simple_lp_example.py - :language: python - :linenos: - -The response is as follows: - -.. code-block:: text - - Optimal solution found in 0.01 seconds - x = 10.0 - y = 0.0 - Objective value = 10.0 - - -.. _simple-qp-example-python: - -Simple Quadratic Programming Example ------------------------------------- - -:download:`simple_qp_example.py ` - -.. literalinclude:: examples/simple_qp_example.py - :language: python - :linenos: - -The response is as follows: - -.. code-block:: text - - Optimal solution found in 0.01 seconds - x = 0.5 - y = 0.5 - Objective value = 0.5 - - -Mixed Integer Linear Programming Example ----------------------------------------- - -:download:`simple_milp_example.py ` - -.. literalinclude:: examples/simple_milp_example.py - :language: python - :linenos: - -The response is as follows: - -.. code-block:: text - - Optimal solution found in 0.00 seconds - x = 36.0 - y = 40.99999999999999 - Objective value = 303.0 - - -Semi-continuous Variable Example --------------------------------- - -:download:`semi_continuous_example.py ` - -.. literalinclude:: examples/semi_continuous_example.py - :language: python - :linenos: - -The response is as follows: - -.. code-block:: text - - Optimal solution found in 0.00 seconds - x = 0.0 - y = 1.0 - Objective value = 0.0 - - -Advanced Example: Production Planning -------------------------------------- - -:download:`production_planning_example.py ` - -.. literalinclude:: examples/production_planning_example.py - :language: python - :linenos: - -The response is as follows: - -.. code-block:: text - - === Production Planning Solution === - - Status: Optimal - Solve time: 0.09 seconds - Product A production: 36.0 units - Product B production: 28.000000000000004 units - Total profit: $2640.00 - -Working with Expressions and Constraints ----------------------------------------- - -:download:`expressions_constraints_example.py ` - -.. literalinclude:: examples/expressions_constraints_example.py - :language: python - :linenos: - -The response is as follows: - -.. code-block:: text - - === Expression Example Results === - x = 0.0 - y = 50.0 - z = 99.99999999999999 - Objective value = 399.99999999999994 - -Working with Quadratic objective matrix ---------------------------------------- - -:download:`qp_matrix_example.py ` - -.. literalinclude:: examples/qp_matrix_example.py - :language: python - :linenos: - -The response is as follows: - -.. code-block:: text - - Optimal solution found in 0.16 seconds - p1 = 30.770728122083014 - p2 = 65.38350784293876 - p3 = 53.84576403497824 - Minimized cost = 1153.8461538953868 - -Inspecting the Problem Solution -------------------------------- - -:download:`solution_example.py ` - -.. literalinclude:: examples/solution_example.py - :language: python - :linenos: - -The response is as follows: - -.. code-block:: text - - Optimal solution found in 0.02 seconds - Objective: 9.0 - x = 1.0, ReducedCost = 0.0 - y = 3.0, ReducedCost = 0.0 - z = 0.0, ReducedCost = 2.999999858578644 - c1 DualValue = 1.0000000592359144 - c2 DualValue = 1.0000000821854418 - -Working with Incumbent Solutions --------------------------------- - -Incumbent solutions are intermediate feasible solutions found during the MIP solving process. They represent the best integer-feasible solution discovered so far and can be accessed through callback functions. - -.. note:: - Incumbent solutions are only available for Mixed Integer Programming (MIP) problems, not for pure Linear Programming (LP) problems. - -:download:`incumbent_solutions_example.py ` - -.. literalinclude:: examples/incumbent_solutions_example.py - :language: python - :linenos: - -The response is as follows: - -.. code-block:: text - - Optimal solution found. - Incumbent 1: x=36.0 y=41.0 cost: 303.00 - Solution objective: 303.000000 , relative_mip_gap 0.000000 solution_bound 303.000000 presolve_time 0.103659 total_solve_time 0.173678 max constraint violation 0.000000 max int violation 0.000000 max var bounds violation 0.000000 nodes 0 simplex_iterations 2 - - === Final Results === - Problem status: Optimal - Solve time: 0.17 seconds - Final solution: x=36.0 y=41.0 - Final objective value: 303.00 - - Total incumbent solutions found: 1 - -Working with PDLP Warmstart Data --------------------------------- - -Warmstart data allows to restart PDLP with a previous solution context. This should be used when you solve a new problem which is similar to the previous one. - -.. note:: - Warmstart data is only available for Linear Programming (LP) problems, not for Mixed Integer Linear Programming (MILP) problems. - -:download:`pdlp_warmstart_example.py ` - -.. literalinclude:: examples/pdlp_warmstart_example.py - :language: python - :linenos: - -The response is as follows: - -.. code-block:: text - - Optimal solution found in 0.01 seconds - x = 25.000000000639382 - y = 0.0 - Objective value = 50.000000001278764 diff --git a/docs/cuopt/source/lp-qp-features.rst b/docs/cuopt/source/lp-qp-features.rst deleted file mode 100644 index 9656f47bcc..0000000000 --- a/docs/cuopt/source/lp-qp-features.rst +++ /dev/null @@ -1,225 +0,0 @@ -======================== -LP/QP/SOCP Features -======================== - -Availability -------------- - -The Linear Programming (LP) and Quadratic Programming (QP) solvers can be accessed in the following ways: - -- **Third-Party Modeling Languages**: cuOpt's LP solver can be called directly from the following third-party modeling languages. This allows you to leverage GPU acceleration while maintaining your existing optimization workflow in these modeling languages. - - Supported modeling languages: - - AMPL - - GAMS - - PuLP - - JuMP - -.. note:: - The QP solver is not currently supported in third-party modeling languages. - -- **C API**: A native C API that provides direct low-level access to cuOpt's LP/QP capabilities, enabling integration into any application or system that can interface with C. - -- **Python SDK**: A Python package that provides direct access to cuOpt's LP/QP capabilities through a simple, intuitive API. This allows for seamless integration into Python applications and workflows. For more information, see :doc:`cuopt-python/quick-start`. - -- **As a Self-Hosted Service**: cuOpt's LP/QP solver can be deployed as a self-hosted service in your own infrastructure, enabling you to maintain full control while integrating it into your existing systems. - -Each option provide the same powerful linear optimization capabilities while offering flexibility in deployment and integration. - -Variable Bounds ---------------- - -Lower and upper bounds can be applied to each variable. If no variable bounds are specified, the default bounds are ``[-inf,+inf]``. - -Constraints ------------ - -The constraint matrix is specified in `Compressed Sparse Row (CSR) format `_. - -There are two ways to specify constraints to the LP solver: - -1. Using row_type and right-hand side: - - Constraints can be specified in the form: - - A*x {<=, =, >=} b - - where A is the constraint matrix in CSR format, x is the variable vector, and b is the right-hand side vector. The relationship {<=, =, >=} is specified via the ``row_type`` parameter. - -2. Using constraint bounds: - - Alternatively, constraints can be specified as two-sided inequalities: - - lb <= A*x <= ub - - where lb and ub are vectors of lower and upper bounds respectively. This form allows specifying both bounds on a single constraint. - - -Quadratic Programming ---------------------- - -cuOpt supports problems with quadratic objectives of the form: - -.. code-block:: text - - minimize x^T*Q*x + c^T*x - subject to A*x {<=, =, >=} b - lb <= x <= ub - -where Q is a symmetric positive semidefinite matrix. Please note that the Q matrix is specified without the 1/2 factor that may be used by other solvers. - -.. note:: Currently, barrier is the only method that supports QPs. - -See :ref:`simple-qp-example-python` for an example of how to create a QP problem with the Python Modeling API. -See :ref:`simple-qp-example-c` for an example of how to create a QP problem with the C API. - -Second-Order Cone Programming (Beta) --------------------------------------- - -.. note:: SOCP support is **beta** in this release. The API is functional but has not been fully hardened for all problem types and edge cases. - -cuOpt supports Second-Order Cone Programming (SOCP) problems — problems with quadratic constraints of the form: - -.. code-block:: text - - minimize c^T*x - subject to A*x {<=, =, >=} b - ||Ax + b||_2 <= c^T*x + d (second-order cone constraints) - lb <= x <= ub - -SOCP constraints are specified as quadratic constraints using ``<=`` or ``>=`` comparisons on a ``QuadraticExpression``. cuOpt automatically converts these quadratic constraints to second-order cone form internally. - -When any quadratic constraint is present, cuOpt automatically selects the barrier method and disables presolve optimizations that apply only to linear problems. - -**Constraints:** - -- Only ``<=`` and ``>=`` sense is supported for quadratic constraints. Equality quadratic constraints are not supported. -- The right-hand side of a quadratic constraint must be zero when the constraint is intended as a SOC constraint. -- Each second-order cone must have dimension at least 2. - -**Python example:** - -.. code-block:: python - - x = problem.addVariable("x", lb=0) - y = problem.addVariable("y", lb=0) - z = problem.addVariable("z", lb=0) - - # ||[x, y]||_2 <= z written as x*x + y*y - z*z <= 0 - problem.addConstraint(x*x + y*y - z*z <= 0, name="soc") - -**C API:** Use :c:func:`cuOptAddQuadraticConstraint` to add quadratic constraints. The solver automatically detects and handles SOC structure. - -.. note:: SOCP problems always use the barrier solver regardless of the ``CUOPT_METHOD`` setting. - -Warm Start ------------ - -A warm starts allow a user to provide an initial solution to help PDLP converge faster. The initial ``primal`` and ``dual`` solutions can be specified by the user. - -Alternatively, previously run solutions can be used to warm start a new solve to decrease solve time. :ref:`Examples ` are shared on the self-hosted page. - -PDLP Solver Mode ----------------- -Users can control how the solver will operate by specifying the PDLP solver mode. The mode choice can drastically impact how fast a specific problem will be solved. Users are encouraged to test different modes to see which one fits the best their problem. - - -Method ------- - -**Concurrent**: The default method for solving linear programs. When concurrent is selected, cuOpt runs three algorithms in parallel: PDLP on the GPU, barrier (interior-point) on the GPU, and dual simplex on the CPU. A solution is returned from the algorithm that finishes first. - -**PDLP**: Primal-Dual Hybrid Gradient for Linear Program is an algorithm for solving large-scale linear programming problems on the GPU. PDLP does not attempt any matrix factorizations during the course of the solve. Select this method if your LP is so large that factorization will not fit into memory. By default PDLP solves to low relative tolerance and the solutions it returns do not lie at a vertex of the feasible region. Enable crossover to obtain a highly accurate basic solution from a PDLP solution. - -.. note:: - PDLP solves to 1e-4 relative accuracy by default. - -**Barrier**: The barrier method (also known as interior-point method) solves linear and quadratic programs using a primal-dual predictor-corrector algorithm. This method uses GPU-accelerated sparse Cholesky and sparse LDLT solves via cuDSS, and GPU-accelerated sparse matrix-vector and matrix-matrix operations via cuSparse. Barrier is particularly effective for large-scale problems and can automatically apply techniques like folding, dualization, and dense column elimination to improve performance. This method solves the linear systems at each iteration using the augmented system or the normal equations (ADAT). Enable crossover to obtain a highly accurate basic solution from a barrier solution. - -.. note:: - Barrier solves to 1e-8 relative accuracy by default. - -**Dual Simplex**: Dual simplex is the simplex method applied to the dual of the linear program. Dual simplex requires the basis factorization of linear program fit into memory. Select this method if your LP is small to medium sized, or if you require a high-quality basic solution. - -.. note:: - Dual Simplex solves to 1e-6 absolute accuracy by default. - - -Crossover ---------- - -Crossover allows you to obtain a high-quality basic solution from the results of a PDLP or barrier solve. When enabled, crossover converts the PDLP or barrier solution to a vertex solution (basic solution) with high accuracy. More details can be found :ref:`here `. - -.. note:: - Crossover is not supported for QP problems. - -Presolve --------- - -Presolve procedure is applied to the problem before the solver is called. It can be used to reduce the problem size and improve solve time. cuOpt supports presolve reductions using PSLP or Papilo for linear programming (LP) problems, and Papilo for mixed-integer programming (MIP) problems. For MIP problems, Papilo presolve is always enabled by default. For LP problems, PSLP presolve is always enabled by default. Users can manually select to disable presolve by setting this parameter to 0, enable Papilo presolve by setting this parameter to 1, or enable PSLP presolve by setting this parameter to 2. -Furthermore, for LP problems with Papilo presolver, when the dual solution is not needed, additional presolve procedures can be applied to further improve solve times. This is achieved by turning off dual postsolve with the ``CUOPT_DUAL_POSTSOLVE`` setting. - - -Logging -------- - -The ``CUOPT_LOG_FILE`` parameter can be set to write detailed solver logs for LP/QP problems. This parameter is available in all APIs that allow setting solver parameters except the cuOpt service. For the service, see the logging callback below. - -Logging Callback in the Service -------------------------------- - -In the cuOpt service API, the ``log_file`` value in ``solver_configs`` is ignored. - -If however you set the ``solver_logs`` flag on the ``/cuopt/request`` REST API call, users can fetch the log file content from the webserver at ``/cuopt/logs/{id}``. Using the logging callback feature through the cuOpt client is shown in :ref:`Examples ` on the self-hosted page. - - -Infeasibility Detection ------------------------ - -The PDLP solver includes the option to detect infeasible problems. If the infeasibilty detection is enabled in solver settings, PDLP will abort as soon as it concludes the problem is infeasible. - -.. note:: - Infeasibility detection is always enabled for dual simplex. - -Time Limit ----------- - -The user may specify a time limit to the solver. By default the solver runs until a solution is found or the problem is determined to be infeasible or unbounded. - -.. note:: - - Note that ``time_limit`` applies only to solve time inside the LP solver. This does not include time for network transfer, validation of input, and other operations that occur outside the solver. The overhead associated with these operations are usually small compared to the solve time. - - -.. _batch-mode: - -Batch Mode ----------- - -Users can submit a set of problems which will be solved in a batch. Problems will be solved at the same time in parallel to fully utilize the GPU. Checkout :ref:`self-hosted client ` example in thin client. - -.. warning:: Deprecated - - LP batch mode (Python ``cuopt.linear_programming.BatchSolve``, server requests - with a list of LP problems, and multi-file ``cuopt_sh`` LP submissions) is - deprecated and will be removed in a future release. Prefer sequential - ``cuopt.linear_programming.Solve`` calls, or implement your own parallelism - (for example with ``concurrent.futures``). Existing batch APIs still run in - parallel today; callers may see a ``DeprecationWarning`` or a deprecation - message in server ``warnings``. - -PDLP Precision Modes --------------------- - -By default, PDLP operates in the native precision of the problem type (FP64 for double-precision problems). The ``pdlp_precision`` parameter provides several modes: - -- **single**: Run PDLP internally in FP32, with automatic conversion of inputs and outputs. FP32 uses half the memory and allows PDHG iterations to be on average twice as fast, but may require more iterations to converge. Compatible with crossover (solution is converted back to FP64 before crossover) and concurrent mode (PDLP runs in FP32 while other solvers run in FP64). -- **mixed**: Use mixed precision SpMV during PDHG iterations. The constraint matrix is stored in FP32 while vectors and compute type remain in FP64, improving SpMV performance with limited impact on convergence. Convergence checking and restart logic always use the full FP64 matrix. -- **double**: Explicitly run in FP64 (same as default for double-precision problems). - -.. note:: The default precision is the native type of the problem (FP64 for double). - -Multi-GPU Mode --------------- - -Users can use multiple GPUs to solve a problem by specifying the ``num_gpus`` parameter. The feature is restricted to LP problems that uses concurrent mode and supports up to 2 GPUs at the moment. Using this mode will run PDLP and barrier in parallel on different GPUs to avoid sharing single GPU resources. diff --git a/docs/cuopt/source/lp-qp-milp-settings.rst b/docs/cuopt/source/lp-qp-milp-settings.rst deleted file mode 100644 index 2de147018c..0000000000 --- a/docs/cuopt/source/lp-qp-milp-settings.rst +++ /dev/null @@ -1,705 +0,0 @@ -================================= -LP, QP, and MILP Settings -================================= - - -This page describes the parameter settings available for cuOpt's LP, QP, and MILP solvers. These parameters are set as :ref:`parameter constants ` in case of C API and in case of Server Thin client as raw strings. -Please refer to examples in :doc:`C ` and :doc:`Server Thin client ` for more details. - -.. note:: - When setting parameters in thin client solver settings, remove ``CUOPT_`` from the parameter name and convert to lowercase. For example, ``CUOPT_TIME_LIMIT`` would be set as ``time_limit``. - -Parameters common to LP/MILP ----------------------------- - -We begin by describing parameters common to both the MILP and LP solvers - - -Time Limit -^^^^^^^^^^ -``CUOPT_TIME_LIMIT`` controls the time limit in seconds after which the solver will stop and return the current solution. -For performance reasons, cuOpt does not constantly checks for time limit. Thus, the solver -may run slightly over the limit. If set along with the iteration limit, cuOpt will stop when -the first limit (iteration or time) is hit. - - -.. note:: By default there is no time limit. So cuOpt will run until it finds an optimal solution, - or proves the problem is infeasible or unbounded. - - - -Log to Console -^^^^^^^^^^^^^^ -``CUOPT_LOG_TO_CONSOLE`` controls whether cuOpt should log information to the console during a solve. -If true, a logging info is written to the console, if false no logging info is written to the console (logs may still be written to a file.) - -.. note:: The default value is true. - -Log File -^^^^^^^^ -``CUOPT_LOG_FILE`` controls the name of a log file where cuOpt should write information about the solve. - -.. note:: The default value is ``""`` and no log file is written. This setting is ignored by the cuOpt service, use the log callback feature instead. - -Solution File -^^^^^^^^^^^^^ -``CUOPT_SOLUTION_FILE`` controls the name of a file where cuOpt should write the solution. - -.. note:: The default value is ``""`` and no solution file is written. This setting is ignored by the cuOpt service. - -User Problem File -^^^^^^^^^^^^^^^^^ -``CUOPT_USER_PROBLEM_FILE`` controls the name of a file where cuOpt should write the user problem. - -.. note:: The default value is ``""`` and no user problem file is written. This setting is ignored by the cuOpt service. - -Num CPU Threads -^^^^^^^^^^^^^^^ -``CUOPT_NUM_CPU_THREADS`` controls the number of CPU threads used in the LP and MIP solvers. Set this to a small value to limit -the amount of CPU resources cuOpt uses. Set this to a large value to improve solve times for CPU -parallel parts of the solvers. - -.. note:: By default the number of CPU threads is automatically determined based on the number of CPU cores. - -Presolve -^^^^^^^^ -``CUOPT_PRESOLVE`` controls which presolver to use for presolve reductions. -cuOpt provides presolve reductions for linear programming (LP) problems using either PSLP or Papilo, and for mixed-integer programming (MIP) problems using Papilo. By default, Papilo presolve is always enabled for MIP problems. For LP problems, PSLP presolve is always enabled by default. You can explicitly control the presolver by setting this parameter to 0 (disable presolve), 1 (Papilo), or 2 (PSLP). - -Probing -^^^^^^^ -``CUOPT_MIP_PROBING`` toggles the probing-cache step of cuOpt's internal MIP presolve. The probing pass evaluates variable fixings to discover implications used later by branch-and-bound and the rounding heuristics. It is enabled by default (``true``); set it to ``false`` to skip probing while leaving the rest of presolve in place. Setting ``CUOPT_PRESOLVE=0`` already turns off the entire presolve pipeline, so ``CUOPT_MIP_PROBING`` only matters when presolve is otherwise enabled. Probing is also skipped in deterministic mode and on LP-only solves. - -Dual Postsolve -^^^^^^^^^^^^^^ -``CUOPT_DUAL_POSTSOLVE`` controls whether dual postsolve is enabled when using Papilo presolver for LP problems. Disabling dual postsolve can improve solve time at the expense of not having -access to the dual solution. Enabled by default for LP when Papilo presolve is selected. This is not relevant for MIP problems. - -Linear Programming ------------------- - -We now describe the parameter settings used to control cuOpt's Linear Programming solvers - -Method -^^^^^^ - -``CUOPT_METHOD`` controls the method to solve the linear programming problem. Four methods are available: - -* ``Concurrent``: Use PDLP, dual simplex, and barrier in parallel (default). -* ``PDLP``: Use the PDLP method. -* ``Dual Simplex``: Use the dual simplex method. -* ``Barrier``: Use the barrier (interior-point) method. - -.. note:: The default method is ``Concurrent``. - -Default accuracy for each method: - -* PDLP solves to 1e-4 relative accuracy by default. -* Barrier solves to 1e-8 relative accuracy by default. -* Dual Simplex solves to 1e-6 absolute accuracy by default. - -C API users should use the constants defined in :ref:`method-constants` for this parameter. - -Server Thin client users should use the :class:`cuopt_sh_client.SolverMethod` for this parameter. - -PDLP Solver Mode -^^^^^^^^^^^^^^^^ - -``CUOPT_PDLP_SOLVER_MODE`` controls the mode under which PDLP should operate. The mode will change the way the -PDLP internally optimizes the problem. The mode choice can drastically impact how fast a -specific problem will be solved. Users are encouraged to test different modes to see which one -fits the best their problem. By default, the solver uses ``Stable3``, the best -overall mode from our experiments. For now, only three modes are available: ``Stable3``, -``Methodical1``, and ``Fast1``. - -For now, we do not offer a mechanism to know upfront which solver mode will be the best -for a specific problem. - -C API users should use the constants defined in :ref:`pdlp-solver-mode-constants` for this parameter. - -Server Thin client users should use the :class:`cuopt_sh_client.PDLPSolverMode` for this parameter. - -Iteration Limit -^^^^^^^^^^^^^^^ - -``CUOPT_ITERATION_LIMIT`` controls the iteration limit after which the solver will stop and return the current solution. -For performance reasons, cuOpt's does not constantly checks for iteration limit, thus, -the solver might run a few extra iterations over the limit. If set along with the time limit, -cuOpt will stop at the first limit (iteration or time) reached. - -.. note:: By default there is no iteration limit. So, cuOpt will run until it finds an optimal solution, - or proves the problem is infeasible or unbounded. - - -Number of GPUs -^^^^^^^^^^^^^^ - -``CUOPT_NUM_GPUS`` controls the number of GPUs to use for the solve. This setting is only relevant for LP problems that uses concurrent mode and supports up to 2 GPUs at the moment. Using this mode will run PDLP and barrier in parallel on different GPUs to avoid sharing single GPU resources. - - -Infeasibility Detection -^^^^^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_INFEASIBILITY_DETECTION`` controls whether PDLP should detect infeasibility. Note that infeasibility detection in PDLP -is not always accurate. Some problems detected as infeasible may converge under a different tolerance factor. -Detecting infeasibility consumes both more runtime and memory. The added runtime is between 3% and 7%, -the added memory consumption is between 10% and 20%. - -.. note:: By default PDLP will not detect infeasibility. Dual simplex will always detect infeasibility - regardless of this setting. - -Strict Infeasibility -^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_STRICT_INFEASIBILITY`` controls the strict infeasibility mode in PDLP. When true if either the current or the average solution -is detected as infeasible, PDLP will stop. When false both the current and average solution need to be -detected as infeasible for PDLP to stop. - -.. note:: The default value is false. - -.. _crossover: - -Crossover -^^^^^^^^^ - -``CUOPT_CROSSOVER`` controls whether PDLP or barrier should crossover to a basic solution after an optimal solution is found. -Changing this value has a significant impact on accuracy and runtime. -By default the solutions provided by PDLP and barrier do not lie at a vertex and thus may have many variables that lie -between their bounds. Enabling crossover allows the user to obtain a high-quality basic solution -that lies at a vertex of the feasible region. If n is the number of variables, and m is the number of -constraints, n - m variables will be on their bounds in a basic solution. - -.. note:: The default value is false. - -Save Best Primal So Far -^^^^^^^^^^^^^^^^^^^^^^^ -``CUOPT_SAVE_BEST_PRIMAL_SOLUTION`` controls whether PDLP should save the best primal solution so far -With this parameter set to true, PDLP -* Will always prioritize a primal feasible to a non primal feasible -* If a new primal feasible is found, the one with the best primal objective will be kept -* If no primal feasible was found, the one with the lowest primal residual will be kept -* If two have the same primal residual, the one with the best objective will be kept - -.. note:: The default value is false. - -First Primal Feasible -^^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_FIRST_PRIMAL_FEASIBLE`` controls whether PDLP should stop when the first primal feasible solution is found. - -.. note:: The default value is false. - -Per Constraint Residual -^^^^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_PER_CONSTRAINT_RESIDUAL`` controls whether PDLP should compute the primal & dual residual per constraint instead of globally. - -.. note:: The default value is false. - -PDLP Precision -^^^^^^^^^^^^^^ - -``CUOPT_PDLP_PRECISION`` controls the precision mode used by the PDLP solver. The following modes are -available: - -- **default** (-1): Use the native precision of the problem type (FP64 for double-precision problems). -- **single** (0): Run PDLP internally in FP32 (float). Inputs are converted from FP64 to FP32 before - solving and outputs are converted back to FP64. FP32 uses half the memory and allows PDHG iterations - to be on average twice as fast, but may require more iterations to converge due to reduced numerical - accuracy. Compatible with crossover (solution is converted back to FP64 before crossover runs) and - concurrent mode (the PDLP leg runs in FP32 while Dual Simplex and Barrier run in FP64). -- **double** (1): Explicitly run in FP64 (same as default for double-precision problems). -- **mixed** (2): Use mixed precision sparse matrix-vector products (SpMV) during PDHG iterations. The - constraint matrix and its transpose are stored in FP32 while vectors and the compute type remain in - FP64, improving SpMV performance. Convergence checking and restart logic always use the - full FP64 matrix, so this mode does not reduce overall memory usage. This provides a middle ground - between full FP64 and FP32: faster PDHG iterations with limited impact on convergence. - -.. note:: The default value is 0 (default precision). - -Barrier Solver Settings -^^^^^^^^^^^^^^^^^^^^^^^^ - -The following settings control the behavior of the barrier (interior-point) method: - -Folding -""""""" - -``CUOPT_FOLDING`` controls whether to fold the linear program. Folding can reduce problem size by exploiting symmetry in the problem. - -* ``-1``: Automatic (default) - cuOpt decides whether to fold based on problem characteristics -* ``0``: Disable folding -* ``1``: Force folding to run - -.. note:: The default value is ``-1`` (automatic). - -Dualize -""""""" - -``CUOPT_DUALIZE`` controls whether to dualize the linear program in presolve. Dualizing can improve solve time for problems, with inequality constraints, where there are more constraints than variables. - -* ``-1``: Automatic (default) - cuOpt decides whether to dualize based on problem characteristics -* ``0``: Don't attempt to dualize -* ``1``: Force dualize - -.. note:: The default value is ``-1`` (automatic). - -Ordering -"""""""" - -``CUOPT_ORDERING`` controls the ordering algorithm used by cuDSS for sparse factorizations. The ordering can significantly impact solver run time. - -* ``-1``: Automatic (default) - cuOpt selects the best ordering -* ``0``: cuDSS default ordering -* ``1``: AMD (Approximate Minimum Degree) ordering - -.. note:: The default value is ``-1`` (automatic). - -Augmented System -"""""""""""""""" - -``CUOPT_AUGMENTED`` controls which linear system to solve in the barrier method. - -* ``-1``: Automatic (default) - cuOpt selects the best linear system to solve -* ``0``: Solve the ADAT system (normal equations) -* ``1``: Solve the augmented system - -.. note:: The default value is ``-1`` (automatic). The augmented system may be more stable for some problems, while ADAT may be faster for others. - -Eliminate Dense Columns -"""""""""""""""""""""""" - -``CUOPT_ELIMINATE_DENSE_COLUMNS`` controls whether to eliminate dense columns from the constraint matrix before solving. Eliminating dense columns can improve performance by reducing fill-in during factorization. -However, extra solves must be performed at each iteration. - -* ``true``: Eliminate dense columns (default) -* ``false``: Don't eliminate dense columns - -This setting only has an effect when the ADAT (normal equation) system is solved. - -.. note:: The default value is ``true``. - -cuDSS Deterministic Mode -""""""""""""""""""""""""" - -``CUOPT_CUDSS_DETERMINISTIC`` controls whether cuDSS operates in deterministic mode. Deterministic mode ensures reproducible results across runs but may be slower. - -* ``true``: Use deterministic mode -* ``false``: Use non-deterministic mode (default) - -.. note:: The default value is ``false``. Enable deterministic mode if reproducibility is more important than performance. - -Dual Initial Point -"""""""""""""""""" - -``CUOPT_BARRIER_DUAL_INITIAL_POINT`` controls the method used to compute the dual initial point for the barrier solver. The choice of initial point will affect the number of iterations performed by barrier. - -* ``-1``: Automatic (default) - cuOpt selects the best method -* ``0``: Use an initial point from a heuristic approach based on the paper "On Implementing Mehrotra's Predictor–Corrector Interior-Point Method for Linear Programming" (SIAM J. Optimization, 1992) by Lustig, Martsten, Shanno. -* ``1``: Use an initial point from solving a least squares problem that minimizes the norms of the dual variables and reduced costs while statisfying the dual equality constraints. - -.. note:: The default value is ``-1`` (automatic). - -Absolute Primal Tolerance -^^^^^^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_ABSOLUTE_PRIMAL_TOLERANCE`` controls the absolute primal tolerance used in the primal feasibility check. -Changing this value might have a significant impact on accuracy and runtime if the relative part -(the right-hand side vector b L2 norm) is close to, or equal to, 0. - - -The primal feasibility condition is computed as follows:: - - primal_feasiblity < absolute_primal_tolerance + relative_primal_tolerance * l2_norm(b) - -Default value is ``1e-4``. - - -Relative Primal Tolerance -^^^^^^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_RELATIVE_PRIMAL_TOLERANCE`` controls the relative primal tolerance used in PDLP's primal feasibility check. -Changing this value has a significant impact on accuracy and runtime. -The primal feasibility condition is computed as follows:: - - primal_feasiblity < absolute_primal_tolerance + relative_primal_tolerance * l2_norm(b) - -.. note:: The default value is ``1e-4``. - -Absolute Dual Tolerance -^^^^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_ABSOLUTE_DUAL_TOLERANCE`` controls the absolute dual tolerance used in PDLP's dual feasibility check. -Changing this value might have a significant impact on accuracy and runtime if the relative part -(the objective vector L2 norm) is close to, or equal to, 0. - -The dual feasibility condition is computed as follows:: - - dual_feasiblity < absolute_dual_tolerance + relative_dual_tolerance * l2_norm(c) - -.. note:: The default value is ``1e-4``. - -Relative Dual Tolerance -^^^^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_RELATIVE_DUAL_TOLERANCE`` controls the relative dual tolerance used in PDLP's dual feasibility check. -Changing this value has a significant impact on accuracy and runtime. -The dual feasibility condition is computed as follows:: - - dual_feasiblity < absolute_dual_tolerance + relative_dual_tolerance * l2_norm(c) - -.. note:: The default value is ``1e-4``. - - -Absolute Gap Tolerance -^^^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_ABSOLUTE_GAP_TOLERANCE`` controls the absolute gap tolerance used in PDLP's duality gap check. -Changing this value might have a significant impact on accuracy and runtime if the relative part ``(|primal_objective| + |dual_objective|)`` is close to, or equal to, 0. - -The duality gap is computed as follows:: - - duality_gap < absolute_gap_tolerance + relative_gap_tolerance * (|primal_objective| + |dual_objective|) - -.. note:: The default value is ``1e-4``. - - -Relative Gap Tolerance -^^^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_RELATIVE_GAP_TOLERANCE`` controls the relative gap tolerance used in PDLP's duality gap check. -Changing this value has a significant impact on accuracy and runtime. -The duality gap is computed as follows:: - - duality_gap < absolute_gap_tolerance + relative_gap_tolerance * (|primal_objective| + |dual_objective|) - -.. note:: The default value is ``1e-4``. - - -Mixed Integer Linear Programming ---------------------------------- - -We now describe parameter settings for the MILP solvers - - -Heuristics only -^^^^^^^^^^^^^^^ - -``CUOPT_MIP_HEURISTICS_ONLY`` controls if only the GPU heuristics should be run for the MIP problem. When set to true, only the primal -bound is improved via the GPU. When set to false, both the GPU and CPU are used and -the dual bound is improved on the CPU. - -.. note:: The default value is false. - -Scaling -^^^^^^^ - -``CUOPT_MIP_SCALING`` controls if scaling should be applied to the MIP problem. - -* ``0``: Scaling is off. -* ``1``: Scaling is on. -* ``2``: Scaling is not applied to the objective (default). - -Absolute Tolerance -^^^^^^^^^^^^^^^^^^ - -``CUOPT_MIP_ABSOLUTE_TOLERANCE`` controls the MIP absolute tolerance. - -.. note:: The default value is ``1e-6``. - -Relative Tolerance -^^^^^^^^^^^^^^^^^^ - -``CUOPT_MIP_RELATIVE_TOLERANCE`` controls the MIP relative tolerance. - -.. note:: The default value is ``1e-12``. - - -Integrality Tolerance -^^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_MIP_INTEGRALITY_TOLERANCE`` controls the MIP integrality tolerance. A variable is considered to be integral, if -it is within the integrality tolerance of an integer. - -.. note:: The default value is ``1e-5``. - -Absolute MIP Gap -^^^^^^^^^^^^^^^^ - -``CUOPT_MIP_ABSOLUTE_GAP`` controls the absolute tolerance used to terminate the MIP solve. The solve terminates when:: - - Best Objective - Dual Bound <= absolute tolerance - -when minimizing or - - Dual Bound - Best Objective <= absolute tolerance - -when maximizing. - -.. note:: The default value is ``1e-10``. - -Relative MIP Gap -^^^^^^^^^^^^^^^^ - -``CUOPT_MIP_RELATIVE_GAP`` controls the relative tolerance used to terminate the MIP solve. The solve terminates when:: - - abs(Best Objective - Dual Bound) / abs(Best Objective) <= relative tolerance - -If the Best Objective and the Dual Bound are both zero the gap is zero. If the best objective value is zero, the -gap is infinity. - -.. note:: The default value is ``1e-4``. - - -Node Limit -^^^^^^^^^^ - -``CUOPT_NODE_LIMIT`` controls the maximum number of branch-and-bound nodes the MILP solver will explore before stopping and returning the current best feasible solution (if any). If set along with the time limit, cuOpt stops at whichever limit is hit first. - -.. note:: By default there is no node limit. The setting only affects MILP; - it is ignored for LP and QP. - -Cut Passes -^^^^^^^^^^ - -``CUOPT_MIP_CUT_PASSES`` controls the number of cut passes to run. Set this value to 0 to disable cuts. Set this value to larger numbers to perform more cut passes. - -.. note:: The default value is ``10``. - -Mixed Integer Rounding Cuts -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_MIP_MIXED_INTEGER_ROUNDING_CUTS`` controls whether to use mixed integer rounding cuts. -The default value of ``-1`` (automatic) means that the solver will decide whether to use mixed integer rounding cuts based on the problem characteristics. -Set this value to 1 to enable mixed integer rounding cuts. -Set this value to 0 to disable mixed integer rounding cuts. - -.. note:: The default value is ``-1`` (automatic). - -Mixed Integer Gomory Cuts -^^^^^^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_MIP_MIXED_INTEGER_GOMORY_CUTS`` controls whether to use mixed integer Gomory cuts. -The default value of ``-1`` (automatic) means that the solver will decide whether to use mixed integer Gomory cuts based on the problem characteristics. -Set this value to 1 to enable mixed integer Gomory cuts. -Set this value to 0 to disable mixed integer Gomory cuts. - -.. note:: The default value is ``-1`` (automatic). - -Strong Chvatal-Gomory Cuts -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_MIP_STRONG_CHVATAL_GOMORY_CUTS`` controls whether to use strong Chvatal-Gomory cuts. -The default value of ``-1`` (automatic) means that the solver will decide whether to use strong Chvatal-Gomory cuts based on the problem characteristics. -Set this value to 1 to enable strong Chvatal Gomory cuts. -Set this value to 0 to disable strong Chvatal Gomory cuts. - -.. note:: The default value is ``-1`` (automatic). - -Knapsack Cuts -^^^^^^^^^^^^^ - -``CUOPT_MIP_KNAPSACK_CUTS`` controls whether to use knapsack cuts. -The default value of ``-1`` (automatic) means that the solver will decide whether to use knapsack cuts based on the problem characteristics. -Set this value to 1 to enable knapsack cuts. -Set this value to 0 to disable knapsack cuts. - -.. note:: The default value is ``-1`` (automatic). - - -Cut Change Threshold -^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_MIP_CUT_CHANGE_THRESHOLD`` controls the threshold for the improvement in the dual bound per cut pass. -Larger values require the dual bound to improve significantly in each cut pass. -Set this value to 0 to allow the cut passes to continue even if the dual bound does not improve. - -.. note:: The default value is ``1e-3``. - -Cut Min Orthogonality -^^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_MIP_CUT_MIN_ORTHOGONALITY`` controls the minimum orthogonality required for a cut to be added to the LP relaxation. -Set this value close to 1, to require all cuts be close to orthogonal to each other. -Set this value close to zero to allow more cuts to be added to the LP relaxation. - -.. note:: The default value is ``0.5``. - -Reduced Cost Strengthening -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_MIP_REDUCED_COST_STRENGTHENING`` controls whether to use reduced-cost strengthening. -When enabled, the solver will use integer feasible solutions to strengthen the bounds of integer variables. -The default value of ``-1`` (automatic) means that the solver will decide whether to use reduced-cost strengthening based on the problem characteristics. -Set this value to 0 to disable reduced-cost strengthening. -Set this value to 1 to perform reduced-cost strengthening during the root cut passes. -Set this value to 2 to perform reduced-cost strengthening during the root cut passes and after strong branching. - -.. note:: The default value is ``-1`` (automatic). - -Reliability Branching -^^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_MIP_RELIABILITY_BRANCHING`` controls the reliability branching mode. -The default value of ``-1`` (automatic) means that the solver will decide whether to use reliability branching, and the reliability branching factor, based on the problem characteristics. -Set this value to 0 to disable reliability branching. -Set this value to k > 0, to enable reliability branching. A variable will be considered reliable if it has been branched on k times. - -.. note:: The default value is ``-1`` (automatic). - -Batch PDLP Strong Branching -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_MIP_BATCH_PDLP_STRONG_BRANCHING`` controls whether to use batched PDLP over Dual Simplex during strong branching at the root. -When enabled, the solver evaluates multiple branching candidates simultaneously in a single batched PDLP solve rather than solving them in parallel using Dual Simplex. This can significantly reduce the time spent in strong branching if Dual Simplex is struggling. -Set this value to 0 to disable batched PDLP strong branching. -Set this value to 1 to enable batched PDLP strong branching. - -.. note:: The default value is ``0`` (disabled). This setting is ignored if the problem is not a MIP problem. - -Batch PDLP Reliability Branching -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_MIP_BATCH_PDLP_RELIABILITY_BRANCHING`` controls whether to use batched PDLP for reliability branching evaluations. -When enabled, candidate variables for reliability branching are evaluated simultaneously using a single batched PDLP solve. -Set this value to 0 to disable. -Set this value to 1 to enable. - -.. note:: The default value is ``0`` (disabled). - -Strong Branching Simplex Iteration Limit -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_MIP_STRONG_BRANCHING_SIMPLEX_ITERATION_LIMIT`` controls the maximum number of simplex iterations allowed per candidate during strong branching. -Reducing this value speeds up strong branching at the cost of less accurate candidate evaluations. - -.. note:: By default there is no iteration limit for strong branching solves. - -MIP Determinism Mode -^^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_MIP_DETERMINISM_MODE`` controls whether the MIP solver runs in opportunistic or deterministic mode. - -* ``0`` (``CUOPT_MODE_OPPORTUNISTIC``): Opportunistic mode — results may vary between runs due to parallelism (default). -* ``1`` (``CUOPT_MODE_DETERMINISTIC``): Deterministic mode — improves reproducibility across runs with the same number of threads. - -.. note:: The default value is ``0`` (opportunistic). - -.. warning:: Deterministic mode is experimental. It improves reproducibility in many cases but does not yet guarantee fully deterministic results in all scenarios. - -MIP Symmetry -^^^^^^^^^^^^^ - -``CUOPT_MIP_SYMMETRY`` controls symmetry detection and handling in the MIP solver. - -* ``-1``: Automatic (default) — cuOpt decides based on problem characteristics. -* ``0``: Disable symmetry handling. -* ``1``: Enable symmetry handling. - -.. note:: The default value is ``-1`` (automatic). - -Flow Cover Cuts -^^^^^^^^^^^^^^^^ - -``CUOPT_MIP_FLOW_COVER_CUTS`` controls whether to use flow cover cuts. -Set this value to ``-1`` (automatic) to let the solver decide. -Set this value to ``0`` to disable flow cover cuts. -Set this value to ``1`` to enable flow cover cuts. - -.. note:: The default value is ``-1`` (automatic). - -Implied Bound Cuts -^^^^^^^^^^^^^^^^^^^ - -``CUOPT_MIP_IMPLIED_BOUND_CUTS`` controls whether to use implied bound cuts. -Set this value to ``-1`` (automatic) to let the solver decide. -Set this value to ``0`` to disable implied bound cuts. -Set this value to ``1`` to enable implied bound cuts. - -.. note:: The default value is ``-1`` (automatic). - -Clique Cuts -^^^^^^^^^^^^ - -``CUOPT_MIP_CLIQUE_CUTS`` controls whether to use clique cuts. -Set this value to ``-1`` (automatic) to let the solver decide. -Set this value to ``0`` to disable clique cuts. -Set this value to ``1`` to enable clique cuts. - -.. note:: The default value is ``-1`` (automatic). - -Objective Step -^^^^^^^^^^^^^^^ - -``CUOPT_MIP_OBJECTIVE_STEP`` controls whether cuOpt automatically detects and exploits discrete step structure in the objective to tighten the dual bound. -When all integer variables have integer objective coefficients, the objective value can only change in multiples of a known step size; enabling this setting allows cuOpt to use that information to close the gap faster. - -* ``0``: Disable objective step detection. -* ``1``: Enable objective step detection (default). - -.. note:: The default value is ``1`` (enabled). - -Semi-Continuous Big-M -^^^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_MIP_SEMICONTINUOUS_BIG_M`` controls the Big-M coefficient used when linearizing semi-continuous variable constraints. -A semi-continuous variable is either zero or takes a value in the range ``[lower_bound, upper_bound]``. -Set this to a positive value that is at least as large as the upper bound of any semi-continuous variable in the problem. - -.. note:: By default cuOpt derives the Big-M from the variable's upper bound. - -Work Limit -^^^^^^^^^^ - -``CUOPT_WORK_LIMIT`` controls the work limit after which the solver will stop and return the current solution. -Work units are a machine-independent measure of solver effort. If set along with the time limit or iteration limit, cuOpt will stop when the first limit is hit. - -.. note:: By default there is no work limit. - -Random Seed -^^^^^^^^^^^^ - -``CUOPT_RANDOM_SEED`` controls the random seed used by the solver. Setting a fixed seed enables reproducible results when running in deterministic mode. - -.. note:: By default the random seed is set automatically. - -Presolve File -^^^^^^^^^^^^^^ - -``CUOPT_PRESOLVE_FILE`` controls the name of a file where cuOpt should write presolve information. - -.. note:: The default value is ``""`` and no presolve file is written. - -Primal Infeasibility Tolerance -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_PRIMAL_INFEASIBLE_TOLERANCE`` controls the tolerance used to detect primal infeasibility in PDLP. -A certificate of primal infeasibility is accepted when the primal infeasibility residual falls below this threshold. - -.. note:: The default value is ``1e-8``. - -Dual Infeasibility Tolerance -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_DUAL_INFEASIBLE_TOLERANCE`` controls the tolerance used to detect dual infeasibility (unboundedness) in PDLP. -A certificate of dual infeasibility is accepted when the dual infeasibility residual falls below this threshold. - -.. note:: The default value is ``1e-8``. - -Barrier Iterative Refinement -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -``CUOPT_BARRIER_ITERATIVE_REFINEMENT`` controls whether iterative refinement is applied after each barrier iteration to improve solution accuracy. - -* ``0`` (``CUOPT_BARRIER_ITERATIVE_REFINEMENT_OFF``): Disable iterative refinement (default). -* ``1`` (``CUOPT_BARRIER_ITERATIVE_REFINEMENT_ON``): Enable iterative refinement. - -.. note:: The default value is ``0`` (off). - -Barrier Step Scale -^^^^^^^^^^^^^^^^^^^ - -``CUOPT_BARRIER_STEP_SCALE`` controls the scaling factor applied to the step size in the barrier method. -Values less than 1 result in more conservative (shorter) steps; values greater than 1 result in more aggressive steps. - -.. note:: By default cuOpt selects the step scale automatically. From 84d20ed286e224d361d314b6a53519a7deceaaba Mon Sep 17 00:00:00 2001 From: Rajesh Gandham Date: Fri, 29 May 2026 16:39:15 -0400 Subject: [PATCH 08/13] Reorganize docs into continuous/ and mip/ subdirectories MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/cuopt/source/continuous-settings.rst | 2 +- .../continuous-c-api.rst | 0 .../continuous-examples.rst | 0 .../examples/Makefile | 0 .../examples/lp_file_example.c | 0 .../examples/mps_file_example.c | 0 .../examples/sample.lp | 0 .../examples/sample.mps | 0 .../examples/simple_lp_example.c | 0 .../examples/simple_qp_example.c | 0 .../cuopt/source/cuopt-c/continuous/index.rst | 14 +++++++++++ docs/cuopt/source/cuopt-c/index.rst | 14 ++++++++--- .../cuopt/source/cuopt-c/lp-qp-milp/index.rst | 24 ------------------- .../examples/milp_mps_example.c | 0 .../examples/mip_sample.mps | 0 .../examples/simple_milp_example.c | 0 docs/cuopt/source/cuopt-c/mip/index.rst | 14 +++++++++++ .../cuopt-c/{lp-qp-milp => mip}/mip-c-api.rst | 0 .../{lp-qp-milp => mip}/mip-examples.rst | 0 docs/cuopt/source/cuopt-grpc/examples.rst | 10 ++++---- docs/cuopt/source/cuopt-grpc/quick-start.rst | 2 +- .../continuous-api.rst | 0 .../continuous-examples.rst | 0 .../expressions_constraints_example.py | 0 .../examples/pdlp_warmstart_example.py | 0 .../examples/production_planning_example.py | 0 .../examples/qp_matrix_example.py | 0 .../examples/simple_lp_example.py | 0 .../examples/simple_qp_example.py | 0 .../examples/solution_example.py | 0 .../source/cuopt-python/continuous/index.rst | 13 ++++++++++ docs/cuopt/source/cuopt-python/index.rst | 14 ++++++++--- .../source/cuopt-python/lp-qp-milp/index.rst | 22 ----------------- .../examples/incumbent_solutions_example.py | 0 .../examples/semi_continuous_example.py | 0 .../examples/simple_milp_example.py | 0 docs/cuopt/source/cuopt-python/mip/index.rst | 13 ++++++++++ .../{lp-qp-milp => mip}/mip-api.rst | 0 .../{lp-qp-milp => mip}/mip-examples.rst | 0 docs/cuopt/source/mip-settings.rst | 2 +- 40 files changed, 84 insertions(+), 60 deletions(-) rename docs/cuopt/source/cuopt-c/{lp-qp-milp => continuous}/continuous-c-api.rst (100%) rename docs/cuopt/source/cuopt-c/{lp-qp-milp => continuous}/continuous-examples.rst (100%) rename docs/cuopt/source/cuopt-c/{lp-qp-milp => continuous}/examples/Makefile (100%) rename docs/cuopt/source/cuopt-c/{lp-qp-milp => continuous}/examples/lp_file_example.c (100%) rename docs/cuopt/source/cuopt-c/{lp-qp-milp => continuous}/examples/mps_file_example.c (100%) rename docs/cuopt/source/cuopt-c/{lp-qp-milp => continuous}/examples/sample.lp (100%) rename docs/cuopt/source/cuopt-c/{lp-qp-milp => continuous}/examples/sample.mps (100%) rename docs/cuopt/source/cuopt-c/{lp-qp-milp => continuous}/examples/simple_lp_example.c (100%) rename docs/cuopt/source/cuopt-c/{lp-qp-milp => continuous}/examples/simple_qp_example.c (100%) create mode 100644 docs/cuopt/source/cuopt-c/continuous/index.rst delete mode 100644 docs/cuopt/source/cuopt-c/lp-qp-milp/index.rst rename docs/cuopt/source/cuopt-c/{lp-qp-milp => mip}/examples/milp_mps_example.c (100%) rename docs/cuopt/source/cuopt-c/{lp-qp-milp => mip}/examples/mip_sample.mps (100%) rename docs/cuopt/source/cuopt-c/{lp-qp-milp => mip}/examples/simple_milp_example.c (100%) create mode 100644 docs/cuopt/source/cuopt-c/mip/index.rst rename docs/cuopt/source/cuopt-c/{lp-qp-milp => mip}/mip-c-api.rst (100%) rename docs/cuopt/source/cuopt-c/{lp-qp-milp => mip}/mip-examples.rst (100%) rename docs/cuopt/source/cuopt-python/{lp-qp-milp => continuous}/continuous-api.rst (100%) rename docs/cuopt/source/cuopt-python/{lp-qp-milp => continuous}/continuous-examples.rst (100%) rename docs/cuopt/source/cuopt-python/{lp-qp-milp => continuous}/examples/expressions_constraints_example.py (100%) rename docs/cuopt/source/cuopt-python/{lp-qp-milp => continuous}/examples/pdlp_warmstart_example.py (100%) rename docs/cuopt/source/cuopt-python/{lp-qp-milp => continuous}/examples/production_planning_example.py (100%) rename docs/cuopt/source/cuopt-python/{lp-qp-milp => continuous}/examples/qp_matrix_example.py (100%) rename docs/cuopt/source/cuopt-python/{lp-qp-milp => continuous}/examples/simple_lp_example.py (100%) rename docs/cuopt/source/cuopt-python/{lp-qp-milp => continuous}/examples/simple_qp_example.py (100%) rename docs/cuopt/source/cuopt-python/{lp-qp-milp => continuous}/examples/solution_example.py (100%) create mode 100644 docs/cuopt/source/cuopt-python/continuous/index.rst delete mode 100644 docs/cuopt/source/cuopt-python/lp-qp-milp/index.rst rename docs/cuopt/source/cuopt-python/{lp-qp-milp => mip}/examples/incumbent_solutions_example.py (100%) rename docs/cuopt/source/cuopt-python/{lp-qp-milp => mip}/examples/semi_continuous_example.py (100%) rename docs/cuopt/source/cuopt-python/{lp-qp-milp => mip}/examples/simple_milp_example.py (100%) create mode 100644 docs/cuopt/source/cuopt-python/mip/index.rst rename docs/cuopt/source/cuopt-python/{lp-qp-milp => mip}/mip-api.rst (100%) rename docs/cuopt/source/cuopt-python/{lp-qp-milp => mip}/mip-examples.rst (100%) diff --git a/docs/cuopt/source/continuous-settings.rst b/docs/cuopt/source/continuous-settings.rst index cbb1d4630c..05adda71e1 100644 --- a/docs/cuopt/source/continuous-settings.rst +++ b/docs/cuopt/source/continuous-settings.rst @@ -3,7 +3,7 @@ Continuous Optimization Settings (LP, QP, SOCP) ================================================ -This page describes the parameter settings available for cuOpt's LP, QP, and SOCP solvers. These parameters are set as :ref:`parameter constants ` in case of C API and in case of Server Thin client as raw strings. Please refer to examples in :doc:`C ` and :doc:`Server Thin client ` for more details. +This page describes the parameter settings available for cuOpt's LP, QP, and SOCP solvers. These parameters are set as :ref:`parameter constants ` in case of C API and in case of Server Thin client as raw strings. Please refer to examples in :doc:`C ` and :doc:`Server Thin client ` for more details. .. note:: When setting parameters in thin client solver settings, remove ``CUOPT_`` from the parameter name and convert to lowercase. For example, ``CUOPT_TIME_LIMIT`` would be set as ``time_limit``. diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/continuous-c-api.rst b/docs/cuopt/source/cuopt-c/continuous/continuous-c-api.rst similarity index 100% rename from docs/cuopt/source/cuopt-c/lp-qp-milp/continuous-c-api.rst rename to docs/cuopt/source/cuopt-c/continuous/continuous-c-api.rst diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/continuous-examples.rst b/docs/cuopt/source/cuopt-c/continuous/continuous-examples.rst similarity index 100% rename from docs/cuopt/source/cuopt-c/lp-qp-milp/continuous-examples.rst rename to docs/cuopt/source/cuopt-c/continuous/continuous-examples.rst diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/examples/Makefile b/docs/cuopt/source/cuopt-c/continuous/examples/Makefile similarity index 100% rename from docs/cuopt/source/cuopt-c/lp-qp-milp/examples/Makefile rename to docs/cuopt/source/cuopt-c/continuous/examples/Makefile diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/examples/lp_file_example.c b/docs/cuopt/source/cuopt-c/continuous/examples/lp_file_example.c similarity index 100% rename from docs/cuopt/source/cuopt-c/lp-qp-milp/examples/lp_file_example.c rename to docs/cuopt/source/cuopt-c/continuous/examples/lp_file_example.c diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/examples/mps_file_example.c b/docs/cuopt/source/cuopt-c/continuous/examples/mps_file_example.c similarity index 100% rename from docs/cuopt/source/cuopt-c/lp-qp-milp/examples/mps_file_example.c rename to docs/cuopt/source/cuopt-c/continuous/examples/mps_file_example.c diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/examples/sample.lp b/docs/cuopt/source/cuopt-c/continuous/examples/sample.lp similarity index 100% rename from docs/cuopt/source/cuopt-c/lp-qp-milp/examples/sample.lp rename to docs/cuopt/source/cuopt-c/continuous/examples/sample.lp diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/examples/sample.mps b/docs/cuopt/source/cuopt-c/continuous/examples/sample.mps similarity index 100% rename from docs/cuopt/source/cuopt-c/lp-qp-milp/examples/sample.mps rename to docs/cuopt/source/cuopt-c/continuous/examples/sample.mps diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/examples/simple_lp_example.c b/docs/cuopt/source/cuopt-c/continuous/examples/simple_lp_example.c similarity index 100% rename from docs/cuopt/source/cuopt-c/lp-qp-milp/examples/simple_lp_example.c rename to docs/cuopt/source/cuopt-c/continuous/examples/simple_lp_example.c diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/examples/simple_qp_example.c b/docs/cuopt/source/cuopt-c/continuous/examples/simple_qp_example.c similarity index 100% rename from docs/cuopt/source/cuopt-c/lp-qp-milp/examples/simple_qp_example.c rename to docs/cuopt/source/cuopt-c/continuous/examples/simple_qp_example.c diff --git a/docs/cuopt/source/cuopt-c/continuous/index.rst b/docs/cuopt/source/cuopt-c/continuous/index.rst new file mode 100644 index 0000000000..a4a9d3e45f --- /dev/null +++ b/docs/cuopt/source/cuopt-c/continuous/index.rst @@ -0,0 +1,14 @@ +Continuous Optimization (LP/QP/SOCP) +===================================== + +This section contains details on the cuOpt LP/QP/SOCP C API. + +.. toctree:: + :maxdepth: 3 + :caption: LP/QP/SOCP C API + :name: LP/QP/SOCP C API + :titlesonly: + + continuous-c-api.rst + ../../continuous-settings.rst + continuous-examples.rst diff --git a/docs/cuopt/source/cuopt-c/index.rst b/docs/cuopt/source/cuopt-c/index.rst index 6b8aed243b..818c122942 100644 --- a/docs/cuopt/source/cuopt-c/index.rst +++ b/docs/cuopt/source/cuopt-c/index.rst @@ -13,8 +13,16 @@ NVIDIA cuOpt supports a C API for GPU-accelerated optimization that enables user .. toctree:: :maxdepth: 3 - :caption: LP, QP and MILP Optimization - :name: LP, QP and MILP Optimization + :caption: Continuous Optimization (LP/QP/SOCP) + :name: Continuous Optimization C API :titlesonly: - Continuous Optimization and MIP + Continuous Optimization + +.. toctree:: + :maxdepth: 3 + :caption: Mixed Integer Programming (MIP) + :name: MIP C API Index + :titlesonly: + + MIP diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/index.rst b/docs/cuopt/source/cuopt-c/lp-qp-milp/index.rst deleted file mode 100644 index 17b7369bf1..0000000000 --- a/docs/cuopt/source/cuopt-c/lp-qp-milp/index.rst +++ /dev/null @@ -1,24 +0,0 @@ -Continuous Optimization and MIP -================================ - -This section contains details on the cuOpt LP/QP/SOCP/MILP C API. - -.. toctree:: - :maxdepth: 3 - :caption: Continuous Optimization (LP/QP/SOCP) - :name: LP/QP/SOCP C API - :titlesonly: - - continuous-c-api.rst - ../../continuous-settings.rst - continuous-examples.rst - -.. toctree:: - :maxdepth: 3 - :caption: Mixed Integer Programming (MIP) - :name: MIP C API - :titlesonly: - - mip-c-api.rst - ../../mip-settings.rst - mip-examples.rst diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/examples/milp_mps_example.c b/docs/cuopt/source/cuopt-c/mip/examples/milp_mps_example.c similarity index 100% rename from docs/cuopt/source/cuopt-c/lp-qp-milp/examples/milp_mps_example.c rename to docs/cuopt/source/cuopt-c/mip/examples/milp_mps_example.c diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/examples/mip_sample.mps b/docs/cuopt/source/cuopt-c/mip/examples/mip_sample.mps similarity index 100% rename from docs/cuopt/source/cuopt-c/lp-qp-milp/examples/mip_sample.mps rename to docs/cuopt/source/cuopt-c/mip/examples/mip_sample.mps diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/examples/simple_milp_example.c b/docs/cuopt/source/cuopt-c/mip/examples/simple_milp_example.c similarity index 100% rename from docs/cuopt/source/cuopt-c/lp-qp-milp/examples/simple_milp_example.c rename to docs/cuopt/source/cuopt-c/mip/examples/simple_milp_example.c diff --git a/docs/cuopt/source/cuopt-c/mip/index.rst b/docs/cuopt/source/cuopt-c/mip/index.rst new file mode 100644 index 0000000000..525e29cacd --- /dev/null +++ b/docs/cuopt/source/cuopt-c/mip/index.rst @@ -0,0 +1,14 @@ +MIP (Mixed Integer Programming) +================================ + +This section contains details on the cuOpt MIP C API. + +.. toctree:: + :maxdepth: 3 + :caption: MIP C API + :name: MIP C API + :titlesonly: + + mip-c-api.rst + ../../mip-settings.rst + mip-examples.rst diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/mip-c-api.rst b/docs/cuopt/source/cuopt-c/mip/mip-c-api.rst similarity index 100% rename from docs/cuopt/source/cuopt-c/lp-qp-milp/mip-c-api.rst rename to docs/cuopt/source/cuopt-c/mip/mip-c-api.rst diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/mip-examples.rst b/docs/cuopt/source/cuopt-c/mip/mip-examples.rst similarity index 100% rename from docs/cuopt/source/cuopt-c/lp-qp-milp/mip-examples.rst rename to docs/cuopt/source/cuopt-c/mip/mip-examples.rst diff --git a/docs/cuopt/source/cuopt-grpc/examples.rst b/docs/cuopt/source/cuopt-grpc/examples.rst index a17816fb48..ccd8860942 100644 --- a/docs/cuopt/source/cuopt-grpc/examples.rst +++ b/docs/cuopt/source/cuopt-grpc/examples.rst @@ -27,16 +27,16 @@ Where to find examples Python (LP / QP / MILP) ----------------------- -* :doc:`../cuopt-python/lp-qp-milp/continuous-examples` — runnable Python samples (LP, QP). With ``CUOPT_REMOTE_HOST`` and ``CUOPT_REMOTE_PORT`` set on the client, solves go to the remote server automatically. -* :doc:`../cuopt-python/lp-qp-milp/mip-examples` — runnable Python samples (MILP). With ``CUOPT_REMOTE_HOST`` and ``CUOPT_REMOTE_PORT`` set on the client, solves go to the remote server automatically. +* :doc:`../cuopt-python/continuous/continuous-examples` — runnable Python samples (LP, QP). With ``CUOPT_REMOTE_HOST`` and ``CUOPT_REMOTE_PORT`` set on the client, solves go to the remote server automatically. +* :doc:`../cuopt-python/mip/mip-examples` — runnable Python samples (MILP). With ``CUOPT_REMOTE_HOST`` and ``CUOPT_REMOTE_PORT`` set on the client, solves go to the remote server automatically. C API (LP / QP / MILP) ---------------------- -* :doc:`../cuopt-c/lp-qp-milp/continuous-examples` — LP and QP C examples. -* :doc:`../cuopt-c/lp-qp-milp/mip-examples` — MILP C examples. +* :doc:`../cuopt-c/continuous/continuous-examples` — LP and QP C examples. +* :doc:`../cuopt-c/mip/mip-examples` — MILP C examples. - Compile and run these programs with the same exports in the shell; ``solve_lp`` / ``solve_mip`` use gRPC when both remote variables are set (see :doc:`../cuopt-c/lp-qp-milp/continuous-c-api` for API reference). + Compile and run these programs with the same exports in the shell; ``solve_lp`` / ``solve_mip`` use gRPC when both remote variables are set (see :doc:`../cuopt-c/continuous/continuous-c-api` for API reference). ``cuopt_cli`` ------------- diff --git a/docs/cuopt/source/cuopt-grpc/quick-start.rst b/docs/cuopt/source/cuopt-grpc/quick-start.rst index 360447a0da..44ccb548f8 100644 --- a/docs/cuopt/source/cuopt-grpc/quick-start.rst +++ b/docs/cuopt/source/cuopt-grpc/quick-start.rst @@ -143,7 +143,7 @@ To solve **locally** with the same file: More options (time limits, relaxation): :doc:`../cuopt-cli/quick-start` and :doc:`examples`. -**C API** — With the same environment variables set, call ``solve_lp`` / ``solve_mip`` as in :doc:`../cuopt-c/lp-qp-milp/continuous-c-api`. +**C API** — With the same environment variables set, call ``solve_lp`` / ``solve_mip`` as in :doc:`../cuopt-c/continuous/continuous-c-api`. More patterns (MPS variants, custom gRPC): :doc:`examples`. diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/continuous-api.rst b/docs/cuopt/source/cuopt-python/continuous/continuous-api.rst similarity index 100% rename from docs/cuopt/source/cuopt-python/lp-qp-milp/continuous-api.rst rename to docs/cuopt/source/cuopt-python/continuous/continuous-api.rst diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/continuous-examples.rst b/docs/cuopt/source/cuopt-python/continuous/continuous-examples.rst similarity index 100% rename from docs/cuopt/source/cuopt-python/lp-qp-milp/continuous-examples.rst rename to docs/cuopt/source/cuopt-python/continuous/continuous-examples.rst diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/examples/expressions_constraints_example.py b/docs/cuopt/source/cuopt-python/continuous/examples/expressions_constraints_example.py similarity index 100% rename from docs/cuopt/source/cuopt-python/lp-qp-milp/examples/expressions_constraints_example.py rename to docs/cuopt/source/cuopt-python/continuous/examples/expressions_constraints_example.py diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/examples/pdlp_warmstart_example.py b/docs/cuopt/source/cuopt-python/continuous/examples/pdlp_warmstart_example.py similarity index 100% rename from docs/cuopt/source/cuopt-python/lp-qp-milp/examples/pdlp_warmstart_example.py rename to docs/cuopt/source/cuopt-python/continuous/examples/pdlp_warmstart_example.py diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/examples/production_planning_example.py b/docs/cuopt/source/cuopt-python/continuous/examples/production_planning_example.py similarity index 100% rename from docs/cuopt/source/cuopt-python/lp-qp-milp/examples/production_planning_example.py rename to docs/cuopt/source/cuopt-python/continuous/examples/production_planning_example.py diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/examples/qp_matrix_example.py b/docs/cuopt/source/cuopt-python/continuous/examples/qp_matrix_example.py similarity index 100% rename from docs/cuopt/source/cuopt-python/lp-qp-milp/examples/qp_matrix_example.py rename to docs/cuopt/source/cuopt-python/continuous/examples/qp_matrix_example.py diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/examples/simple_lp_example.py b/docs/cuopt/source/cuopt-python/continuous/examples/simple_lp_example.py similarity index 100% rename from docs/cuopt/source/cuopt-python/lp-qp-milp/examples/simple_lp_example.py rename to docs/cuopt/source/cuopt-python/continuous/examples/simple_lp_example.py diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/examples/simple_qp_example.py b/docs/cuopt/source/cuopt-python/continuous/examples/simple_qp_example.py similarity index 100% rename from docs/cuopt/source/cuopt-python/lp-qp-milp/examples/simple_qp_example.py rename to docs/cuopt/source/cuopt-python/continuous/examples/simple_qp_example.py diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/examples/solution_example.py b/docs/cuopt/source/cuopt-python/continuous/examples/solution_example.py similarity index 100% rename from docs/cuopt/source/cuopt-python/lp-qp-milp/examples/solution_example.py rename to docs/cuopt/source/cuopt-python/continuous/examples/solution_example.py diff --git a/docs/cuopt/source/cuopt-python/continuous/index.rst b/docs/cuopt/source/cuopt-python/continuous/index.rst new file mode 100644 index 0000000000..dd2727f046 --- /dev/null +++ b/docs/cuopt/source/cuopt-python/continuous/index.rst @@ -0,0 +1,13 @@ +Continuous Optimization (LP/QP/SOCP) +===================================== + +This section contains details on the cuOpt LP/QP/SOCP Python API. + +.. toctree:: + :maxdepth: 3 + :caption: LP/QP/SOCP Python API + :name: LP/QP/SOCP Python API + :titlesonly: + + continuous-api.rst + continuous-examples.rst diff --git a/docs/cuopt/source/cuopt-python/index.rst b/docs/cuopt/source/cuopt-python/index.rst index b39a8d5d79..34ba1867a6 100644 --- a/docs/cuopt/source/cuopt-python/index.rst +++ b/docs/cuopt/source/cuopt-python/index.rst @@ -26,8 +26,16 @@ This section contains details on the cuOpt Python package. .. toctree:: :maxdepth: 3 - :caption: Continuous Optimization and MIP - :name: Continuous Optimization and MIP Python API + :caption: Continuous Optimization (LP/QP/SOCP) + :name: Continuous Optimization Python API :titlesonly: - Continuous Optimization and MIP + Continuous Optimization + +.. toctree:: + :maxdepth: 3 + :caption: Mixed Integer Programming (MIP) + :name: MIP Python API Index + :titlesonly: + + MIP diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/index.rst b/docs/cuopt/source/cuopt-python/lp-qp-milp/index.rst deleted file mode 100644 index 7b928b408d..0000000000 --- a/docs/cuopt/source/cuopt-python/lp-qp-milp/index.rst +++ /dev/null @@ -1,22 +0,0 @@ -Continuous Optimization and MIP Python API -============================================ - -This section contains details on the cuOpt LP/QP/SOCP/MILP Python API. - -.. toctree:: - :maxdepth: 3 - :caption: Continuous Optimization (LP/QP/SOCP) - :name: LP/QP/SOCP Python API - :titlesonly: - - continuous-api.rst - continuous-examples.rst - -.. toctree:: - :maxdepth: 3 - :caption: Mixed Integer Programming (MIP) - :name: MIP Python API - :titlesonly: - - mip-api.rst - mip-examples.rst diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/examples/incumbent_solutions_example.py b/docs/cuopt/source/cuopt-python/mip/examples/incumbent_solutions_example.py similarity index 100% rename from docs/cuopt/source/cuopt-python/lp-qp-milp/examples/incumbent_solutions_example.py rename to docs/cuopt/source/cuopt-python/mip/examples/incumbent_solutions_example.py diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/examples/semi_continuous_example.py b/docs/cuopt/source/cuopt-python/mip/examples/semi_continuous_example.py similarity index 100% rename from docs/cuopt/source/cuopt-python/lp-qp-milp/examples/semi_continuous_example.py rename to docs/cuopt/source/cuopt-python/mip/examples/semi_continuous_example.py diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/examples/simple_milp_example.py b/docs/cuopt/source/cuopt-python/mip/examples/simple_milp_example.py similarity index 100% rename from docs/cuopt/source/cuopt-python/lp-qp-milp/examples/simple_milp_example.py rename to docs/cuopt/source/cuopt-python/mip/examples/simple_milp_example.py diff --git a/docs/cuopt/source/cuopt-python/mip/index.rst b/docs/cuopt/source/cuopt-python/mip/index.rst new file mode 100644 index 0000000000..97ef5711a9 --- /dev/null +++ b/docs/cuopt/source/cuopt-python/mip/index.rst @@ -0,0 +1,13 @@ +MIP (Mixed Integer Programming) +================================ + +This section contains details on the cuOpt MIP Python API. + +.. toctree:: + :maxdepth: 3 + :caption: MIP Python API + :name: MIP Python API + :titlesonly: + + mip-api.rst + mip-examples.rst diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/mip-api.rst b/docs/cuopt/source/cuopt-python/mip/mip-api.rst similarity index 100% rename from docs/cuopt/source/cuopt-python/lp-qp-milp/mip-api.rst rename to docs/cuopt/source/cuopt-python/mip/mip-api.rst diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/mip-examples.rst b/docs/cuopt/source/cuopt-python/mip/mip-examples.rst similarity index 100% rename from docs/cuopt/source/cuopt-python/lp-qp-milp/mip-examples.rst rename to docs/cuopt/source/cuopt-python/mip/mip-examples.rst diff --git a/docs/cuopt/source/mip-settings.rst b/docs/cuopt/source/mip-settings.rst index f767aaf4d9..99191fa41b 100644 --- a/docs/cuopt/source/mip-settings.rst +++ b/docs/cuopt/source/mip-settings.rst @@ -3,7 +3,7 @@ MIP Settings ============ -This page describes the parameter settings available for cuOpt's MIP solver. These parameters are set as :ref:`parameter constants ` in case of C API and in case of Server Thin client as raw strings. Please refer to examples in :doc:`C ` and :doc:`Server Thin client ` for more details. +This page describes the parameter settings available for cuOpt's MIP solver. These parameters are set as :ref:`parameter constants ` in case of C API and in case of Server Thin client as raw strings. Please refer to examples in :doc:`C ` and :doc:`Server Thin client ` for more details. .. note:: When setting parameters in thin client solver settings, remove ``CUOPT_`` from the parameter name and convert to lowercase. For example, ``CUOPT_TIME_LIMIT`` would be set as ``time_limit``. From 8b888226386f0bdbf9d24793507a0e8a1134a09a Mon Sep 17 00:00:00 2001 From: Rajesh Gandham Date: Fri, 29 May 2026 16:42:26 -0400 Subject: [PATCH 09/13] Fix SOCP docs: users specify QCQP form, not cone constraints directly 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 --- docs/cuopt/source/continuous-features.rst | 25 +++++++++---------- .../cuopt-c/continuous/continuous-c-api.rst | 8 +++--- 2 files changed, 16 insertions(+), 17 deletions(-) diff --git a/docs/cuopt/source/continuous-features.rst b/docs/cuopt/source/continuous-features.rst index 487cdf4dfc..8e00a1fb01 100644 --- a/docs/cuopt/source/continuous-features.rst +++ b/docs/cuopt/source/continuous-features.rst @@ -73,29 +73,27 @@ where Q is a symmetric positive semidefinite matrix. Please note that the Q matr See :ref:`simple-qp-example-python` for an example of how to create a QP problem with the Python Modeling API. See :ref:`simple-qp-example-c` for an example of how to create a QP problem with the C API. -Second-Order Cone Programming (Beta) --------------------------------------- +Quadratically Constrained Programming / SOCP (Beta) +----------------------------------------------------- -.. note:: SOCP support is **beta** in this release. The API is functional but has not been fully hardened for all problem types and edge cases. +.. note:: QCQP/SOCP support is **beta** in this release. The API is functional but has not been fully hardened for all problem types and edge cases. -cuOpt supports Second-Order Cone Programming (SOCP) problems — problems with quadratic constraints of the form: +cuOpt supports problems with quadratic constraints (QCQP). Problems are specified in quadratic constraint form: .. code-block:: text - minimize c^T*x + minimize x^T*Q*x + c^T*x subject to A*x {<=, =, >=} b - ||Ax + b||_2 <= c^T*x + d (second-order cone constraints) + x^T*P_i*x + q_i^T*x {<=, >=} r_i (quadratic constraints) lb <= x <= ub -SOCP constraints are specified as quadratic constraints using ``<=`` or ``>=`` comparisons on a ``QuadraticExpression``. cuOpt automatically converts these quadratic constraints to second-order cone form internally. +cuOpt internally converts the quadratic constraints to second-order cone form and solves using the barrier method. Users do not specify cone constraints directly — all quadratic constraints are written in the standard QCQP form above. When any quadratic constraint is present, cuOpt automatically selects the barrier method and disables presolve optimizations that apply only to linear problems. **Constraints:** - Only ``<=`` and ``>=`` sense is supported for quadratic constraints. Equality quadratic constraints are not supported. -- The right-hand side of a quadratic constraint must be zero when the constraint is intended as a SOC constraint. -- Each second-order cone must have dimension at least 2. **Python example:** @@ -105,12 +103,13 @@ When any quadratic constraint is present, cuOpt automatically selects the barrie y = problem.addVariable("y", lb=0) z = problem.addVariable("z", lb=0) - # ||[x, y]||_2 <= z written as x*x + y*y - z*z <= 0 - problem.addConstraint(x*x + y*y - z*z <= 0, name="soc") + # Quadratic constraint: x^2 + y^2 - z^2 <= 0 + # cuOpt converts this to second-order cone form internally + problem.addConstraint(x*x + y*y - z*z <= 0, name="qc") -**C API:** Use :c:func:`cuOptAddQuadraticConstraint` to add quadratic constraints. The solver automatically detects and handles SOC structure. +**C API:** Use :c:func:`cuOptAddQuadraticConstraint` to add quadratic constraints. cuOpt automatically converts them to second-order cone form internally. -.. note:: SOCP problems always use the barrier solver regardless of the ``CUOPT_METHOD`` setting. +.. note:: QCQP problems always use the barrier solver regardless of the ``CUOPT_METHOD`` setting. Warm Start ----------- diff --git a/docs/cuopt/source/cuopt-c/continuous/continuous-c-api.rst b/docs/cuopt/source/cuopt-c/continuous/continuous-c-api.rst index ac4e21173e..0396688fc0 100644 --- a/docs/cuopt/source/cuopt-c/continuous/continuous-c-api.rst +++ b/docs/cuopt/source/cuopt-c/continuous/continuous-c-api.rst @@ -64,10 +64,10 @@ after creating a linear problem: .. doxygenfunction:: cuOptAddQuadraticConstraint .. note:: - ``cuOptAddQuadraticConstraint`` also enables **Second-Order Cone Programming (SOCP)** - support **(beta)**. When one or more quadratic constraints are present, cuOpt automatically - converts them to second-order cone form and selects the barrier solver. Only ``CUOPT_LESS_THAN`` - and ``CUOPT_GREATER_THAN`` sense is supported; equality quadratic constraints are not supported. + ``cuOptAddQuadraticConstraint`` enables **QCQP/SOCP (beta)** support. Quadratic constraints + are specified in standard QCQP form; cuOpt internally converts them to second-order cone form + and selects the barrier solver. Only ``CUOPT_LESS_THAN`` and ``CUOPT_GREATER_THAN`` sense is + supported; equality quadratic constraints are not supported. A optimization problem must be destroyed with the following function From 0dd669b578222153896f8487e74666cccae19a4b Mon Sep 17 00:00:00 2001 From: Rajesh Gandham Date: Fri, 29 May 2026 16:43:17 -0400 Subject: [PATCH 10/13] Remove redundant beta note text in QCQP/SOCP section Co-Authored-By: Claude Sonnet 4.6 --- docs/cuopt/source/continuous-features.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cuopt/source/continuous-features.rst b/docs/cuopt/source/continuous-features.rst index 8e00a1fb01..7c0d7b37e3 100644 --- a/docs/cuopt/source/continuous-features.rst +++ b/docs/cuopt/source/continuous-features.rst @@ -76,7 +76,7 @@ See :ref:`simple-qp-example-c` for an example of how to create a QP problem with Quadratically Constrained Programming / SOCP (Beta) ----------------------------------------------------- -.. note:: QCQP/SOCP support is **beta** in this release. The API is functional but has not been fully hardened for all problem types and edge cases. +.. note:: QCQP/SOCP support is **beta** in this release. cuOpt supports problems with quadratic constraints (QCQP). Problems are specified in quadratic constraint form: From 69c52becfbe3b532b8bcd734b868786092c3f027 Mon Sep 17 00:00:00 2001 From: Rajesh Gandham Date: Fri, 29 May 2026 16:44:40 -0400 Subject: [PATCH 11/13] Clarify SOCP docs: SOC-structured quadratic inequalities only, not general 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 --- docs/cuopt/source/continuous-features.rst | 32 +++++++++++-------- .../cuopt-c/continuous/continuous-c-api.rst | 9 +++--- 2 files changed, 23 insertions(+), 18 deletions(-) diff --git a/docs/cuopt/source/continuous-features.rst b/docs/cuopt/source/continuous-features.rst index 7c0d7b37e3..798e468adf 100644 --- a/docs/cuopt/source/continuous-features.rst +++ b/docs/cuopt/source/continuous-features.rst @@ -73,29 +73,34 @@ where Q is a symmetric positive semidefinite matrix. Please note that the Q matr See :ref:`simple-qp-example-python` for an example of how to create a QP problem with the Python Modeling API. See :ref:`simple-qp-example-c` for an example of how to create a QP problem with the C API. -Quadratically Constrained Programming / SOCP (Beta) ------------------------------------------------------ +Second-Order Cone Programming (Beta) +-------------------------------------- -.. note:: QCQP/SOCP support is **beta** in this release. +.. note:: SOCP support is **beta** in this release. -cuOpt supports problems with quadratic constraints (QCQP). Problems are specified in quadratic constraint form: +cuOpt supports Second-Order Cone Programming (SOCP) problems of the form: .. code-block:: text - minimize x^T*Q*x + c^T*x + minimize c^T*x subject to A*x {<=, =, >=} b - x^T*P_i*x + q_i^T*x {<=, >=} r_i (quadratic constraints) + ||u_i||_2 <= t_i (second-order cone constraints) lb <= x <= ub -cuOpt internally converts the quadratic constraints to second-order cone form and solves using the barrier method. Users do not specify cone constraints directly — all quadratic constraints are written in the standard QCQP form above. +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. + +.. note:: + Only SOC-structured quadratic inequalities are supported. General quadratic constraints + (arbitrary quadratic forms) are not supported. When any quadratic constraint is present, cuOpt automatically selects the barrier method and disables presolve optimizations that apply only to linear problems. **Constraints:** -- Only ``<=`` and ``>=`` sense is supported for quadratic constraints. Equality quadratic constraints are not supported. +- Only ``<=`` and ``>=`` sense is supported. Equality quadratic constraints are not supported. +- The quadratic constraint must have valid second-order cone structure. -**Python example:** +**Python example** — expressing ``||[x, y]||_2 <= z`` as a quadratic inequality: .. code-block:: python @@ -103,13 +108,12 @@ When any quadratic constraint is present, cuOpt automatically selects the barrie y = problem.addVariable("y", lb=0) z = problem.addVariable("z", lb=0) - # Quadratic constraint: x^2 + y^2 - z^2 <= 0 - # cuOpt converts this to second-order cone form internally - problem.addConstraint(x*x + y*y - z*z <= 0, name="qc") + # SOC constraint ||[x,y]||_2 <= z expressed as x^2 + y^2 - z^2 <= 0 + problem.addConstraint(x*x + y*y - z*z <= 0, name="soc") -**C API:** Use :c:func:`cuOptAddQuadraticConstraint` to add quadratic constraints. cuOpt automatically converts them to second-order cone form internally. +**C API:** Use :c:func:`cuOptAddQuadraticConstraint` to add SOC constraints expressed as quadratic inequalities. cuOpt detects the SOC structure and converts to cone form internally. -.. note:: QCQP problems always use the barrier solver regardless of the ``CUOPT_METHOD`` setting. +.. note:: SOCP problems always use the barrier solver regardless of the ``CUOPT_METHOD`` setting. Warm Start ----------- diff --git a/docs/cuopt/source/cuopt-c/continuous/continuous-c-api.rst b/docs/cuopt/source/cuopt-c/continuous/continuous-c-api.rst index 0396688fc0..851a11ba6f 100644 --- a/docs/cuopt/source/cuopt-c/continuous/continuous-c-api.rst +++ b/docs/cuopt/source/cuopt-c/continuous/continuous-c-api.rst @@ -64,10 +64,11 @@ after creating a linear problem: .. doxygenfunction:: cuOptAddQuadraticConstraint .. note:: - ``cuOptAddQuadraticConstraint`` enables **QCQP/SOCP (beta)** support. Quadratic constraints - are specified in standard QCQP form; cuOpt internally converts them to second-order cone form - and selects the barrier solver. Only ``CUOPT_LESS_THAN`` and ``CUOPT_GREATER_THAN`` sense is - supported; equality quadratic constraints are not supported. + ``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 + SOC structure and converts to cone form internally, then selects the barrier solver. Only + ``CUOPT_LESS_THAN`` and ``CUOPT_GREATER_THAN`` sense is supported; equality constraints and + general quadratic constraints are not supported. A optimization problem must be destroyed with the following function From cc4ac1d45b9ba7dab2bcf1fbd4c402dae9bf1cdd Mon Sep 17 00:00:00 2001 From: Rajesh Gandham Date: Fri, 29 May 2026 19:40:15 -0400 Subject: [PATCH 12/13] Update third-party modeling language support table 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 --- docs/cuopt/source/continuous-features.rst | 31 ++++++++++++++++++----- 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/docs/cuopt/source/continuous-features.rst b/docs/cuopt/source/continuous-features.rst index 798e468adf..5bf80bfee5 100644 --- a/docs/cuopt/source/continuous-features.rst +++ b/docs/cuopt/source/continuous-features.rst @@ -7,16 +7,35 @@ Availability The Linear Programming (LP), Quadratic Programming (QP), and Second-Order Cone Programming (SOCP) solvers can be accessed in the following ways: -- **Third-Party Modeling Languages**: cuOpt's LP solver can be called directly from the following third-party modeling languages. This allows you to leverage GPU acceleration while maintaining your existing optimization workflow in these modeling languages. +- **Third-Party Modeling Languages**: cuOpt's LP/QP solver can be called directly from the following third-party modeling languages. This allows you to leverage GPU acceleration while maintaining your existing optimization workflow in these modeling languages. Supported modeling languages: - - AMPL - - GAMS - - PuLP - - JuMP + + .. list-table:: + :header-rows: 1 + :widths: 30 15 15 + + * - Language + - LP + - QP + * - AMPL + - ✓ + - + * - CVXPY + - ✓ + - ✓ + * - GAMS + - ✓ + - + * - JuMP + - ✓ + - ✓ + * - PuLP + - ✓ + - .. note:: - The QP and SOCP solvers are not currently supported in third-party modeling languages. + SOCP is not currently supported in third-party modeling languages. - **C API**: A native C API that provides direct low-level access to cuOpt's LP/QP/SOCP capabilities, enabling integration into any application or system that can interface with C. From 0e7368da29d578740ba7ca00503e7e7249a0f3dd Mon Sep 17 00:00:00 2001 From: Rajesh Gandham Date: Fri, 29 May 2026 19:43:27 -0400 Subject: [PATCH 13/13] Add QP support for GAMS in modeling language table Co-Authored-By: Claude Sonnet 4.6 --- docs/cuopt/source/continuous-features.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cuopt/source/continuous-features.rst b/docs/cuopt/source/continuous-features.rst index 5bf80bfee5..06ac2bdaf4 100644 --- a/docs/cuopt/source/continuous-features.rst +++ b/docs/cuopt/source/continuous-features.rst @@ -26,7 +26,7 @@ The Linear Programming (LP), Quadratic Programming (QP), and Second-Order Cone P - ✓ * - GAMS - ✓ - - + - ✓ * - JuMP - ✓ - ✓