## GlobalSearch and MultiStart Properties (Options)

### How to Set Properties

To create a `GlobalSearch`

or `MultiStart`

object
with nondefault properties, use name-value pairs. For example, to
create a `GlobalSearch`

object that has iterative display
and runs only from feasible points with respect to bounds and inequalities,
enter

gs = GlobalSearch("Display","iter", ... "StartPointsToRun","bounds-ineqs");

To set a property of an existing `GlobalSearch`

or `MultiStart`

object, use dot notation. For example, if
`ms`

is a `MultiStart`

object,
and you want to set the `Display`

property to
`"iter"`

, enter

`ms.Display = "iter";`

To set multiple properties of an existing object simultaneously, use the constructor (`GlobalSearch`

or `MultiStart`

) with name-value arguments. For example, to set the
`Display`

property to `"iter"`

and the
`MaxTime`

property to `100`

, enter

`ms = MultiStart(ms,Display="iter",MaxTime=100);`

For more information on setting properties, see Changing Global Options.

### Properties of Both Objects

You can create a `MultiStart`

object from a `GlobalSearch`

object
and vice-versa.

The syntax for creating a new object from an existing object is:

ms = MultiStart(gs); or gs = GlobalSearch(ms);

The new object contains the properties that apply of the old object. This section describes those shared properties:

#### Display

Values for the `Display`

property are:

`"final"`

(default) — Summary results to command line after last solver run.`"off"`

— No output to command line.`"iter"`

— Summary results to command line after each local solver run.

#### FunctionTolerance

The `FunctionTolerance`

property describes
how close two objective function values must be for solvers to consider
them identical for creating the vector of local solutions. Set `FunctionTolerance`

to `0`

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

to
a larger value to have fewer results.

Solvers consider two solutions identical if they are within `XTolerance`

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

of
each other. If both conditions are not met, solvers report the solutions
as distinct. The tolerances are relative, not absolute. For details,
see When fmincon Runs for `GlobalSearch`

,
and Create GlobalOptimSolution Object for `MultiStart`

.

#### MaxTime

The `MaxTime`

property describes a tolerance
on the number of seconds since the solver began its run. Solvers halt
when they see `MaxTime`

seconds have passed since
the beginning of the run. Time means *wall clock* as
opposed to processor cycles. The default is `Inf`

.

#### OutputFcn

The `OutputFcn`

property directs the global solver to run one or more output
functions after each local solver run completes. The output functions also run
when the global solver starts and ends. Include a handle to an output function
written in the appropriate syntax, or include a cell array of such handles. The
default is an empty entry (`[]`

). There is one built-in output
function that collects all the local solutions found. To use it, set the solver
parameter `OutputFcn=@savelocalsolutions`

. See Output Functions for GlobalSearch and MultiStart.

The syntax of an output function is:

stop = outFcn(optimValues,state)

`stop`

is a Boolean. When`true`

, the algorithm stops. When`false`

, the algorithm continues.**Note**A local solver can have an output function. The global solver does not necessarily stop when a local solver output function causes a local solver run to stop. If you want the global solver to stop in this case, have the global solver output function stop when

`optimValues.localsolution.exitflag=-1`

.`optimValues`

is a structure, described in optimValues Structure.`state`

is the current state of the global algorithm:`"init"`

— The global solver has not called the local solver. The fields in the`optimValues`

structure are empty, except for`localrunindex`

, which is`0`

, and`funccount`

, which contains the number of objective and constraint function evaluations.`"iter"`

— The global solver calls output functions after each local solver run.`"done"`

— The global solver finished calling local solvers. The fields in`optimValues`

generally have the same values as the ones from the final output function call with`state`

=`"iter"`

. However, the value of`optimValues.funccount`

for`GlobalSearch`

can be larger than the value in the last function call with`"iter"`

, because the`GlobalSearch`

algorithm might have performed some function evaluations that were not part of a local solver. For more information, see GlobalSearch Algorithm.

For an example using an output function, see Custom GlobalSearch Output Function.

**Note**

Output and plot functions do not run when `MultiStart`

has
the `UseParallel`

option set to `true`

and
there is an open `parpool`

.

**optimValues Structure. **The `optimValues`

structure contains the following
fields:

`bestx`

— The current best point`bestfval`

— Objective function value at`bestx`

`constrviolation`

— Maximum constraint violation. Zero for no constraint violations.`funccount`

— Total number of function evaluations`localrunindex`

— Index of the local solver run`localsolution`

— A structure containing part of the output of the local solver call:`X`

,`Fval`

and`Exitflag`

#### PlotFcn

The `PlotFcn`

property directs the global solver
to run one or more plot functions after each local solver run completes.
Include a handle to a plot function written in the appropriate syntax,
or include a cell array of such handles. The default is an empty entry
(`[]`

).

The syntax of a plot function is the same as that of an output function. For details, see OutputFcn.

There are two predefined plot functions for the global solvers:

`@gsplotbestf`

plots the best objective function value.`@gsplotfunccount`

plots the number of function evaluations.

For an example using a plot function, see MultiStart Plot Function.

If you specify more than one plot function, all plots appear as subplots in the same window. Right-click any subplot to obtain a larger version in a separate figure window.

**Note**

Output and plot functions do not run when `MultiStart`

has
the `UseParallel`

option set to `true`

and
there is an open `parpool`

.

#### StartPointsToRun

The `StartPointsToRun`

property directs the
solver to exclude certain start points from being run:

`all`

— Accept all start points.`bounds`

— Reject start points that do not satisfy bounds.`bounds-ineqs`

— Reject start points that do not satisfy bounds or inequality constraints.

#### XTolerance

The `XTolerance`

property describes how close two points must be for solvers
to consider them identical for creating the vector of local solutions. Set
`XTolerance`

to `0`

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

to a larger value
to have fewer results. Solvers compute the distance between a pair of points
with `norm`

, the Euclidean distance.

Solvers consider two solutions identical if they are within `XTolerance`

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

of
each other. If both conditions are not met, solvers report the solutions
as distinct. The tolerances are relative, not absolute. For details,
see When fmincon Runs for `GlobalSearch`

,
and Create GlobalOptimSolution Object for `MultiStart`

.

### GlobalSearch Properties

#### NumTrialPoints

Number of potential start points to examine in addition to `x0`

from
the `problem`

structure. `GlobalSearch`

runs
only those potential start points that pass several tests. For more
information, see GlobalSearch Algorithm.

Default: `1000`

#### NumStageOnePoints

Number of start points in Stage 1. For details, see Obtain Stage 1 Start Point, Run.

Default: `200`

#### MaxWaitCycle

A positive integer tolerance appearing in several points in the algorithm.

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

Default: `20`

#### BasinRadiusFactor

A basin radius decreases after `MaxWaitCycle`

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

.

Default: `0.2`

#### DistanceThresholdFactor

A multiplier for determining whether a trial point is in an
existing basin of attraction. For details, see Examine Stage 2 Trial Point to See if fmincon Runs. Default: `0.75`

#### PenaltyThresholdFactor

Determines increase in penalty threshold. For details, see React to Large Counter Values.

Default: `0.2`

### MultiStart Properties

#### UseParallel

The `UseParallel`

property determines whether
the solver distributes start points to multiple processors:

`false`

(default) — Do not run in parallel.`true`

— Run in parallel.

For the solver to run in parallel you must set up a parallel environment with
`parpool`

. For details, see How to Use Parallel Processing in Global Optimization Toolbox.