CPXXgetcallbackinfo and CPXgetcallbackinfo

The routine CPXXgetcallbackinfo/CPXgetcallbackinfo accesses information about the current optimization process from within a user-written callback function.

int CPXXgetcallbackinfo( CPXCENVptr env, void * cbdata, int wherefrom, int whichinfo, void * result_p )

int CPXgetcallbackinfo( CPXCENVptr env, void * cbdata, int wherefrom, int whichinfo, void * result_p )

Description

The routine CPXXgetcallbackinfo/CPXgetcallbackinfo accesses information about the current optimization process from within a user-written callback function.

Note:

This routine is the only routine that can access optimization status information from within a nonadvanced user-written callback function. It is also the only Callable Library routine that may be called from within a nonadvanced user-written callback function, and in fact, may only be called from the callback function.

Important:

Some of the values can be queried by two different whichinfo arguments. For example, the iteration count can be queried by CPX_CALLBACK_INFO_ITCOUNT and CPX_CALLBACK_INFO_ITCOUNT_LONG. Similarly, the node count can be queried by CPX_CALLBACK_INFO_NODE_COUNT and CPX_CALLBACK_INFO_NODE_COUNT_LONG. When the query uses CPX_CALLBACK_INFO_ITCOUNT_LONG (or CPX_CALLBACK_INFO_NODE_COUNT_LONG), then result_p must point to a value of type CPXLONG. When the query uses CPX_CALLBACK_INFO_ITCOUNT (or CPX_CALLBACK_INFO_NODE_COUNT), 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.

For LP algorithms:

whichinfo type of *result_p description
CPX_CALLBACK_INFO_STARTDETTIME double deterministic time stamp
CPX_CALLBACK_INFO_STARTTIME double system time stamp
CPX_CALLBACK_INFO_ENDDETTIME double deterministic time stamp
CPX_CALLBACK_INFO_ENDTIME double system time stamp
CPX_CALLBACK_INFO_PRIMAL_OBJ double primal objective value
CPX_CALLBACK_INFO_DUAL_OBJ double dual objective value
CPX_CALLBACK_INFO_PRIMAL_INFMEAS double measure of primal infeasibility
CPX_CALLBACK_INFO_DUAL_INFMEAS double measure of dual infeasibility
CPX_CALLBACK_INFO_PRIMAL_FEAS int 1 if primal feasible, 0 if not
CPX_CALLBACK_INFO_DUAL_FEAS int 1 if dual feasible, 0 if not
CPX_CALLBACK_INFO_ITCOUNT CPXINT iteration count, truncated to 32bit
CPX_CALLBACK_INFO_ITCOUNT_LONG CPXLONG iteration count
CPX_CALLBACK_INFO_CROSSOVER_PPUSH CPXINT primal push crossover itn. count, truncated to 32bit
CPX_CALLBACK_INFO_CROSSOVER_PPUSH_LONG CPXLONG primal push crossover itn. count
CPX_CALLBACK_INFO_CROSSOVER_PEXCH CPXINT primal exchange crossover itn. count, truncated to 32bit
CPX_CALLBACK_INFO_CROSSOVER_PEXCH_LONG CPXLONG primal exchange crossover itn. count
CPX_CALLBACK_INFO_CROSSOVER_DPUSH CPXINT dual push crossover itn. count, truncated to 32bit
CPX_CALLBACK_INFO_CROSSOVER_DPUSH_LONG CPXLONG dual push crossover itn. count
CPX_CALLBACK_INFO_CROSSOVER_DEXCH int dual exchange crossover itn. count
CPX_CALLBACK_INFO_CROSSOVER_SBCNT int number of super-basic variables left in the basis
CPX_CALLBACK_INFO_USER_PROBLEM CPXCLPptr returns pointer to original user problem; available for primal, dual, barrier, mip

Crossover from a barrier to a simplex solution reduces the super-basic count. In fact, in a barrier crossover, if the count reaches 0 (zero), the crossover has finished. Thus, the super-basic count serves as a measure of progress for the crossover algorithm.

For Network algorithms:

whichinfo type of *result_p description
CPX_CALLBACK_INFO_STARTDETTIME double deterministic time stamp
CPX_CALLBACK_INFO_STARTTIME double system time stamp
CPX_CALLBACK_INFO_ENDDETTIME double deterministic time stamp
CPX_CALLBACK_INFO_ENDTIME double time stamp
CPX_CALLBACK_INFO_PRIMAL_OBJ double primal objective value
CPX_CALLBACK_INFO_PRIMAL_INFMEAS double measure of primal infeasibility
CPX_CALLBACK_INFO_ITCOUNT CPXINT iteration count, truncate to 32bit
CPX_CALLBACK_INFO_ITCOUNT_LONG CPXLONG iteration count
CPX_CALLBACK_INFO_PRIMAL_FEAS int 1 if primal feasible, 0 if not

For Presolve algorithms:

whichinfo type of *result_p description
CPX_CALLBACK_INFO_STARTDETTIME double deterministic time stamp
CPX_CALLBACK_INFO_STARTTIME double system time stamp
CPX_CALLBACK_INFO_ENDDETTIME double deterministic time stamp
CPX_CALLBACK_INFO_ENDTIME double time stamp
CPX_CALLBACK_INFO_PRESOLVE_ROWSGONE CPXINT number of rows eliminated
CPX_CALLBACK_INFO_PRESOLVE_COLSGONE CPXINT number of columns eliminated
CPX_CALLBACK_INFO_PRESOLVE_AGGSUBST CPXINT number of aggregator substitutions, truncated to 32bit
CPX_CALLBACK_INFO_PRESOLVE_AGGSUBST_LONG CPXLONG number of aggregator substitutions
CPX_CALLBACK_INFO_PRESOLVE_COEFFS CPXINT number of modified coefficients, truncated to 32bit
CPX_CALLBACK_INFO_PRESOLVE_COEFFS_LONG CPXLONG number of modified coefficients

For MIP algorithms and informational callbacks:

whichinfo type of *result_p description
CPX_CALLBACK_INFO_STARTDETTIME double deterministic time stamp
CPX_CALLBACK_INFO_STARTTIME double system time stamp
CPX_CALLBACK_INFO_ENDDETTIME double deterministic time stamp
CPX_CALLBACK_INFO_ENDTIME double time stamp
CPX_CALLBACK_INFO_BEST_INTEGER double obj. value of best integer solution
CPX_CALLBACK_INFO_BEST_REMAINING double obj. value of best remaining node
CPX_CALLBACK_INFO_NODE_COUNT CPXINT total number of nodes solved, truncated to 32bit
CPX_CALLBACK_INFO_NODE_COUNT_LONG CPXLONG total number of nodes solved
CPX_CALLBACK_INFO_NODES_LEFT CPXINT number of remaining nodes, truncated to 32bit
CPX_CALLBACK_INFO_NODES_LEFT_LONG CPXLONG number of remaining nodes
CPX_CALLBACK_INFO_MIP_ITERATIONS CPXINT total number of MIP iterations, truncated to 32bit
CPX_CALLBACK_INFO_MIP_ITERATIONS_LONG CPXLONG total number of MIP iterations
CPX_CALLBACK_INFO_MIP_REL_GAP double accesses the current relative gap, like the routine CPXXgetmiprelgap/CPXgetmiprelgap.
CPX_CALLBACK_INFO_MIP_FEAS CPXINT returns 1 (one) if a feasible solution exists; otherwise, 0 (zero)
CPX_CALLBACK_INFO_CUTOFF double updated cutoff value
CPX_CALLBACK_INFO_PROBE_PHASE int current phase of probing (0-3)
CPX_CALLBACK_INFO_PROBE_PROGRESS double fraction of probing phase completed (0.0-1.0)
CPX_CALLBACK_INFO_FRACCUT_PROGRESS double fraction of Gomory cut generation for the pass completed (0.0 - 1.0)
CPX_CALLBACK_INFO_DISJCUT_PROGRESS double fraction of disjunctive cut generation for the pass completed (0.0 - 1.0)
CPX_CALLBACK_INFO_FLOWMIR_PROGRESS double fraction of flow cover and MIR cut generation for the pass completed (0.0 - 1.0)
CPX_CALLBACK_INFO_KAPPA_STABLE double percentage of stable simplex bases (condition number less than 1e+7)
CPX_CALLBACK_INFO_KAPPA_SUSPICIOUS double percentage of questionable simplex bases (condition number between 1e+7 and 1e+10)
CPX_CALLBACK_INFO_KAPPA_UNSTABLE double percentage of unstable simplex bases (condition number between 1e+10 and 1e+14)
CPX_CALLBACK_INFO_KAPPA_ILLPOSED double percentage of ill-posed simplex bases (condition number greater than 1e+14)
CPX_CALLBACK_INFO_KAPPA_MAX double highest condition number encountered
CPX_CALLBACK_INFO_KAPPA_ATTENTION double Indicator of numerical difficulties. See the symbolic value CPX_KAPPA_ATTENTION for more detail.

The information specified by variations of CPX_CALLBACK_INFO_KAPPA_ is available only when all of these conditions are met:

  • The subproblems are solved by simplex.
  • The parameter to control MIP kappa computation (CPXPARAM_MIP_Strategy_KappaStats) is set.
  • CPLEX has processed at least one LP-basis during the solve.

In all other cases, CPLEX returns the error CPXERR_NO_KAPPASTATS.

You can query the relative MIP gap between the current best primal and dual bounds outside a callback with the routine CPXXgetmiprelgap/CPXgetmiprelgap.

For distributed parallel MIP algorithms and informational callbacks:

Because of the distributed aspects of such an application, special considerations apply to informational callbacks in a distributed parallel MIP application. For example, when you query certain information by means of this routine in the Callable Library (C API), the following considerations apply:
  • Queries about cut counts, such as CPX_CALLBACK_INFO_COVER_COUNT, always return 0 (zero).
  • Queries about MIP kappa statistics, such as CPX_CALLBACK_INFO_KAPPA_MAX, result in the error message CPXERR_NO_KAPPASTATS.
  • The number of threads, as queried by CPX_CALLBACK_INFO_USER_THREADS, is always 1 (one).
  • The user thread index as identified by CPX_CALLBACK_INFO_MY_THREAD_NUM is always 0 (zero).
  • Queries about the current node count, the number of nodes left, and the iteration count all return correct values during distributed MIP tree search (that is, branch and bound) after ramp up terminates. However, during ramp up, the following queries always return 0 (zero):
    • CPX_CALLBACK_INFO_NODE_COUNT
    • CPX_CALLBACK_INFO_NODE_COUNT_LONG
    • CPX_CALLBACK_INFO_NODES_LEFT
    • CPX_CALLBACK_INFO_NODES_LEFT_LONG
    • CPX_CALLBACK_INFO_MIP_ITERATIONS
    • CPX_CALLBACK_INFO_MIP_ITERATIONS_LONG
  • The informational callback is only called at synchronization points during distributed MIP optimization; that is, less frequently than in conventional MIP optimization in shared memory.

For MIP algorithms and advanced callbacks:

whichinfo type of *result_p description
CPX_CALLBACK_INFO_STARTDETTIME double deterministic time stamp
CPX_CALLBACK_INFO_STARTTIME double system time stamp
CPX_CALLBACK_INFO_ENDDETTIME double deterministic time stamp
CPX_CALLBACK_INFO_ENDTIME double time stamp
CPX_CALLBACK_INFO_BEST_INTEGER double obj. value of best integer solution
CPX_CALLBACK_INFO_BEST_REMAINING double obj. value of best remaining node
CPX_CALLBACK_INFO_NODE_COUNT CPXINT total number of nodes solved, truncated to 32bit
CPX_CALLBACK_INFO_NODE_COUNT_LONG CPXLONG total number of nodes solved
CPX_CALLBACK_INFO_NODES_LEFT CPXINT number of remaining nodes, truncate to 32bit
CPX_CALLBACK_INFO_NODES_LEFT_LONG CPXLONG number of remaining nodes
CPX_CALLBACK_INFO_MIP_ITERATIONS CPXINT total number of MIP iterations, truncate to 32bit
CPX_CALLBACK_INFO_MIP_ITERATIONS_LONG CPXLONG total number of MIP iterations
CPX_CALLBACK_INFO_MIP_FEAS int returns 1 (one) if a feasible solution exists; otherwise, 0 (zero)
CPX_CALLBACK_INFO_CUTOFF double updated cutoff value
CPX_CALLBACK_INFO_CLIQUE_COUNT int number of clique cuts added
CPX_CALLBACK_INFO_COVER_COUNT int number of cover cuts added
CPX_CALLBACK_INFO_DISJCUT_COUNT int number of disjunctive cuts added
CPX_CALLBACK_INFO_FLOWCOVER_COUNT int number of flow cover cuts added
CPX_CALLBACK_INFO_FLOWPATH_COUNT int number of flow path cuts added
CPX_CALLBACK_INFO_FRACCUT_COUNT int number of Gomory fractional cuts added
CPX_CALLBACK_INFO_GUBCOVER_COUNT int number of GUB cover cuts added
CPX_CALLBACK_INFO_IMPLBD_COUNT int number of implied bound cuts added
CPX_CALLBACK_INFO_LANDPCUT_COUNT int number of lift and project cuts added
CPX_CALLBACK_INFO_MCFCUT_COUNT int number of multi-commodity flow cuts added
CPX_CALLBACK_INFO_MIRCUT_COUNT int number of mixed integer rounding cuts added
CPX_CALLBACK_INFO_ZEROHALFCUT_COUNT int number of zero-half cuts added
CPX_CALLBACK_INFO_USERCUT_COUNT int number of user cuts added
CPX_CALLBACK_INFO_TABLECUT_COUNT int number of lazy constraints added
CPX_CALLBACK_INFO_SOLNPOOLCUT_COUNT int number of solution pool cuts added
CPX_CALLBACK_INFO_USER_PROBLEM CPXCLPptr returns pointer to original user problem; available for primal, dual, barrier, MIP
CPX_CALLBACK_INFO_PROBE_PHASE int current phase of probing (0-3)
CPX_CALLBACK_INFO_PROBE_PROGRESS double fraction of probing phase completed (0.0 - 1.0)
CPX_CALLBACK_INFO_FRACCUT_PROGRESS double fraction of Gomory cut generation for the pass completed (0.0 - 1.0)
CPX_CALLBACK_INFO_DISJCUT_PROGRESS double fraction of disjunctive cut generation for the pass completed (0.0 - 1.0)
CPX_CALLBACK_INFO_FLOWMIR_PROGRESS double fraction of flow cover and MIR cut generation for the pass completed (0.0 - 1.0)
CPX_CALLBACK_INFO_KAPPA_STABLE double percentage of stable simplex bases (condition number less than 1e+7)
CPX_CALLBACK_INFO_KAPPA_SUSPICIOUS double percentage of questionable simplex bases (condition number between 1e+7 and 1e+10)
CPX_CALLBACK_INFO_KAPPA_UNSTABLE double percentage of unstable simplex bases (condition number between 1e+10 and 1e+14)
CPX_CALLBACK_INFO_KAPPA_ILLPOSED double percentage of ill-posed simplex bases (condition number greater than 1e+14)
CPX_CALLBACK_INFO_KAPPA_MAX double highest condition number encountered
CPX_CALLBACK_INFO_KAPPA_ATTENTION double Indicator of numerical difficulties. See the symbolic value CPX_KAPPA_ATTENTION for more detail.
CPX_CALLBACK_INFO_MY_THREAD_NUM int identifier of the parallel thread making this call
CPX_CALLBACK_INFO_USER_THREADS int total number of parallel threads currently running

For Tuning:

whichinfo type of *result_p description
CPX_CALLBACK_INFO_STARTDETTIME double deterministic time stamp
CPX_CALLBACK_INFO_STARTTIME double system time stamp
CPX_CALLBACK_INFO_ENDDETTIME double deterministic time stamp
CPX_CALLBACK_INFO_ENDTIME double time stamp
CPX_CALLBACK_INFO_TUNING_PROGRESS double elapsed percentage of total tuning time

Arguments

Name Description
env

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

cbdata

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

wherefrom

An integer value specifying the optimization algorithm from which the user-written callback function was called. The argument wherefrom must be the value of wherefrom passed to the user-written callback function. See CPXXgetlpcallbackfunc/CPXgetlpcallbackfunc, CPXXgetmipcallbackfunc/CPXgetmipcallbackfunc, and CPXXgetnetcallbackfunc/CPXgetnetcallbackfunc for possible values of wherefrom and their meaning.

whichinfo

An integer value specifying the specific information that should be returned by CPXXgetcallbackinfo/ CPXgetcallbackinfo to the result argument. Values for whichinfo, the type of the information returned into *result_p, plus a description appear in the table.

result_p

A generic pointer to a variable of type double, CPXINT, or CPXLONG, depending on the value of whichinfo, as documented in the following tables.

Return

The routine returns 0 (zero) if successful and nonzero if an error occurs. If nonzero, the requested value may not be available for the specific optimization algorithm. For example, the dual objective is not available from primal simplex.

Example

See lpex4.c in the CPLEX User's Manual.

Suppose you want to know the objective value on each iteration for a graphical user display. In addition, if primal simplex is not feasible after 1000 iterations, you want to stop the optimization. The function mycallback is a callback function to do this.

int mycallback (CPXCENVptr env, void *cbdata, int wherefrom,
void *cbhandle)
{
int itcount;
double objval;
int ispfeas;
int status = 0;

if ( wherefrom == CPX_CALLBACK_PRIMAL ) {
status = CPXgetcallbackinfo (env, cbdata, wherefrom,
			    CPX_CALLBACK_INFO_PRIMAL_FEAS,
			    &ispfeas);
if ( status ) {
  fprintf (stderr,"error %d in CPXgetcallbackinfo \n", status);
  status = 1;
  goto TERMINATE;
}
if ( ispfeas ) {
  status = CPXgetcallbackinfo (env, cbdata, wherefrom,
			       CPX_CALLBACK_INFO_PRIMAL_OBJ,
			       &objval) )
  if ( status ) {
     fprintf (stderr,"error %d in CPXgetcallbackinfo \n",
	      status);
     status = 1;
     goto TERMINATE;
  }
}
else {
  status = CPXgetcallbackinfo (env, cbdata, wherefrom,
			       CPX_CALLBACK_INFO_ITCOUNT,
			       &itcount);
  if ( status ) {
     fprintf (stderr,"error %d in CPXgetcallbackinfo \n", status);
     status = 1;
     goto TERMINATE;
  }
  if ( itcount > 1000 ) status = 1;
}
}

TERMINATE:
return (status);
}