Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# 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`

## `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
`PDHG` | 10 | Currently in PDHG

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).
`MEMUSED` | double | Allocated memory (GB).
`MAXMEMUSED` | double | Maximum memory ever allocated (GB).

### `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 multi-objective models, this counter is reset to 0 at the beginning of each multi-objective 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 multi-objective models, this counter is reset to 0 at the beginning of each multi-objective 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 multi-objective models, this counter is reset to 0 at the beginning of each multi-objective 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. 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.

### `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 that were presented through the `MIPSOL` callback for the current objective.
`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.
`MULTIOBJ_STATUS` | int | Optimization status for current objective (see the Status Code section for further information).
`MULTIOBJ_OBJBST` | double | Best value for current objective.
`MULTIOBJ_OBJBND` | double | Best bound for current objective.
`MULTIOBJ_MIPGAP` | double | MIP gap of the current objective (only available if the model is a MIP).
`MULTIOBJ_ITRCNT` | double | Simplex iteration count for current objective.
`MULTIOBJ_NODCNT` | double | Explored node count for current objective.
`MULTIOBJ_NODLFT` | double | Unexplored node count for current objective.
`MULTIOBJ_RUNTIME` | double | Elapsed solver runtime (seconds) for current objective.
`MULTIOBJ_WORK` | double | Elapsed solver work (work units) for current objective.

### `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.

### `where = PDHG`

`what` | Result type | Description
--- | --- | ---
`PDHG_ITRCNT` | int | Current PDHG iteration count.
`PDHG_PRIMOBJ` | double | Primal objective value for current PDHG iterate.
`PDHG_DUALOBJ` | double | Dual objective value for current PDHG iterate.
`PDHG_PRIMINF` | double | Primal infeasibility for current PDHG iterate.
`PDHG_DUALINF` | double | Dual infeasibility for current PDHG iterate.
`PDHG_COMPL` | double | Complementarity violation for current PDHG iterate.

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

Help and Feedback

Press `/` or click to search this documentation | Gurobi website | Gurobi community forum
Go to other Gurobi documentation | Gurobi download | Contact support