Using the Callbacks

Console users are constantly provided with information on the standard output device by the Optimizer as it searches for a solution to the current problem. The same output is also available to library users if a log file has been set up using XPRSsetlogfile. However, whilst Console users can respond to this information as it is produced and allow it to influence their session, the same is not immediately true for library users, since their program must be written and compiled before the session is initiated. For such users, a more interactive alternative to the above forms of output is provided by the use of callback functions.

The library callbacks are a collection of functions which allow user–defined routines to be specified to the Optimizer. In this way, users may define their own routines which should be called at various stages during the optimization process, prompting the Optimizer to return to the user's program before continuing with the solution algorithm. Perhaps the three most general of the callback functions are those associated with the search for an LP solution. However, the vast majority of situations in which such routines might be called are associated with the global search, and will be addressed below.

Output Callbacks

Instead of catching the standard output from the Optimizer and saving it to a log file, the callback XPRSaddcbmessage allows the user to define a routine which should be called every time a text line is output by the Optimizer. Since this returns the status of each message output, the user's routine could test for error or warning messages and take appropriate action accordingly.

LP Callbacks

The functions XPRSaddcblplog and XPRSaddcbbarlog allow the user to respond after each iteration of either the simplex or barrier algorithms, respectively. The controls LPLOG and BAROUTPUT may additionally be set to reduce the frequency at which these routines should be called.

Global Search Callbacks

When a problem with global entities is to be optimized, a large number of sub problems, called nodes, must typically be solved as part of the global tree search. At various points in this process user–defined routines can be called, depending on the callback that is used to specify the routine to the Optimizer.

In a global tree search, the Optimizer starts by selecting an active node amongst all candidates (known as a full backtrack) and then proceed with solving it, which can lead to new descendent nodes being created. If there is a descendent node, the optimizer will by default select one of these next to solve and repeat this iterative descend while new descendent nodes are being created. This dive stops when it reaches a node that is found to be infeasible or cutoff, at which point the Optimizer will perform a full backtrack again and repeat the process with a new active node.

A routine may be called whenever a node is selected by the optimizer during a full backtrack, using XPRSaddcbchgnode. This will also allow a user to directly select the active node for the optimizer. Whenever a new node is created, a routine set by XPRSaddcbnewnode will be called, which can be used to record the identifier of the new node, e.g. for use with XPRSaddcbchgnode.

When the Optimizer solves a new node, it will first call any routine set by XPRSaddcbprenode, which can be used to e.g. tighten bounds on columns (with XPRSchgbounds) as part of a user node presolve. Afterwards, the LP relaxation of the node problem is solved to obtain a feasible solution and a best bound for the node. This might be followed by one or more rounds of cuts. If the node problem is found to be infeasible or cutoff during this process, a routine set by XPRSaddcbinfnode will be called. Otherwise, a routine set by XPRSaddcboptnode will be called to let the user know that the optimizer now has an optimal solution to the LP relaxation of the node problem. In this routine, the user is allowed to add cuts (see section Working with the Cut Manager) and tighten bounds to tighten the node problem, or apply branching objects (see XPRS_bo_create) to separate on the current node problem. If the user modifies the problem inside this optnode callback routine, the optimizer will automatically resolve the node LP and, if the LP is still feasible, call the optnode routine again.

If the LP relaxation solution to the node problem also satisfies all global entities and the user has not added any branching objects, i.e., if it is a MIP solution, the Optimizer will call a routine set by XPRSaddcbpreintsol before saving the new solution, and call a routine set by XPRSaddcbintsol after saving the solution. These two routines will also be called whenever a new MIP solution is found using one of the Optimizer heuristics.

Otherwise, if the node LP solution does not satisfy the global entities (or any user branching objects), the Optimizer will proceed with branching. After the optimizer has selected the candidate entity for branching, a routine set by XPRSaddcbchgbranch will be called, which also allows a user to change the selected candidate. If, during the candidate evaluation the optimizer discovers that e.g. bounds can be tightened, it will tighten the node problem and go back to resolving the node LP, followed by the callback routines explained above.

When the Optimizer finds a better MIP solution, it is possible that some of the nodes in the active nodes pool are cut off due to having an LP solution bound that is worse than the new cutoff value. For such nodes, a routine set by XPRSaddcbnodecutoff will be called and the node will be dropped from the active nodes pool.

The final global callback, XPRSaddcbgloballog, is more similar to the LP search callbacks, allowing a user's routine to be called whenever a line of the global log is printed. The frequency with which this occurs is set by the control MIPLOG.