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/QP/QCQP problems, if licensed, and CLP/CBC (for LP/MIP) or Ipopt (for QP/QCQP) otherwise. By setting options MIP_SOLVER, LP_SOLVER, MILP_SOLVER, QP_SOLVER, or QCQP_SOLVER, the automatic solver selection can be overwritten.
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. Range: Quadratic_Concave_Constraint, Quadratic_Equality_Constraint, Exponential_Reformulation, Continuous_Relaxation. | Quadratic_Concave_Constraint |
| 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. SSLINEAR linearises the BQP using a modified version of Sherali and Smith, “An improved linearization strategy for zero-one quadratic programming problems”, 2007. 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. Range: AUTOMATIC, LINEAR, QUADRATIC, SSLINEAR | 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. See also the Octeract docu. 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). See also the Octeract docu. 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. See also the Octeract docu. 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. See also the Octeract docu. 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. See also the Octeract docu. Range: real | 1 |
| LLB_TOLERANCE | Tolerance used to decide whether solutions from lower and upper problems are the "same". See also the Octeract docu. 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, 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, 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, OSICBC, HIGHS | CPLEX if licensed, otherwise OSICBC. |
| 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} | GAMS threads |
| 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. See also the Octeract docu. Range: {1, ..., ∞} | ∞ |
| OBBT_MAX_ITERATIONS | This sets the maximum number of passes for OBBT. See also the Octeract docu. 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. See also the Octeract docu. 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. See also the Octeract docu. Range: boolean | 1 |
| USE_FBBT | Whether to use Feasibility Based Bound Tightening. See also the Octeract docu. Range: boolean | 1 |
| USE_MILP_RELAXATION | Whether to use mixed-integer linear relaxations. See also the Octeract docu. 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. See also the Octeract docu. Range: boolean | 1 |
| USE_PROBING | Enables or disables probing techniques for domain reduction . See also the Octeract docu. 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. See also the Octeract docu. Range: boolean | 1 |
| USE_SIMPLIFICATION | Enables or disables standard reformulation rules for nonlinear and discontinuous functions. See also the Octeract docu. 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 |
Link Options
| Option | Description | Default |
|---|---|---|
| Options for expert users | ||
| nlbinary | Whether .nl file should be written in binary form Range: boolean | 1 |