# run

Run multiple-start solver

## Description

example

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

example

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

example

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

example

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

example

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

example

[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

collapse all

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

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

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

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

collapse all

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

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

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

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

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

collapse all

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

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.

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.

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

FieldMeaning
funcCountNumber of function evaluations.
localSolverIncompleteNumber of local solver runs with 0 exit flag.
localSolverNoSolutionNumber of local solver runs with negative exit flag.
localSolverSuccessNumber of local solver runs with positive exit flag.
localSolverTotalTotal number of local solver runs.
messageExit message.

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