docs: Release Notes 26.10 and missing settings docs

.gitignore

@@ -65,6 +65,8 @@ docs/cuopt/source/cuopt-server/client-api/sh-cli-help.txt
 docs/cuopt/source/cuopt-server/server-api/server-cli-help.txt
 docs/cuopt/source/cuopt-cli/cuopt-cli-help.txt
 docs/cuopt/source/cuopt_spec.yaml
+docs/cuopt/source/cuopt-grpc/protos/
+docs/cuopt/source/cuopt-grpc/cuopt-protos.zip
 python/cuopt_self_hosted/cuopt_sh_client/tests/utils/certs/*.key
 docs/cuopt/build
 

RELEASE-NOTES.md

@@ -1,5 +1,156 @@
 # Release Notes
 
+## Release Notes 26.10
+
+### New Features (26.10)
+
+- New Java interface for LP, QP, QCQP, SOCP and MIP
+- New RENS (Relaxation Enforced Neighboorhood Search) and mutation heuristics for MIP
+- MIP solver now runs diving and recursive sub-MIP heuristics during the cut passes
+- New primal heuristic for MIPs with arc-flow formulations
+- MIP solver includes new portfolio of CPUFJ heuristics with diversification
+- New compound move types in MIP CPUFJ: 2-opt, probing implication chain, clique exchange, set-partitioning row exchange and compound repair
+- New LNS heuristic for MIP that uses ruin-and-repair logic
+- New techniques for exploiting degeneracy in MIP
+- New implied indicator and capacity lifting presolve strengthening for fixed-charge MIP models
+- New MIP presolve: Block Bounded Value Elimination for binary problems
+- New MIP presolve: dual aggregation for binary variables with a single lock
+- New MIP presolve: exhaustive coefficient reduction for binary rows
+- New Curtis-Reid scaling for PDLP
+- New primal simplex method for LPs
+- Support for reusing the barrier ordering and symbolic factorization when solving a sequence of problems with different linear objectives and right-hand sides
+- The C API now exposes solver statistics as scalar solution attributes
+- New `cuOptSetLogCallback` for capturing solver logs in C API
+- Routing now supports per-vehicle distance-based breaks, so charging, refueling, or rest stops can be constrained by cumulative travel distance rather than time
+- The gRPC server now solves routing problems (VRP, TSP, and PDP). A Python gRPC routing client is included with cuOpt
+- A new HTTP proxy forwards requests to the gRPC server. The 26.10 container starts the proxy and gRPC server by default
+
+
+### Breaking Changes (26.10)
+
+- The container image now runs the proxy and gRPC servers by default; the legacy HTTP server is an optional start command
+- The proxy and gRPC servers (container defaults) support routing problems of up to 5500 locations with a travel time matrix, or 8000 without one. For larger problems use the legacy HTTP server.
+- `libcuopt` is split into client, mathopt and routing components, with separate wheels and conda packages; `libcuopt` is now a thin metapackage
+- The CUOPT_DISTRIBUTED_PDLP_PARTITIONER setting introduced in 26.08 is now CUOPT_MULTIGPU_PDLP_PARTITIONER
+- The CUOPT_USE_DISTRIBUTED_PDLP setting introduced in 26.08 has been removed; use method and num_gpus instead
+- When building from source the build.sh script no longer installs libcuopt into conda env by default
+
+### Improvements (26.10)
+
+- MIP heuristics improved by 3.2x on primal integral metric (geomean over the feasible MIPLIB2017 instances)
+- QP/QCQP solve 1.3X faster (geomean over QPLIB and Hans Mittelmann test set)
+- PDLP now uses column reduction on large problems (~2x faster in geomean over LPFeas addendum instances)
+- Dual simplex is 1.4X faster (geomean over MIPLIB root relaxations)
+- PDLP now fuses the Halpern update into the projection kernels to improve performance
+- Concurrent LP now uses a threshold on the number of nonzeros to decide whether to launch barrier and dual simplex
+- LP presolve now uses less memory by freeing the transpose matrix and PSLP reduced problem
+- LPs with poor scaling are now attempted without presolve, even if PSLP declares infeasibility
+- LP presolve now uses PSLP version 0.1.0; this version includes many improvements and bug fixes
+- MIP presolve now uses iteration and work limits rather than time limits
+- Set solution callbacks now use presolve and postsolve
+- Dual simplex now perturbs the cost more aggressively and uses primal simplex to remove perturbations
+- Dual simplex now attempts to remove perturbations when variables leave the basis
+- Dual simplex now tries several initial points on problems with dual degenerate bounded variables
+- Dual simplex's bound flipping ratio test is now approximately O(n) and combines Harris ratio test with bound flips
+- SOCP now use a tighter default tolerance on the duality gap without a performance regression
+- QCQP to SOCP conversion performance is improved and memory required is reduced
+- QP/SOCP presolve now eliminates free variables with zero cost
+- QP presolve now removes empty columns
+- Barrier now performs Ruiz scaling and builds the augmented system on the GPU
+- Barrier now scales QCQP/SOCP constraints by variable bounds before Ruiz equilibration
+- Barrier now performs iterative refinement on GPU when using the normal equations
+- Barrier now prints the cumulative setup time before the solve
+- Barrier termination check now has reduced GPU/host synchronization overhead
+- Barrier now has parameters to control adaptive regularization
+- Barrier now has parameters for tuning primal and dual regularization
+- Barrier now has a parameter to control bounding free variables
+- Barrier now has more initial point options
+- MIP root relaxation now honors the LP method selected
+- MIP performance improvement in duplicate cut detection
+- MIP reduced cost strengthening now stores lurking bounds based on incumbent objective value
+- MIP now includes a new Mod-2 cut separator for zero-half cuts
+- MIP random number generators are now per-worker instead of process wide; eliminating a source of nondeterminism
+- MIP time to first solution is improved by reducing overheads
+- MIP CPUFJ now has a fast-path heuristic for binary problems with integer activities
+- MIP CPUFJ now has structure-aware starts and repairs
+- Solution callback publication is now unified across solver components
+- Routing now uses cost instead of distance terminology when the objective does not represent a physical distance
+- The gRPC server now accepts a MIP starting solution
+- The gRPC server now checks GPU health and shuts down if the GPU is unusable. It also provides the standard gRPC readiness and liveness probes
+
+### Bug Fixes (26.10)
+
+- Fix an issue in the C API when accessing solutions on infeasible problems
+- Fix an issue in MPS writer on problems with no linear constraints
+- Fix ranged constraint conversion and MPS writing/reading round trips
+- Fix an issue in LP/MIP presolve where the user specified feasibility tolerance was not propagated to Papilo
+- Fix an issue in PDLP where reduced costs where not returned for the default PDLP preset (Stable3)
+- Fix a missing header in log for multi-GPU PDLP
+- Fix an issue in multi-GPU PDLP where the solver stopped silently when asking for more GPUs than available
+- Fix an issue on the C API where performing a multi-GPU PDLP solve on a problem built from row types and RHS was not supported
+- Fix an issue on multi-GPU PDLP where project_initial_primal was ignored
+- Fix a barrier crash when concurrent LP solving returned from cuDSS before its asynchronous work finished
+- Fix a segfault in concurrent LP if dual simplex or barrier finished without setting a solution
+- Fix several issues in barrier related to the cuDSS threading layer
+- Fix a bug on QCQP/SOCP problems with ranged rows
+- Fix an issue in QP/SOCP presolve where removing empty columns could corrupt memory, causing heap corruption errors or `cudaErrorLaunchFailure`
+- Fix nondeterminism in barrier when `--cudss-deterministic=1`
+- Fix an issue with QPs where duality gap was not included in the termination criteria
+- Fix a buffer overflow when getting the dual solution or reduced costs of a QCQP; these requests now return an error
+- Fix an issue in QP and SOCP where a large dual residual was reported for the final solution, even at an optimal solution
+- Fix an issue in dual simplex logs where bound flips were not accounted for in objective
+- Fix an issue in dual simplex inside MIP where cut off incorrectly used the perturbed objective
+- Fix an issue in dual simplex where dual variables and dual feasibility was not recomputed after basis repair
+- Fix MIP presolve incorrectly fixing continuous variables using integer-variable tolerance
+- Fix false optimality declaration in MIP deterministic mode
+- Fix several issues in MIP where the time limit was not respected
+- Fix an issue in MIP where flow cover cut generation was accidentally O(n^2)
+- Fix an issue in MIP where a large amount of time could elapse between logs
+- Fix an issue in MIP when converting knapsack constraints to rational coefficients could remove integer solutions
+- Fix an issue in MIP where termination was delayed during root cut passes
+- Fix an issue in MIP where the sub-MIP was not correctly stopped when the main solve finished
+- Fix an issue in MIP with halting cut passes
+- Fix an issue in MIP feasibility jump where weights were uninitialized when adding an objective cut
+- Fix an issue in MIP GF2 presolve where rank-deficient problems were incorrectly classified as infeasible
+- Fix an issue in MIP GF2 presolve where some one-sided rows were treated as equalities
+- Fix an issue in MIP presolve when performing single-lock-dual-aggregation
+- Fix an issue with tolerances in MIP mod-2 cuts
+- Fix a race condition in the asynchronous clique table generator and clique cuts
+- Fix an unsynchronized read/write of the MIP clique table
+- Fix a memory overflow in MIP when there were many feasible solutions
+- Disable clique table generation in MIP when running in deterministic mode
+- Fix an issue where the random number seed could change if multiple solves were performed within the same process
+- Fix an issue in routing: keep host sources alive for async route-view copies
+- Fix an issue in routing: avoid division by zero when vehicle capacity is zero
+- Fix an issue in routing: guard diagonal element lookup against negative offsets in top_k
+- Fix an issue in routing: uncapturable RMM copies inside CUDA graph captures
+- Fix an issue in routing: handle CUDA graph errors
+- Fix an issue where a PDLP warm start was ignored on a remote gRPC solve
+- Fix an issue where a gRPC connection could be closed during a long or idle solve because the server did not accept the client's keepalive pings
+- Fix an issue where stopping `cuopt_cli` or `cuopt_grpc_server` did not stop the solver process
+- Fix an issue in the Python gRPC client where waiting for a remote solve blocked other Python threads
+
+### Deprecations (26.10)
+
+- The container's default server is now the HTTP proxy plus `cuopt_grpc_server`, in place of the legacy HTTP server. The legacy HTTP server is still shipped in 26.10 and will be removed in 26.12. See "Starting the Container" on the Legacy HTTP Server page in the 26.10 user guide for the legacy container command and for `CUOPT_SERVER_TYPE=legacy` in Kubernetes. That page links to the 26.08 guide. Differences are in "Deprecated Interfaces Not Provided by the Proxy Server" in the 26.10 user guide.
+- Custom gRPC clients should now send solver settings through the `parameters` string map; individual setting fields are deprecated
+
+### Documentation (26.10)
+
+- Show mamba commands directly instead of a conda-then-swap note
+- Document the VRP gRPC client (RoutingClient)
+- Update NVIDIA Brev documentation links
+
+### New Contributors (26.10)
+
+- @nvidiacbrissette (#1524)
+- @vgong-nv (#1888)
+- @Juan-Francisco-Robles (#1299)
+- @ZedingZhang (#1925)
+- @vuule (#1900)
+- @neuriv (#1947)
+- @derluke (#1775)
+
 ## Release Notes 26.08
 
 ### New Features (26.08)

docs/cuopt/source/conf.py

@@ -8,6 +8,7 @@
 import cuopt
 import yaml
 from packaging.version import Version
+import shutil
 import subprocess
 import sys
 import os
@@ -35,6 +36,21 @@
     ["cuopt_cli", "--help"], stdout=open("cuopt-cli/cuopt-cli-help.txt", "w")
 )
 
+# Copy the gRPC protos next to the docs so api.rst can offer them for download. They import
+# each other by file name, so they share one directory.
+_grpc_src = Path(__file__).resolve().parents[3] / "cpp" / "src" / "grpc"
+_proto_dir = Path("cuopt-grpc/protos")
+_proto_dir.mkdir(exist_ok=True)
+for _proto in (
+    "cuopt_remote_service.proto",
+    "cuopt_remote.proto",
+    "codegen/generated/cuopt_remote_data.proto",
+    "routing/cuopt_routing.proto",
+    "routing/cuopt_routing_solution.proto",
+):
+    shutil.copy(_grpc_src / _proto, _proto_dir)
+shutil.make_archive("cuopt-grpc/cuopt-protos", "zip", _proto_dir)
+
 with open("cuopt_spec.yaml", "w") as f:
     yaml.dump(
         get_openapi(

docs/cuopt/source/convex-features.rst

@@ -239,16 +239,18 @@ Method
 .. note::
    PDLP solves to 1e-4 relative accuracy by default.
 
-**Barrier**: The barrier method (also known as interior-point method) solves linear and quadratic programs using a primal-dual predictor-corrector algorithm. This method uses GPU-accelerated sparse Cholesky and sparse LDLT solves via cuDSS, and GPU-accelerated sparse matrix-vector and matrix-matrix operations via cuSparse. Barrier is particularly effective for large-scale problems and can automatically apply techniques like folding, dualization, and dense column elimination to improve performance. This method solves the linear systems at each iteration using the augmented system or the normal equations (ADAT). Enable crossover to obtain a highly accurate basic solution from a barrier solution.
+**Barrier**: The barrier method (also known as interior-point) solves linear, quadratic, and second-order cone programs using a primal-dual predictor-corrector algorithm. This method uses GPU-accelerated sparse Cholesky and sparse LDLT solves via cuDSS, and GPU-accelerated sparse matrix-vector and matrix-matrix operations via cuSparse. Barrier is particularly effective for large-scale problems and can automatically apply techniques like folding, dualization, and dense column elimination to improve performance. This method solves the linear systems at each iteration using the augmented system or the normal equations (ADAT). Enable crossover to obtain a highly accurate basic solution from a barrier solution.
 
 .. note::
    Barrier solves to 1e-8 relative accuracy by default.
 
-**Dual Simplex**: Dual simplex is the simplex method applied to the dual of the linear program. Dual simplex requires the basis factorization of linear program fit into memory. Select this method if your LP is small to medium sized, or if you require a high-quality basic solution.
+**Dual Simplex**: Dual simplex begins with a dual feasible point and iterates until primal feasibility and optimality is established. Dual simplex requires the basis factorization of linear program fit into memory. Select this method if your LP is small to medium sized, or if you require a high-quality basic solution.
 
 .. note::
    Dual Simplex solves to 1e-6 absolute accuracy by default.
 
+**Primal Simplex**: Primal simplex begins with a primal feasible point and iterates until dual feasibility and optimality is established. Primal simplex is also used by dual simplex to remove cost perturbations. Primal simplex is typically slower than dual simplex (about 2.3x in internal testing). Select dual simplex or the default concurrent method unless you have a specific reason to use primal simplex.
+
 
 Crossover
 ---------
@@ -313,6 +315,15 @@ Users can submit a set of problems which will be solved in a batch. Problems wil
    parallel today; callers may see a ``DeprecationWarning`` or a deprecation
    message in server ``warnings``.
 
+Sequence Solves
+---------------
+
+When a sequence of convex optimization problems with the same constraint matrix are solved, cuOpt can reuse work from the first solve. To enable this, set the ``sequence_solve`` setting to true and solve with the barrier method. After the first solve you can change the linear objective with :meth:`~cuopt.linear_programming.data_model.DataModel.update_linear_objective` or the constraint right-hand side with :meth:`~cuopt.linear_programming.data_model.DataModel.update_rhs`, and solve again. Subsequent solves skip ordering and symbolic factorization.
+
+The quadratic objective, the constraint matrix, the row senses, and the variable bounds must stay unchanged between solves. See ``CUOPT_SEQUENCE_SOLVE`` in :doc:`convex-settings` for details and limits.
+
+.. note:: Sequence solves are currently only supported with the Python API.
+
 PDLP Precision Modes
 --------------------
 
@@ -327,4 +338,9 @@ By default, PDLP operates in the native precision of the problem type (FP64 for
 Multi-GPU Mode
 --------------
 
-Users can use multiple GPUs to solve a problem by specifying the ``num_gpus`` parameter. The feature is restricted to LP problems that uses concurrent mode and supports up to 2 GPUs at the moment. Using this mode will run PDLP and barrier in parallel on different GPUs to avoid sharing single GPU resources.
+Multiple GPUs may be used to solve a linear program by specifying the ``num_gpus`` parameter. Multiple GPUs are used differently depending on the ``method`` parameter:
+
+* When the PDLP method is specified, multi-GPU PDLP is used to solve LPs faster or solve very large LPs that do not fit in the memory of a single GPU.
+* When the concurrent method is specified, setting ``num_gpus=2``, will run PDLP and barrier concurrently on two GPUs to avoid sharing resources on a single GPU. Increasing ``num_gpus`` beyond two has no effect in this mode.
+
+.. note:: Concurrent is the default method; to run multi-GPU PDLP, users must specify the PDLP method. Multi-GPU mode is not supported on QP, QCQP, or SOCP problems.