The routine CPXgetbranchcallbackfunc accesses the user-written callback routine to be called during MIP optimization after a branch has been selected but before the branch is carried out. ILOG CPLEX uses the callback routine to change its branch selection.

Example

 CPXgetbranchcallbackfunc(env, &current_callback,
                          &current_handle);

See also Advanced MIP Control Interface in the ILOG CPLEX User's Manual.

Parameters

env

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

branchcallback_p

The address of the pointer to the current user-written branch callback. If no callback has been set, the returned pointer evaluates to NULL.

cbhandle_p

The address of a variable to hold the user's private pointer.

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.

Custom branching strategies can be implemented by calling the CPLEX function CPXbranchcallbackbranchbds 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 on success 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.