CPXXsetincumbentcallbackfunc and CPXsetincumbentcallbackfunc

Description

The routine CPXXsetincumbentcallbackfunc/CPXsetincumbentcallbackfunc sets and modifies the user-written callback routine to be called when an integer solution has been found but before this solution replaces the incumbent. This callback can be used to discard solutions that do not meet criteria beyond that of the mixed integer programming formulation. When the user-written callback is used in that manner, the user must set the parameter that controls primal and dual reduction type (CPXPARAM_Preprocessing_Reduce) to either the value CPX_PREREDUCE_PRIMALONLY or the value CPX_PREREDUCE_NOPRIMALORDUAL. This setting of the parameter is not necessary when the incumbent callback is used for other purposes.

Variables are 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, variables are in terms of the presolved problem.

Arguments

env

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

incumbentcallback

A pointer to a user-written incumbent 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

Example

 status = CPXsetincumbentcallbackfunc (env, myincumbentcheck,
                                       mydata);

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

Callback description

 int CPXPUBLIC
 callback (CPXCENVptr env,
           void *cbdata,
           int wherefrom,
           void *cbhandle,
           double objval,
           double *x,
           int *isfeas_p,
           int *useraction_p);
 

The incumbent callback is called when CPLEX has found an integer solution, but before this solution replaces the incumbent integer solution.

Variables are 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, variables are in terms of the presolved problem.

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 can have one of the following values:

• CPX_CALLBACK_MIP_INCUMBENT_NODESOLN specifies that the incumbent callback was called for an integral solution in a node of the search tree of the relaxation.
• CPX_CALLBACK_MIP_INCUMBENT_HEURSOLN specifies that the incumbent callback was called for a solution generated by the internal heuristics of CPLEX.
• CPX_CALLBACK_MIP_INCUMBENT_USERSOLN specifies that the incumbent callback was called for a solution generated by the user.
• CPX_CALLBACK_MIP_INCUMBENT_MIPSTART specifies that the incumbent callback was called during MIP start processing. Note that in this case not all callback functionality is available since this happens very early in the search process. For example, you cannot attach or get user data to/from the current node, nor can you do anything else that requires a search tree node context.

cbhandle

A pointer to user private data.

objval

A variable that contains the objective value of the integer solution.

x

An array that contains primal solution values for the integer solution.

isfeas_p

A pointer to an integer variable that determines whether or not CPLEX should use the integer solution specified in x to replace the current incumbent. A nonzero value states that the incumbent should be replaced by x; a zero value states that it should not.

useraction_p

A pointer to an integer to contain the specifier of the action to be taken on completion of the user callback. The table summarizes the possible values.