Examining Results

Single Solution

You obtain the single best solution found during the run by calling run with the syntax

[x fval eflag output] = run(...);

• x is the location of the local minimum with smallest objective function value.

• fval is the objective function value evaluated at x.

• eflag is an exit flag for the global solver. Values:

  Global Solver Exit Flags

  2	At least one local minimum found. Some runs of the local solver converged (had positive exit flag).
  1	At least one local minimum found. All runs of the local solver converged (had positive exit flag).
  0	No local minimum found. Local solver called at least once, and at least one local solver exceeded the MaxIter or MaxFunEvals tolerances.
  -1	Solver stopped by output function or plot function.
  -2	No feasible local minimum found.
  -5	MaxTime limit exceeded.
  -8	No solution found. All runs had local solver exit flag -1 or smaller.
  -10	Failures encountered in user-provided functions.

• output is a structure with details about the multiple runs of the local solver. For more information, see Global Output Structures.

The list of outputs is for the case eflag > 0. If eflag <= 0, then x is the following:

• If some local solutions are feasible, x represents the location of the lowest objective function value. "Feasible" means the constraint violations are smaller than problem.options.TolCon.

• If no solutions are feasible, x is the solution with lowest infeasibility.

• If no solutions exist, x, fval, and output are empty ([]).

Back to Top

Multiple Solutions

You obtain multiple solutions in an object by calling run with the syntax

[x fval eflag output manymins] = run(...);

manymins is a vector of solution objects; see GlobalOptimSolution. The vector is in order of objective function value, from lowest (best) to highest (worst). Each solution object contains the following properties (fields):

• X — a local minimum

• Fval — the value of the objective function at X

• Exitflag — the exit flag for the global solver (described here)

• Output — an output structure (described here)

• X0 — a cell array of start points that led to the solution point X

There are several ways to examine the vector of solution objects:

• In the MATLAB Workspace Browser. Double-click the solution object, and then double-click the resulting display in the Variable Editor.

  

  

  

• Using dot addressing. GlobalOptimSolution properties are capitalized. Use proper capitalization to access the properties.

  For example, to find the vector of function values, enter:

  fcnvals = [manymins.Fval]
  
  fcnvals =
     -1.0316   -0.2155         0

  To get a cell array of all the start points that led to the lowest function value (the first element of manymins), enter:

  smallX0 = manymins(1).X0

• Plot some field values. For example, to see the range of resulting Fval, enter:

  hist([manymins.Fval])

  This results in a histogram of the computed function values. (The figure shows a histogram from a different example than the previous few figures.)

  

Example: Changing the Definition of Distinct Solutions

You might find out, after obtaining multiple local solutions, that your tolerances were not appropriate. You can have many more local solutions than you want, spaced too closely together. Or you can have fewer solutions than you want, with GlobalSearch or MultiStart clumping together too many solutions.

To deal with this situation, run the solver again with different tolerances. The TolX and TolFun tolerances determine how the solvers group their outputs into the GlobalOptimSolution vector. These tolerances are properties of the GlobalSearch or MultiStart object.

For example, suppose you want to use the active-set algorithm in fmincon to solve the problem in Example of Run with MultiStart. Further suppose that you want to have tolerances of 0.01 for both TolX and TolFun. The run method groups local solutions whose objective function values are within TolFun of each other, and which are also less than TolX apart from each other. To obtain the solution:

ms = MultiStart('TolFun',0.01,'TolX',0.01);
opts = optimset('Algorithm','active-set');
sixmin = @(x)(4*x(1)^2 - 2.1*x(1)^4 + x(1)^6/3 ...
    + x(1)*x(2) - 4*x(2)^2 + 4*x(2)^4);
problem = createOptimProblem('fmincon','x0',[-1,2],...
    'objective',sixmin,'lb',[-3,-3],'ub',[3,3],...
    'options',opts);
[xminm,fminm,flagm,outptm,someminsm] = run(ms,problem,50);

MultiStart completed the runs from all start points.

All 50 local solver runs converged with a
positive local solver exit flag.

someminsm

someminsm = 

  1x6 GlobalOptimSolution

  Properties:
    X
    Fval
    Exitflag
    Output
    X0

In this case, MultiStart generated six distinct solutions. Here "distinct" means that the solutions are more than 0.01 apart in either objective function value or location.

Back to Top

Iterative Display

Iterative display gives you information about the progress of solvers during their runs.

There are two types of iterative display:

• Global solver display

• Local solver display

Both types appear at the command line, depending on global and local options.

Obtain local solver iterative display by setting the Display option in the problem.options structure to 'iter' or 'iter-detailed' with optimset. For more information, see Iterative Display in the Optimization Toolbox documentation.

Obtain global solver iterative display by setting the Display property in the GlobalSearch or MultiStart object to 'iter'.

Global solvers set the default Display option of the local solver to 'off', unless the problem structure has a value for this option. Global solvers do not override any setting you make for local options.

Note   Setting the local solver Display option to anything other than 'off' can produce a great deal of output. The default Display option created by optimset(@solver) is 'final'.

Example: Types of Iterative Display

Run the example described in Run the Solver using GlobalSearch with GlobalSearch iterative display:

gs = GlobalSearch('Display','iter');
opts = optimset('Algorithm','interior-point');
sixmin = @(x)(4*x(1)^2 - 2.1*x(1)^4 + x(1)^6/3 ...
    + x(1)*x(2) - 4*x(2)^2 + 4*x(2)^4);
problem = createOptimProblem('fmincon','x0',[-1,2],...
    'objective',sixmin,'lb',[-3,-3],'ub',[3,3],...
    'options',opts);
[xming,fming,flagg,outptg,manyminsg] = run(gs,problem);

Num Pts                Best         Current    Threshold     Local          Local                  
Analyzed  F-count      f(x)         Penalty     Penalty       f(x)        exitflag        Procedure
       0       34      -1.032                                  -1.032            1    Initial Point
     200     1441      -1.032                                       0            1    Stage 1 Local
     300     1641      -1.032         290.7      0.07006                             Stage 2 Search
     400     1841      -1.032           101       0.8017                             Stage 2 Search
     500     2041      -1.032         51.23        3.483                             Stage 2 Search
     541     2157      -1.032         5.348        5.456       -1.032            1    Stage 2 Local
     542     2190      -1.032         2.993        5.348       -1.032            1    Stage 2 Local
     544     2227      -1.032         1.807        2.993       -1.032            1    Stage 2 Local
     545     2260      -1.032         1.609        1.807       -1.032            1    Stage 2 Local
     546     2296      -1.032        0.9061        1.609       -1.032            1    Stage 2 Local
     552     2348      -1.032        0.6832       0.9061      -0.2155            1    Stage 2 Local
     600     2444      -1.032         1.079       0.1235                             Stage 2 Search
     700     2644      -1.032        0.4859      -0.4791                             Stage 2 Search
     800     2844      -1.032         136.9       0.8202                             Stage 2 Search
     900     3044      -1.032         37.77       0.4234                             Stage 2 Search
    1000     3244      -1.032      -0.05542       -0.598                             Stage 2 Search

GlobalSearch stopped because it analyzed all the start points.

All 8 local solver runs converged with a positive local solver exit flag.

Run the same example without GlobalSearch iterative display, but with fmincon iterative display:

gs.Display = 'final';
problem.options.Display = 'iter';
[xming,fming,flagg,outptg,manyminsg] = run(gs,problem);

                                            First-order      Norm of
 Iter F-count            f(x)  Feasibility   optimality         step
    0       3   4.823333e+001   0.000e+000   1.088e+002
    1       7   2.020476e+000   0.000e+000   2.176e+000   2.488e+000
    2      10   6.525252e-001   0.000e+000   1.937e+000   1.886e+000
    3      13  -8.776121e-001   0.000e+000   9.076e-001   8.539e-001
    4      16  -9.121907e-001   0.000e+000   9.076e-001   1.655e-001
    5      19  -1.009367e+000   0.000e+000   7.326e-001   8.558e-002
    6      22  -1.030423e+000   0.000e+000   2.172e-001   6.670e-002
    7      25  -1.031578e+000   0.000e+000   4.278e-002   1.444e-002
    8      28  -1.031628e+000   0.000e+000   8.777e-003   2.306e-003
    9      31  -1.031628e+000   0.000e+000   8.845e-005   2.750e-004
   10      34  -1.031628e+000   0.000e+000   8.744e-007   1.354e-006

Local minimum found that satisfies the constraints.

Optimization completed because the objective function is non-decreasing in 
feasible directions, to within the selected value of the function tolerance,
and constraints were satisfied to within the selected value of the constraint tolerance.

<stopping criteria details>
                                            First-order      Norm of
 Iter F-count            f(x)  Feasibility   optimality         step
    0       3  -5.372419e-001   0.000e+000   1.913e+000

... MANY ITERATIONS DELETED ...

    9      39  -2.154638e-001   0.000e+000   2.425e-007   6.002e-008

Local minimum found that satisfies the constraints.

Optimization completed because the objective function is non-decreasing in 
feasible directions, to within the selected value of the function tolerance,
and constraints were satisfied to within the selected value of the constraint tolerance.

<stopping criteria details>

GlobalSearch stopped because it analyzed all the start points.

All 7 local solver runs converged with a positive local solver exit flag.

Setting GlobalSearch iterative display, as well as fmincon iterative display, yields both displays intermingled.

For an example of iterative display in a parallel environment, see Example: Parallel MultiStart.

Back to Top

Global Output Structures

run can produce two types of output structures:

• A global output structure. This structure contains information about the overall run from multiple starting points. Details follow.

• Local solver output structures. The vector of GlobalOptimSolution objects contains one such structure in each element of the vector. For a description of this structure, see Output Structures in the Optimization Toolbox documentation, or the function reference pages for the local solvers: fmincon, fminunc, lsqcurvefit, or lsqnonlin.

Global Output Structure

A positive exit flag from a local solver generally indicates a successful run. A negative exit flag indicates a failure. A 0 exit flag indicates that the solver stopped by exceeding the iteration or function evaluation limit. For more information, see Exit Flags and Exit Messages or Tolerances and Stopping Criteria in the Optimization Toolbox documentation.

Back to Top

Example: Visualizing the Basins of Attraction

Which start points lead to which basin? For a steepest descent solver, nearby points generally lead to the same basin; see Basins of Attraction. However, for Optimization Toolbox solvers, basins are more complicated.

Plot the MultiStart start points from the example, Example of Run with MultiStart, color-coded with the basin where they end.

% rng(14,'twister')
% Uncomment the previous line to get the same output
ms = MultiStart;
opts = optimset('Algorithm','interior-point');
sixmin = @(x)(4*x(1)^2 - 2.1*x(1)^4 + x(1)^6/3 ...
+ x(1)*x(2) - 4*x(2)^2 + 4*x(2)^4);
problem = createOptimProblem('fmincon','x0',[-1,2],...
'objective',sixmin,'lb',[-3,-3],'ub',[3,3],...
'options',opts);
[xminm,fminm,flagm,outptm,manyminsm] = run(ms,problem,50);

possColors = 'kbgcrm';
hold on
for i = 1:size(manyminsm,2)
    
    % Color of this line
    cIdx = rem(i-1, length(possColors)) + 1;
    color = possColors(cIdx);

    % Plot start points
    u = manyminsm(i).X0; 
    x0ThisMin = reshape([u{:}], 2, length(u));
    plot(x0ThisMin(1, :), x0ThisMin(2, :), '.', ...
        'Color',color,'MarkerSize',25);

    % Plot the basin with color i
    plot(manyminsm(i).X(1), manyminsm(i).X(2), '*', ...
        'Color', color, 'MarkerSize',25); 
end % basin center marked with a *, start points with dots
hold off

The figure shows the centers of the basins by colored * symbols. Start points with the same color as the * symbol converge to the center of the * symbol.

Start points do not always converge to the closest basin. For example, the red points are closer to the green basin center than to the red basin center. Also, many black and blue start points are closer to the opposite basin centers.

The magenta and red basins are shallow, as you can see in the following contour plot.

 Code for Generating the Figure

possColors = 'kbgcrm';
sixmin = @(x)(4*x(:,1).^2 - 2.1*x(:,1).^4 + x(:,1).^6/3 ...
    + x(:,1).*x(:,2) - 4*x(:,2).^2 + 4*x(:,2).^4);
f = @(x,y)sixmin([x,y]); % vectorized objective fcn
ezcontour(f,[-2 2 -1.1 1.1])
hold on
for i = 1:size(manyminsm,2)
    cIdx = rem(i-1, length(possColors)) + 1;
    color = possColors(cIdx);
    plot(manyminsm(i).X(1),manyminsm(i).X(2),'*','Color',...
        color,'MarkerSize',25); % plot center of basin with *
end
hold off

Back to Top

Output Functions for GlobalSearch and MultiStart

• What Are Output Functions?

• Example: GlobalSearch Output Function

• No Parallel Output Functions

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 in the Optimization Toolbox documentation.

To use global output functions:

• Write output functions using the syntax described in OutputFcns.

• Set the OutputFcns property of your GlobalSearch or MultiStart solver to the function handle of your output function. You can use multiple output functions by setting the OutputFcns property to a cell array of function handles.

Example: 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 in the MATLAB Mathematics documentation.

1. Write the output function using the syntax described in OutputFcns.

   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];
           end
           % 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

2. Save StopAfterFive.m as a file in a folder on your MATLAB path.

3. Write the objective function and create an optimization problem structure as in Example: Finding 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

4. Save sawtoothxy.m as a file in a folder on your MATLAB path.

5. At the command line, create the problem structure:

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

6. Create a GlobalSearch object with @StopAfterFive as the output function, and set the iterative display property to 'iter'.

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

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

   rng('default')

8. 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 465 422.9 422.9 2 Initial Point 200 1744 1.547e-015 1.547e-015 1 Stage 1 Local GlobalSearch stopped by the output or plot function. All 2 local solver runs converged with a positive local solver exit flag. x = 1.0e-007 * 0.0414 0.1298 fval = 1.5467e-015

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

Back to Top

Plot Functions for GlobalSearch and MultiStart

• What Are Plot Functions?

• Example: MultiStart Plot Function

• No Parallel Plot Functions

What Are Plot Functions?

The PlotFcns field of the options structure specifies one or more functions that an optimization function calls at each iteration. Plot functions plot various measures of progress while the algorithm executes. Pass a function handle or cell array of function handles. The structure of a plot function is the same as the structure of an output function. For more information on this structure, see OutputFcns.

Plot functions are specialized output functions (see Output Functions for GlobalSearch and MultiStart). There are two predefined plot functions:

• @gsplotbestf plots the best objective function value.

• @gsplotfunccount plots the number of function evaluations.

Plot function windows have Pause and Stop buttons. By default, all plots appear in one window.

To use global plot functions:

• Write plot functions using the syntax described in OutputFcns.

• Set the PlotFcns property of your GlobalSearch or MultiStart object to the function handle of your plot function. You can use multiple plot functions by setting the PlotFcns property to a cell array of function handles.

Details of Built-In Plot Functions.  The built-in plot functions have characteristics that can surprise you.

• @gsplotbestf can have plots that are not strictly decreasing. This is because early values can result from local solver runs with negative exit flags (such as infeasible solutions). A subsequent local solution with positive exit flag is better even if its function value is higher. Once a local solver returns a value with a positive exit flag, the plot is monotone decreasing.

• @gsplotfunccount might not plot the total number of function evaluations. This is because GlobalSearch can continue to perform function evaluations after it calls the plot function for the last time. For more information, see GlobalSearch AlgorithmProperties for GlobalSearch.

Example: MultiStart Plot Function

This example plots the number of local solver runs it takes to obtain a better local minimum for MultiStart. The example also uses a built-in plot function to show the current best function value.

The example problem is the same as in Example: Finding Global or Multiple Local Minima, with additional bounds.

The example uses persistent variables to store previous best values. The plot function examines the best function value after each local solver run, available in the bestfval field of the optimValues structure. If the value is not lower than the previous best, the plot function adds 1 to the number of consecutive calls with no improvement and draws a bar chart. If the value is lower than the previous best, the plot function starts a new bar in the chart with value 1. Before plotting, the plot function takes a logarithm of the number of consecutive calls. The logarithm helps keep the plot legible, since some values can be much larger than others.

To store local results using nested functions instead of persistent variables, see Example of a Nested Output Function in the MATLAB Mathematics documentation.

1. Write the objective function:

   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;

2. Save sawtoothxy.m as a file in a folder on your MATLAB path.

3. Write the plot function:

   function stop = NumberToNextBest(optimValues, state)
   
   persistent bestfv bestcounter
   
   stop = false;
   switch state
       case 'init'
           % Initialize variable to record best function value.
           bestfv = []; 
           
           % Initialize counter to record number of
           % local solver runs to find next best minimum.
           bestcounter = 1; 
           
           % Create the histogram.
           bar(log(bestcounter),'tag','NumberToNextBest');
           xlabel('Number of New Best Fval Found');
           ylabel('Log Number of Local Solver Runs');
           title('Number of Local Solver Runs to Find Lower Minimum')
       case 'iter'
           % Find the axes containing the histogram.
           NumToNext = ...
             findobj(get(gca,'Children'),'Tag','NumberToNextBest');
           
           % Update the counter that records number of local
           % solver runs to find next best minimum.
           if ~isequal(optimValues.bestfval, bestfv)
               bestfv = optimValues.bestfval;
               bestcounter = [bestcounter 1];
           else
               bestcounter(end) = bestcounter(end) + 1;
           end
           
           % Update the histogram.
           set(NumToNext,'Ydata',log(bestcounter))
   end

4. Save NumberToNextBest.m as a file in a folder on your MATLAB path.

5. Create the problem structure and global solver. Set lower bounds of [-3e3,-4e3], upper bounds of [4e3,3e3] and set the global solver to use the plot functions:

   problem = createOptimProblem('fmincon',...
       'objective',@(x)sawtoothxy(x(1),x(2)),...
       'x0',[100,-50],'lb',[-3e3 -4e3],...
       'ub',[4e3,3e3],'options',...
       optimset('Algorithm','sqp'));
   
   ms = MultiStart('PlotFcns',{@NumberToNextBest,@gsplotbestf});

6. Run the global solver for 100 local solver runs:

   [x fv] = run(ms,problem,100);

7. The plot functions produce the following figure (your results can differ, since the solution process is stochastic):

No Parallel Plot 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 Processing.

Back to Top

How to Optimize with GlobalSearch and MultiStart

How GlobalSearch and MultiStart Work

Free Optimization Interactive Kit

Learn how to use optimization to solve systems of equations, fit models to data, or optimize system performance.

Get free kit

Trials Available

Try the latest version of optimization products.

Get trial software