CPXXsetusercutcallbackfunc and CPXsetusercutcallbackfunc

The routine CPXXsetusercutcallbackfunc/CPXsetusercutcallbackfunc sets and modifies the user-written callback for adding cuts.

int CPXXsetusercutcallbackfunc( CPXENVptr env, int(CPXPUBLIC *cutcallback)(CPXX_CALLBACK_CUT_ARGS), void * cbhandle )

int CPXsetusercutcallbackfunc( CPXENVptr env, int(CPXPUBLIC *cutcallback)(CALLBACK_CUT_ARGS), void * cbhandle )

Description

The routine CPXXsetusercutcallbackfunc/CPXsetusercutcallbackfunc sets and modifies the user-written callback for adding cuts. The user-written callback is called by CPLEX during MIP branch and cut for every node that has an LP optimal solution with objective value below the cutoff and that is also integer infeasible.

Warning:

This is an advanced routine. Advanced routines typically demand a thorough understanding of the algorithms used by CPLEX. Thus they incur a higher risk of incorrect behavior in your application, behavior that can be difficult to debug. Therefore, the team encourages you to consider carefully whether you can accomplish the same task by means of other Callable Library routines instead.

The callback routine adds globally or locally valid cuts to the LP subproblem. The cut may be for 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 invocation of CPXXmipopt/CPXmipopt that calls the callback. Otherwise, the cut is for the presolved problem.

Within the user-written cut callback, the routine CPXXgetcallbacknodelp/CPXgetcallbacknodelp and other query routines from the Callable Library access information about the subproblem. The routines CPXXgetcallbacknodeintfeas/CPXgetcallbacknodeintfeas and CPXXgetcallbacksosinfo/CPXgetcallbacksosinfo examine the status of integer entities.

Within the user-written cut callback, the routine CPXXcutcallbackadd/CPXcutcallbackadd adds globally valid cuts to the current node LP subproblem during MIP branch and cut. Likewise, the routine CPXXcutcallbackaddlocal/CPXcutcallbackaddlocal adds locally valid cuts to the current node LP subproblem during MIP branch and cut. Cuts added to the problem are first put into a cut pool, so they are not present in the subproblem LP until after the user-written cut callback finishes.

Any cuts that are duplicates of cuts already in the subproblem are not added to the subproblem. Otherwise, CPLEX treats the user generated cuts according to the value of the argument purgeable in effect when the cuts are added. See the routine CPXXcutcallbackadd/CPXcutcallbackadd for important details about the argument purgeable.

If cuts have been added, the subproblem is re-solved and evaluated, and, if the LP solution is still integer infeasible and not cut off, the cut callback is called again.

If the model has names, user-added cuts have names of the form unumber where number is a sequence number among all cuts generated.

Special considerations

When you set the MIP callback switch between original model and reduced, presolved model (CPXPARAM_MIP_Strategy_CallbackReducedLP) to CPX_OFF before you call CPXXmipopt and CPXmipopt (that is, you intend for the user cut callback to apply to the original problem), special considerations arise. In this case, CPLEX has to crush the cuts that you added by means of CPXXcutcallbackadd and CPXcutcallbackadd, or CPXXcutcallbackaddlocal and CPXcutcallbackaddlocal. This attempt to crush the cuts can fail due to nonlinear reductions applied in presolve preprocessing. If crushing fails, CPLEX returns the error CPXERR_PRESLV_CRUSHFORM

To avoid this error condition, and to make sure that CPLEX can crush any cut that you supply, disable nonlinear reductions by setting the linear reduction switch (deprecated) (CPXPARAM_Preprocessing_Linear) to CPX_OFF.

Tip:

Crush means to convert an element of the original problem to an element of the presolved problem.

Arguments

env: A pointer to the CPLEX environment, as returned by CPXXopenCPLEX/CPXopenCPLEX.
cutcallback: The pointer to the current user-written cut 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 cut callback.

Return

The routine returns 0 (zero) if successful and nonzero if an error occurs.

Example


 status = CPXsetusercutcallbackfunc(env, cutcallback, cbhandle);

See also the example admipex5.c in the standard distribution of the product.

Callback description


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

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. Its possible values and the corresponding situations are:

Value	Symbolic Constant	Where the callback was called from
`106`	`CPX_CALLBACK_MIP_CUT_LOOP`	The callback was called from the cut loop CPLEX executes at each node.
`114`	`CPX_CALLBACK_MIP_CUT_LAST`	cplex gave up generating cuts, but gives one last chance for the user to generate some more. If, as a result, cuts are added to the relaxation CPLEX goes back into the cut loop.

cbhandle

A pointer to user private data.

useraction_p

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

Table 1. Actions to be taken after a user-written cut callback
Value	Symbolic Constant	Action
`0`	`CPX_CALLBACK_DEFAULT`	Use cuts as added
`1`	`CPX_CALLBACK_FAIL`	Exit optimization
`2`	`CPX_CALLBACK_SET`	Use cuts as added
`3`	`CPX_CALLBACK_ABORT_CUT_LOOP`	Exit the cut loop and move on to branching.