GRBCallback#

classGRBCallback#

Gurobi callback class. This is an abstract class. To implement acallback, you should create a subclass of this class and implement acallback() method. If you pass an object of this subclass to methodGRBModel::setCallback before callingGRBModel::optimize orGRBModel::computeIIS, thecallback() method of the class will be called periodically.Depending on where the callback is called from, you can obtain variousinformation about the progress of the optimization.

Note that this class contains one protectedint member variable:where. You can query this variable from yourcallback() methodto determine where the callback was called from.

Gurobi callbacks can be used both to monitor the progress of theoptimization and to modify the behavior of the Gurobi Optimizer. Asimple user callback function might call theGRBCallback::getIntInfo orGRBCallback::getDoubleInfo methods toproduce a custom display, or perhaps to terminate optimization early(usingGRBCallback::abort) or to proceed to the nextphase of the computation (usingGRBCallback::proceed). More sophisticated MIPcallbacks might useGRBCallback::getNodeRel orGRBCallback::getSolution to retrieve valuesfrom the solution to the current node, and then useGRBCallback::addCut orGRBCallback::addLazy to add a constraint to cutoff that solution, orGRBCallback::setSolutionto import a heuristic solution built from that solution. Formulti-objective problems, you might useGRBCallback::stopOneMultiObj to interruptthe optimization process of one of theoptimization steps in a multi-objective MIP problem without stopping thehierarchical optimization process.

When solving a model using multiple threads, the user callback is onlyever called from a single thread, so you don’t need to worry about thethread-safety of your callback.

A few parameters arecallback settable. These parameters can be modified from withina callback call usingGRBCallback::set methods.

You can look at thecallback_c++.cppexample for details of how to use Gurobi callbacks.

GRBCallbackGRBCallback()#

Callback constructor.

Returns:

A callback object.

voidabort()#

Abort optimization. When the optimization stops, theStatusattribute will be equal toGRB_INTERRUPTED.

voidaddCut(constGRBLinExpr&lhsExpr,charsense,doublerhsVal)#

Add a cutting plane to the MIP model from within a callback function.Note that this method can only be invoked when thewhere membervariable is equal toGRB_CB_MIPNODE (see theCallback Codes section for more information).

Cutting planes can be added at any node of the branch-and-cut tree.However, they should be added sparingly, since they increase the size ofthe relaxation model that is solved at each node and can significantlydegrade node processing speed.

Cutting planes are typically used to cut off the current relaxationsolution. To retrieve the relaxation solution at the current node, youshould first callgetNodeRel.

You should consider setting parameterPreCrush to value1 when adding your own cuts. This setting shuts off a few presolvereductions that can sometimes prevent your cut from being applied to thepresolved model (which would result in your cut being silently ignored).

Note that cutting planes added through this method must truly be cuttingplanes – they can cut off continuous solutions, but they may not cutoff integer solutions that respect the original constraints of themodel. Ignoring this restriction will lead to incorrect solutions.

Parameters:

• lhsExpr – Left-hand side expression for new cutting plane.

• sense – Sense for new cutting plane (GRB_LESS_EQUAL,GRB_EQUAL, orGRB_GREATER_EQUAL).

• rhsVal – Right-hand side value for new cutting plane.

voidaddCut(GRBTempConstr&tc)#

Add a cutting plane to the MIP model from within a callback function.Note that this method can only be invoked when thewhere membervariable is equal toGRB_CB_MIPNODE (see theCallback Codes section for more information).

Cutting planes can be added at any node of the branch-and-cut tree.However, they should be added sparingly, since they increase the size ofthe relaxation model that is solved at each node and can significantlydegrade node processing speed.

Cutting planes are typically used to cut off the current relaxationsolution. To retrieve the relaxation solution at the current node, youshould first callgetNodeRel.

You should consider setting parameterPreCrush to value1 when adding your own cuts. This setting shuts off a few presolvereductions that can sometimes prevent your cut from being applied to thepresolved model (which would result in your cut being silently ignored).

Note that cutting planes added through this method must truly be cuttingplanes – they can cut off continuous solutions, but they may not cutoff integer solutions that respect the original constraints of themodel. Ignoring this restriction will lead to incorrect solutions.

Parameters:

tc – Temporary constraint object, created using an overloadedcomparison operator. SeeGRBTempConstr for moreinformation.

voidaddLazy(constGRBLinExpr&lhsExpr,charsense,doublerhsVal)#

Add a lazy constraint to the MIP model from within a callback function.Note that this method can only be invoked when thewhere membervariable is equal toGRB_CB_MIPNODE orGRB_CB_MIPSOL (see theCallback Codes section for more information).

Lazy constraints are typically used when the full set of constraints fora MIP model is too large to represent explicitly. By only including theconstraints that are actually violated by solutions found during thebranch-and-cut search, it is sometimes possible to find a proven optimalsolution while only adding a fraction of the full set of constraints.

You would typically add a lazy constraint by first querying the currentnode solution (by callinggetSolution from aGRB_CB_MIPSOL callback, orgetNodeRel from aGRB_CB_MIPNODE callback), and then callingaddLazy() to add aconstraint that cuts off the solution. Gurobi guarantees that you willhave the opportunity to cut off any solutions that would otherwise beconsidered feasible.

MIP solutions may be generated outside of a MIP node. Thus, generatinglazy constraints is optional when thewhere value in the callbackfunction equalsGRB_CB_MIPNODE. To avoid this, we recommend toalways check when thewhere value equalsGRB_CB_MIPSOL.

Your callback should be prepared to cut off solutions that violate anyof your lazy constraints, including those that have already been added.Node solutions will usually respect previously added lazy constraints,but not always.

Note that you must set theLazyConstraints parameter ifyou want to use lazy constraints.

Parameters:

• lhsExpr – Left-hand side expression for new lazy constraint.

• sense – Sense for new lazy constraint (GRB_LESS_EQUAL,GRB_EQUAL, orGRB_GREATER_EQUAL).

• rhsVal – Right-hand side value for new lazy constraint.

voidaddLazy(GRBTempConstr&tc)#

Add a lazy constraint to the MIP model from within a callback function.Note that this method can only be invoked when thewhere membervariable is equal toGRB_CB_MIPNODE orGRB_CB_MIPSOL (see theCallback Codes section for more information).

Lazy constraints are typically used when the full set of constraints fora MIP model is too large to represent explicitly. By only including theconstraints that are actually violated by solutions found during thebranch-and-cut search, it is sometimes possible to find a proven optimalsolution while only adding a fraction of the full set of constraints.

You would typically add a lazy constraint by first querying the currentnode solution (by callinggetSolution from aGRB_CB_MIPSOL callback, orgetNodeRel from aGRB_CB_MIPNODE callback), and then callingaddLazy() to add aconstraint that cuts off the solution. Gurobi guarantees that you willhave the opportunity to cut off any solutions that would otherwise beconsidered feasible.

MIP solutions may be generated outside of a MIP node. Thus, generatinglazy constraints is optional when thewhere value in the callbackfunction equalsGRB_CB_MIPNODE. To avoid this, we recommend toalways check when thewhere value equalsGRB_CB_MIPSOL.

Your callback should be prepared to cut off solutions that violate anyof your lazy constraints, including those that have already been added.Node solutions will usually respect previously added lazy constraints,but not always.

Note that you must set theLazyConstraints parameter ifyou want to use lazy constraints.

Parameters:

tc – Temporary constraint object, created using an overloadedcomparison operator. SeeGRBTempConstr for moreinformation.

doublegetDoubleInfo(intwhat)#

Request double-valued callback information. The available informationdepends on the value of thewhere member. For information onpossible values ofwhere, and the double-valued information that canbe queried for different values ofwhere, please refer to theCallback section.

Parameters:

what – Information requested (refer the list of GurobiCallback Codes for possible values).

Returns:

Value of requested callback information.

intgetIntInfo(intwhat)#

Request int-valued callback information. The available informationdepends on the value of thewhere member. For information onpossible values ofwhere, and the int-valued information that can bequeried for different values ofwhere, please refer to theCallback section.

Parameters:

what – Information requested (refer to the list of GurobiCallback Codes for possible values).

Returns:

Value of requested callback information.

doublegetNodeRel(GRBVarv)#

Retrieve a value from the node relaxation solution at the current node.Only available when thewhere member variable is equal toGRB_CB_MIPNODE, andGRB_CB_MIPNODE_STATUS is equal toGRB_OPTIMAL (see theCallback Codessection for more information).

Note that the relaxation solutionretrieved at a node is not necessarily feasible for the user model.

Parameters:

v – The variable whose value is desired.

Returns:

The value of the specified variable in the node relaxation forthe current node.

double*getNodeRel(constGRBVar*xvars,intlen)#

Retrieve values from the node relaxation solution at the current node.Only available when thewhere member variable is equal toGRB_CB_MIPNODE, andGRB_CB_MIPNODE_STATUS is equal toGRB_OPTIMAL (see theCallback Codessection for more information).

Note that the relaxation solutionretrieved at a node is not necessarily feasible for the user model.

Parameters:

• xvars – The list of variables whose values are desired.

• len – The number of variables in the list.

Returns:

The values of the specified variables in the node relaxation forthe current node. Note that the result is heap-allocated, and must bereturned to the heap by the user.

doublegetSolution(GRBVarv)#

Retrieve values from the current solution vector. Only available whenthewhere member variable is equal toGRB_CB_MIPSOL orGRB_CB_MULTIOBJ.

Parameters:

v – The variable whose value is desired.

Returns:

The value of the specified variable in the current solutionvector.

double*getSolution(constGRBVar*xvars,intlen)#

Retrieve values from the current solution vector. Only available whenthewhere member variable is equal toGRB_CB_MIPSOL orGRB_CB_MULTIOBJ.

Parameters:

• xvars – The list of variables whose values are desired.

• len – The number of variables in the list.

Returns:

The values of the specified variables in the current solution.Note that the result is heap-allocated, and must be returned to the heapby the user.

stringgetStringInfo(intwhat)#

Request string-valued callback information. The available informationdepends on the value of thewhere member. For information onpossible values ofwhere, and the string-valued information that canbe queried for different values ofwhere, please refer to theCallback section.

Parameters:

what – Information requested (refer to the list of GurobiCallback Codes for possible values).

Returns:

Value of requested callback information.

voidproceed()#

Generate a request to proceed to the next phase of the computation. Notethat the request is only accepted in a few phases of the algorithm, andit won’t be acted upon immediately.

In the current Gurobi version, this callback allows you to proceed fromthe NoRel heuristic to the standard MIP search. You can determine thecurrent algorithm phase usingMIP_PHASE,MIPNODE_PHASE, orMIPSOL_PHASE queries from a callback.

voidset(GRB_DoubleParamparam,doublenewvalue)#

Allows to modifycallback settable double-valued parameters during a deterministic callback.

That is, when thewhere value isGRB_CB_PRESOLVED,GRB_CB_SIMPLEX,GRB_CB_MIP,GRB_CB_MIPSOL,GRB_CB_MIPNODE,GRB_CB_BARRIER, orGRB_CB_MULTIOBJ (see theCallback Codes section for more information)

In case of a remote server, the change of a parameter from within acallback may not be taken into account immediately.

Parameters:

• param – The parameter being modified.

• newvalue – The desired new value for the parameter.

voidset(GRB_IntParamparam,intnewvalue)#

Allows to modifycallback settable int-valued parameters during a deterministic callback.

That is, when thewhere value isGRB_CB_PRESOLVED,GRB_CB_SIMPLEX,GRB_CB_MIP,GRB_CB_MIPSOL,GRB_CB_MIPNODE,GRB_CB_BARRIER, orGRB_CB_MULTIOBJ (see theCallback Codes section for more information)

In case of a remote server, the change of a parameter from within acallback may not be taken into account immediately.

Parameters:

• param – The parameter being modified.

• newvalue – The desired new value for the parameter.

voidset(GRB_StringParamparam,stringnewvalue)#

Allows to modifycallback settable string-valued parameters during a deterministic callback.

That is, when thewhere value isGRB_CB_PRESOLVED,GRB_CB_SIMPLEX,GRB_CB_MIP,GRB_CB_MIPSOL,GRB_CB_MIPNODE,GRB_CB_BARRIER, orGRB_CB_MULTIOBJ (see theCallback Codes section for more information)

In case of a remote server, the change of a parameter from within acallback may not be taken into account immediately.

Parameters:

• param – The parameter being modified.

• newvalue – The desired new value for the parameter.

voidsetSolution(GRBVarv,doubleval)#

Import solution values for a heuristic solution. Only available when thewhere member variable is equal toGRB_CB_MIP,GRB_CB_MIPNODE, orGRB_CB_MIPSOL (see theCallback Codes section for more information).

When you specify a heuristic solution from a callback, variablesinitially take undefined values. You should use this method to specifyvariable values. You can make multiple calls tosetSolution from onecallback invocation to specify values for multiple sets of variables.After the callback, if values have been specified for any variables, theGurobi Optimizer will try to compute a feasible solution from thespecified values, possibly filling in values for variables whose valueswere left undefined. You can also optionally calluseSolution within your callback function to try toimmediately compute a feasible solution from the specified values.

In the context of a Compute Server environment, for performance reasons,the solutions sent throughsetSolution are not necessarily processed bythe Compute Server immediately. They may show up in the solving processa bit later after the client callback has sent them. In extreme cases,it could even be that the Compute Server optimization job terminatesbefore it processes the user solution.

Parameters:

• v – The variable whose values is being set.

• val – The value of the variable in the new solution.

voidsetSolution(constGRBVar*xvars,constdouble*sol,intlen)#

Import solution values for a heuristic solution. Only available when thewhere member variable is equal toGRB_CB_MIP,GRB_CB_MIPNODE, orGRB_CB_MIPSOL (see theCallback Codes section for more information).

When you specify a heuristic solution from a callback, variablesinitially take undefined values. You should use this method to specifyvariable values. You can make multiple calls tosetSolution from onecallback invocation to specify values for multiple sets of variables.After the callback, if values have been specified for any variables, theGurobi Optimizer will try to compute a feasible solution from thespecified values, possibly filling in values for variables whose valueswere left undefined. You can also optionally calluseSolution within your callback function to try toimmediately compute a feasible solution from the specified values.

In the context of a Compute Server environment, for performance reasons,the solutions sent throughsetSolution are not necessarily processed bythe Compute Server immediately. They may show up in the solving processa bit later after the client callback has sent them. In extreme cases,it could even be that the Compute Server optimization job terminatesbefore it processes the user solution.

Parameters:

• xvars – The variables whose values are being set.

• sol – The values of the variables in the new solution.

• len – The number of variables.

voidstopOneMultiObj(intobjcnt)#

Interrupt the optimization process of one of theoptimization steps in a multi-objective MIP problem without stopping thehierarchical optimization process. Only available for multi-objective MIPmodels and when the where member variable is not equal to GRB_CB_MULTIOBJ(see theCallback Codes section for moreinformation).

You would typically stop amulti-objective optimization step by querying the last finished numberof multi-objectives steps, and using that number to stop the currentstep and move on to the next hierarchical objective (if any) as shown inthe following example:

#include<ctime>classmycallback:publicGDBCallback{public:intobjcnt=0;time_tstarttime=time();protected:voidcallback(){if(where==GRB_CB_MULTIOBJ){/* get current objective number */objcnt=getIntInfo(GRB_CB_MULTIOBJ_OBJCNT);/* reset start time to current time */starttime=time();}elseif(time()-startime>BIG||/* takes too long or good enough  */){/* stop only this optimization step */stopOneMultiObj(objcnt);}}}

You should refer to the section onMultiple Objectives for information onhow to specify multiple objective functions and control the trade-offbetween them.

Parameters:

objnum – The number of the multi-objective optimizationstep to interrupt. For processes running locally, this argument can have the specialvalue -1, meaning to stop the current step.

doubleuseSolution()#

Once you have imported solution values usingsetSolution,you can optionally calluseSolution in aGRB_CB_MIPNODE callbackto immediately use these values to try to compute a heuristic solution.Alternatively, you can calluseSolution in aGRB_CB_MIP orGRB_CB_MIPSOL callback, which will store the solution until it canbe processed internally.

Returns:

The objective value for the solution obtained from your solutionvalues. It equalsGRB_INFINITY if no improved solution is found orthe method has been called from a callback other thanGRB_CB_MIPNODEas, in these contexts, the solution is stored instead of being processedimmediately.