CPXXsetnodecallbackfunc and CPXsetnodecallbackfunc

Description

The routine CPXXsetnodecallbackfunc/CPXsetnodecallbackfunc sets and modifies the user-written callback to be called during MIP optimization after CPLEX has selected a node to explore, but before this exploration is carried out. The callback routine can change the node selected by CPLEX to a node selected by the user.

In opportunistic parallel mode, CPLEX supports queries only about the current node, that is, the node with index 0 (zero). CPLEX does not support queries about any other open node. Queries about any other open node than the current node with index 0 (zero) in opportunistic parallel mode can provoke undefined behavior. Consequently, the user should not use the node callback in opportunistic parallel mode. If you think you need the node callback in opportunistic parallel mode, restrict its use to simple tracking; that is, ask only about the current node, and set the user action to CPX_CALLBACK_DEFAULT.

Arguments

env

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

nodecallback

A pointer to the current user-written node callback. If no callback has been set, the pointer evaluates to NULL.

cbhandle

A pointer to user private data. This pointer is passed to the user-written node callback.

Return

Example

 status = CPXsetnodecallbackfunc(env, mynodefunc, mydata);

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

Callback description

 int CPXPUBLIC
 callback (CPXCENVptr env,
           void *cbdata,
           int wherefrom,
           void *cbhandle,
           CPXCNT *nodeindex_p,
           int *useraction_p);
 

 int CPXPUBLIC
 callback (CPXCENVptr env,
           void *cbdata,
           int wherefrom,
           void *cbhandle,
           int *nodeindex_p,
           int *useraction_p);
 

CPLEX calls the node callback after selecting the next node to explore. The user can choose another node by setting the argument values of the callback.

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 has the value CPX_CALLBACK_MIP_NODE.

cbhandle

A pointer to user private data.

nodeindex_p

A pointer to an integer that specifies the node number of the user-selected node. The node selected by CPLEX is node number 0 (zero). Other nodes are numbered relative to their position in the tree, and this number changes with each tree operation. The unchanging identifier for a node is its sequence number. To access the sequence number of a node, use the routine CPXXgetcallbacknodeinfo/CPXgetcallbacknodeinfo. An error results if a user attempts to select a node that has been moved to a node file. (See the topic Using node files in the CPLEX User's Manual for more information about node files.)

useraction_p

A pointer to an integer specifying the action to be taken on completion of the user callback. The table summarizes the possible actions.