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

where Values

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	At the end of a multi-objective iteration
IIS	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)

what	Result type	Description
RUNTIME	double	Elapsed solver runtime (seconds).
WORK	double	Elapsed solver work (work units).

where = PRESOLVE

what	Result type	Description
PRE_COLDEL	int	The number of columns removed by presolve to this point.
PRE_ROWDEL	int	The number of rows removed by presolve to this point.
PRE_SENCHG	int	The number of constraint senses changed by presolve to this point.
PRE_BNDCHG	int	The number of variable bounds changed by presolve to this point.
PRE_COECHG	int	The number of coefficients changed by presolve to this point.

where = SIMPLEX

what	Result type	Description
SPX_ITRCNT	double	Current simplex iteration count.
SPX_OBJVAL	double	Current simplex objective value.
SPX_PRIMINF	double	Current primal infeasibility.
SPX_DUALINF	double	Current dual infeasibility.
SPX_ISPERT	int	Is problem currently perturbed?

where = MIP

what	Result type	Description
MIP_OBJBST	double	Current best objective.
MIP_OBJBND	double	Current best objective bound.
MIP_NODCNT	double	Current explored node count.
MIP_SOLCNT	int	Number of solutions that were presented through the MIPSOL callback. For multiobjective models, this counter is reset to 0 at the beginning of each multiobjective pass.
MIP_CUTCNT	int	Current count of cutting planes applied.
MIP_NODLFT	double	Current unexplored node count.
MIP_ITRCNT	double	Current simplex iteration count.
MIP_OPENSCENARIOS	int	Number of scenarios that are still open in a multi-scenario model.
MIP_PHASE	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

what	Result type	Description
MIPSOL_SOL	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 callback methods getSolution in C++, getSolution in Java, GetSolution in .NET, and cbGetSolution in Python.
MIPSOL_OBJ	double	Objective value for new solution. Not necessarily better than the current incumbent.
MIPSOL_OBJBST	double	Current best objective.
MIPSOL_OBJBND	double	Current best objective bound.
MIPSOL_NODCNT	double	Current explored node count.
MIPSOL_SOLCNT	int	Number of solutions that were presented through the MIPSOL callback before the current invocation. It may happen, particularly at the beginning of the root node, that some invocations of the MIPSOL callback are not accounted for immediately, and the value presented for MIPSOL_SOLCNT is temporarily lower than what could be expected. For multiobjective models, this counter is reset to 0 at the beginning of each multiobjective pass.
MIPSOL_OPENSCENARIOS	int	Number of scenarios that are still open in a multi-scenario model.
MIPSOL_PHASE	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

what	Result type	Description
MIPNODE_STATUS	int	Optimization status of current MIP node (see the Status Code section for further information).
MIPNODE_OBJBST	double	Current best objective.
MIPNODE_OBJBND	double	Current best objective bound.
MIPNODE_NODCNT	double	Current explored node count.
MIPNODE_SOLCNT	int	Number of solutions that were presented through the MIPSOL callback. For multiobjective models, this counter is reset to 0 at the beginning of each multiobjective pass.
MIPNODE_OPENSCENARIOS	int	Number of scenarios that are still open in a multi-scenario model.
MIPNODE_PHASE	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	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 callback methods getNodeRel in C++, getNodeRel in Java, GetNodeRel in .NET, and cbGetNodeRel in Python.

where = BARRIER

what	Result type	Description
BARRIER_ITRCNT	int	Current barrier iteration count.
BARRIER_PRIMOBJ	double	Primal objective value for current barrier iterate.
BARRIER_DUALOBJ	double	Dual objective value for current barrier iterate.
BARRIER_PRIMINF	double	Primal infeasibility for current barrier iterate.
BARRIER_DUALINF	double	Dual infeasibility for current barrier iterate.
BARRIER_COMPL	double	Complementarity violation for current barrier iterate.

where = MULTIOBJ

what	Result type	Description
MULTIOBJ_OBJCNT	int	Current count of objectives already optimized.
MULTIOBJ_SOLCNT	int	Number of solutions stored in the solution pool.
MULTIOBJ_SOL	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 callback methods getSolution in C++, getSolution in Java, GetSolution in .NET, and cbGetSolution in Python.

where = IIS

what	Result type	Description
IIS_CONSTRMIN	int	Minimum number of constraints in the IIS.
IIS_CONSTRMAX	int	Maximum number of constraints in the IIS.
IIS_CONSTRGUESS	int	Estimated number of constraints in the IIS.
IIS_BOUNDMIN	int	Minimum number of variable bounds in the IIS.
IIS_BOUNDMAX	int	Maximum number of variable bounds in the IIS.
IIS_BOUNDGUESS	int	Estimated number of variable bounds in the IIS.

where = MESSAGE

what	Result type	Description
MSG_STRING	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.