diff --git a/docs/cuopt/source/lp-qp-features.rst b/docs/cuopt/source/continuous-features.rst similarity index 73% rename from docs/cuopt/source/lp-qp-features.rst rename to docs/cuopt/source/continuous-features.rst index bf9ff574c6..06ac2bdaf4 100644 --- a/docs/cuopt/source/lp-qp-features.rst +++ b/docs/cuopt/source/continuous-features.rst @@ -1,26 +1,45 @@ -================== -LP/QP Features -================== +======================== +LP/QP/SOCP Features +======================== Availability ------------- -The Linear Programming (LP) and Quadratic Programming (QP) solvers can be accessed in the following ways: +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 solver is 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 capabilities, enabling integration into any application or system that can interface with C. +- **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 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`. +- **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. @@ -73,6 +92,48 @@ 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. + +cuOpt supports Second-Order Cone Programming (SOCP) problems of the form: + +.. code-block:: text + + minimize c^T*x + subject to A*x {<=, =, >=} b + ||u_i||_2 <= t_i (second-order cone constraints) + lb <= x <= ub + +Because cuOpt does not accept cone constraints directly, SOC constraints are specified through the quadratic constraint API. Each SOC constraint ``||u||_2 <= t`` is expressed as the equivalent quadratic inequality ``u^T*u - t^2 <= 0``. cuOpt detects the SOC structure and converts to cone form internally before solving with the barrier method. + +.. 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. Equality quadratic constraints are not supported. +- The quadratic constraint must have valid second-order cone structure. + +**Python example** — expressing ``||[x, y]||_2 <= z`` as a quadratic inequality: + +.. code-block:: python + + x = problem.addVariable("x", lb=0) + y = problem.addVariable("y", lb=0) + z = problem.addVariable("z", lb=0) + + # 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 SOC constraints expressed as quadratic inequalities. cuOpt detects the SOC structure and converts to cone form internally. + +.. note:: SOCP problems always use the barrier solver regardless of the ``CUOPT_METHOD`` setting. + Warm Start ----------- @@ -117,7 +178,7 @@ Crossover allows you to obtain a high-quality basic solution from the results of 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. +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. diff --git a/docs/cuopt/source/lp-qp-milp-settings.rst b/docs/cuopt/source/continuous-settings.rst similarity index 66% rename from docs/cuopt/source/lp-qp-milp-settings.rst rename to docs/cuopt/source/continuous-settings.rst index 985204e1b2..05adda71e1 100644 --- a/docs/cuopt/source/lp-qp-milp-settings.rst +++ b/docs/cuopt/source/continuous-settings.rst @@ -1,16 +1,15 @@ -================================= -LP, QP, and MILP Settings -================================= +================================================ +Continuous Optimization Settings (LP, QP, SOCP) +================================================ -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. +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``. -Parameters common to LP/MILP ----------------------------- +Common Parameters +----------------- We begin by describing parameters common to both the MILP and LP solvers @@ -66,10 +65,6 @@ 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 @@ -375,184 +370,36 @@ The duality gap is computed as follows:: .. note:: The default value is ``1e-4``. +Primal Infeasibility Tolerance +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -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. +``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. -Cut Passes -^^^^^^^^^^ +.. note:: The default value is ``1e-8``. -``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. +Dual Infeasibility Tolerance +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. note:: The default value is ``10``. +``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. -Mixed Integer Rounding Cuts -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. note:: The default value is ``1e-8``. -``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. +Barrier Iterative Refinement +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. note:: The default value is ``-1`` (automatic). +``CUOPT_BARRIER_ITERATIVE_REFINEMENT`` controls whether iterative refinement is applied after each barrier iteration to improve solution accuracy. -Mixed Integer Gomory Cuts -^^^^^^^^^^^^^^^^^^^^^^^^^ +* ``0`` (``CUOPT_BARRIER_ITERATIVE_REFINEMENT_OFF``): Disable iterative refinement (default). +* ``1`` (``CUOPT_BARRIER_ITERATIVE_REFINEMENT_ON``): Enable iterative refinement. -``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). +.. note:: The default value is ``0`` (off). -Batch PDLP Strong Branching -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Barrier Step Scale +^^^^^^^^^^^^^^^^^^^ -``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. +``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:: The default value is ``0`` (disabled). This setting is ignored if the problem is not a MIP problem. +.. note:: By default cuOpt selects the step scale automatically. diff --git a/docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rst b/docs/cuopt/source/cuopt-c/continuous/continuous-c-api.rst similarity index 81% rename from docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rst rename to docs/cuopt/source/cuopt-c/continuous/continuous-c-api.rst index ea9bf30925..851a11ba6f 100644 --- a/docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-milp-c-api.rst +++ b/docs/cuopt/source/cuopt-c/continuous/continuous-c-api.rst @@ -1,7 +1,7 @@ -cuOpt LP/QP/MILP C API Reference +cuOpt LP/QP/SOCP C API Reference ======================================== -This section contains the cuOpt LP/QP/MILP 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 --------------------------------- @@ -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, loaded, or written via the following functions .. doxygenfunction:: cuOptReadProblem +.. doxygenfunction:: cuOptWriteProblem .. doxygenfunction:: cuOptCreateProblem .. doxygenfunction:: cuOptCreateRangedProblem .. doxygenfunction:: cuOptCreateQuadraticProblem @@ -56,12 +57,19 @@ Optimization problems can be created via five different 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`` 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 .. doxygenfunction:: cuOptDestroyProblem @@ -101,6 +109,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 -------------------------------- @@ -142,7 +157,7 @@ When you are done with a solve you should destroy a `cuOptSolverSettings` object 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. +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 @@ -156,9 +171,9 @@ The following functions are used to set and get parameters. You can find more de 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. +These constants are used as parameter names in the :c:func:`cuOptSetParameter`, :c:func:`cuOptGetParameter`, and similar functions. For more details on the available parameters, see the :doc:`Continuous Optimization settings <../../continuous-settings>` and :doc:`MIP settings <../../mip-settings>` sections. -.. LP/MIP parameter string constants +.. LP/QP parameter string constants .. doxygendefine:: CUOPT_ABSOLUTE_DUAL_TOLERANCE .. doxygendefine:: CUOPT_RELATIVE_DUAL_TOLERANCE .. doxygendefine:: CUOPT_ABSOLUTE_PRIMAL_TOLERANCE @@ -171,23 +186,13 @@ 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_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_PRESOLVE -.. doxygendefine:: CUOPT_MIP_PROBING .. doxygendefine:: CUOPT_LOG_TO_CONSOLE .. doxygendefine:: CUOPT_CROSSOVER .. doxygendefine:: CUOPT_FOLDING @@ -197,9 +202,12 @@ 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_PDLP_PRECISION @@ -239,6 +247,29 @@ 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 + +.. _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 @@ -290,4 +321,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-c/lp-qp-milp/lp-qp-example.rst b/docs/cuopt/source/cuopt-c/continuous/continuous-examples.rst similarity index 99% rename from docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-example.rst rename to docs/cuopt/source/cuopt-c/continuous/continuous-examples.rst index d4b981719c..1bfb1156c1 100644 --- a/docs/cuopt/source/cuopt-c/lp-qp-milp/lp-qp-example.rst +++ b/docs/cuopt/source/cuopt-c/continuous/continuous-examples.rst @@ -6,7 +6,7 @@ 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 `. +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 `): 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 9f424cdcb9..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: - LP, QP and MILP + 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 57de6053a5..0000000000 --- a/docs/cuopt/source/cuopt-c/lp-qp-milp/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -Linear Programming -================== - -This section contains details on the cuOpt LP/QP/MILP C API. - -.. toctree:: - :maxdepth: 3 - :caption: LP/QP/MILP - :name: LP/QP/MILP - :titlesonly: - - lp-qp-milp-c-api.rst - ../../lp-qp-milp-settings.rst - lp-qp-example.rst - milp-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/mip/mip-c-api.rst b/docs/cuopt/source/cuopt-c/mip/mip-c-api.rst new file mode 100644 index 0000000000..1870b8d5ec --- /dev/null +++ b/docs/cuopt/source/cuopt-c/mip/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/milp-examples.rst b/docs/cuopt/source/cuopt-c/mip/mip-examples.rst similarity index 98% rename from docs/cuopt/source/cuopt-c/lp-qp-milp/milp-examples.rst rename to docs/cuopt/source/cuopt-c/mip/mip-examples.rst index a6d446d4b3..0d925677a6 100644 --- a/docs/cuopt/source/cuopt-c/lp-qp-milp/milp-examples.rst +++ b/docs/cuopt/source/cuopt-c/mip/mip-examples.rst @@ -5,7 +5,7 @@ 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 `. +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 `): 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..ccd8860942 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/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/lp-qp-example` — LP and QP C examples. -* :doc:`../cuopt-c/lp-qp-milp/milp-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/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/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 b3c0ca2cc1..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/lp-qp-milp-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/lp-qp-milp-api.rst b/docs/cuopt/source/cuopt-python/continuous/continuous-api.rst similarity index 70% rename from docs/cuopt/source/cuopt-python/lp-qp-milp/lp-qp-milp-api.rst rename to docs/cuopt/source/cuopt-python/continuous/continuous-api.rst index 609e11b34b..e0a4fb672c 100644 --- a/docs/cuopt/source/cuopt-python/lp-qp-milp/lp-qp-milp-api.rst +++ b/docs/cuopt/source/cuopt-python/continuous/continuous-api.rst @@ -1,11 +1,11 @@ ============================= -LP, QP and MILP API Reference +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, 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: @@ -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: @@ -30,12 +31,6 @@ LP, QP and MILP API Reference :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 diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/lp-qp-milp-examples.rst b/docs/cuopt/source/cuopt-python/continuous/continuous-examples.rst similarity index 59% rename from docs/cuopt/source/cuopt-python/lp-qp-milp/lp-qp-milp-examples.rst rename to docs/cuopt/source/cuopt-python/continuous/continuous-examples.rst index 8237a560df..e4ad75f4e7 100644 --- a/docs/cuopt/source/cuopt-python/lp-qp-milp/lp-qp-milp-examples.rst +++ b/docs/cuopt/source/cuopt-python/continuous/continuous-examples.rst @@ -1,12 +1,12 @@ ======================== -LP, QP and MILP Examples +LP, QP and SOCP Examples ======================== -This section contains examples of how to use the cuOpt linear programming, quadratic programming and mixed integer linear programming Python API. +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 linear programming, quadratic programming and mixed integer linear programming Python API. For more examples, please refer to the `cuopt-examples GitHub repository `_. + 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 @@ -49,44 +49,6 @@ The response is as follows: 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 ------------------------------------- @@ -167,36 +129,6 @@ The response is as follows: 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 -------------------------------- 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 49b805a801..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: Linear Programming, Quadratic Programming and Mixed Integer Linear Programming - :name: LP, QP and MILP API + :caption: Continuous Optimization (LP/QP/SOCP) + :name: Continuous Optimization Python API :titlesonly: - LP, QP and MILP + 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 e7fb2f6445..0000000000 --- a/docs/cuopt/source/cuopt-python/lp-qp-milp/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -============================================================================== -Linear Programming, Quadratic Programming and Mixed Integer Linear Programming -============================================================================== - -This section contains details on the cuOpt linear programming, quadratic programming and mixed integer linear programming Python API. - -.. toctree:: - :maxdepth: 3 - :caption: LP, QP and MILP - :name: LP, QP and MILP - :titlesonly: - - lp-qp-milp-api.rst - lp-qp-milp-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/mip/mip-api.rst b/docs/cuopt/source/cuopt-python/mip/mip-api.rst new file mode 100644 index 0000000000..c84707a2f7 --- /dev/null +++ b/docs/cuopt/source/cuopt-python/mip/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/mip/mip-examples.rst b/docs/cuopt/source/cuopt-python/mip/mip-examples.rst new file mode 100644 index 0000000000..a0e7b56644 --- /dev/null +++ b/docs/cuopt/source/cuopt-python/mip/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..99191fa41b --- /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 ------------------------------------