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. Whentrue
, the algorithm stops. Whenfalse
, 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 theoptimValues
structure are empty, except forlocalrunindex
, which is0
, andfunccount
, 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 inoptimValues
generally have the same values as the ones from the final output function call withstate
="iter"
. However, the value ofoptimValues.funccount
forGlobalSearch
can be larger than the value in the last function call with"iter"
, because theGlobalSearch
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 pointbestfval
— Objective function value atbestx
constrviolation
— Maximum constraint violation. Zero for no constraint violations.funccount
— Total number of function evaluationslocalrunindex
— Index of the local solver runlocalsolution
— A structure containing part of the output of the local solver call:X
,Fval
andExitflag
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
.
Note
Plot functions do not support the subplot
statement, because the plot
function framework manages the axes. To specify multiple subplots, write separate plot
functions and pass them to the solver as a cell array:
options = optimoptions("solvername",PlotFcn={@plot1,@plot2,@plot3});
Output functions support subplot
, so you can include multiple plots in
one function by using an output function instead of a plot function.
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
s
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.