Main Content

*Output functions* allow you to
examine intermediate results in an optimization. Additionally, they
allow you to halt a solver programmatically.

There are two types of output functions, like the two types of output structures:

Global output functions run after each local solver run. They also run when the global solver starts and ends.

Local output functions run after each iteration of a local solver. See Output Functions for Optimization Toolbox™.

To use global output functions:

Write output functions using the syntax described in OutputFcn.

Set the

`OutputFcn`

property of your`GlobalSearch`

or`MultiStart`

solver to the function handle of your output function. You can use multiple output functions by setting the`OutputFcn`

property to a cell array of function handles.

This output function stops `GlobalSearch`

after
it finds five distinct local minima with positive exit flags, or after
it finds a local minimum value less than `0.5`

. The
output function uses a persistent local variable, `foundLocal`

,
to store the local results. `foundLocal`

enables
the output function to determine whether a local solution is distinct
from others, to within a tolerance of `1e-4`

.

To store local results using nested functions instead of persistent variables, see Example of a Nested Output Function.

Write the output function using the syntax described in OutputFcn.

function stop = StopAfterFive(optimValues, state) persistent foundLocal stop = false; switch state case 'init' foundLocal = []; % initialized as empty case 'iter' newf = optimValues.localsolution.Fval; eflag = optimValues.localsolution.Exitflag; % Now check if the exit flag is positive and % the new value differs from all others by at least 1e-4 % If so, add the new value to the newf list if eflag > 0 && all(abs(newf - foundLocal) > 1e-4) foundLocal = [foundLocal;newf]; % Now check if the latest value added to foundLocal % is less than 1/2 % Also check if there are 5 local minima in foundLocal % If so, then stop if foundLocal(end) < 0.5 || length(foundLocal) >= 5 stop = true; end end end

Save

`StopAfterFive.m`

as a file in a folder on your MATLAB^{®}path.Write the objective function and create an optimization problem structure as in Find Global or Multiple Local Minima.

function f = sawtoothxy(x,y) [t r] = cart2pol(x,y); % change to polar coordinates h = cos(2*t - 1/2)/2 + cos(t) + 2; g = (sin(r) - sin(2*r)/2 + sin(3*r)/3 - sin(4*r)/4 + 4) ... .*r.^2./(r+1); f = g.*h; end

Save

`sawtoothxy.m`

as a file in a folder on your MATLAB path.At the command line, create the problem structure:

problem = createOptimProblem('fmincon',... 'objective',@(x)sawtoothxy(x(1),x(2)),... 'x0',[100,-50],'options',... optimoptions(@fmincon,'Algorithm','sqp'));

Create a

`GlobalSearch`

object with`@StopAfterFive`

as the output function, and set the iterative display property to`'iter'`

.gs = GlobalSearch('OutputFcn',@StopAfterFive,'Display','iter');

(Optional) To get the same answer as this example, set the default random number stream.

rng default

Run the problem.

[x,fval] = run(gs,problem) Num Pts Best Current Threshold Local Local Analyzed F-count f(x) Penalty Penalty f(x) exitflag Procedure 0 200 555.5 555.5 0 Initial Point 200 1463 1.547e-15 1.547e-15 1 Stage 1 Local GlobalSearch stopped by the output or plot function. 1 out of 2 local solver runs converged with a positive local solver exit flag. x = 1.0e-07 * 0.0414 0.1298 fval = 1.5467e-15

The run stopped early because `GlobalSearch`

found
a point with a function value less than `0.5`

.

While `MultiStart`

can run in parallel, it does
not support global output functions and plot functions in parallel.
Furthermore, while local output functions and plot functions run on
workers when `MultiStart`

runs in parallel, the effect
differs from running serially. Local output and plot functions do
not create a display when running on workers. You do not see any other
effects of output and plot functions until the worker passes its results
to the client (the originator of the `MultiStart`

parallel
jobs).

For information on running `MultiStart`

in parallel,
see Parallel Computing.