intlinprog Output Function and Plot Function Syntax

`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});

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'`.