The routine CPXsetbranchcallbackfunc sets and modifies the user-written 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.

Example

 status = CPXsetbranchcallbackfunc (env, mybranchfunc, mydata);
 

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

Parameters

env

A pointer to the CPLEX environment, as returned by 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.

Callback description

 int callback (CPXCENVptr env,
               void       *cbdata,
               int        wherefrom,
               void       *cbhandle,
               int        type,
               int        sos,
               int        nodecnt,
               int        bdcnt,
               double     *nodeest,
               int        *nodebeg,
               int        *indices,
               char       *lu,
               int        *bd,
               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 ILOG 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. ILOG CPLEX occasionally elects to branch by changing a number of variables bounds 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.

Custom branching strategies can be implemented by calling the CPLEX routine CPXbranchcallbackbranchbds, CPXbranchcallbadkbranchconstraints, or CPXbranchcallbackbranchgeneral and setting the useraction variable to CPX_CALLBACK_SET. Then CPLEX will carry out these branches instead of the CPLEX-selected branches.

Branch variables are in terms of the original problem if the parameter CPX_PARAM_MIPCBREDLP is set to CPX_OFF before the call to CPXmipopt that calls the callback. Otherwise, branch variables are in terms of the presolved problem.

Callback return value

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

Callback arguments

env

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

cbdata

A pointer passed from the optimization routine to the user-written callback that identifies the problem being optimized. The only purpose of this pointer is to pass it to the callback information routines.

wherefrom

An integer value indicating 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 indicates the type of branch. This table summarizes possible values.

sos

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

nodecnt

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

• 0 (zero), or
• 1, or
• 2.

If the argument is 0, the node will be fathomed unless user-specified branches are made; that is, no child nodes are created and the node itself is discarded.

bdcnt

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

nodeest

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

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 indicating 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] indicates the new value of the bound.

useraction_p

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