Try our new documentation site (beta).
Callback Codes
The Gurobi callback routines make use of a pair of arguments:
where and what. When a user callback function is called,
the where argument indicates from where in the Gurobi
optimizer it is being called (presolve, simplex, barrier, MIP, etc.).
When the user callback wishes to obtain more detailed information
about the state of the optimization, the what argument can be
passed to an appropriate get method for your language
to obtain additional information
(e.g., GRBcbget in C,
GRBCallback::getIntInfo in C++,
GRBCallback.getIntInfo in Java,
GRBCallback.GetIntInfo in .NET, and
Model.cbGet in Python).
More detailed information on how to use callbacks in your application can be found in the reference manuals for the different Gurobi language interfaces (C, C++, Java, .NET, and Python).
Note that changing parameters from within a callback is not supported, doing so may lead to undefined behavior.
Possible values for the where and what arguments are
listed in the following tables. Note that these values are referred
to in slightly different ways from the different Gurobi interfaces.
Consider the SIMPLEX value as an example. You would
refer to this constant as follows from the different Gurobi APIs:
| Language | Callback constant |
|---|---|
| C | GRB_CB_SIMPLEX |
| C++ | GRB_CB_SIMPLEX |
| Java | GRB.Callback.SIMPLEX |
| .NET | GRB.Callback.SIMPLEX |
| Python | GRB.Callback.SIMPLEX |
Possible where values are:
where |
Numeric value | Optimizer status |
|---|---|---|
| POLLING | 0 | Periodic polling callback |
| PRESOLVE | 1 | Currently performing presolve |
| SIMPLEX | 2 | Currently in simplex |
| MIP | 3 | Currently in MIP |
| MIPSOL | 4 | Found a new MIP incumbent |
| MIPNODE | 5 | Currently exploring a MIP node |
| MESSAGE | 6 | Printing a log message |
| BARRIER | 7 | Currently in barrier |
| MULTIOBJ | 8 | Currently in multi-objective optimization |
| IIS | 9 | Currently computing an IIS |
Allowable what values depend on the value of the where
argument. Valid combinations are:
what |
where |
Result type | Description |
|---|---|---|---|
| RUNTIME | Any except POLLING | double | Elapsed solver runtime (seconds). |
| WORK | Any except POLLING | double | Elapsed solver work (work units). |
| PRE_COLDEL | PRESOLVE | int | The number of columns removed by presolve to this point. |
| PRE_ROWDEL | PRESOLVE | int | The number of rows removed by presolve to this point. |
| PRE_SENCHG | PRESOLVE | int | The number of constraint senses changed by presolve to this point. |
| PRE_BNDCHG | PRESOLVE | int | The number of variable bounds changed by presolve to this point. |
| PRE_COECHG | PRESOLVE | int | The number of coefficients changed by presolve to this point. |
| SPX_ITRCNT | SIMPLEX | double | Current simplex iteration count. |
| SPX_OBJVAL | SIMPLEX | double | Current simplex objective value. |
| SPX_PRIMINF | SIMPLEX | double | Current primal infeasibility. |
| SPX_DUALINF | SIMPLEX | double | Current dual infeasibility. |
| SPX_ISPERT | SIMPLEX | int | Is problem currently perturbed? |
| MIP_OBJBST | MIP | double | Current best objective. |
| MIP_OBJBND | MIP | double | Current best objective bound. |
| MIP_NODCNT | MIP | double | Current explored node count. |
| MIP_SOLCNT | MIP | int | Current count of feasible solutions found. |
| MIP_CUTCNT | MIP | int | Current count of cutting planes applied. |
| MIP_NODLFT | MIP | double | Current unexplored node count. |
| MIP_ITRCNT | MIP | double | Current simplex iteration count. |
| MIP_OPENSCENARIOS | MIP | int | Number of scenarios that are still open in a multi-scenario model. |
| MIP_PHASE | MIP | int | Current phase in the MIP solution process. Possible values are 0 (in the NoRel heuristic), 1 (in the standard MIP search), or 2 (performing MIP solution improvement). Predefined constants are available (e.g., GRB.PHASE_MIP_SEARCH). |
| MIPSOL_SOL | MIPSOL | double * | Solution vector for new solution (C only). The resultP argument to C routine GRBcbget should point to an array of doubles that is at least as long as the number of variables in the user model. Use the getSolution callback method in the object-oriented interfaces. |
| MIPSOL_OBJ | MIPSOL | double | Objective value for new solution. |
| MIPSOL_OBJBST | MIPSOL | double | Current best objective. |
| MIPSOL_OBJBND | MIPSOL | double | Current best objective bound. |
| MIPSOL_NODCNT | MIPSOL | double | Current explored node count. |
| MIPSOL_SOLCNT | MIPSOL | int | Current count of feasible solutions found. |
| MIPSOL_OPENSCENARIOS | MIPSOL | int | Number of scenarios that are still open in a multi-scenario model. |
| MIPSOL_PHASE | MIPSOL | int | Current phase in the MIP solution. Possible values are 0 (in the NoRel heuristic), 1 (in the standard MIP search), or 2 (performing MIP solution improvement). Predefined constants are available (e.g., GRB.PHASE_MIP_SEARCH). |
| MIPNODE_STATUS | MIPNODE | int | Optimization status of current MIP node (see the Status Code section for further information). |
| MIPNODE_OBJBST | MIPNODE | double | Current best objective. |
| MIPNODE_OBJBND | MIPNODE | double | Current best objective bound. |
| MIPNODE_NODCNT | MIPNODE | double | Current explored node count. |
| MIPNODE_SOLCNT | MIPNODE | int | Current count of feasible solutions found. |
| MIPNODE_OPENSCENARIOS | MIPNODE | int | Number of scenarios that are still open in a multi-scenario model. |
| MIPNODE_PHASE | MIPNODE | int | Current phase in the MIP solution process. Possible values are 0 (in the NoRel heuristic), 1 (in the standard MIP search), or 2 (performing MIP solution improvement). Predefined constants are available (e.g., GRB.PHASE_MIP_SEARCH). |
| MIPNODE_REL | MIPNODE | double * | Relaxation solution for the current node, when its optimization status is GRB_OPTIMAL (C only). The resultP argument to C routine GRBcbget should point to an array of doubles that is at least as long as the number of variables in the user model. Use the getNodeRel callback method in the object-oriented interfaces. |
| BARRIER_ITRCNT | BARRIER | int | Current barrier iteration count. |
| BARRIER_PRIMOBJ | BARRIER | double | Primal objective value for current barrier iterate. |
| BARRIER_DUALOBJ | BARRIER | double | Dual objective value for current barrier iterate. |
| BARRIER_PRIMINF | BARRIER | double | Primal infeasibility for current barrier iterate. |
| BARRIER_DUALINF | BARRIER | double | Dual infeasibility for current barrier iterate. |
| BARRIER_COMPL | BARRIER | double | Complementarity violation for current barrier iterate. |
| MULTIOBJ_OBJCNT | MULTIOBJ | int | Current count of objectives already optimized. |
| MULTIOBJ_SOLCNT | MULTIOBJ | int | Current count of feasible solutions found. |
| MULTIOBJ_SOL | MULTIOBJ | double * | Solution vector for new solution (C only). The resultP argument to C routine |
| IIS_CONSTRMIN | IIS | int | Minimum number of constraints in the IIS. |
| IIS_CONSTRMAX | IIS | int | Maximum number of constraints in the IIS. |
| IIS_CONSTRGUESS | IIS | int | Estimated number of constraints in the IIS. |
| IIS_BOUNDMIN | IIS | int | Minimum number of variable bounds in the IIS. |
| IIS_BOUNDMAX | IIS | int | Maximum number of variable bounds in the IIS. |
| IIS_BOUNDGUESS | IIS | int | Estimated number of variable bounds in the IIS. |
| MSG_STRING | MESSAGE | char * | The message that is being printed. |
Remember that the appropriate prefix must be added to the what
or where name listed above, depending on the language you are
using.
Callback notes
Note that the POLLING callback does not allow any
additional information to be retrieved. It is provided in order to
allow interactive applications to regain control frequently, so that
they can maintain application responsiveness.
The object-oriented interfaces have specialized methods for obtaining
the incumbent or relaxation solution. While in C you would use
GRBcbget, you use getSolution
or getNodeRel in the object-oriented interfaces. Please
consult the callback descriptions for
C++,
Java,
.NET, or
Python for further details.
Note that the MIPNODE callback will be called once for each cut
pass during the root node solve. The MIPNODE_NODCNT value will
remain at 0 until the root node is complete. If you query relaxation
values from during the root node, the first MIPNODE callback
will give the relaxation with no cutting planes, and the last will
give the relaxation after all root cuts have been applied.
Note that the multi-objective optimization algorithm solves a sequence of
optimization problems. In each solve the MULTIOBJ callback will be
called. Also, MIP-related callbacks will be called if the original model is a
MIP, and LP-related callbacks will be called if the original model is an LP.
Note that there are certain restrictions concerning the available callbacks when using the Gurobi Remote Services (Compute Server, Instant Cloud, etc.). Please refer to the Callbacks section of the Gurobi Remote Services Manual for more information.
