run

Run multiple-start solver

Syntax

x = run(gs,problem)

x = run(ms,problem,k)

x = run(ms,problem,startpts)

[x,fval] = run(___)

[x,fval,exitflag,output] = run(___)

[x,fval,exitflag,output,solutions] = run(___)

Description

x = run(gs,problem) runs GlobalSearch to find a solution or multiple local solutions to problem.

x = run(ms,problem,k) runs MultiStart on k start points to find a solution or multiple local solutions to problem.

x = run(ms,problem,startpts) runs MultiStart on problem from the start points described in startpts.

[x,fval] = run(___) returns the objective function value at x, the best point found, using any of the arguments in the previous syntaxes. For the lsqcurvefit and lsqnonlin local solvers, fval contains the squared norm of the residual.

[x,fval,exitflag,output] = run(___) also returns an exit flag describing the return condition, and an output structure describing the iterations of the run.

[x,fval,exitflag,output,solutions] = run(___) also returns a vector of solutions containing the distinct local minima found during the run. solutions correspond to positive local solver exit flags.

Examples

Run GlobalSearch on Multidimensional Problem

Create an optimization problem that has several local minima, and try to find the global minimum using GlobalSearch. The objective is the six-hump camel back problem (see Run the Solver).

rng default % For reproducibility
gs = GlobalSearch;
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]);
x = run(gs,problem)

GlobalSearch stopped because it analyzed all the trial points.

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

x = 1×2

   -0.0898    0.7127

You can request the objective function value at x when you call run by using the following syntax:

[x,fval] = run(gs,problem)

However, if you neglected to request fval, you can still compute the objective function value at x.

fval = sixmin(x)

fval = 
-1.0316

Run a Multiple Start Solver

Use a default MultiStart object to solve the six-hump camel back problem (see Run the Solver).

rng default % For reproducibility
ms = MultiStart;
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]);
[x,fval,exitflag,outpt,solutions] = run(ms,problem,30);

MultiStart completed the runs from all start points. 

All 30 local solver runs converged with a positive local solver exitflag.

Examine the best function value and the location where the best function value is attained.

fprintf('The best function value is %f.\n',fval)

The best function value is -1.031628.

fprintf('The location where this value is attained is [%f,%f].',x)

The location where this value is attained is [-0.089842,0.712656].

Run MultiStart from a Regular Array

Create a set of initial 2-D points for MultiStart in the range [-3,3] for each component.

v = -3:0.5:3;
[X,Y] = meshgrid(v);
ptmatrix = [X(:),Y(:)];
tpoints = CustomStartPointSet(ptmatrix);

Find the point that minimizes the six-hump camel back problem (see Run the Solver) by starting MultiStart at the points in tpoints.

rng default % For reproducibility
ms = MultiStart;
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]);
x = run(ms,problem,tpoints)

MultiStart completed the runs from all start points. 

All 169 local solver runs converged with a positive local solver exitflag.

x = 1×2

    0.0898   -0.7127

Examine GlobalSearch Process

Create an optimization problem that has several local minima, and try to find the global minimum using GlobalSearch. The objective is the six-hump camel back problem (see Run the Solver).

rng default % For reproducibility
gs = GlobalSearch;
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]);
[x,fval,exitflag,output,solutions] = run(gs,problem);

GlobalSearch stopped because it analyzed all the trial points.

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

To understand what GlobalSearch did to solve this problem, examine the output structure and solutions object.

disp(output)

                funcCount: 2245
         localSolverTotal: 8
       localSolverSuccess: 8
    localSolverIncomplete: 0
    localSolverNoSolution: 0
                  message: 'GlobalSearch stopped because it analyzed all the trial points....'

• GlobalSearch evaluated the objective function 2261 times.

• GlobalSearch ran fmincon starting from eight different points.

• All of the fmincon runs converged successfully to a local solution.

disp(solutions)

  1x4 GlobalOptimSolution array with properties:

    X
    Fval
    Exitflag
    Output
    X0

arrayfun(@(x)x.Output.funcCount,solutions)

ans = 1×4

    31    34    40     3

The eight local solver runs found four solutions. The funcCount output shows that fmincon took no more than 40 function evaluations to reach each of the four solutions. The output does not show how many function evaluations four of the fmincon runs took. Most of the 2261 function evaluations seem to be for GlobalSearch to evaluate trial points, not for fmincon to run starting from those points.

Input Arguments

gs — GlobalSearch solver

GlobalSearch object

GlobalSearch solver, specified as a GlobalSearch object. Create gs using the GlobalSearch command.

ms — MultiStart solver

MultiStart object

MultiStart solver, specified as a MultiStart object. Create ms using the MultiStart command.

problem — Optimization problem

problem structure

Optimization problem, specified as a problem structure. Create problem using createOptimProblem. For further details, see Create Problem Structure.

Example: problem = createOptimProblem('fmincon','objective',fun,'x0',x0,'lb',lb)

Data Types: struct

k — Number of start points

positive integer

Number of start points, specified as a positive integer. MultiStart generates k - 1 start points using the same algorithm as for a RandomStartPointSet object. MultiStart also uses the x0 point from the problem structure.

Example: 50

Data Types: double

startpts — Start points for MultiStart

CustomStartPointSet object | RandomStartPointSet object | cell array of such objects

Start points for MultiStart, specified as a CustomStartPointSet object, as a RandomStartPointSet object, or as a cell array of such objects.

Example: {custompts,randompts}

Output Arguments

x — Best point found

real array

Best point found, returned as a real array. The best point is the one with lowest objective function value.

fval — Lowest objective function value encountered

real scalar

Lowest objective function value encountered, returned as a real scalar. For lsqcurvefit and lsqnonlin, the objective function is the sum of squares, also known as the squared norm of the residual.

exitflag — Exit condition summary

integer

Exit condition summary, returned as an integer.

Global Solver Exit Flags

2	At least one feasible local minimum found. Some runs of the local solver did not converge.
1	At least one feasible 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 MaxIterations or MaxFunctionEvaluations tolerances.
-1	One or more local solver runs stopped by the local solver output or plot function.
-2	No feasible local minimum found.
-5	MaxTime limit exceeded.
-8	No solution found. All runs had local solver exit flag -2 or lower, not all equal -2.
-10	Failures encountered in user-provided functions.

output — Solution process details

structure

Solution process details, returned as a structure with the following fields.

Field	Meaning
funcCount	Number of function evaluations.
localSolverIncomplete	Number of local solver runs with 0 exit flag.
localSolverNoSolution	Number of local solver runs with negative exit flag.
localSolverSuccess	Number of local solver runs with positive exit flag.
localSolverTotal	Total number of local solver runs.
message	Exit message.

solutions — Distinct local solutions

vector of GlobalOptimSolution objects

Distinct local solutions, returned as a vector of GlobalOptimSolution objects. These solutions correspond to positive local solver exit flags. In other words, if a local solver exit flag is nonpositive, the corresponding solution is not recorded in solutions. To obtain all local solutions, use the @savelocalsolutions Output Functions for GlobalSearch and MultiStart.

Version History

Introduced in R2010a