Output Functions for GlobalSearch and MultiStart

What Are Output Functions?

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.

GlobalSearch Output Function

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;
        exitflag = 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 exitflag > 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.

No Parallel Output Functions

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.