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).

A few parameters are callback settable. These parameters can be modified from within a callback call. How to do that for the different APIs is illustrated here.

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	At the end of a multi-objective iteration
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).
MEMUSED	Any except POLLING	double	Allocated memory (GB).
MAXMEMUSED	Any except POLLING	double	Maximum memory ever allocated (GB).
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	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	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 callback methods getSolution in C++, getSolution in Java, GetSolution in .NET, and cbGetSolution in Python.
MIPSOL_OBJ	MIPSOL	double	Objective value for new solution. Not necessarily better than the current incumbent.
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	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	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	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	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. Note that the relaxation solution retrieved at a node is not necessarily feasible for the user model. Use callback methods getNodeRel in C++, getNodeRel in Java, GetNodeRel in .NET, and cbGetNodeRel in Python.
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	Number of solutions that were presented through the MIPSOL callback for the current objective.
MULTIOBJ_SOL	MULTIOBJ	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.
MULTIOBJ_STATUS	MULTIOBJ	int	Optimization status for current objective (see the Status Code section for further information).
MULTIOBJ_OBJBST	MULTIOBJ	double	Best value for current objective.
MULTIOBJ_OBJBND	MULTIOBJ	double	Best bound for current objective.
MULTIOBJ_MIPGAP	MULTIOBJ	double	MIP gap of the current objective (only available if the model is a MIP).
MULTIOBJ_ITRCNT	MULTIOBJ	double	Simplex iteration count for current objective.
MULTIOBJ_NODCNT	MULTIOBJ	double	Explored node count for current objective.
MULTIOBJ_NODLFT	MULTIOBJ	double	Unexplored node count for current objective.
MULTIOBJ_RUNTIME	MULTIOBJ	double	Elapsed solver runtime (seconds) for current objective.
MULTIOBJ_WORK	MULTIOBJ	double	Elapsed solver work (work units) for current objective.
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 is an optional callback that is only invoked if other callbacks have not been called in a while. It does not allow any progress information to be retrieved. It is simply provided 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 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.

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.