# TOMLAB  
# REGISTER (TOMLAB)
# LOGIN  
# myTOMLAB
TOMLAB LOGO

« Previous « Start » Next »

D  The Matlab Interface Routines - Callback Routines

D.1  xpcb_bl

Purpose
XpressMP Barrier Log Callback routine

Calling Syntax
[quit,xpcontrol] = xpcb_bl(x, slack, pi, rc, Prob)

Description of Input

x
Solution vector x with decision variable values (n × 1 vector)
slack Vector of slack variables.
pi Lagrange multipliers for the linear constraints, i.e. the dual variables.
rc Lagrange multipliers for the inequality variable constraints, i.e. the reduced costs.
Prob A structure. If TOMLAB calls xpress, then Prob is the standard TOMLAB problem structure, otherwise the user optionally can set: Prob.P = ProblemNumber;, where ProblemNumber is some integer. When the callback routine is called then the arrays that define the current problem are added as fields in Prob. The additional fields are Prob.QP.c, Prob.QP.F, Prob.x_L, Prob.x_U, Prob.A, Prob.b_L, Prob.b_U. Also Prob.MIP.KNAPSACK is set and variables defining the set of integer variables.

Description of Output

quit
Return flag. If non-zero, XpressMP will exit.
xpcontrol Structure with the control fields that the user wishes to be set in XpressMP 

Global Parameters Used
   
xpControlVariables Structure with all XpressMP ontrol variables. Set before the callback.
xpProblemAttrib Structure with all XpressMP roblem attributes. Set before the callback.
 

Description
At each iteration running the barrier algorithm, this routine is called.

Examples
Default some printing is done, and the user should instead write the Matlab statements wanted. The definition of a few control variables are shown as comments.

See Also
See the documentation for the XpressMP routine XPRSsetcbbarlog.

D.2  xpcb_gl

Purpose
XpressMP Global Log Callback routine

Calling Syntax
[quit,xpcontrol] = xpcb_gl(x, xBIS, Prob)

Description of Input

x
Latest solution vector x with decision variable values (n × 1 vector). If control variable MIPINFEAS = 0, then x is a new integer solution. If MIPINFEAS > 0, then x is the latest simplex solution.
xBIS Solution vector xBIS with best integer solution found (n × 1 vector), otherwise empty. If control variable MIPINFEAS = 0, then xBIS is the best integer solution found before this step. The new integer solution might or might not be an improvement. If MIPINFEAS > 0, then xBIS is either empty, or the best integer solution found so far.

Description of Input

Prob
A structure. If TOMLAB calls xpress, then Prob is the standard TOMLAB problem structure, otherwise the user optionally can set: Prob.P = ProblemNumber;, where ProblemNumber is some integer. When the callback routine is called then the arrays that define the current problem are added as fields in Prob. The additional fields are Prob.QP.c, Prob.QP.F, Prob.x_L, Prob.x_U, Prob.A, Prob.b_L, Prob.b_U.

Description of Output

quit
Return flag. If non-zero, XpressMP will exit.
xpcontrol Structure with the control fields that the user wishes to be set in XpressMP 

Global Parameters Used
   
xpControlVariables Structure with all XpressMP control variables. Set before the callback.
xpProblemAttrib Structure with all XpressMP problem attributes. Set before the callback.

Description
This is the global log callback routine. How often it is called is dependent on the control variable MIPLOG:
  • MIPLOG = 0. No printout in global.
  • MIPLOG = 1. Print out summary statement at the end.
  • MIPLOG = 2. Print out all solutions found, i.e. all integer valued solutions.
  • MIPLOG = 3. Print out each node.
  • MIPLOG < 0. Print out each −MIPLOGth node.
The default value is MIPLOG = −100. If to apply the simple KNAPSACK heuristic that is programmed as an example in this callback routine, then xpcontrol.MIPLOG = 3 should be set.

The following logic describes what x and xBIS are set as, and the relations to the problem attributes that contains function values.
if XPRS_MIPINFEAS > 0
   x    is LP      solution, f(x) = XPRS_LPOBJVAL
   xBIS is empty or the best integer solution, f(x) = XPRS_MIPOBJVAL
   XPRS_MIPOBJVAL == 1E20 before the first integer solution is found
end
if XPRS_MIPINFEAS == 0
   if XPRS_LPOBJVAL == XPRS_MIPOBJVAL
      x    is the best integer solution found, f(x) = XPRS_LPOBJVAL
      xBIS is the old best integer solution found, unknown f(xBIS).
           f(xBIS) could be computed as Prob.QP.c' * xBIS;
   else
      x    is the a new integer solution, but not the best, f(x) = XPRS_LPOBJVAL
      xBIS is the best integer solution found, f(xBIS) = XPRS_MIPOBJVAL
   end
end
Examples
The routine writes out the node number, the node depth, the best bound and the best integer solution so far found. The Matlab code shows an implementation of a simple heuristic, an XpressMP standard example similar to the example file:
\xpressmp\examples\optimizer\knapsack\knapsack.c.
This implementation assumes that a minimum problem is solved. The heuristic is used if Prob.MIP.KNAPSACK is true. Also xpcontrol.MIPLOG = 3 must be set.

See Also
See the documentation for the XpressMP routine XPRSsetcbgloballog.

D.3  xpcb_il

Purpose
XpressMP Simplex Log Callback routine

Calling Syntax
[quit,xpcontrol] = xpcb_il(x, slack, pi, rc, Prob)

Description of Input

x
Solution vector x with decision variable values (n × 1 vector)
slack Vector of slack variables.
pi Lagrange multipliers for the linear constraints, i.e. the dual variables.
rc Lagrange multipliers for the inequality variable constraints, i.e. the reduced costs.
Prob A structure. If TOMLAB calls xpress, then Prob is the standard TOMLAB problem structure, otherwise the user optionally can set: Prob.P = ProblemNumber;, where ProblemNumber is some integer. When the callback routine is called then the arrays that define the current problem are added as fields in Prob. The additional fields are Prob.QP.c, Prob.QP.F, Prob.x_L, Prob.x_U, Prob.A, Prob.b_L, Prob.b_U.

Description of Output

quit
Return flag. If non-zero, XpressMP will exit.
xpcontrol Structure with the control fields that the user wishes to be set in XpressMP 

Global Parameters Used
   
xpControlVariables Structure with all XpressMP control variables. Set before the callback.
xpProblemAttrib Structure with all XpressMP problem attributes. Set before the callback.

Description
Called at the 0 and last simplex iteration, as well as each LPLOG iteration, where LPLOG is the XPRS_LPLOG control variable.

Examples
Default the routine prints the problem number, the iteration number and the current value of the objective function. The user could instead write the Matlab statements wanted. The definition of a few control variables are shown as comments.

See Also
See the documentation for the XpressMP routine XPRSsetcblplog.

Bugs
The variables x, slack, pi and rc are just set as empty. It is not possible to retrieve these variables during the simplex iterations. They will probably be deleted later on.

D.4  xpcb_ucb

Purpose
XpressMP User Choose Branching Variable Callback routine

Calling Syntax
[iPtr, iDir, estdeg, xpcontrol] = xpcb_ucb(iPtr, iDir, estdeg, Prob)

Description of Input

iPtr
Pointer to the variable or the set to branch.
iDir 1 or 3 ( for sets) means upward branch. 0 or 2 ( for sets) means downward branch.
estdeg Estimated degradation using the selected variable or set.
Prob A structure. If TOMLAB calls xpress, then Prob is the standard TOMLAB problem structure, otherwise the user optionally can set: Prob.P = ProblemNumber;, where ProblemNumber is some integer. When the callback routine is called then the arrays that define the current problem are added as fields in Prob. The additional fields are Prob.QP.c, Prob.QP.F, Prob.x_L, Prob.x_U, Prob.A, Prob.b_L, Prob.b_U.

Description of Output

iPtr
Pointer to the variable or the set to branch.
iDir 1 or 3 ( for sets) means upward branch. 0 or 2 ( for sets) means downward branch.
estdeg Estimated degradation using the selected variable or set.
xpcontrol Structure with the control fields that the user wishes to be set in XpressMP 

Global Parameters Used
   
xpControlVariables Structure with all XpressMP control variables. Set before the callback.
xpProblemAttrib Structure with all XpressMP problem attributes. Set before the callback.

Description
At each global iteration, the User Choose Branching Variable Callback routine is called. It gives the user the possibility to set the wanted branching variable. New values for the control variables are also possible to return.

Examples
Default the node number, the branch pointer, the direction and the estimated degradation is printed. The user should instead write the Matlab statements to set the branch pointer, the direction and the estimated degradation.

See Also
See the documentation for the XpressMP routine XPRSsetcbchgbranch. It is demonstrated how to choose branching on the most fractional integer.

D.5  xpcb_ucn

Purpose
XpressMP User Node Cut-Off Callback routine

Calling Syntax
[xpcontrol] = xpcb_ucn(node, Prob)

Description of Input

node
Node selected by XpressMP 
Prob A structure. If TOMLAB calls xpress, then Prob is the standard TOMLAB problem structure, otherwise the user optionally can set: Prob.P = ProblemNumber;, where ProblemNumber is some integer. When the callback routine is called then the arrays that define the current problem are added as fields in Prob. The additional fields are Prob.QP.c, Prob.QP.F, Prob.x_L, Prob.x_U, Prob.A, Prob.b_L, Prob.b_U.

Description of Output

xpcontrol
Structure with the control fields that the user wishes to be set in XpressMP 

Global Parameters Used
   
xpControlVariables Structure with all XpressMP control variables. Set before the callback.
xpProblemAttrib Structure with all XpressMP problem attributes. Set before the callback.

Description
Declares a user node cutoff callback function, called every time a node is cut off as a result of an improved integer solution being found during the Branch and Bound search. New values for the control variables may be returned as sub fields in the xpcontrol variable.

Examples
Default the node number is printed.

See Also
See the documentation for the XpressMP routine XPRSsetcbnodecutoff.

D.6  xpcb_uin

Purpose
XpressMP User Infeasible Node Callback routine

Calling Syntax
[xpcontrol] = xpcb_uin(Prob)

Description of Input

Prob
A structure. If TOMLAB calls xpress, then Prob is the standard TOMLAB problem structure, otherwise the user optionally can set: Prob.P = ProblemNumber;, where ProblemNumber is some integer. When the callback routine is called then the arrays that define the current problem are added as fields in Prob. The additional fields are Prob.QP.c, Prob.QP.F, Prob.x_L, Prob.x_U, Prob.A, Prob.b_L, Prob.b_U.

Description of Output

xpcontrol
Structure with the control fields that the user wishes to be set in XpressMP 

Global Parameters Used
   
xpControlVariables Structure with all XpressMP control variables. Set before the callback.
xpProblemAttrib Structure with all XpressMP problem attributes. Set before the callback.

Description
At each global iteration, when an infeasible node is found the User Infeasible Node Callback routine is called. The infeasible node is picked up using the global structure xpProblemAttrib.NODES. New values for the control variables is returned as sub fields in the xpcontrol variable.

Examples
Default the infeasible node number is printed.

See Also
See the documentation for the XpressMP routine XPRSsetcbinfnode.

D.7  xpcb_uis

Purpose
XpressMP User Integer Solution Callback routine

Calling Syntax
[xpcontrol] = xpcb_uis(Prob)

Description of Input

Prob
A structure. If TOMLAB calls xpress, then Prob is the standard TOMLAB problem structure, otherwise the user optionally can set: Prob.P = ProblemNumber;, where ProblemNumber is some integer. When the callback routine is called then the arrays that define the current problem are added as fields in Prob. The additional fields are Prob.QP.c, Prob.QP.F, Prob.x_L, Prob.x_U, Prob.A, Prob.b_L, Prob.b_U.

Description of Output

xpcontrol
Structure with the control fields that the user wishes to be set in XpressMP 

Global Parameters Used
   
xpControlVariables Structure with all XpressMP control variables. Set before the callback.
xpProblemAttrib Structure with all XpressMP problem attributes. Set before the callback.

Description
At each global iteration, when an integer solution is found the User Integer Solution Callback routine is called. The integer valued node is picked up using the global structure xpProblemAttrib.NODES. New values for the control variables is returned as sub fields in the xpcontrol variable.

Examples
Default the node number with an integer solution is printed, together with the objective function value.

See Also
See the documentation for the XpressMP routine XPRSsetcbintsol.

D.8  xpcb_uon

Purpose
XpressMP User Optimal Node Callback routine

Calling Syntax
[Feasible] = xpcb_uon(Prob)

Description of Input

Prob
A structure. If TOMLAB calls xpress, then Prob is the standard TOMLAB problem structure, otherwise the user optionally can set: Prob.P = ProblemNumber;, where ProblemNumber is some integer. When the callback routine is called then the arrays that define the current problem are added as fields in Prob. The additional fields are Prob.QP.c, Prob.QP.F, Prob.x_L, Prob.x_U, Prob.A, Prob.b_L, Prob.b_U.

Description of Output

Feasible
If 0, the node is accepted as optimal.

Global Parameters Used
   
xpControlAttrib Structure with all XpressMP control variables. Set before the callback.
xpProblemVariables Structure with all XpressMP problem attributes. Set before the callback.

Description
When an optimal solution for the current node is found the User Optimal Node Callback routine is called.

Examples
Default the node number and the function value is printed.

See Also
See the documentation for the XpressMP routine XPRSsetcboptnode.

D.9  xpcb_uop

Purpose
XpressMP User Output Callback routine

Calling Syntax
xpcb_uop(msg, msgLevel, Prob)

Description of Input

msg
Error message string.
msgLevel Error Level
 
4 = Error
3 = Warning
2 = Dialogue
1 = Information
0 = Flush buffers
-1 = No message
Prob A structure. If TOMLAB calls xpress, then Prob is the standard TOMLAB problem structure, otherwise the user optionally can set: Prob.P = ProblemNumber;, where ProblemNumber is some integer. When the callback routine is called then the arrays that define the current problem are added as fields in Prob. The additional fields are Prob.QP.c, Prob.QP.F, Prob.x_L, Prob.x_U, Prob.A, Prob.b_L, Prob.b_U.

Description of Output

xpcontrol
Structure with the control fields that the user wishes to be set in XpressMP 

Global Parameters Used
   
xpControlVariables Structure with all XpressMP control variables. Set before the callback.
xpProblemAttrib Structure with all XpressMP problem attributes. Set before the callback.

Description
Every time the XpressMP solver wants to output a message, this routine is called. An error or warning message is always printed in the Matlab command window, if this callback is enabled. If the control variable OUTPUTLOG is true, then also normal messages are printed in the Matlab command window.

See Also
See the documentation for the XpressMP routine XPRSsetcbmessage.

D.10  xpcb_upn

Purpose
XpressMP User Preprocess Node Callback routine

Calling Syntax
[Feasible] = xpcb_upn(Prob)

Description of Input

Prob
A structure. If TOMLAB calls xpress, then Prob is the standard TOMLAB problem structure, otherwise the user optionally can set: Prob.P = ProblemNumber;, where ProblemNumber is some integer. When the callback routine is called then the arrays that define the current problem are added as fields in Prob. The additional fields are Prob.QP.c, Prob.QP.F, Prob.x_L, Prob.x_U, Prob.A, Prob.b_L, Prob.b_U.

Description of Output

Feasible
A 1 shows the node is LP infeasible, a 0 that it is feasible.

Global Parameters Used
   
xpControlVariables Structure with all XpressMP control variables. Set before the callback.
xpProblemAttrib Structure with all XpressMP problem attributes. Set before the callback.

Description
The User Preprocess Node Callback routine is called before the analysis of the node. The user might have an efficient method in determining if the node is LP feasible or not. If the return flag is changed to one, the node is not further considered.

Examples
Default the node number is printed.

See Also
See the documentation for the XpressMP routine XPRSsetcbprenode.

D.11  xpcb_usn

Purpose
XpressMP User Select Node Callback routine

Calling Syntax
[xpcontrol] = xpcb_usn(node, Prob)

Description of Input

node
Node selected by XpressMP 
Prob A structure. If TOMLAB calls xpress, then Prob is the standard TOMLAB problem structure, otherwise the user optionally can set: Prob.P = ProblemNumber;, where ProblemNumber is some integer. When the callback routine is called then the arrays that define the current problem are added as fields in Prob. The additional fields are Prob.QP.c, Prob.QP.F, Prob.x_L, Prob.x_U, Prob.A, Prob.b_L, Prob.b_U.

Description of Output

node
User selected node.

Global Parameters Used
   
xpControlVariables Structure with all XpressMP control variables. Set before the callback.
xpProblemAttrib Structure with all XpressMP problem attributes. Set before the callback.

Description
Every time the code backtracks to select a new node during the MIP search, the User Select Node Callback routine is called. It is then possible to return another node number, if the user has a better strategy for selecting the new node.

Examples
Default the node number is printed.

See Also
See the documentation for the XpressMP routine XPRSsetcbchgnode.

« Previous « Start » Next »