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 |
|
C++ |
|
Java |
|
.NET |
|
Python |
|
where
Values#
|
Numeric value |
Optimizer status |
---|---|---|
|
0 |
Periodic polling callback |
|
1 |
Currently performing presolve |
|
2 |
Currently in simplex |
|
3 |
Currently in MIP |
|
4 |
Found a new MIP incumbent |
|
5 |
Currently exploring a MIP node |
|
6 |
Printing a log message |
|
7 |
Currently in barrier |
|
8 |
At the end of a multi-objective iteration |
|
9 |
Currently computing an IIS |
The POLLING
callback is an optional callback that is only invoked if other
callbacks have not been called in a while. It is intended to give user code the
opportunity to do background operations and does not allow to query information
from Gurobi. Hence, there are no what
values available for POLLING
.
what
Values#
General information about the progress of the optimization can be queried for
all where
arguments except for POLLING. In addition, each where
argument
has specific what
values available. All what
values and the where
values for which they may be queried are listed in the tables below. Remember
that the appropriate prefix must be added to the what
and where
name,
depending on the language you are using.
where=
any (except POLLING
)#
|
Result type |
Description |
---|---|---|
|
double |
Elapsed solver runtime (seconds). |
|
double |
Elapsed solver work (work units). |
where = PRESOLVE
#
|
Result type |
Description |
---|---|---|
|
int |
The number of columns removed by presolve to this point. |
|
int |
The number of rows removed by presolve to this point. |
|
int |
The number of constraint senses changed by presolve to this point. |
|
int |
The number of variable bounds changed by presolve to this point. |
|
int |
The number of coefficients changed by presolve to this point. |
where = SIMPLEX
#
|
Result type |
Description |
---|---|---|
|
double |
Current simplex iteration count. |
|
double |
Current simplex objective value. |
|
double |
Current primal infeasibility. |
|
double |
Current dual infeasibility. |
|
int |
Is problem currently perturbed? |
where = MIP
#
|
Result type |
Description |
---|---|---|
|
double |
Current best objective. |
|
double |
Current best objective bound. |
|
double |
Current explored node count. |
|
int |
Number of solutions that were presented through the |
|
int |
Current count of cutting planes applied. |
|
double |
Current unexplored node count. |
|
double |
Current simplex iteration count. |
|
int |
Number of scenarios that are still open in a multi-scenario model. |
|
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). |
where = MIPSOL
#
|
Result type |
Description |
---|---|---|
|
double * |
Solution vector for new solution (C only). The resultP argument to C
routine Use callback methods |
|
double |
Objective value for new solution. Not necessarily better than the current incumbent. |
|
double |
Current best objective. |
|
double |
Current best objective bound. |
|
double |
Current explored node count. |
|
int |
Number of solutions that were presented through the |
|
int |
Number of scenarios that are still open in a multi-scenario model. |
|
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). |
where = MIPNODE
#
|
Result type |
Description |
---|---|---|
|
int |
Optimization status of current MIP node (see the Status Code section for further information). |
|
double |
Current best objective. |
|
double |
Current best objective bound. |
|
double |
Current explored node count. |
|
int |
Number of solutions that were presented through the |
|
int |
Number of scenarios that are still open in a multi-scenario model. |
|
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). |
|
double * |
Relaxation solution for the current node, when its optimization status
is GRB_OPTIMAL (C only). The resultP argument to C routine
Use callback methods |
where = BARRIER
#
|
Result type |
Description |
---|---|---|
|
int |
Current barrier iteration count. |
|
double |
Primal objective value for current barrier iterate. |
|
double |
Dual objective value for current barrier iterate. |
|
double |
Primal infeasibility for current barrier iterate. |
|
double |
Dual infeasibility for current barrier iterate. |
|
double |
Complementarity violation for current barrier iterate. |
where = MULTIOBJ
#
|
Result type |
Description |
---|---|---|
|
int |
Current count of objectives already optimized. |
|
int |
Number of solutions stored in the solution pool. |
|
double * |
Solution vector for new solution (C only). The Use callback methods |
where = IIS
#
|
Result type |
Description |
---|---|---|
|
int |
Minimum number of constraints in the IIS. |
|
int |
Maximum number of constraints in the IIS. |
|
int |
Estimated number of constraints in the IIS. |
|
int |
Minimum number of variable bounds in the IIS. |
|
int |
Maximum number of variable bounds in the IIS. |
|
int |
Estimated number of variable bounds in the IIS. |
where = MESSAGE
#
|
Result type |
Description |
---|---|---|
|
char * |
The message that is being printed. |
Additional Remarks#
Note that the MIPSOL
callback might also be called for solutions
that do not improve the incumbent. This has technical reasons and should
only happen in rare cases. You might want to check the MIPSOL_OBJ
value
if your code relies on stricly improving solutions. The MIPSOL
callback
will also be called once for each MIP start.
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
which we refer to as optimization passes. The MULTIOBJ
callback will be
called once at the end of each pass. Also, during each pass, 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.