## 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.

The built-in `@savelocalsolutions`

output function saves all
local solutions to the `localSolTable`

variable in the base
workspace. This output function saves the infeasible local solutions as well as the
feasible local solutions; the `solutions`

output of `run`

returns
only the local solutions with positive exit flag.

### Collect All Local Solutions

This example shows how to use the `savelocalsolutions`

output
function with `MultiStart`

to collect all the local solutions found
during a run. Begin by specifying `savelocalsolutions`

as an output
function for `MultiStart`

.

ms = MultiStart(OutputFcn=@savelocalsolutions);

Create a problem in three variables for `MultiStart`

using the
`bigtoleft`

objective function and the
`twocone`

nonlinear constraint function, listed in Helper Functions at the end of this
example. Set lower bounds of –`1e5`

in each component and upper
bounds of `1e5`

. For details of this objective function and
nonlinear constraint function, see fmincon Interior-Point Algorithm with Analytic Hessian.

fun = @bigtoleft; lb = -1e5*ones(1,3); ub = -lb;

The objective and constraint functions contain derivative information. Set the options to use derivatives.

```
opts = optimoptions(@fmincon,SpecifyObjectiveGradient=true,...
SpecifyConstraintGradient=true);
```

Set the initial point to [–10,–10,–10] and create the optimization problem.

x0 = -10*ones(1,3); prob = createOptimProblem("fmincon",x0=x0,... lb = lb,ub = ub,... objective=fun,nonlcon=@twocone,options=opts);

For reproducibility, set the random seed. Run `MultiStart`

on 35
start points.

```
rng default
[x,fval,eflag,output,solns] = run(ms,prob,35)
```

MultiStart completed some of the runs from the start points. 11 out of 35 local solver runs converged with a positive local solver exitflag. x = -6.5000 -0.0000 -3.5000 fval = -2.8941e+03 eflag = 2 output = struct with fields: funcCount: 73904 localSolverTotal: 35 localSolverSuccess: 11 localSolverIncomplete: 23 localSolverNoSolution: 1 message: 'MultiStart completed some of the runs from the start points. ↵↵11 out of 35 local solver runs converged with a positive local solver exitflag.' solns = 1×2 GlobalOptimSolution array with properties: X Fval Exitflag Output X0

The workspace contains the `localSolTable`

variable, which has
all 35 local solutions. In contrast, the output structure shows that only 11 local
solver runs were successful.

size(localSolTable)

ans = 35 4

To see the kind of information returned by the output function, view the first
line of `localSolTable`

.

disp(localSolTable(1,:))

X fval exitflag constrviolation ________________________________ _______ ________ _______________ -6.5 2.3432e-07 -3.5 -2894.1 1 0

The output function returns the local solution `X`

, its
associated objective function value `fval`

, the exit flag
corresponding to that local solver run, and the constraint violation, which is
`0`

for no constraint violations.

#### Helper Functions

This code creates the `bigtoleft`

helper function.

function [f,gradf] = bigtoleft(x) % This is a simple function that grows rapidly negative % as x(1) becomes negative % f = 10*x(:,1).^3+x(:,1).*x(:,2).^2+x(:,3).*(x(:,1).^2+x(:,2).^2); if nargout > 1 gradf=[30*x(1)^2+x(2)^2+2*x(3)*x(1); 2*x(1)*x(2)+2*x(3)*x(2); (x(1)^2+x(2)^2)]; end end

This code creates the `twocone`

helper function.

function [c,ceq,gradc,gradceq] = twocone(x) % This constraint is two cones, z > -10 + r % and z < 3 - r ceq = []; r = sqrt(x(1)^2 + x(2)^2); c = [-10+r-x(3); x(3)-3+r]; if nargout > 2 gradceq = []; gradc = [x(1)/r,x(1)/r; x(2)/r,x(2)/r; -1,1]; end end

### Custom 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.