diff --git a/README.md b/README.md index f497d6b67..5cbdc8b63 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ -# cuOpt - GPU accelerated Optimization Engine + +# cuOpt - GPU-accelerated Optimization [![Build Status](https://github.com/NVIDIA/cuopt/actions/workflows/build.yaml/badge.svg)](https://github.com/NVIDIA/cuopt/actions/workflows/build.yaml) [![Version](https://img.shields.io/badge/version-26.02.00-blue)](https://github.com/NVIDIA/cuopt/releases) @@ -11,12 +12,15 @@ -NVIDIA® cuOpt™ is a GPU-accelerated optimization engine that excels in mixed integer linear programming (MILP), linear programming (LP), quadratic programming (QP) and vehicle routing problems (VRP). It enables near real-time solutions for large-scale challenges with millions of variables and constraints, offering -easy integration into existing solvers and seamless deployment across hybrid and multi-cloud environments. +NVIDIA® cuOpt™ is a GPU-accelerated optimization engine that excels in mixed integer linear programming (MILP), linear programming (LP), quadratic programming (QP), and vehicle routing problems (VRP). It enables near real-time solutions for large-scale LPs with millions of variables and constraints, and MIPs with hundreds of thousands of variables. cuOpt offers easy integration into existing modeling languages and seamless deployment across hybrid and multi-cloud environments. The core engine is written in C++ and wrapped with a C API, Python API and Server API. -For the latest stable version ensure you are on the `main` branch. +For the latest version, ensure you are on the `main` branch. + +## Latest Documentation + +[cuOpt Documentation](https://docs.nvidia.com/cuopt/user-guide/latest/introduction.html) ## Supported APIs @@ -153,6 +157,10 @@ cuOpt follows the RAPIDS release schedule and is part of the **"others"** catego For current release timelines and dates, refer to the [RAPIDS Maintainers Docs](https://docs.rapids.ai/maintainers/). +## For AI Coding Agents + +See [AGENTS.md](./AGENTS.md) for agent-specific guidelines. + ## Contributing Guide Review the [CONTRIBUTING.md](CONTRIBUTING.md) file for information on how to contribute code and issues to the project. diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md index 3112b56ec..752f11aac 100644 --- a/RELEASE-NOTES.md +++ b/RELEASE-NOTES.md @@ -1,6 +1,56 @@ # Release Notes - +## Release Notes 26.02 + +### New Features (26.02) + +- New parallel reliability branching inside MIP solver +- Mixed Integer Gomory, Mixed Integer Rounding, Knapsack and Strong Chvatal Gomory cuts are now added at root node +- Added an option to use batch PDLP when running strong branching at the root. Based on [Batched First-Order Methods for Parallel LP Solving in MIP](https://arxiv.org/abs/2601.21990) ([Nicolas Blin](https://github.com/Kh4ster), [Stefano Gualandi](https://github.com/stegua), [Christopher Maes](https://github.com/chris-maes), [Andrea Lodi](https://github.com/andrealodi), [Bartolomeo Stellato](https://github.com/bstellato)) +- Quadratic programming (QP) solver is now generally available (previously beta) +- New infeasibility detection option for PDLP's default solver mode Stable3 +- Solutions callbacks added to C API. Users can now retrieve the dual bound and pass in user data +- Multiple new diving techniques added for finding integer feasible solutions +- The [PSLP presolver](https://github.com/dance858/PSLP) is enabled by default for LP problems. Use the presolve option to select Papilo or disable +- Added a batch solve for routing to boost throughput for many similar instances +- Added experimental support for determinism in the parallel branch-and-bound solver. GPU heuristics are not supported yet in this mode + +### Breaking Changes (26.02) + +- The signatures of the solution callbacks have changed for the Python API +- To use PDLP warm start, presolve must now be explicitly disabled by setting `CUOPT_PRESOLVE=0`. Previously, presolve was disabled automatically + +### Improvements (26.02) + +- Improved primal/dual warm start for PDLP's default solver mode Stable3 +- Quadratic objectives can now be constructed via a matrix in Python API +- QP barrier now updates and solves augmented system on the GPU +- Improved performance for LP folding +- Probing implications and better variable ordering to strengthen presolve and branching +- Replace deprecated cuDF Column/Buffer APIs with pylibcudf and public cuDF interfaces +- Modernize dependency pinnings; make CUDA runtime linkage static for portability +- Build/tooling: add `--split-compile`, `--jobserver`, Clang host build, ThreadSanitizer, improved container scripts, and branch/commit metadata in images +- Use explicit `cudaStream_t` with `cub::DeviceTransform` and non-blocking streams for GPU control +- Enable barrier LP tests, add regression testing, and add SonarQube static analysis +- Added parameter for specifying the random seed used by the solver + +### Bug Fixes (26.02) + +- Fixed an issue with incorrect signs of dual variables and reduced costs on maximization problems +- Fix out-of-bounds in dense-column detection in barrier +- Correct infeasible-list handling to avoid incorrect infeasibility reports in dual simplex +- Fix race conditions found via Clang host build + ThreadSanitizer +- Resolve CUDA–Numba version mismatches with cuDF +- Fix device code to include required trailing return types +- Fix issue in crossover after dualization in barrier +- Repair container build and test failures +- Miscellaneous additional fixes and stability improvements + +### Documentation (26.02) + +- Update README and top-level docs for current build and usage +- Document new repository branching strategies and release-cycle details in README and CONTRIBUTING +- Add best practices for batch solving ## Release Notes 25.12 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 index fc382bbbb..07182501f 100644 --- 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 @@ -143,9 +143,6 @@ You should see the following output: Simple Quadratic Programming Example ------------------------------------ -.. note:: - The QP solver is currently in beta. - 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 `): diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/examples/qp_matrix_example.py b/docs/cuopt/source/cuopt-python/lp-qp-milp/examples/qp_matrix_example.py index f822ead9f..40609f4a1 100644 --- a/docs/cuopt/source/cuopt-python/lp-qp-milp/examples/qp_matrix_example.py +++ b/docs/cuopt/source/cuopt-python/lp-qp-milp/examples/qp_matrix_example.py @@ -5,9 +5,6 @@ Quadratic Programming Matrix Example ==================================== -.. note:: - The QP solver is currently in beta. - This example demonstrates how to formulate and solve a Quadratic Programming (QP) problem represented in a matrix format using the cuOpt Python API. diff --git a/docs/cuopt/source/cuopt-python/lp-qp-milp/examples/simple_qp_example.py b/docs/cuopt/source/cuopt-python/lp-qp-milp/examples/simple_qp_example.py index d9ff455e8..7a91b060b 100644 --- a/docs/cuopt/source/cuopt-python/lp-qp-milp/examples/simple_qp_example.py +++ b/docs/cuopt/source/cuopt-python/lp-qp-milp/examples/simple_qp_example.py @@ -5,9 +5,6 @@ Simple Quadratic Programming Example ==================================== -.. note:: - The QP solver is currently in beta. - This example demonstrates how to formulate and solve a simple Quadratic Programming (QP) problem using the cuOpt 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 index 3a4f603d4..0c8923d2c 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 @@ -18,9 +18,6 @@ LP, QP and MILP API Reference :members: :undoc-members: -.. note:: - The QP solver is currently in beta. - .. autoclass:: cuopt.linear_programming.problem.QuadraticExpression :members: :undoc-members: 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 index 76dfb7d74..a3412d1a8 100644 --- 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 @@ -33,9 +33,6 @@ The response is as follows: Simple Quadratic Programming Example ------------------------------------ -.. note:: - The QP solver is currently in beta. - :download:`simple_qp_example.py ` .. literalinclude:: examples/simple_qp_example.py diff --git a/docs/cuopt/source/cuopt-python/routing/examples/tsp_batch_example.py b/docs/cuopt/source/cuopt-python/routing/examples/tsp_batch_example.py new file mode 100644 index 000000000..f64881bc7 --- /dev/null +++ b/docs/cuopt/source/cuopt-python/routing/examples/tsp_batch_example.py @@ -0,0 +1,55 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +# +# TSP batch solve example: solve multiple TSP instances in one call for higher throughput. +# Use this when you have many similar routing problems (e.g., many small TSPs) to solve. + +import cudf +import numpy as np + +from cuopt import routing + + +def create_tsp_cost_matrix(n_locations): + """Create a simple symmetric cost matrix for a TSP of size n_locations.""" + cost_matrix = np.zeros((n_locations, n_locations), dtype=np.float32) + for i in range(n_locations): + for j in range(n_locations): + cost_matrix[i, j] = abs(i - j) + return cudf.DataFrame(cost_matrix) + + +def main(): + # Define multiple TSP sizes to solve in one batch + tsp_sizes = [5, 8, 10, 6, 7, 9] + + # Build one DataModel per TSP + data_models = [] + for n_locations in tsp_sizes: + cost_matrix = create_tsp_cost_matrix(n_locations) + dm = routing.DataModel(n_locations, 1) # n_locations, 1 vehicle (TSP) + dm.add_cost_matrix(cost_matrix) + data_models.append(dm) + + # Shared solver settings for the batch + settings = routing.SolverSettings() + settings.set_time_limit(5.0) + + # Solve all TSPs in batch (parallel execution) + solutions = routing.BatchSolve(data_models, settings) + + # Inspect results + print(f"Solved {len(solutions)} TSPs in batch.") + for i, (size, solution) in enumerate(zip(tsp_sizes, solutions)): + status = solution.get_status() + status_str = ( + "SUCCESS" if status == routing.SolutionStatus.SUCCESS else status + ) + vehicle_count = solution.get_vehicle_count() + print( + f" TSP {i} (size {size}): status={status_str}, vehicles={vehicle_count}" + ) + + +if __name__ == "__main__": + main() diff --git a/docs/cuopt/source/cuopt-python/routing/index.rst b/docs/cuopt/source/cuopt-python/routing/index.rst index 64abac5f8..eaeb735b4 100644 --- a/docs/cuopt/source/cuopt-python/routing/index.rst +++ b/docs/cuopt/source/cuopt-python/routing/index.rst @@ -11,4 +11,5 @@ This section contains details on the cuOpt routing optimization Python API. :titlesonly: routing-api.rst + routing-examples.rst Routing Example diff --git a/docs/cuopt/source/cuopt-python/routing/routing-api.rst b/docs/cuopt/source/cuopt-python/routing/routing-api.rst index e5e8c0881..41b7894d2 100644 --- a/docs/cuopt/source/cuopt-python/routing/routing-api.rst +++ b/docs/cuopt/source/cuopt-python/routing/routing-api.rst @@ -25,6 +25,8 @@ cuOpt Routing Python API Reference .. autofunction:: cuopt.routing.Solve +.. autofunction:: cuopt.routing.BatchSolve + .. autoclass:: cuopt.routing.Assignment :members: :undoc-members: diff --git a/docs/cuopt/source/cuopt-python/routing/routing-examples.rst b/docs/cuopt/source/cuopt-python/routing/routing-examples.rst new file mode 100644 index 000000000..5aebd989d --- /dev/null +++ b/docs/cuopt/source/cuopt-python/routing/routing-examples.rst @@ -0,0 +1,42 @@ +======================================== +Routing Examples +======================================== + +This section contains examples for the cuOpt routing Python API. + +TSP Batch Mode +-------------- + +The routing Python API supports **batch mode** for solving many TSP (or routing) instances in a single call. Instead of calling :func:`cuopt.routing.Solve` repeatedly, you build a list of :class:`cuopt.routing.DataModel` objects and call :func:`cuopt.routing.BatchSolve`. The solver runs the problems in parallel to improve throughput. + +**When to use batch mode:** + +- You have **many similar routing problems** (e.g., dozens or hundreds of small TSPs). +- You want to **maximize throughput** by utilizing the GPU across multiple problems at once. +- Problem sizes and structure are compatible with the same :class:`cuopt.routing.SolverSettings` (e.g., same time limit). + +**Returns:** A list of :class:`cuopt.routing.Assignment` objects, one per input data model, in the same order as ``data_model_list``. Use :meth:`cuopt.routing.Assignment.get_status` and other assignment methods to inspect each solution. + +The following example builds several TSPs of different sizes, solves them in one batch, and prints a short summary per solution. + +:download:`tsp_batch_example.py ` + +.. literalinclude:: examples/tsp_batch_example.py + :language: python + :linenos: + +Sample output: + +.. code-block:: text + + Solved 6 TSPs in batch. + TSP 0 (size 5): status=SUCCESS, vehicles=1 + TSP 1 (size 8): status=SUCCESS, vehicles=1 + TSP 2 (size 10): status=SUCCESS, vehicles=1 + ... + +**Notes:** + +- All problems in the batch use the **same** :class:`cuopt.routing.SolverSettings` (e.g., time limit, solver options). +- Callbacks are not supported in batch mode. +- For best practices when batching many instances, see the *Add best practices for batch solving* note in the release documentation. diff --git a/docs/cuopt/source/cuopt-server/examples/lp/examples/warmstart_example.py b/docs/cuopt/source/cuopt-server/examples/lp/examples/warmstart_example.py index a408b86d2..860ef0bbe 100644 --- a/docs/cuopt/source/cuopt-server/examples/lp/examples/warmstart_example.py +++ b/docs/cuopt/source/cuopt-server/examples/lp/examples/warmstart_example.py @@ -10,6 +10,11 @@ Note: Warmstart is only applicable to LP, not for MILP. +Important: + To use warm start with PDLP, presolve must be explicitly disabled. + Set "presolve": "off" in solver_config, as presolve transforms the problem + and the warm start solution from the original problem cannot be applied. + Requirements: - cuOpt server running (default: localhost:5000) - cuopt_sh_client package installed diff --git a/docs/cuopt/source/faq.rst b/docs/cuopt/source/faq.rst index 2ecdf7285..66744819f 100644 --- a/docs/cuopt/source/faq.rst +++ b/docs/cuopt/source/faq.rst @@ -374,6 +374,11 @@ Linear Programming FAQs 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. Presolve is controlled by the ``CUOPT_PRESOLVE`` setting. +.. dropdown:: How do I use warm start with PDLP? + + To use warm start functionality with PDLP, you must explicitly disable presolve by setting ``CUOPT_PRESOLVE=0`` in solver_config. + This is required because presolve transforms the problem, and the warm start solution from the original problem + cannot be applied to the presolved problem. Mixed Integer Linear Programming FAQs -------------------------------------- diff --git a/docs/cuopt/source/lp-qp-features.rst b/docs/cuopt/source/lp-qp-features.rst index 3dbed1489..4bd178ed5 100644 --- a/docs/cuopt/source/lp-qp-features.rst +++ b/docs/cuopt/source/lp-qp-features.rst @@ -58,9 +58,6 @@ There are two ways to specify constraints to the LP solver: Quadratic Programming --------------------- -.. note:: - The QP solver is currently in beta. - cuOpt supports problems with quadratic objectives of the form: .. code-block:: text diff --git a/docs/cuopt/source/lp-qp-milp-settings.rst b/docs/cuopt/source/lp-qp-milp-settings.rst index 37b362eea..51c6142c2 100644 --- a/docs/cuopt/source/lp-qp-milp-settings.rst +++ b/docs/cuopt/source/lp-qp-milp-settings.rst @@ -1,9 +1,9 @@ ================================= -LP, QP and MILP Settings +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. +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:: @@ -23,7 +23,7 @@ may run slightly over the limit. If set along with the iteration limit, cuOpt wi 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, +.. 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. @@ -33,25 +33,25 @@ 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. +.. 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. +.. 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. +.. 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. +.. note:: The default value is ``""`` and no user problem file is written. This setting is ignored by the cuOpt service. Num CPU Threads ^^^^^^^^^^^^^^^ @@ -59,7 +59,7 @@ Num CPU Threads 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. +.. note:: By default the number of CPU threads is automatically determined based on the number of CPU cores. Presolve ^^^^^^^^ @@ -123,7 +123,7 @@ For performance reasons, cuOpt's does not constantly checks for iteration limit, 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, +.. 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. @@ -141,7 +141,7 @@ is not always accurate. Some problems detected as infeasible may converge under 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 +.. note:: By default PDLP will not detect infeasibility. Dual simplex will always detect infeasibility regardless of this setting. Strict Infeasibility @@ -151,7 +151,7 @@ Strict Infeasibility 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. +.. note:: The default value is false. .. _crossover: @@ -165,7 +165,7 @@ between their bounds. Enabling crossover allows the user to obtain a high-qualit 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. +.. note:: The default value is false. Save Best Primal So Far ^^^^^^^^^^^^^^^^^^^^^^^ @@ -176,21 +176,21 @@ With this parameter set to true, PDLP * 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. +.. 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. +.. 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. +.. note:: The default value is false. Barrier Solver Settings ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -206,7 +206,7 @@ Folding * ``0``: Disable folding * ``1``: Force folding to run -.. note:: the default value is ``-1`` (automatic). +.. note:: The default value is ``-1`` (automatic). Dualize """"""" @@ -217,7 +217,7 @@ Dualize * ``0``: Don't attempt to dualize * ``1``: Force dualize -.. note:: the default value is ``-1`` (automatic). +.. note:: The default value is ``-1`` (automatic). Ordering """""""" @@ -228,7 +228,7 @@ Ordering * ``0``: cuDSS default ordering * ``1``: AMD (Approximate Minimum Degree) ordering -.. note:: the default value is ``-1`` (automatic). +.. note:: The default value is ``-1`` (automatic). Augmented System """""""""""""""" @@ -239,7 +239,7 @@ Augmented System * ``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. +.. 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 """""""""""""""""""""""" @@ -252,7 +252,7 @@ However, extra solves must be performed at each iteration. This setting only has an effect when the ADAT (normal equation) system is solved. -.. note:: the default value is ``true``. +.. note:: The default value is ``true``. cuDSS Deterministic Mode """"""""""""""""""""""""" @@ -262,7 +262,7 @@ cuDSS Deterministic Mode * ``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. +.. note:: The default value is ``false``. Enable deterministic mode if reproducibility is more important than performance. Dual Initial Point """""""""""""""""" @@ -273,7 +273,7 @@ Dual Initial Point * ``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). +.. note:: The default value is ``-1`` (automatic). Absolute Primal Tolerance ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -299,7 +299,7 @@ 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``. +.. note:: The default value is ``1e-4``. Absolute Dual Tolerance ^^^^^^^^^^^^^^^^^^^^^^^ @@ -312,7 +312,7 @@ 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``. +.. note:: The default value is ``1e-4``. Relative Dual Tolerance ^^^^^^^^^^^^^^^^^^^^^^^ @@ -323,7 +323,7 @@ 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``. +.. note:: The default value is ``1e-4``. Absolute Gap Tolerance @@ -336,7 +336,7 @@ 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``. +.. note:: The default value is ``1e-4``. Relative Gap Tolerance @@ -348,7 +348,7 @@ 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``. +.. note:: The default value is ``1e-4``. Mixed Integer Linear Programming @@ -364,7 +364,7 @@ Heuristics only 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. +.. note:: The default value is false. Scaling ^^^^^^^ @@ -372,7 +372,7 @@ Scaling ``CUOPT_MIP_SCALING`` controls if scaling should be applied to the MIP problem. When true scaling is applied, when false, no scaling is applied. -.. note:: the defaulte value is true. +.. note:: The default value is false. Absolute Tolerance @@ -380,14 +380,14 @@ Absolute Tolerance ``CUOPT_MIP_ABSOLUTE_TOLERANCE`` controls the MIP absolute tolerance. -.. note:: the default value is ``1e-6``. +.. 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``. +.. note:: The default value is ``1e-12``. Integrality Tolerance @@ -396,7 +396,7 @@ 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``. +.. note:: The default value is ``1e-5``. Absolute MIP Gap ^^^^^^^^^^^^^^^^ @@ -411,7 +411,7 @@ when minimizing or when maximizing. -.. note:: the default value is ``1e-10``. +.. note:: The default value is ``1e-10``. Relative MIP Gap ^^^^^^^^^^^^^^^^ @@ -423,4 +423,93 @@ Relative MIP Gap 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``. +.. note:: The default value is ``1e-4``. + + +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). diff --git a/docs/cuopt/source/routing-features.rst b/docs/cuopt/source/routing-features.rst index 9e044ff58..7442bbd21 100644 --- a/docs/cuopt/source/routing-features.rst +++ b/docs/cuopt/source/routing-features.rst @@ -13,6 +13,11 @@ The Routing solver is available in two forms: Both options provide the same routing optimization capabilities while offering flexibility in deployment and integration approaches. +Batch Solving (TSP) +------------------------------ + +The Python API supports solving multiple TSP (or routing) instances in a single call via **batch mode**. Use :func:`cuopt.routing.BatchSolve` with a list of :class:`cuopt.routing.DataModel` objects to run many problems in parallel and improve throughput. See :doc:`cuopt-python/routing/routing-examples` for details and an example. + Heterogeneous Fleet ------------------------------