intlinprog Output Function and Plot Function Syntax

What Are Output Functions and Plot Functions?

intlinprog can call an output function or plot function after certain events occur in the algorithm. These events include completing a phase of the algorithm such as solving the root LP problem, adding cuts, completing a heuristic successfully, finding a new integer feasible solution during branch-and-bound, appreciably improving the relative gap, or exploring a number of nodes in a branch-and-bound tree.

Caution

intlinprog output functions and plot functions differ from those in other solvers. For output functions or plot functions in other Optimization Toolbox™ solvers, see Output Function and Plot Function Syntax and Plot Functions.

• There is one built-in output function: savemilpsolutions. This function collects the integer feasible points that the algorithm finds at event times. It puts the feasible points in a matrix named xIntSol in your base workspace, where each column is one integer feasible point. It saves the objective function values in a vector named fIntSol, where each entry is the objective function of the corresponding column in xIntSol.

• There is one built-in plot function: optimplotmilp. This function plots the internally-calculated bounds on the best objective function value. For an example of its use, see Factory, Warehouse, Sales Allocation Model: Solver-Based.

Call output functions or plot functions by passing the OutputFcn or PlotFcn name-value arguments, including the handle to the output function or plot function. For example,

options = optimoptions(@intlinprog,...
    OutputFcn=@savemilpsolutions,PlotFcn=@optimplotmilp);
x = intlinprog(f,intcon,A,b,Aeq,beq,lb,ub,options);

If you have several output functions or plot functions, pass them as a cell array.

options = optimoptions(@intlinprog,...
    OutputFcn={@savemilpsolutions,@customFcn});

Note

Plot functions do not support the subplot statement, because the plot function framework manages the axes. To specify multiple subplots, write separate plot functions and pass them to the solver as a cell array:

options = optimoptions("solvername",PlotFcn={@plot1,@plot2,@plot3});

Output functions support subplot, so you can include multiple plots in one function by using an output function instead of a plot function.

Custom Function Syntax

Write your own output function or plot function using this syntax:

function stop = customFcn(x,optimValues,state)

intlinprog passes the data x, optimValues, and state to your function.

• stop — Set to true to halt intlinprog. Set to false to allow intlinprog to continue.

• x — Either an empty matrix [] or an N-by-1 vector that is a feasible point. x is nonempty only when intlinprog finds a new integer feasible solution. x can be nonempty when phase is 'heuristics' or 'branching'.

• optimValues — A structure whose details are in optimValues Structure.

• state — One of these values:

  • 'init' — intlinprog is starting. Use this state to set up any plots or data structures that you need.

  • 'iter' — intlinprog is solving the problem. Access data related to the solver’s progress. For example, plot or perform file operations.

  • 'done' — intlinprog has finished solving the problem. Close any files, finish annotating plots, etc.

For examples of writing output or plot functions, see the built-in functions savemilpsolutions.m or optimplotmilp.m.

optimValues Structure

optimValues Field	Meaning
dualbound	Global lower bound of the objective function value for minimization problems, global upper bound for maximization problems. Empty when phase = 'rootlp'.
fval	Best objective function found so far at an integer feasible point. When phase = 'rootlp', fval is the objective function value at the root node, which is not necessarily an integer feasible point.
numfeaspoints	Number of integer feasible solutions found that improve the current solution.
numnodes	Number of explored nodes. Nonzero only when phase = 'branching'.
phase	Phase of the algorithm. For the "highs" algorithm, phase is always ''. For the "legacy" algorithm, the possible values are: 'rootlp' — intlinprog solved the root LP problem. 'cutgen' — intlinprog added cuts and improved the lower bound. 'heuristics' — intlinprog found new feasible points using heuristics. 'branching' — intlinprog is creating and exploring nodes in a branch-and-bound tree. 'none' — state is 'done' and no new points are found.
relativegap	Relative gap between dualbound and fval. For the "legacy" algorithm, relativegap is a percentage from 0 to 100, exactly as in the output argument. For the "highs" algorithm, relativegap is a scalar from 0 to 1. relativegap is empty when phase = 'rootlp' or numfeaspoints = 0.
time	Time in seconds spent so far, measured with tic and toc from the time when state = 'init'.