CPXXgetcallbacknodeinfo and CPXgetcallbacknodeinfo

Description

The routine CPXXgetcallbacknodeinfo/CPXgetcallbacknodeinfo is called from within user-written callbacks during a MIP optimization and accesses information about nodes. The node information is from the original problem if the MIP callback switch between original model and reduced, presolved model (CPXPARAM_MIP_Strategy_CallbackReducedLP) is turned off (set to CPX_OFF). Otherwise, the information is from the presolved problem.

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.

The primary purpose of this routine is to examine nodes in order to select one from which to proceed. In this case, the wherefrom argument is CPX_CALLBACK_MIP_NODE, and a node with any nodeindex value can be queried.

A secondary purpose of this routine is to obtain information about the current node. When the wherefrom argument is any one of the following values, only the current node can be queried.

• CPX_CALLBACK_MIP_CUT_FEAS
• CPX_CALLBACK_MIP_CUT_UNBD
• CPX_CALLBACK_MIP_CUT_LOOP
• CPX_CALLBACK_MIP_CUT_LAST
• CPX_CALLBACK_MIP_INCUMBENT_NODESOLN
• CPX_CALLBACK_MIP_INCUMBENT_HEURSOLN
• CPX_CALLBACK_MIP_INCUMBENT_USERSOLN
• CPX_CALLBACK_MIP_HEURISTIC
• CPX_CALLBACK_MIP_SOLVE
• CPX_CALLBACK_MIP_BRANCH

To query the current node, specify a nodeindex value of 0 (zero). Other values of the wherefrom argument are invalid for this routine. An invalid nodeindex value or wherefrom argument value will result in an error as return value.

The values returned for CPX_CALLBACK_INFO_NODE_SIINF and CPX_CALLBACK_INFO_NODE_NIINF for the current node are the values that applied to the node when it was stored and thus before the branch was solved. As a result, these values should not be used to assess the feasibility of the node. Instead, use the routine CPXXgetcallbacknodeintfeas/CPXgetcallbacknodeintfeas to check the feasibility of a node.

This routine cannot retrieve information about nodes that have been moved to node files. For more information about node files, see the topic Using node files in the CPLEX User's Manual. If the argument nodeindex refers to a node in a node file, CPXXgetcallbacknodeinfo/CPXgetcallbacknodeinfo returns the value CPXERR_NODE_ON_DISK. Nodes still in memory have the lowest index numbers, so a user can loop through the nodes until CPXXgetcallbacknodeinfo/CPXgetcallbacknodeinfo returns an error, and then exit the loop.

Arguments

env

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

cbdata

The pointer passed to the user-written callback. This argument must be the value of cbdata passed to the user-written callback.

wherefrom

An integer value reporting where the user-written callback was called from. This argument must be the value of wherefrom passed to the user-written callback. Do not call this routine with wherefrom==CPX_CALLBACK_MIP_DELETENODE.

Important:

Any routine that queries the current LP solution can yield invalid data when wherefrom==CPX_CALLBACK_MIP because in that case, the MIP callback is called before the LP relaxation of the current node is solved.

nodeindex

The index of the node for which information is requested. Nodes are indexed from 0 (zero) to (nodesleft-1) where nodesleft is obtained from the callback information function CPXXgetcallbackinfo/CPXgetcallbackinfo, with a whichinfo value of CPX_CALLBACK_INFO_NODES_LEFT.

whichinfo

An integer specifying which information is requested. Table 1 summarizes the possible values. Table 2 summarizes possible values returned when the type of information requested is branch type (that is, whichinfo = CPX_CALLBACK_INFO_NODE_TYPE).

result_p

A generic pointer to a variable of type double, CPXINT, CPXLONG, or void*, representing the value returned by whichinfo. (The column C Type in Table 1 shows the type of various values returned by whichinfo.)

Return

The routine returns 0 (zero) if successful and nonzero if an error occurs. The return value CPXERR_NODE_ON_DISK reports an attempt to access a node currently located in a node file on disk.

Example

 status = CPXgetcallbacknodeinfo(env,
                                 cbdata,
                                 wherefrom,
                                 0,
                                 CPX_CALLBACK_INFO_NODE_NIINF,
                                 &numiinf);
 

Some of the values can be queried by two different whichinfo parameters. For example, the depth of a node can be queried by CPX_CALLBACK_INFO_NODE_DEPTH and CPX_CALLBACK_INFO_NODE_DEPTH_LONG. When a query uses CPX_CALLBACK_INFO_NODE_DEPTH_LONG, then result_p must point to a value of type CPXLONG. When a query uses CPX_CALLBACK_INFO_NODE_DEPTH, then result_p must point to a value of type CPXINT. In this case, if the value to be returned in result_p exceeds the maximum value of a 32-bit signed integer, the routine will store INT_MAX in *result_p and return the error CPXERR_OVERFLOW.

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