CPXXsetbranchcallbackfunc and CPXsetbranchcallbackfunc

Sets and modifies the user-written legacy callback routine to be called after a branch has been selected but before the branch is carried out during MIP optimization.

int CPXXsetbranchcallbackfunc( CPXENVptr env, int(CPXPUBLIC *branchcallback)(CPXX_CALLBACK_BRANCH_ARGS), void * cbhandle )

int CPXsetbranchcallbackfunc( CPXENVptr env, int(CPXPUBLIC *branchcallback)(CALLBACK_BRANCH_ARGS), void * cbhandle )

Description

Warning:

This is an advanced routine. Advanced routines typically demand a thorough understanding of the algorithms used by CPLEX. Thus they incur a higher risk of incorrect behavior in your application, behavior that can be difficult to debug. Therefore, the team encourages you to consider carefully whether you can accomplish the same task by means of other Callable Library routines instead.

The routine CPXXsetbranchcallbackfunc/CPXsetbranchcallbackfunc sets and modifies the user-written legacy callback routine to be called after a branch has been selected but before the branch is carried out during MIP optimization. In the callback routine, the CPLEX-selected branch can be changed to a user-selected branch.

Tip:

If you make all branching decisions yourself

By design, a CPLEX branch callback provides the branching decisions that CPLEX would make if you as a user create no branches in the callback. Depending on variable selection and other factors, computation of these candidate branches can be time-consuming. If you know certainly that your callback never uses the branching candidates suggested by CPLEX, then you can save time by disabling strong branching and similar features.

Arguments

env: A pointer to the CPLEX environment, as returned by CPXXopenCPLEX/CPXopenCPLEX.
branchcallback: A pointer to a user-written branch callback. If the callback is set to NULL, no callback can be called during optimization.
cbhandle: A pointer to user private data. This pointer is passed to the callback.

Return

The routine returns 0 (zero) if successful and nonzero if an error occurs.

Example

 status = CPXsetbranchcallbackfunc (env, mybranchfunc, mydata);

See also the example admipex1.c in the standard distribution.

Callback description

CPXX API CPX API

 int CPXPUBLIC
 callback (CPXCENVptr env,
           void *cbdata,
           int wherefrom,
           void *cbhandle,
           int type,
           CPXDIM sos,
           int nodecnt,
           CPXDIM bdcnt,
           const CPXDIM *nodebeg,
           const CPXDIM *indices,
           const char *lu,
           const double *bd,
           const double *nodeest,
           int *useraction_p);

 int CPXPUBLIC
 callback (CPXCENVptr env,
           void *cbdata,
           int wherefrom,
           void *cbhandle,
           int type,
           int sos,
           int nodecnt,
           int bdcnt,
           const int *nodebeg,
           const int *indices,
           const char *lu,
           const double *bd,
           const double *nodeest,
           int *useraction_p);

The call to the branch callback occurs after a branch has been selected but before the branch is carried out. This function is written by the user. On entry to the callback, the CPLEX-selected branch is defined in the arguments. The arguments to the callback specify a list of changes to make to the bounds of variables when child nodes are created. One, two, or zero child nodes can be created, so one, two, or zero lists of changes are specified in the arguments. The first branch specified is considered first. The callback is called with zero lists of bound changes when the solution at the node is integer feasible. CPLEX occasionally elects to branch by changing a number of bounds on variables or by adding constraints to the node subproblem; the branch type is then CPX_TYPE_ANY. The details of the constraints added for a CPX_TYPE_ANY branch are not available to the user.

You can implement custom branching strategies by calling the CPLEX routine CPXXbranchcallbackbranchbds/CPXbranchcallbackbranchbds, CPXXbranchcallbackbranchconstraints/CPXbranchcallbackbranchconstraints, or CPXXbranchcallbackbranchgeneral/CPXbranchcallbackbranchgeneral and setting the useraction argument to CPX_CALLBACK_SET. Then CPLEX will carry out these branches instead of the CPLEX-selected branches.

Branch variables are expressed in terms of the original problem if the MIP callback switch between original model and reduced, presolved model (CPXPARAM_MIP_Strategy_CallbackReducedLP) is set to CPX_OFF before the call to CPXXmipopt/CPXmipopt that calls the callback. Otherwise, branch variables are in terms of the presolved problem.

If you set the MIP callback switch between original model and reduced, presolved model (CPXPARAM_MIP_Strategy_CallbackReducedLP) to CPX_OFF, you must also disable dual and nonlinear presolve reductions. To do so, set the parameter that controls primal and dual reduction type (CPXPARAM_Preprocessing_Reduce) to 1 (one), and set the linear reduction switch (CPXPARAM_Preprocessing_Linear) to 0 (zero).

Callback return value

The callback returns 0 (zero) if successful and nonzero if an error occurs.

Callback arguments

env

A pointer to the CPLEX environment, as returned by CPXXopenCPLEX/CPXopenCPLEX.

cbdata

A pointer to pass to functions that obtain callback-specific information, such as the number of integer-infeasible values at the current node, or that take callback-specific action, such as to add a cut in a user cut callback.

wherefrom

An integer value reporting where in the optimization this function was called. It will have the value CPX_CALLBACK_MIP_BRANCH.

cbhandle

A pointer to user-private data.

int type

An integer that specifies the type of branch. This table summarizes possible values.

Table 1. Branch Types
Symbolic Constant	Value	Branch
`CPX_TYPE_VAR`	`'0'`	variable branch
`CPX_TYPE_SOS1`	`'1'`	SOS1 branch
`CPX_TYPE_SOS2`	`'2'`	SOS2 branch
`CPX_TYPE_ANY`	`'A'`	multiple bound changes or constraints will be used for branching

sos

An integer that specifies the special ordered set (SOS) used for this branch. A value of -1 specifies that this branch is not an SOS-type branch.

nodecnt

An integer that specifies the number of nodes CPLEX will create from this branch. Possible values are:

0 (zero), or
1, or
2.

If the argument is 0 (zero), the node will be fathomed unless user-specified branches are made; that is, no child nodes are created and the node itself is discarded. Fathoming nodes in this way is not compatible with the method CPXXpopulate and CPXpopulate because that method retains fathomed nodes for subsequent use.

bdcnt

An integer that specifies the number of bound changes defined in the arrays indices, lu, and bd that define the CPLEX-selected branch.

nodebeg

An array with nodecnt entries. The i-th entry is the index into the arrays indices, lu, and bd of the first bound changed for the ith node.

indices

Together with lu and bd, this array defines the bound changes for each of the created nodes. The entry indices[i] is the index for the variable.

lu

Together with indices and bd, this array defines the bound changes for each of the created nodes. The entry lu[i] is one of the three possible values specifying which bound to change:

'L' for lower bound, or
'U' for upper bound, or
'B' for both bounds.

bd

Together with indices and lu, this array defines the bound changes for each of the created nodes. The entry bd[i] specifies the new value of the bound.

nodeest

An array with nodecnt entries that contains estimates of the integer objective-function value that will be attained from the created node.

useraction_p

A pointer to an integer specifying the action for CPLEX to take at the completion of the user callback. The table summarizes the possible actions.

Table 2. Actions to be taken after a user-written branch callback
Value	Symbolic Constant	Action
`0`	`CPX_CALLBACK_DEFAULT`	Use CPLEX-selected branch
`1`	`CPX_CALLBACK_FAIL`	Exit optimization
`2`	`CPX_CALLBACK_SET`	Use user-selected branch, as defined by calls to `CPXXbranchcallbackbranchbds/CPXbranchcallbackbranchbds`