A status of SUBOPTIMAL (13) means that the Gurobi Optimizer terminated without satisfying the conditions required to report an optimal result. See Optimization Status Codes.
Although Gurobi may return solution information with this status, do not assume that a usable feasible solution is available. Make sure to inspect the relevant solution-quality attributes.
The status can arise in MIP branch-and-bound, the barrier algorithm, hierarchical multi-objective optimization, and the local nonlinear solver. Its precise meaning depends on the algorithm that produced it.
MIP
Sub-optimal termination (unable to solve some node relaxations)This message indicates that Gurobi could not reliably solve one or more node relaxations to continue processing or safely prune the corresponding nodes. Because an unresolved part of the branch-and-bound tree may contain a better integer solution, Gurobi cannot certify optimality.
If an incumbent exists, it remains the best solution found, but it has no optimality certificate. In some cases, no incumbent may be available at all, so check SolCount before querying solution values. Also, inspect the reported best bound and optimality gap when they are available.
Barrier
Sub-optimal termination - objective 6.73030560e+06The barrier algorithm prints this message when it cannot satisfy all of its convergence requirements, and further iterations are no longer making reliable progress. Typical symptoms include stalled objective or residual progress, an inability to reduce primal or dual infeasibility, and unreliable complementarity or step calculations. Numerical scaling or ill-conditioning is often the underlying cause.
The point returned by the barrier is not necessarily feasible to the requested tolerance. Before using it, inspect the solution's quality attributes. Crossover can sometimes clean up primal or dual infeasibility after barrier.
Multi-objective optimization
Sub-optimal termination for some objective, not solved to optimalityHierarchical multi-objective optimization performs a sequence of optimization passes in decreasing order of priority. There is one pass per distinct priority level; objectives that share a priority are combined into a single pass.
This message means that at least one pass terminated without reaching optimality. The cause may be numerical difficulty, reaching a termination limit, such as IterationLimit, NodeLimit, or SolutionLimit, or an intentional interruption of one pass from a callback.
Local nonlinear solver
Sub-optimal termination (unable to satisfy NL barrier tolerances)Starting with Gurobi 13.0, setting OptimalityTarget to 1 enables the local nonlinear solver for continuous nonlinear models. This solver uses a nonlinear barrier algorithm to seek a first-order locally optimal solution. For a nonconvex model, such a solution is not generally a certificate of global optimality.
The message above means that the algorithm terminated without satisfying all three tolerances that define an acceptable locally optimal point:
- NLBarPFeasTol for primal feasibility;
- NLBarDFeasTol for dual feasibility; and
- NLBarCFeasTol for complementarity.
What to do about it
Start by determining whether the returned result is usable. Check that a solution exists, inspect the relevant quality attributes, and review the final residuals or violations in the log.
For MIP node-relaxation failures and linear or quadratic barrier failures, numerical difficulties such as poor scaling and ill-conditioning are the usual cause. For the local nonlinear solver, a difficult starting point or failure to converge locally may also contribute. A multi-objective pass can also stop simply because it reached a limit.
The following parameter changes can be useful as diagnostics or workarounds.
NumericFocus
Try values 1, 2, and 3. Higher values cause Gurobi to devote more effort to numerically sensitive computations, potentially increasing runtime.
Presolve and aggregation
Compare the coefficient statistics of the original and presolved models. If presolve produces much less favorable ranges or less stable behavior, try Aggregate=0. If necessary, also test Presolve=0. Setting AggFill=0 can be a less drastic alternative to disabling aggregation completely.
Presolve aggregation substitutes variables and combines rows. On some models, this can amplify roundoff error or produce a less numerically favorable formulation; on many others, aggregation is beneficial. Treat Aggregate=0 as an experiment rather than a universal recommendation.
ScaleFlag
Scaling changes the numerical representation on which the algorithms operate. The automatic setting is not always best for every model, so experiment with the available settings. If the objective coefficients are the main source of the poor range, also consider ObjScale.
The Model Scaling module in the Gurobi Model Analyzer package can help evaluate alternative scalings.
Algorithm choice
For a continuous LP or QP that encounters trouble with the barrier, test the primal or dual simplex by setting Method to 0 or 1. Simplex can be more robust than barrier on some numerically difficult models.
Unless there is a specific reason to disable it, also test the barrier with crossover enabled. Crossover may be able to clean up residual primal or dual infeasibility. BarHomogeneous=1 is another useful experiment, particularly when infeasibility or unboundedness is suspected.
Tolerances: use with care
Changing tolerances should generally be a last resort, not the first response to numerical trouble.
The relevant tolerances depend on the algorithm:
-
BarConvTolandBarQCPConvTolcontrol barrier convergence; -
FeasibilityTolandOptimalityTolaffect primal and dual acceptance; and -
NLBarPFeasTol,NLBarDFeasTol, andNLBarCFeasTolcontrol the local nonlinear barrier conditions.
Loosening a tolerance may cause Gurobi to accept a point it previously rejected, but it does not improve the model's numerical conditioning. It simply weakens the acceptance criterion. Tightening tolerances can sometimes help diagnose instability, but it should likewise not be regarded as a durable fix.
See Solver Parameters to Manage Numerical Issues for additional options.
Fix the model, not just the run
Parameter changes may mitigate the symptoms, but the durable solution is usually to address the source of the numerical difficulty. In particular:
- reduce excessively wide ranges in matrix coefficients, large objective coefficients, bounds, and right-hand sides;
- choose units that keep typical magnitudes reasonably comparable;
- replace oversized big-(M) values with tighter valid bounds or stronger formulations;
- provide tight bounds for variables that participate in nonlinear expressions;
- avoid unnecessary rounding when constructing coefficients; and
- inspect the coefficient statistics of both the original and presolved models.
Does My Model Have Numerical Issues? and Gurobi Model Analyzer explain how to locate likely sources of instability. Reformulation and improved scaling are more reliable than repeatedly adjusting parameters around a poorly conditioned model.