# 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

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

## 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 exit flag. ```

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 exit flag. ```
```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.

 `2` At least one local minimum found. Some runs of the local solver converged. `1` At least one local minimum found. All runs of the local solver converged. `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 smaller, not all equal `-2`. `-10` Failures encountered in user-provided functions.

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

FieldMeaning
`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.

Distinct local solutions, returned as a vector of `GlobalOptimSolution` objects.

### Topics

Introduced in R2010a

## Support 평가판 신청