Convex Optimization Settings#

This page describes the parameter settings available for cuOpt’s convex optimization solvers. These parameters are set as parameter constants in case of C API and in case of Server Thin client as raw strings. Refer to examples in C and 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 MIP and LP solvers

Time Limit#

CUOPT_TIME_LIMIT controls the time limit in seconds after which the solver will stop and return the current solution. For performance reasons, cuOpt does not constantly checks for time limit. Thus, the solver may run slightly over the limit. If set along with the iteration limit, cuOpt will stop when the first limit (iteration or time) is hit.

Note

By default there is no time limit. So cuOpt will run until it finds an optimal solution, or proves the problem is infeasible or unbounded.

Log to Console#

CUOPT_LOG_TO_CONSOLE controls whether cuOpt should log information to the console during a solve. If true, a logging info is written to the console, if false no logging info is written to the console (logs may still be written to a file.)

Note

The default value is true.

Log File#

CUOPT_LOG_FILE controls the name of a log file where cuOpt should write information about the solve.

Note

The default value is "" and no log file is written. This setting is ignored by the cuOpt service, use the log callback feature instead.

Solution File#

CUOPT_SOLUTION_FILE controls the name of a file where cuOpt should write the solution.

Note

The default value is "" and no solution file is written. This setting is ignored by the cuOpt service.

User Problem File#

CUOPT_USER_PROBLEM_FILE controls the name of a file where cuOpt should write the user problem.

Note

The default value is "" and no user problem file is written. This setting is ignored by the cuOpt service.

Num CPU Threads#

CUOPT_NUM_CPU_THREADS controls the number of CPU threads used in the LP and MIP solvers. Set this to a small value to limit the amount of CPU resources cuOpt uses. Set this to a large value to improve solve times for CPU parallel parts of the solvers.

Note

By default the number of CPU threads is automatically determined based on the number of CPU cores.

Presolve#

CUOPT_PRESOLVE controls which presolver to use for presolve reductions. cuOpt provides presolve reductions for linear programming (LP) problems using either PSLP or Papilo, and for mixed-integer programming (MIP) problems using Papilo. By default, Papilo presolve is always enabled for MIP problems. For LP problems, PSLP presolve is always enabled by default. You can explicitly control the presolver by setting this parameter to 0 (disable presolve), 1 (Papilo), or 2 (PSLP).

Dual Postsolve#

CUOPT_DUAL_POSTSOLVE controls whether dual postsolve is enabled when using Papilo presolver for LP problems. Disabling dual postsolve can improve solve time at the expense of not having access to the dual solution. Enabled by default for LP when Papilo presolve is selected. This is not relevant for MIP problems.

Linear Programming#

We now describe the parameter settings used to control cuOpt’s Linear Programming solvers

Method#

CUOPT_METHOD controls the method to solve the linear program. Five methods are available:

  • Concurrent: Use PDLP, dual simplex, and barrier in parallel (default).

  • PDLP: Use the PDLP method.

  • Dual Simplex: Use the dual simplex method.

  • Barrier: Use the barrier (interior-point) method.

  • Primal Simplex: Use the primal simplex method.

Note

The default method is Concurrent.

Default tolerances for each method:

  • PDLP solves to 1e-4 relative tolerance by default.

  • Barrier solves to 1e-8 relative tolerance by default.

  • Simplex solves to 1e-6 absolute tolerance by default.

See below for how to change the default tolerances.

C API users should use the constants defined in Method Constants for this parameter.

Server Thin client users should use the cuopt_sh_client.SolverMethod for this parameter.

Absolute Primal Tolerance#

CUOPT_ABSOLUTE_PRIMAL_TOLERANCE controls the absolute primal tolerance used in the primal feasibility check. Changing this value might have a significant impact on accuracy and runtime if the relative part (the right-hand side vector b L2 norm) is close to, or equal to, 0.

The primal feasibility condition is computed as follows:

primal_feasiblity < absolute_primal_tolerance + relative_primal_tolerance * l2_norm(b)

Default value is 1e-4.

Relative Primal Tolerance#

CUOPT_RELATIVE_PRIMAL_TOLERANCE controls the relative primal tolerance used in the primal feasibility check. Changing this value has a significant impact on accuracy and runtime. The primal feasibility condition is computed as follows:

primal_feasiblity < absolute_primal_tolerance + relative_primal_tolerance * l2_norm(b)

Note

The default value is 1e-4.

Absolute Dual Tolerance#

CUOPT_ABSOLUTE_DUAL_TOLERANCE controls the absolute dual tolerance used in the dual feasibility check. Changing this value might have a significant impact on accuracy and runtime if the relative part (the objective vector L2 norm) is close to, or equal to, 0.

The dual feasibility condition is computed as follows:

dual_feasiblity < absolute_dual_tolerance + relative_dual_tolerance * l2_norm(c)

Note

The default value is 1e-4.

Relative Dual Tolerance#

CUOPT_RELATIVE_DUAL_TOLERANCE controls the relative dual tolerance used in the dual feasibility check. Changing this value has a significant impact on accuracy and runtime. The dual feasibility condition is computed as follows:

dual_feasiblity < absolute_dual_tolerance + relative_dual_tolerance * l2_norm(c)

Note

The default value is 1e-4.

Absolute Gap Tolerance#

CUOPT_ABSOLUTE_GAP_TOLERANCE controls the absolute gap tolerance used in the duality gap check. Changing this value might have a significant impact on accuracy and runtime if the relative part (|primal_objective| + |dual_objective|) is close to, or equal to, 0.

The duality gap is computed as follows:

duality_gap < absolute_gap_tolerance + relative_gap_tolerance * (|primal_objective| + |dual_objective|)

Note

The default value is 1e-4.

Relative Gap Tolerance#

CUOPT_RELATIVE_GAP_TOLERANCE controls the relative gap tolerance used in the duality gap check. Changing this value has a significant impact on accuracy and runtime. The duality gap is computed as follows:

duality_gap < absolute_gap_tolerance + relative_gap_tolerance * (|primal_objective| + |dual_objective|)

Note

The default value is 1e-4.

PDLP Solver Mode#

CUOPT_PDLP_SOLVER_MODE controls the mode under which PDLP should operate. The mode will change the way the PDLP internally optimizes the problem. The mode choice can drastically impact how fast a specific problem will be solved. Users are encouraged to test different modes to see which one fits the best their problem. By default, the solver uses Stable3, the best overall mode from our experiments. For now, only three modes are available: Stable3, Methodical1, and Fast1.

For now, we do not offer a mechanism to know upfront which solver mode will be the best for a specific problem.

C API users should use the constants defined in PDLP Solver Mode Constants for this parameter.

Server Thin client users should use the cuopt_sh_client.PDLPSolverMode for this parameter.

Large Number of Nonzeros Threshold#

CUOPT_LARGE_NNZ_THRESHOLD sets a threshold for what cuOpt considers to be a large linear program. When the number of nonzeros in the constraint matrix exceeds this threshold, cuOpt uses different algorithmic strategies.

The default threshold is 50 million nonzeros. When presolve is enabled, the threshold applies to the matrix after presolve, not the original input matrix.

At or above the threshold:

  • Concurrent solves run only PDLP, skipping barrier and dual simplex.

  • PDLP column reduction is enabled for certain PDLP modes.

Below the threshold, concurrent solves use their normal solver selection, and PDLP column reduction is off unless explicitly enabled.

A special value is available:

  • -1: Concurrent solves use their normal solver selection regardless of matrix nonzeros. PDLP column reduction is off unless explicitly enabled.

Iteration Limit#

CUOPT_ITERATION_LIMIT controls the iteration limit after which the solver will stop and return the current solution. For performance reasons, cuOpt’s does not constantly checks for iteration limit, thus, the solver might run a few extra iterations over the limit. If set along with the time limit, cuOpt will stop at the first limit (iteration or time) reached.

Note

By default there is no iteration limit. So, cuOpt will run until it finds an optimal solution, or proves the problem is infeasible or unbounded.

Number of GPUs#

CUOPT_NUM_GPUS controls the number of GPUs to use for the solve. When solving an LP in concurrent mode, this supports up to 2 GPUs, running PDLP and barrier in parallel on different GPUs to avoid sharing single GPU resources.

With CUOPT_METHOD set to PDLP, CUOPT_NUM_GPUS set to -1 (all GPUs visible to the process) or a value greater than 1 instead dispatches to multi-GPU PDLP, which shards the problem across GPUs. See CUOPT_MULTIGPU_PDLP_PARTITIONER below for how the problem is partitioned. Multi-GPU PDLP currently only supports linear programs.

Multi-GPU PDLP Partitioner#

CUOPT_MULTIGPU_PDLP_PARTITIONER selects how multi-GPU PDLP splits the problem across GPUs: 0 Auto (default; RoundRobin on 1 GPU, KaMinPar otherwise), 1 KaMinPar (multi-threaded graph partitioner, better balanced shards at the cost of extra partitioning time), or 2 RoundRobin (no partitioning graph built).

Infeasibility Detection#

CUOPT_INFEASIBILITY_DETECTION controls whether PDLP should detect infeasibility. Note that infeasibility detection in PDLP is not always accurate. Some problems detected as infeasible may converge under a different tolerance factor. Detecting infeasibility consumes both more runtime and memory. The added runtime is between 3% and 7%, the added memory consumption is between 10% and 20%.

Note

By default PDLP will not detect infeasibility. Dual simplex will always detect infeasibility regardless of this setting.

Strict Infeasibility#

CUOPT_STRICT_INFEASIBILITY controls the strict infeasibility mode in PDLP. When true if either the current or the average solution is detected as infeasible, PDLP will stop. When false both the current and average solution need to be detected as infeasible for PDLP to stop.

Note

The default value is false.

Crossover#

CUOPT_CROSSOVER controls whether PDLP or barrier should crossover to a basic solution after an optimal solution is found. Changing this value has a significant impact on accuracy and runtime. By default the solutions provided by PDLP and barrier do not lie at a vertex and thus may have many variables that lie between their bounds. Enabling crossover allows the user to obtain a high-quality basic solution that lies at a vertex of the feasible region. If n is the number of variables, and m is the number of constraints, n - m variables will be on their bounds in a basic solution.

Note

The default value is false.

Save Best Primal So Far#

CUOPT_SAVE_BEST_PRIMAL_SOLUTION controls whether PDLP should save the best primal solution so far With this parameter set to true, PDLP * Will always prioritize a primal feasible to a non primal feasible * If a new primal feasible is found, the one with the best primal objective will be kept * If no primal feasible was found, the one with the lowest primal residual will be kept * If two have the same primal residual, the one with the best objective will be kept

Note

The default value is false.

First Primal Feasible#

CUOPT_FIRST_PRIMAL_FEASIBLE controls whether PDLP should stop when the first primal feasible solution is found.

Note

The default value is false.

Per Constraint Residual#

CUOPT_PER_CONSTRAINT_RESIDUAL controls whether PDLP should compute the primal & dual residual per constraint instead of globally.

Note

The default value is false.

PDLP Precision#

CUOPT_PDLP_PRECISION controls the precision mode used by the PDLP solver. The following modes are available:

  • default (-1): Use the native precision of the problem type (FP64 for double-precision problems).

  • single (0): Run PDLP internally in FP32 (float). Inputs are converted from FP64 to FP32 before solving and outputs are converted back to FP64. FP32 uses half the memory and allows PDHG iterations to be on average twice as fast, but may require more iterations to converge due to reduced numerical accuracy. Compatible with crossover (solution is converted back to FP64 before crossover runs) and concurrent mode (the PDLP leg runs in FP32 while Dual Simplex and Barrier run in FP64).

  • double (1): Explicitly run in FP64 (same as default for double-precision problems).

  • mixed (2): Use mixed precision sparse matrix-vector products (SpMV) during PDHG iterations. The constraint matrix and its transpose are stored in FP32 while vectors and the compute type remain in FP64, improving SpMV performance. Convergence checking and restart logic always use the full FP64 matrix, so this mode does not reduce overall memory usage. This provides a middle ground between full FP64 and FP32: faster PDHG iterations with limited impact on convergence.

Note

The default value is 0 (default precision).

Simplex Settings#

The following settings control the behavior of the simplex methods:

Primal Simplex Pricing#

CUOPT_PRIMAL_SIMPLEX_PRICING controls the pricing rule used by the primal simplex algorithm.

  • 0: Dantzig pricing

  • 1: Devex pricing (default)

Note

The default value is 1 (Devex).

Dual Simplex Initial Perturbation#

CUOPT_DUAL_SIMPLEX_INITIAL_PERTURBATION controls whether the dual simplex method perturbs the objective at the start of solve.

  • -1: Automatic (default) - cuOpt decides whether and how strongly to perturb

  • 0: Do not perturb

  • 1: Perturb

Note

The default value is -1 (automatic).

Dual Simplex Remove Perturbation#

CUOPT_DUAL_SIMPLEX_REMOVE_PERTURBATION controls whether dual simplex removes the cost perturbation during the solve, when variables leave the basis, rather than only at the end. Removing perturbations earlier helps avoid clean up at the end of the solve.

  • -1: Automatic (default)

  • 0: Disabled

  • 1: Enabled

Note

The default value is -1 (automatic).

Barrier Solver Settings#

The following settings control the behavior of the barrier (interior-point) method:

Note

The barrier method uses cuDSS for sparse Cholesky factorization, whose threading layer must be built against the same GNU OpenMP runtime as cuOpt itself. pip installs, conda installs, and source builds using the conda dev environment all handle this automatically; only a source build done entirely outside that environment needs the host to provide libgomp.so.1. If missing, or if a mismatched CUDSS_THREADING_LIB override is set, the solve falls back to single-threaded cuDSS instead of failing. See System Requirements and FAQ.

Folding#

CUOPT_FOLDING controls whether to fold the linear program. Folding can reduce problem size by exploiting symmetry in the problem.

  • -1: Automatic (default) - cuOpt decides whether to fold based on problem characteristics

  • 0: Disable folding

  • 1: Force folding to run

Note

The default value is -1 (automatic).

Dualize#

CUOPT_DUALIZE controls whether to dualize the linear program in presolve. Dualizing can improve solve time for problems, with inequality constraints, where there are more constraints than variables.

  • -1: Automatic (default) - cuOpt decides whether to dualize based on problem characteristics

  • 0: Don’t attempt to dualize

  • 1: Force dualize

Note

The default value is -1 (automatic).

Ordering#

CUOPT_ORDERING controls the ordering algorithm used by cuDSS for sparse factorizations. The ordering can significantly impact solver run time.

  • -1: Automatic (default) - cuOpt selects the best ordering

  • 0: cuDSS default ordering

  • 1: AMD (Approximate Minimum Degree) ordering

Note

The default value is -1 (automatic).

Augmented System#

CUOPT_AUGMENTED controls which linear system to solve in the barrier method.

  • -1: Automatic (default) - cuOpt selects the best linear system to solve

  • 0: Solve the ADAT system (normal equations)

  • 1: Solve the augmented system

Note

The default value is -1 (automatic). The augmented system may be more stable for some problems, while ADAT may be faster for others.

Eliminate Dense Columns#

CUOPT_ELIMINATE_DENSE_COLUMNS controls whether to eliminate dense columns from the constraint matrix before solving. Eliminating dense columns can improve performance by reducing fill-in during factorization. However, extra solves must be performed at each iteration.

  • true: Eliminate dense columns (default)

  • false: Don’t eliminate dense columns

This setting only has an effect when the ADAT (normal equation) system is solved.

Note

The default value is true.

cuDSS Deterministic Mode#

CUOPT_CUDSS_DETERMINISTIC controls whether cuDSS operates in deterministic mode. Deterministic mode ensures reproducible results across runs but may be slower.

  • true: Use deterministic mode

  • false: Use non-deterministic mode (default)

Note

The default value is false. Enable deterministic mode if reproducibility is more important than performance.

Dual Initial Point#

CUOPT_BARRIER_DUAL_INITIAL_POINT controls the method used to compute the dual initial point for the barrier solver. The choice of initial point will affect the number of iterations performed by barrier.

  • -1: Automatic (default) - cuOpt selects the best method

  • 0: Use an initial point from a heuristic approach based on the paper “On Implementing Mehrotra’s Predictor–Corrector Interior-Point Method for Linear Programming” (SIAM J. Optimization, 1992) by Lustig, Martsten, Shanno

  • 1: Use an initial point from solving a least squares problem that minimizes the norms of the dual variables and reduced costs while statisfying the dual equality constraints

  • 2: Use an initial point from a heurisitic approach based on SeDuMi by Jos Sturm

Note

The default value is -1 (automatic).

Barrier Initial Point Safeguard#

CUOPT_BARRIER_INITIAL_POINT_SAFEGUARD sets the margin used to push the barrier method’s initial point into the interior of the nonnegative orthant and, for second-order cone problems, into the interior of the cones. The initial point is shifted so that it is at least this far from the boundary. The value must be greater than or equal to 0. This setting only has an effect when CUOPT_BARRIER_DUAL_INITIAL_POINT is 0 or 1.

Note

The default value is 10.0.

Barrier Iterative Refinement#

CUOPT_BARRIER_ITERATIVE_REFINEMENT controls whether iterative refinement is applied after each barrier iteration to improve solution accuracy.

  • 0 (CUOPT_BARRIER_ITERATIVE_REFINEMENT_OFF): Disable iterative refinement (default).

  • 1 (CUOPT_BARRIER_ITERATIVE_REFINEMENT_ON): Enable iterative refinement.

Note

The default value is 0 (off).

Barrier Step Scale#

CUOPT_BARRIER_STEP_SCALE controls the scaling factor applied to the step size in the barrier method. The step scale must be strictly less than 1. A value like 0.9 is conservative, while a value like 0.999 is aggressive.

Note

By default cuOpt selects the step scale automatically.

Barrier Adaptive Regularization#

CUOPT_BARRIER_ADAPTIVE_REGULARIZATION controls whether adaptive regularization is enabled in the barrier method.

  • -1: Automatic (default) - cuOpt decides whether to enable adaptive regularization based on problem characteristics

  • 0: Disable adaptive regularization

  • 1: Enable adaptive regularization

Note

The default value is -1 (automatic).

Barrier Presolve Bound Free Variables#

CUOPT_BARRIER_PRESOLVE_BOUND_FREE_VARIABLES controls whether the barrier presolve attempts to put bounds on free variables using the linear constraints.

  • -1: Automatic (default) - cuOpt decides based on the problem

  • 0: Disable bounding of free variables

  • 1: Enable bounding of free variables

Note

The default value is -1 (automatic).

Barrier Primal and Dual Regularization#

CUOPT_BARRIER_PRIMAL_REGULARIZATION and CUOPT_BARRIER_DUAL_REGULARIZATION set the initial primal and dual regularization applied to the augmented system. They apply to the first factorization only. If adaptive regularization is enabled (see CUOPT_BARRIER_ADAPTIVE_REGULARIZATION), it can still scale the regularization up or down in later iterations.

  • -1: Automatic (default) - cuOpt uses its built-in heuristic

  • A value greater than or equal to 0: Use this value as the starting regularization

Note

The default value of both settings is -1 (automatic).

Sequence Solve#

CUOPT_SEQUENCE_SOLVE controls whether cuOpt caches the ordering and symbolic factorization so that a sequence of related barrier solves can reuse it. When enabled, and the first solve with the barrier method finishes with an optimal solution, cuOpt stores information about the factorization. In subsequent solves, the linear objective and the right-hand side of the linear equality constraints may be changed with update_linear_objective() or update_rhs() without recomputing the ordering or the symbolic factorization.

  • true: Cache the ordering and symbolic factorization for later solves

  • false: Do not cache (default)

Note

The default value is false.

Note

Reuse requires that the quadratic objective, the constraint matrix, the row senses, and the variable bounds stay unchanged between solves. Problems with range rows are not supported. When sequence solve is enabled, CUOPT_FOLDING and CUOPT_BARRIER_PRESOLVE_BOUND_FREE_VARIABLES are disabled.