CPX_CALLBACKCONTEXT_CANDIDATE

Generic callback at feasible solution candidate

#define CPX_CALLBACKCONTEXT_CANDIDATE 0x0020

Description

CPLEX invokes the generic callback when it has found a new candidate for an integer-feasible solution or has encountered an unbounded relaxation. CPLEX offers the callback a chance to reject the candidate solution or the unbounded relaxation. To distinguish whether the callback was invoked for a candidate integer-feasible solution or an unbounded relaxation, use the routines CPXXcallbackcandidateispoint and CPXcallbackcandidateispoint and CPXXcallbackcandidateisray and CPXcallbackcandidateisray.

If CPXXcallbackcandidateispoint and CPXcallbackcandidateispoint shows that CPLEX has found a candidate feasible point, then you can query that point by using CPXXcallbackgetcandidatepoint and CPXcallbackgetcandidatepoint.

If CPXXcallbackcandidateisray and CPXcallbackcandidateisray shows that CPLEX has encountered an unbounded relaxation, then you can get the unbounded ray from CPXXcallbackgetcandidateray and CPXcallbackgetcandidateray.

In either the case, the user can reject the feasible point or unbounded direction by means of the routines CPXXcallbackrejectcandidate and CPXcallbackrejectcandidate and CPXXcallbackrejectcandidatelocal and CPXcallbackrejectcandidatelocal.

You can use the constant CPX_CALLBACKCONTEXT_CANDIDATE in two different ways:
  • As a value passed into the generic callback function to specify in which context the generic callback is invoked.
  • As a bit-wise OR with the where argument of the routine CPXXcallbacksetfunc and CPXcallbacksetfunc to specify in which situations CPLEX should invoke the generic callback.
Important: All information queried from a callback in this context is thread-local.
Important: If the callback is invoked for a feasible point and does not reject the candidate, this is no guarantee that the candidate will become the new incumbent. The callback is only one of many feasibility tests that are performed on a candidate solution.

Candidate context and lazy constraint separation

This context allows a user to separate lazy constraints. These constraints are always specified in terms of the original model and possibly have to be crushed to the presolved model. (This crushing happens internally in CPLEX.) To guarantee that lazy constraints can be crushed, certain presolve reductions (such as nonlinear reductions) have to be disabled.

CPLEX cannot tell whether the user plans to separate lazy constraints. Consequently, CPLEX always disables dual and nonlinear reductions in presolve if the user asks for the callback to be invoked in this context.

Moreover, if a user calls CPXXcallbacksetfunc and CPXcallbacksetfunc to modify the callback function or the set of contexts in which the callback is invoked, then this change can render a resident solution invalid: a new or modified callback possibly rejected that solution. CPLEX does not validate any resident solution information against a potential new callback. If you modify the callback settings with respect to CPX_CALLBACKCONTEXT_CANDIDATE, then it is best to set advanced start switch to 0 (zero) and re-solve. This way, you can be sure that solution information is consistent with lazy constraints separated in a callback.

Incompatibility with Benders algorithm

This context is incompatible with Benders algorithm.

See also