Octeract Engine

Octeract Engine is a deterministic solver to find globally optimal solutions for mixed-integer nonlinear programs (MINLPs). Distinguishing highlights of Octeract are its powerful and flexible symbolic reformulation engine and its parallelism capabilities. For more detailed information, we refer to the Octeract Math Blog.

# Usage

The following statement can be used inside your GAMS program to specify that Octeract should be used:

Option SOLVER = OCTERACT;


The above statement should appear before the Solve statement. If Octeract was specified as the default solver during GAMS installation, the above statement is not necessary.

GAMS/Octeract by default uses CPLEX to solve LP/MIP problems, if licensed, and CLP/CBC otherwise. By setting options LP_SOLVER or MILP_SOLVER, other solvers can be selected:

• If a license for GAMS/CPLEX, GAMS/OsiCPLEX, GAMS/CPLEX-link is available, then CPLEX can be used.
• If a Gurobi license is installed on the machine, then Gurobi can be used.
• If a FICO Xpress license is installed on the machine, then Xpress can be used. A GAMS/XPRESS license is currently not sufficient.

GAMS/Octeract by default uses CPLEX to solve QP/QCQP problems, if licensed, and Ipopt otherwise. By setting options QP_SOLVER or QCQP_SOLVER, Ipopt can be selected.

## Specification of Octeract Options

GAMS/OCTERACT supports the GAMS parameters reslim, iterlim, nodlim, workspace, optcr, optca, and threads. The interpretation of threads differs from its original meaning in the sense that also on systems with hyperthreading enabled only the number of actual processor cores is taken into account. Further, GAMS/OCTERACT is limited to the use of at most 16 cores and distributed parallelization is not available.

Options can be specified by a solver options file. A small example for an octeract.opt file is:

LP_SOLVER    HIGHS
MILP_SOLVER  HIGHS
STARTING_POINT_IPOPT VARIABLE_MID_POINT


It causes Octeract to use HiGHS to solve LP or MIP problems and to use a different starting point strategy for calls of Ipopt.

# List of Octeract Options

In the following, we give a detailed list of all Octeract options.

## Octeract Options

Option Description Default
APPLY_CB This enables or disables constraint probing for domain reduction.
Range: boolean
0
BIG_COEFF_TOLERANCE Sets the maximum acceptable absolute value of a coefficient in the lower bounding problem.
If a coefficient is greater than this number, the solver will use other, less effective methods instead of solving the lower bounding linear problem (LP). Coefficients are naturally improved through branching. However, if the problem is not numerically well-behaved, increasing this tolerance will force the solver to solve the ill-posed lower bounding problems. This is small-ish by default because the global solution guarantee can be compromised otherwise, but in practice it’s perfectly fine to increase this most of the time. Your clue that there might be a problem relating to this is that an (MI)LP relaxation was generated and you get a gap that never improves.
Range: [0, ∞]
1e+09
BIG_GAP_TOLERANCE If the difference between a node’s upper bound and the parent’s lower bound is smaller than BIG_GAP_TOLERANCE, then solve the relaxation, otherwise skip.
Range: [0, ∞]
1e+60
BINARY_REFORMULATION_PROCEDURE If REFORMULATE_BINARIES is enabled, this option determines which method to use in the reformulation of binary variables.
All of these methods transform the binary variables to continuous, either by adding constraints, or simply by dropping integrality ( Continuous_Relaxation ). The constraint adding methods tend to suck, and obviously dropping integrality means you’re now solving a different problem, so you should only really fiddle with this if you’re reaaaally desperate or you really know what you’re doing.
BOUND_VIOLATION_TOLERANCE Bound violation tolerance is used to confirm whether solutions returned by third-party solvers (IPOPT, CPLEX, Gurobi, CBC, etc) are indeed feasible within that tolerance.
Relaxing this tolerance can help in problems where finding a feasible solution is difficult, or where the global solution is eliminated due to slight constraint violations.
Range: [1e-12, 1]
1e-06
BQCQP_REFORMULATION_METHOD Type of reformulation used for BQCQPs.
The default option is SSLINEARBQCQP, which linearises the BQCQP following Sherali and Smith, “An improved linearization strategy for zero-one quadratic programming problems”, 2007. The CONVEXIFY option tries to convexify the problem in a similar way as the convexification for BQPs. See also the Octeract docu.
Range: SSLINEARBQCQP, CONVEXIFY
SSLINEARBQCQP
BQP_REFORMULATION_METHOD This option forces the reformulation method applied to Binary Quadratic Problems.
Note that this applies to the preprocessing state machine, i.e., if your problem is reformulated to a BQP by the preprocessor, you can use this option to force how that BQP will be reformulated. See also the Octeract docu.
AUTOMATIC
BQP_SPARSITY_TOLERANCE The maximal sparsity for a BQP to be reformulated as a linear problem.
Range: [0, 1]
0.8
BRANCHING_STRATEGY The heuristic for selecting the variable to branch in the branch and bound method when solving a problem.
Range: AUTOMATIC, MOST_VIOLATED_TERM, HYBRID_INTEGER_LEAST_REDUCED_AXIS, MAX_SEPARATION_DISTANCE, STRONG_BRANCHING, MOST_FRACTIONAL_VARIABLE, MODIFIED_MOST_NONCONVEX_VARIABLE
AUTOMATIC
CALCULATE_LB_LARGE_COEFFS If this option is enabled the Engine will treat constraints with large coefficients as every other constraint.
This check happens when solving a relaxation to find the lower bound at every node, and by default the engine will modify the pathological constraints to a safer form. However, this safety-first approach enlarges the feasible region, which means that your LLB may get stuck or improve much more slowly than it otherwise could. If you observe this behaviour, try setting this to true.
Range: boolean
0
CONSTRAINT_VIOLATION_TOLERANCE This is the acceptable constraint violation when qualifying a solution as feasible.
Relaxing this tolerance can help in problems where finding a feasible solution is difficult, or where the global solution is eliminated due to slight constraint violations.
Range: [0, 1]
1e-06
CONVERGENCE_TOLERANCE This sets a tolerance to determine whether the algorithm has converged to global optimality.
Note that this is used as both absolute and a relative gap tolerance. See also the Octeract docu.
Range: [0, ∞]
min(GAMS optcr, GAMS optca)
CP_MAX_ITERATIONS This option sets the limit for the number of passes performed by Constraint Propagation (CP) per node.
More of this means potentially better domain reduction per node, at the expense of speed and numerical correctness. See also the Octeract docu.
Range: {0, ..., ∞}
5
CP_NUMBER_COMPARISON_TOLERANCE This is the tolerance for comparison of two values within the Constraint Propagation (CP) algorithm.
CP is numerically unsafe by nature, so we have a metric ton of fail-safes and tolerances built into the implementation to make sure it doesn’t eliminate the global solution. This tolerance specifies when CP can safely consider whether a number is definitely larger/smaller/equal than another very similar one. Decreasing this can improve the stability of the algorithm, and increasing it can improve the quality of domain reduction by allowing more numerically unsafe operations. See also the Octeract docu.
Range: [0, 1]
1e-06
CP_SCALING Enabling this option may help avoid numerical issues for extremely badly scaled problems, i.e., constraints containing coefficients of widely different scales, wide range of scales for variable bounds, etc.
For MINLPs this can also be the case when you have fractions in your formulation without having properly contained the denominator range. This option sucks for regular problems, but it might help you in cases where the global solution is getting incorrectly fathomed. See also the Octeract docu.
Range: boolean
0
CP_VOLUME_IMPROVEMENT_FACTOR This sets the required volume improvement factor for iterations of constraint propagation.
More of this gives you more aggressive (and expensive) CP. See also the Octeract docu.
Range: [0, 1]
0.999
CUT_POOL_MAX_SIZE This sets the maximum number of cuts to be kept in the cut pool.
Range: {0, ..., ∞}
10000
FBBT_MAX_ITERATIONS This option sets the maximum number of variable bisections when performing Feasibility Based Bounds Tightening (FBBT).
More of this means more more domain reduction, but this can be really expensive, especially if you have dense nonlinear functions in your model. As with all domain reduction-related settings, doing more of it increases the odds of numerics going wrong, so use with caution. See also the Octeract docu.
Range: {0, ..., ∞}
5
FBBT_TIMEOUT Sets a working limit, in seconds, for Feasibility Based Bounds Tightening (FBBT).
This is typically applied per node of the branch-and-bound tree. See also the Octeract docu.
Range: [0, ∞]
0.3
FBBT_TOLERANCE This is the epsilon-termination condition for the width of a variable box when performing Feasibility Based Bounds Tightening (FBBT).
Range: [0, 1]
0.0001
FIRST_FEASIBLE_SOLUTION Setting this to true will force the engine to exit the moment a feasible solution is found, even if it’s a very bad one.
Range: boolean
0
FORCE_EXPANSION If USE_AUTOMATIC_EXPANSION is disabled, this setting gives you control over symbolic expansion.
Setting this to true will force the engine to symbolically expand all formulas in your problem, and setting this to false will force the engine to process the formulas exactly as you input them.
Range: boolean
0
HEUR_CONSTRAINT_PENALTY Controls the constraint penalty heuristic.
Range: OFF, NONLINEAR_CONSTRAINTS, ALL_CONSTRAINTS
OFF
HEUR_CONSTRAINT_PENALTY_COEFF This sets the penalty coefficient for the Constraint Penalty primal heuristic.
Higher values will make the solver prioritise feasibility over optimality, but will also increase the likelihood of numerical instability.
Range: [0, ∞]
1000
HEUR_CS Enables or disables the Constraint Satisfaction (CS) heuristic.
This can be quite expensive, so try turning this off it the solver is spending too much time trying to find a feasible solution.
Range: boolean
1
HEUR_FIXING Enables or disables a basic fixing heuristic.
Range: boolean
1
HEUR_GUIDED_DIVING Enables or disables the Guided Diving heuristic.
Can be quite expensive, so it’s off by default.
Range: boolean
0
HEUR_INEQUALITY Enables or disables the Inequality heuristic.
Range: boolean
1
HEUR_LB Enables or disables a simple Lower Bound (LB) heuristic.
Range: boolean
1
HEUR_MINLP_DIVING Enables or disables all Diving heuristics.
Range: boolean
1
HEUR_NL_FEASIBILITY_PUMP Enables or disables the Nonlinear (NL) Feasibility Pump heuristic.
Range: boolean
1
HEUR_PENALTY Enables or disables a simple penalty heuristic.
Range: boolean
1
HEUR_QPDIVING Enables or disables the QP Diving heuristic.
This can be very good for convex MI problems, but it’s pretty expensive so it’s off by default.
Range: boolean
0
HEUR_SAP Enables or disables the Shift and Propagate (SAP) heuristic.
Range: boolean
1
HEUR_SUPREME Primal heuristic that can be useful for some unbounded problems.
Range: boolean
0
HEUR_ZERO Enables or disables the Zero heuristic.
Range: boolean
1
INFINITY Default bound for unbounded variables.
Note that if unbounded variables are bounded this way, optimal solutions beyond these bounds may be cutoff, thus global optimality is no longer guaranteed. The returned model status and dual bound may NOT be valid in this case.
Range: [0, ∞]
1e+07
INTEGER_REFORMULATION_VAR_RANGE_LIMIT This option sets the max integer variable range up to which which integers will be reformulated to binaries.
Range: {0, ..., 100000}
5000
INTEGRALITY_VIOLATION_TOLERANCE Integrality violation tolerance is the acceptable violation before the solver determines that a variable is no longer an integer.
Relaxing this tolerance can make it much easier for the solver to find feasible solutions for discrete problems, especially problems with many integers or highly non-linear discrete functional forms.
Range: [0, 1]
0.001
IPOPT_INITIAL_VALUE When STARTING_POINT_IPOPT is set to CUSTOM_CONSTANT_VALUE,  this option determines the value of the initialisation of the primal variables given to IPOPT.
Range: real
1
LLB_TOLERANCE Tolerance used to decide whether solutions from lower and upper problems are the "same".
Range: [0, ∞]
0.001
LOCAL_SEARCH If enabled, the engine will run in local optimisation mode.
This mode skips all expensive preprocessing, and uses specialised local search algorithms to return a good feasible solution as quickly as possible. Highly recommended for folks who dislike waiting.
Range: boolean
0
LP_SOLVER This sets the solver which will be used to solve Linear Programming (LP) problems.
Range: IPOPT, OSICLP, OSICBC, CPLEX, GUROBI, XPRESS, HIGHS
OSICLP
MAX_CB_DEPTH This sets the maximum depth in the branching tree at which constraint probing should be adding additional constraints.
If this is set to 0, depth is unlimited.
Range: {0, ..., ∞}
1
MAX_SOLVER_ITERATIONS This sets the maximum number of solver iterations in serial mode.
This option is ignored in parallel mode.
Range: {1, ..., ∞}
GAMS iterlim
MAX_SOLVER_MEMORY This option sets the memory limit allowed during the solving process in MB.
If the memory used exceeds this limit the solving process is terminated. Note that when running MPI this is the memory consumed by the main process. Before you ask, yes, we could make this include the workers too but (i) getting precise memory consumption for the OS is iffy at best, and (ii) these system calls are actually quite expensive.
Range: {0, ..., ∞}
GAMS workspace
MAX_SOLVER_TIME Sets the timeout for the solver in real time seconds.
Range: [1, ∞]
GAMS reslim
MILP_LB_MAX_NODES This sets the maximum number of nodes that the MILP solver will be allowed to explore when solving a lower bounding problem.
By default it’s infinite (-1), but setting this to a finite number can improve the performance of MILP relaxations per node, at the expense of the quality of the lower bound per said node.
Range: {-1, ..., 2000000000}
-1
MILP_LB_TIMEOUT This option sets the timeout (in real-time seconds) for the MIP solver that it is used to solve MILP lower bounding problems at every node of the branch-and-bound tree.
Giving the MIP solver more time means that the lower bound per node can be superior, at the expense of computing time. Increase the timeout if: Your MIP relaxation starts clustering when it gets close to the global solution Decrease the timeout if: A lot of time is spent solving MIP problems but you don’t see the bounds improving even after a lot of nodes have been explored.
Range: [1, ∞]
5
MILP_SOLVER Sets the solver which will be used to solve MILP problems.
Range: OSICBC, CPLEX, GUROBI, XPRESS, HIGHS
OSICBC
MIP_SOLVER Umbrella option to use the specified MIP solver to solve all types of sub-problems it supports.
If set, it will overwrite LP_SOLVER and MILP_SOLVER. If set to CPLEX, it will also override QP_SOLVER and QCQP_SOLVER.
Range: CPLEX, GUROBI, XPRESS, OSICBC, HIGHS
NUM_CORES Number of MPI processes to spawn.
If the problem is reformulated to a MIP, the MPI workers go to sleep and this setting determines the number of threads for the MIP solver.
Range: {-∞, ..., 16}
NUMBER_COMPARISON_TOLERANCE This tolerance is used to determine whether two floating point numbers are the same.
Its use in the engine is context sensitive, therefore changing this can have unforeseen consequences, for the better or worse. Reducing this tolerance smaller can accelerate convergence, as the solver becomes more aggressive in domain reduction, at the risk of eliminating otherwise acceptable solutions. Increasing this tolerance can slows down convergence, as the solver adopts a more conservative approach, but may help in cases where the global solution is being incorrectly fathomed.
Range: [0, 1]
1e-06
OBBT_MAX_DEPTH This sets the maximum depth in the branch-and-bound tree at which Optimality Based Bounds Tightening (OBBT) should be applied.
Range: {1, ..., ∞}
OBBT_MAX_ITERATIONS This sets the maximum number of passes for OBBT.
Range: {1, ..., ∞}
1
OUTPUT_FREQUENCY The solver will print output every OUTPUT_FREQUENCY  iterations.
This only has meaning in serial mode, as there are no iterations in MPI mode.
Range: {1, ..., ∞}
1
OUTPUT_TIME_FREQUENCY The solver will print output every OUTPUT_TIME_FREQUENCY  seconds.
Range: {1, ..., ∞}
1
PRESOLVE Enables or disables the presolver.
Range: boolean
1
PURGE_CUTS Disable this if you want the solver to save all cuts since the beginning of time in its cut pool.
This will override all other cut management options, including the limit for max cuts. Is it not recommended to change this option.
Range: boolean
1
QCQP_SOLVER Sets the solver that will be used to solve QCQP sub-problems.
Setting the  MIP_SOLVER  option overrides this option.
Range: CPLEX, IPOPT
IPOPT
QP_SOLVER Sets the solver that will be used to solve QP sub-problems.
Setting the  MIP_SOLVER  option overrides this option.
Range: CPLEX, IPOPT
IPOPT
REDUCE_LINEAR_CONSTRAINTS If this option is enabled, the Engine will try to reduce the size of the linear constraints by eliminating a variable in the constraint if its coefficient is close to zero.
Range: boolean
0
REFORMULATE_BINARIES Enables or disables the reformulation of binary variables into continuous nonlinear constraints according to the BINARY_REFORMULATION_PROCEDURE option.
Range: boolean
0
REFORMULATE_INTEGERS Enables or disables the reformulation of integer variables as binary.
Range: boolean
0
REFORMULATE_INTEGERS_IN_MIQCQP Enables or disables the reformulation of integer variables as binary in MIQCQP problems.
Range: boolean
1
SOLVE_CONTINUOUS_RELAXATION Setting this option to true will relax all discrete variables to continuous.
This can be useful if you want to investigate the lower bound of large problems with a lot of integer or binary variables.
Range: boolean
0
STARTING_POINT_IPOPT Set the strategy that the engine will use to generate starting points for IPOPT.
Change this if you are having trouble getting IPOPT to converge, or if it’s being too slow. See also the Octeract docu.
Range: CONSTANT_VALUE_ONE, CUSTOM_CONSTANT_VALUE, VARIABLE_MID_POINT, VARIABLE_MAX_POINT, VARIABLE_MIN_POINT
CONSTANT_VALUE_ONE
STRENGTHEN_LINEAR_CONSTRAINTS If enabled, for each linear constraint that contains binary or integer variables, the engine will try to find a tighter constraint by changing the coefficients of said variables.
Range: boolean
0
STRONG_BRANCHING_DEPTH When BRANCHING_STRATEGY = STRONG_BRANCHING, this option sets the maximum tree depth up to which to apply strong branching.
The solver will then revert back to AUTOMATIC.
Range: {0, ..., ∞}
0
STRONG_BRANCHING_VARIABLE_COUNT When BRANCHING_STRATEGY = STRONG_BRANCHING , this option sets the (maximum) number of variables to “test” while strong branching.
Range: {0, ..., ∞}
100
UB_FREQUENCY This option sets how often the solver should solve local optimisation problems to find upper bounds.
Small values for this option can be helpful in problems where finding feasible upper bounds is challenging. For instance, UB_FREQUENCY = 1  will instruct the solver to calculate an upper bound on every node processed in the branch and bound algorithm, increasing the probability that a feasible solution is going to be located. This, of course, comes with a trade-off of increased solution time, i.e. the smaller the UB_FREQUENCY, the more time is spent every iteration solving the upper bounding problem. The value of this option highly affects solver performance, especially in problems where a lot of time is spent solving primal heuristics. Note that the value of this option is more of a hint for the solver of how much to focus on solving UB problems rather than a hard-coded value, as it will load balance automatically when/which primal heuristics are solved.
Range: {1, ..., ∞}
4
USE_AUTOMATIC_EXPANSION This option enables or disables the dual expansion algorithm for mathematical expressions.
If enabled, the engine will create an alternative expanded version of the problem where functions like (x-2)2 will be replaced by x2-4x+4. The engine will then use a heuristic to select the most promising model to solve between the original (unexpanded) and alternative (expanded) version.
Range: boolean
1
USE_CONVEXITY_CUTS Enables or disables convexity cuts.
Range: boolean
1
USE_CP Turns constraint propagation on or off.
Range: boolean
1
USE_FBBT Whether to use Feasibility Based Bound Tightening.
Range: boolean
1
USE_MILP_RELAXATION Whether to use mixed-integer linear relaxations.
Range: boolean
1
USE_NONLINEAR_RELAXATION Turns nonlinear relaxations on or off, regardless of problem type.
Range: auto, true, false
auto
USE_NONLINEAR_RELAXATION_FOR_CONVEX_MINLP Control the use of nonlinear relaxations specifically for convex MINLPs.
Note that “MINLP” here is refers to all discrete problem classes up to and including DMINLP (so BQP, MIQCP, MBNLP, etc). In other words, if your problem is nonlinear and has discrete variables, this option applies.
Range: auto, true, false
auto
USE_OBBT Whether to use Optimisation Based Bound Tightening.
Range: boolean
1
USE_PROBING Enables or disables probing techniques for domain reduction .
Range: boolean
1
USE_REDUCED_COST Enables or disables reduced cost domain reduction.
Range: boolean
1
USE_REFORMULATION_LINEARIZATION Enables or disables the use of RLT to create redundant constraints in order to tighten the formulation.
Range: boolean
1
USE_SIMPLIFICATION Enables or disables standard reformulation rules for nonlinear and discontinuous functions.
Range: boolean
1
USE_STRUCTURE_DETECTOR Whether linear variables in objective function that are defined by a linear equation should be replaced if possible.
Range: boolean
1