# GlobalSearch

Find global minimum

## Description

A `GlobalSearch`

object contains properties
(options) that affect how `run`

repeatedly runs a local solver to
generate a `GlobalOptimSolution`

object. When run, the
solver attempts to locate a solution that has the lowest objective function
value.

## Creation

### Syntax

### Description

`gs = GlobalSearch`

creates `gs`

, a
`GlobalSearch`

solver with its properties
set to the defaults.

`gs = GlobalSearch(Name,Value)`

sets properties using
name-value pairs.

`gs = GlobalSearch(oldGS,Name,Value)`

creates a copy of the
`oldGS`

`GlobalSearch`

solver, and sets properties using
name-value pairs.

`gs = GlobalSearch(ms)`

creates `gs`

, a
`GlobalSearch`

solver, with common property
values from the `ms`

`MultiStart`

solver.

## Properties

`BasinRadiusFactor`

— Basin radius decrease factor

`0.2`

(default) | scalar from `0`

through `1`

Basin radius decrease factor, specified as a scalar from
`0`

through `1`

. A basin radius
decreases after `MaxWaitCycle`

consecutive start points are
within the basin. The basin radius decreases by a factor of
1 – `BasinRadiusFactor`

.

Set `BasinRadiusFactor`

to `0`

to
disable updates of the basin radius.

**Example: **
`0.5`

**Data Types: **`double`

`Display`

— Level of display to the Command Window

`'final'`

(default) | `'iter'`

| `'off'`

Level of display to the Command Window, specified as one of the following character vectors or strings:

`'final'`

– Report summary results after`run`

finishes.`'iter'`

– Report results after the initial`fmincon`

run, after Stage 1, after every 200 start points, and after every run of`fmincon`

, in addition to the final summary.`'off'`

– No display.

**Example: **
`'iter'`

**Data Types: **`char`

| `string`

`DistanceThresholdFactor`

— Multiplier for determining trial point is in existing basin

`0.75`

(default) | nonnegative scalar

Multiplier for determining whether a trial point is in an existing basin of attraction, specified as a nonnegative scalar. For details, see Examine Stage 2 Trial Point to See if fmincon Runs.

**Example: **`0.5`

**Data Types: **`double`

`FunctionTolerance`

— Tolerance on function values for considering solutions equal

`1e-6`

(default) | nonnegative scalar

Tolerance on function values for considering solutions equal, specified as a
nonnegative scalar. Solvers consider two solutions identical if they are within
`XTolerance`

relative distance of each other and have objective
function values within `FunctionTolerance`

relative difference of each
other. If both conditions are not met, solvers report the solutions as distinct. Set
`FunctionTolerance`

to `0`

to obtain the results
of every local solver run. Set `FunctionTolerance`

to a larger value to
have fewer results. For `GlobalSearch`

details, see **Update Solution Set ** in When fmincon Runs. For
`MultiStart`

details, see Create GlobalOptimSolution Object.

**Example: **
`1e-4`

**Data Types: **`double`

`MaxTime`

— Maximum time in seconds that GlobalSearch runs

`Inf`

(default) | positive
scalar

Maximum time in seconds that GlobalSearch
runs, specified as a positive scalar. GlobalSearch and its local solvers halt when
`MaxTime`

seconds have passed since the beginning of the run, as
measured by `tic`

and `toc`

.

`MaxTime`

does not interrupt local
solvers during a run, so the total time can exceed
`MaxTime`

.

**Example: **`180`

stops the
solver the first time a local solver call finishes after 180
seconds.

**Data Types: **`double`

`MaxWaitCycle`

— Algorithm control parameter

`20`

(default) | positive integer

Algorithm control parameter, specified as a positive integer.

If the observed penalty function of

`MaxWaitCycle`

consecutive trial points is at least the penalty threshold, then raise the penalty threshold (see PenaltyThresholdFactor).If

`MaxWaitCycle`

consecutive trial points are in a basin, then update that basin's radius (see BasinRadiusFactor).

**Example: **`40`

**Data Types: **`double`

`NumStageOnePoints`

— Number of Stage 1 points

`200`

(default) | positive integer

Number of Stage 1 points, specified as a positive integer. For details, see Obtain Stage 1 Start Point, Run.

**Example: **`1000`

**Data Types: **`double`

`NumTrialPoints`

— Number of potential start points

`1000`

(default) | positive integer

Number of potential start points, specified as a positive integer.

**Example: **`3e4`

**Data Types: **`double`

`OutputFcn`

— Report on solver progress or halt solver

`[]`

(default) | `@savelocalsolutions`

| function handle | cell array of function handles

Report on solver progress or halt solver, specified as a function handle or cell array of function handles. Output functions run after each local solver call. They also run when the global solver starts and ends. Write output functions using the syntax described in OutputFcn. See Custom GlobalSearch Output Function.

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. For an example, see Collect All Local Solutions.

**Data Types: **`cell`

| `function_handle`

`PenaltyThresholdFactor`

— Increase in penalty threshold

`0.2`

(default) | positive scalar

Increase in the penalty threshold, specified as a positive scalar. For details, see React to Large Counter Values.

**Example: **`0.4`

**Data Types: **`double`

`PlotFcn`

— Plot solver progress

`[]`

(default) | function handle | cell array of function handles

Plot solver progress, specified as a function handle or cell array of function handles. Plot functions run after each local solver call. They also run when the global solver starts and ends. Write plot functions using the syntax described in OutputFcn.

There are two built-in plot functions:

`@gsplotbestf`

plots the best objective function value.`@gsplotfunccount`

plots the number of function evaluations.

**Example: **
`@gsplotbestf`

**Data Types: **`cell`

| `function_handle`

`StartPointsToRun`

— Start points to run

`'all'`

(default) | `'bounds'`

| `'bounds-ineqs'`

Start points to run, specified as:

`'all'`

— Run all start points.`'bounds'`

— Run only start points that satisfy bounds.`'bounds-ineqs'`

— Run only start points that satisfy bounds and inequality constraints.

`GlobalSearch`

checks the
`StartPointsToRun`

property only during Stage 2 of the
`GlobalSearch`

algorithm (the main loop). For more
information, see GlobalSearch Algorithm.

**Example: **
`'bounds'`

runs only points that satisfy all
bounds.

**Data Types: **`char`

| `string`

`XTolerance`

— Tolerance on distance for considering solutions equal

`1e-6`

(default) | nonnegative
scalar

Tolerance on distance for considering solutions equal, specified as a nonnegative
scalar. Solvers consider two solutions identical if they are within
`XTolerance`

relative distance of each other and have objective
function values within `FunctionTolerance`

relative difference of each
other. If both conditions are not met, solvers report the solutions as distinct. Set
`XTolerance`

to `0`

to obtain the results of every
local solver run. Set `XTolerance`

to a larger value to have fewer
results. For `GlobalSearch`

details, see **Update Solution Set ** in When fmincon Runs. For
`MultiStart`

details, see Create GlobalOptimSolution Object.

**Example: **`2e-4`

**Data Types: **`double`

## Object Functions

`run` | Run multiple-start solver |

## 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 `GlobalSearch`

on 1-D Problem

Consider a function with several local minima.

fun = @(x) x.^2 + 4*sin(5*x); fplot(fun,[-5,5])

To search for the global minimum, run `GlobalSearch`

using the `fmincon`

`'sqp'`

algorithm.

rng default % For reproducibility opts = optimoptions(@fmincon,'Algorithm','sqp'); problem = createOptimProblem('fmincon','objective',... fun,'x0',3,'lb',-5,'ub',5,'options',opts); gs = GlobalSearch; [x,f] = run(gs,problem)

GlobalSearch stopped because it analyzed all the trial points. All 23 local solver runs converged with a positive local solver exit flag.

x = -0.3080

f = -3.9032

`GlobalSearch`

Using Common Properties from `MultiStart`

Create a nondefault `MultiStart`

object.

ms = MultiStart('FunctionTolerance',2e-4,'UseParallel',true)

ms = MultiStart with properties: UseParallel: 1 Display: 'final' FunctionTolerance: 2.0000e-04 MaxTime: Inf OutputFcn: [] PlotFcn: [] StartPointsToRun: 'all' XTolerance: 1.0000e-06

Create a `GlobalSearch`

object that uses the available properties from `ms`

.

gs = GlobalSearch(ms)

gs = GlobalSearch with properties: NumTrialPoints: 1000 BasinRadiusFactor: 0.2000 DistanceThresholdFactor: 0.7500 MaxWaitCycle: 20 NumStageOnePoints: 200 PenaltyThresholdFactor: 0.2000 Display: 'final' FunctionTolerance: 2.0000e-04 MaxTime: Inf OutputFcn: [] PlotFcn: [] StartPointsToRun: 'all' XTolerance: 1.0000e-06

`gs`

has the same nondefault value of `FunctionTolerance`

as `ms`

. But `gs`

does not use the `UseParallel`

property.

### Update `GlobalSearch`

Properties

Create a `GlobalSearch`

object with a `FunctionTolerance`

of `1e-4`

.

`gs = GlobalSearch('FunctionTolerance',1e-4)`

gs = GlobalSearch with properties: NumTrialPoints: 1000 BasinRadiusFactor: 0.2000 DistanceThresholdFactor: 0.7500 MaxWaitCycle: 20 NumStageOnePoints: 200 PenaltyThresholdFactor: 0.2000 Display: 'final' FunctionTolerance: 1.0000e-04 MaxTime: Inf OutputFcn: [] PlotFcn: [] StartPointsToRun: 'all' XTolerance: 1.0000e-06

Update the `XTolerance`

property to `1e-3`

and the `StartPointsToRun`

property to `'bounds'`

.

gs = GlobalSearch(gs,'XTolerance',1e-3,'StartPointsToRun','bounds')

gs = GlobalSearch with properties: NumTrialPoints: 1000 BasinRadiusFactor: 0.2000 DistanceThresholdFactor: 0.7500 MaxWaitCycle: 20 NumStageOnePoints: 200 PenaltyThresholdFactor: 0.2000 Display: 'final' FunctionTolerance: 1.0000e-04 MaxTime: Inf OutputFcn: [] PlotFcn: [] StartPointsToRun: 'bounds' XTolerance: 1.0000e-03

You can also update properties one at a time by using dot notation.

gs.MaxTime = 1800

gs = GlobalSearch with properties: NumTrialPoints: 1000 BasinRadiusFactor: 0.2000 DistanceThresholdFactor: 0.7500 MaxWaitCycle: 20 NumStageOnePoints: 200 PenaltyThresholdFactor: 0.2000 Display: 'final' FunctionTolerance: 1.0000e-04 MaxTime: 1800 OutputFcn: [] PlotFcn: [] StartPointsToRun: 'bounds' XTolerance: 1.0000e-03

## Algorithms

For a detailed description of the algorithm, see GlobalSearch Algorithm. Ugray et al. [1] describe both the algorithm and the scatter-search method of generating trial points.

## References

[1] Ugray, Zsolt, Leon Lasdon,
John Plummer, Fred Glover, James Kelly, and Rafael Martí. *Scatter Search and
Local NLP Solvers: A Multistart Framework for Global Optimization*.
INFORMS Journal on Computing, Vol. 19, No. 3, 2007, pp. 328–340.

## Version History

**Introduced in R2010a**

### R2024a: Output Function: Built-in output function and updated `optimValues`

structure

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 optimValues Structure in
output functions and plot functions now contains the
`constrviolation`

field, which has the maximum constraint
violation. This value is `0`

for no constraint violations.

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)