Pattern Search Options
Options for Pattern Search
Set options for patternsearch
by using
optimoptions
.
options = optimoptions("patternsearch",... Option1=value1,Option2=value2);
Some options are listed in
italics
. These options do not appear in the listing thatoptimoptions
returns. To see whyoptimoptions
hides these option values, see Options that optimoptions Hides.Ensure that you pass options to the solver. Otherwise,
patternsearch
uses the default option values.[x,fval] = patternsearch(fun,x0,A,b,Aeq,beq,lb,ub,nonlcon,options)
Algorithm Options
Algorithm
specifies the algorithm used by
patternsearch
to solve a problem.
"classic"
— Use the original algorithm as described in How Pattern Search Polling Works."nups"
— Use the Nonuniform Pattern Search algorithm as described in Nonuniform Pattern Search (NUPS) Algorithm."nupsgps"
— Use the Nonuniform Pattern Search algorithm restricted to the GPS (generalized pattern search) polling algorithm (no OrthoMADS (orthogonal mesh adaptive direct search) polling)."nupsmads"
— Use the Nonuniform Pattern Search algorithm restricted to the OrthoMADS polling algorithm (no GPS polling).
For examples of algorithm effects, see Explore patternsearch Algorithms and Explore patternsearch Algorithms in Optimize Live Editor Task.
Plot Options
PlotFcn
specifies the plot function or functions called at each
iteration by patternsearch
or
paretosearch
. Set the PlotFcn
option to be a
builtin plot function name or a handle to the plot function. You can stop the
algorithm at any time by clicking the Stop button on the plot
window. For example, to display the best function value, set
options
as follows:
options = optimoptions("patternsearch",PlotFcn="psplotbestf");
To display multiple plots, use a cell array of builtin plot function names or a cell array of function handles:
options = optimoptions("patternsearch",... PlotFcn={@plotfun1, @plotfun2, ...});
where @plotfun1
, @plotfun2
, and so on are
function handles to the plot functions. If you specify more than one plot function,
all plots appear as subplots in the same window. Rightclick any subplot to obtain a
larger version in a separate figure window.
Available plot functions for patternsearch
or for
paretosearch
with a single objective function:
"psplotbestf"
— Plot the best objective function value."psplotfuncount"
— Plot the number of function evaluations."psplotmeshsize"
— Plot the mesh size."psplotbestx"
— Plot the current best point."psplotmaxconstr"
— Plot the maximum nonlinear constraint violation.You can also create and use your own plot function. Structure of the Plot Functions describes the structure of a custom plot function. Pass any custom function as a function handle. For an example, see Custom Plot Function.
For paretosearch
with multiple objective functions, you can
select a custom function that you pass as a function handle, or any of the following
functions.
"psplotfuncount"
— Plot the number of function evaluations."psplotmaxconstr"
— Plot the maximum nonlinear constraint violation."psplotdistance"
— Plot the distance metric. See paretosearch Algorithm."psplotparetof"
— Plot the objective function values. Applies to three or fewer objectives."psplotparetox"
— Plot the current points in parameter space. Applies to three or fewer dimensions."psplotspread"
— Plot the spread metric. See paretosearch Algorithm."psplotvolume"
— Plot the volume metric. See paretosearch Algorithm.
For patternsearch
, the
PlotInterval
option specifies the
number of iterations between consecutive calls to the plot function.
Structure of the Plot Functions
The first line of a plot function has the form
function stop = plotfun(optimvalues, flag)
The input arguments to the function are
optimvalues
— Structure containing information about the current state of the solver. The structure contains the following fields forpatternsearch
:x
— Current pointiteration
— Iteration numberfval
— Objective function valuemeshsize
— Current mesh sizefunccount
— Number of function evaluationsmethod
— Method used in last iterationTolFun
— Tolerance on function value in last iterationTolX
— Tolerance onx
value in last iterationnonlinineq
— Nonlinear inequality constraints, displayed only when a nonlinear constraint function is specifiednonlineq
— Nonlinear equality constraints, displayed only when a nonlinear constraint function is specified
The structure contains the following fields for
paretosearch
:x
— Current pointfval
— Objective function valueiteration
— Iteration numberfunccount
— Number of function evaluationsnonlinineq
— Nonlinear inequality constraints, displayed only when a nonlinear constraint function is specifiednonlineq
— Nonlinear equality constraints, always empty[]
volume
— Volume measure (see Definitions for paretosearch Algorithm)averagedistance
— Distance measure (see Definitions for paretosearch Algorithm)spread
— Spread measure (see Definitions for paretosearch Algorithm)
flag
— Current state in which the plot function is called. The possible values forflag
are"init"
— Initialization state"iter"
— Iteration state"interrupt"
— Intermediate stage"done"
— Final state
For details of
flag
, see Structure of the Output Function.
Passing Extra Parameters explains how to provide additional parameters to the function.
The output argument stop
provides a way to stop the
algorithm at the current iteration. stop
can have the
following values:
false
— The algorithm continues to the next iteration.true
— The algorithm terminates at the current iteration.
Poll Options
Poll options control how the pattern search polls the mesh points at each iteration.
PollMethod
specifies the pattern the algorithm
uses to create the mesh. There are two patterns for each of the classes of direct
search algorithms: the generalized pattern search (GPS) algorithm, the generating
set search (GSS) algorithm, and the mesh adaptive direct search (MADS) algorithm.
These patterns are the Positive basis 2N and the Positive basis
N+1:
The default pattern for
patternsearch
,"GPSPositiveBasis2N"
, consists of the following 2N vectors, where N is the number of independent variables for the objective function.[1 0 0...0] [0 1 0...0] ...[0 0 0...1] [–1 0 0...0] [0 –1 0...0] [0 0 0...–1].
For example, if the optimization problem has three independent variables, the pattern consists of the following six vectors.
[1 0 0] [0 1 0] [0 0 1] [–1 0 0] [0 –1 0] [0 0 –1].
The default pattern for
paretosearch
,"GPSPositiveBasis2Np2"
, is the same as"GPSPositiveBasis2N"
with two more points: all ones and all minus ones.[1 1 1...1] [–1 –1 –1...–1]
For example, if the optimization problem has three independent variables, the pattern consists of the following eight vectors.
[1 0 0] [0 1 0] [0 0 1] [–1 0 0] [0 –1 0] [0 0 –1] [1 1 1] [–1 –1 –1].
The
"GSSPositiveBasis2N"
pattern is similar to"GPSPositiveBasis2N"
, but adjusts the basis vectors to account for linear constraints."GSSPositiveBasis2N"
is more efficient than"GPSPositiveBasis2N"
when the current point is near a linear constraint boundary.paretosearch
also has the"GSSPositiveBasis2Np2"
pattern that is similar to"GPSPositiveBasis2Np2"
.The
"MADSPositiveBasis2N"
pattern consists of 2N randomly generated vectors, where N is the number of independent variables for the objective function. This is done by randomly generating N vectors which form a linearly independent set, then using this first set and the negative of this set gives 2N vectors. As shown above, the"GPSPositiveBasis2N"
pattern is formed using the positive and negative of the linearly independent identity, however, with the"MADSPositiveBasis2N"
, the pattern is generated using a random permutation of an NbyN linearly independent lower triangular matrix that is regenerated at each iteration.Note
You cannot use MADS polling when the problem has linear equality constraints.
The
"GPSPositiveBasisNp1"
pattern consists of the following N + 1 vectors.[1 0 0...0] [0 1 0...0] ...[0 0 0...1] [–1 –1 –1...–1].
For example, if the objective function has three independent variables, the pattern consists of the following four vectors.
[1 0 0] [0 1 0] [0 0 1] [–1 –1 –1].
The
"GSSPositiveBasisNp1"
pattern is similar to"GPSPositiveBasisNp1"
, but adjusts the basis vectors to account for linear constraints."GSSPositiveBasisNp1"
is more efficient than"GPSPositiveBasisNp1"
when the current point is near a linear constraint boundary.The
"MADSPositiveBasisNp1"
pattern consists of N randomly generated vectors to form the positive basis, where N is the number of independent variables for the objective function. Then, one more random vector is generated, giving N+1 randomly generated vectors. Each iteration generates a new pattern when the"MADSPositiveBasisNp1"
is selected.Note
You cannot use MADS polling when the problem has linear equality constraints.
The
"OrthoMADSPositiveBasis2N"
pattern is the same as the"GPSPositiveBasis2N"
pattern followed by a random rotation in N dimensions.The
"OrthoMADSPositiveBasisNp1"
pattern is the same as the"GPSPositiveBasisNp1"
pattern followed by a random rotation in N dimensions.
UseCompletePoll
specifies whether all the points in the current
mesh must be polled at each iteration. UseCompletePoll
can have
the values true
or false
.
UseCompletePoll
applies only when
Algorithm
is "classic"
.
If you set
UseCompletePoll
totrue
, the algorithm polls all the points in the mesh at each iteration and chooses the point with the smallest objective function value as the current point at the next iteration.If you set
UseCompletePoll
tofalse
, the default value, the algorithm stops the poll as soon as it finds a point whose objective function value is less than that of the current point. The algorithm then sets that point as the current point at the next iteration.For
paretosearch
only, theMinPollFraction
option specifies the fraction of poll directions that are investigated during a poll, instead of the binary value ofUseCompletePoll
. To specify a complete poll, setMinPollFraction
to1
. To specify that the poll stops as soon as it finds a point that improves all objective functions, setMinPollFraction
to0
.
PollOrderAlgorithm
specifies the order in which the algorithm
searches the points in the current mesh. PollOrderAlgorithm
applies only when Algorithm
is "classic"
. The
options are
"Consecutive"
(default) — The algorithm polls the mesh points in consecutive order, that is, the order of the pattern vectors as described in Poll Method."Random"
— The polling order is random."Success"
— The first search direction at each iteration is the direction in which the algorithm found the best point at the previous iteration. After the first point, the algorithm polls the mesh points in the same order as"Consecutive"
.
Multiobjective Options
The paretosearch
solver mainly uses patternsearch
options. Several of the available builtin plot functions differ; see Plot Options. The
following options apply only to paretosearch
.
In the table, N
represents the number of decision
variables.
Multiobjective Pattern Search Options
Option  Definition  Allowed and { Default}
Values 

ParetoSetSize  Number of points in the Pareto set.  Positive integer  {max(60,number of objectives)
} 
ParetoSetChangeTolerance  Tolerance on the change in volume or spread of solutions. When
either of these measures relatively changes by less than
ParetoSetChangeTolerance , the iterations end.
For details, see Stopping Conditions.  Positive scalar  {1e4} 
MinPollFraction  Minimum fraction of the pattern to poll.  Scalar from 0 through 1  {0} 
InitialPoints  Initial points for
If there are missing entries in the
 Matrix with 
Search Options
The SearchFcn
option specifies an optional search that the
algorithm can perform at each iteration prior to the polling. If the search returns
a point that improves the objective function, the algorithm uses that point at the
next iteration and omits the polling. If you select the same
SearchFcn
and PollMethod
, only the Poll
method is used, although both are used when the selected options differ.
You can select a poll method as a search method only for the
"classic"
algorithm.
The values for SearchFcn
are listed below.
[]
, the default, specifies no search step.Any builtin poll algorithm:
"GPSPositiveBasis2N"
,"GPSPositiveBasisNp1"
,"GSSPositiveBasis2N"
,"GSSPositiveBasisNp1"
,"MADSPositiveBasis2N"
,"MADSPositiveBasisNp1"
,"OrthoMADSPositiveBasis2N"
, or"OrthoMADSPositiveBasisNp1"
."searchga"
specifies a search using the genetic algorithm. You can modify the genetic algorithm search using two additional parameters:options = optimoptions("patternsearch",SearchFcn=... {@searchga,iterlim,optionsGA})
iterlim
— Positive integer specifying the number of iterations of the pattern search for which the genetic algorithm search is performed. The default foriterlim
is 1. The recommendation is not to change this value, because performing these timeconsuming searches more than once is not likely to improve results.optionsGA
— Options for the genetic algorithm, which you can set usingoptimoptions
. If you do not specify anysearchga
options, thensearchga
uses the sameUseParallel
andUseVectorized
option settings aspatternsearch
.
"searchlhs"
specifies a Latin hypercube search.patternsearch
generates each point for the search as follows. For each component, take a random permutation of the vector[1,2,...,k]
minusrand(1,k)
, divided byk
. (k
is the number of points.) This yieldsk
points, with each component close to evenly spaced. The resulting points are then scaled to fit any bounds.Latin hypercube
uses default bounds of1
and1
.The way the search is performed depends on the setting for the
UseCompleteSearch
option.If you set
UseCompleteSearch
totrue
, the algorithm polls all the points that are randomly generated at each iteration by the Latin hypercube search and chooses the one with the smallest objective function value.If you set
UseCompleteSearch
tofalse
(the default), the algorithm stops the poll as soon as it finds one of the randomly generated points whose objective function value is less than that of the current point, and chooses that point for the next iteration.
You can modify the Latin hypercube search using two additional parameters:
options = optimoptions("patternsearch",SearchFcn=... {@searchlhs,iterlim,level})
iterlim
— Positive integer specifying the number of iterations of the pattern search for which the Latin hypercube search is performed. The default foriterlim
is 1.level
— Thelevel
is the number of pointspatternsearch
searches, a positive integer. The default forlevel
is 15 times the number of dimensions.
"searchneldermead"
specifies a search usingfminsearch
, which uses the NelderMead algorithm. You can modify the NelderMead search using two additional parameters:options = optimoptions("patternsearch",SearchFcn=... {@searchneldermead,iterlim,optionsNM})
iterlim
— Positive integer specifying the number of iterations of the pattern search for which the NelderMead search is performed. The default foriterlim
is 1.optionsNM
— Options forfminsearch
, which you can create using theoptimset
function.
"rbfsurrogate"
specifies a search using a radial basis function surrogate, similar to thesurrogateopt
surrogate (see Surrogate Optimization Algorithm). The surrogate is formed from the most recentN
+1 or more evaluation points, whereN
is the number of variables (size ofx0
). After the algorithm evaluates 10*N
points, the surrogate is reset (erased) and the points for a new surrogate come from points after the reset. The radial basis function requires at leastN
+1 points, so after a reset, the search does not run until the algorithm evaluates at leastN
+1 additional points. The surrogate requires upper and lower bounds on all variables. If you do not supply a bound, the algorithm constructs one from the recent point list. Therefore, when you do not provide a bound for some variables, the algorithm performs more computations and runs a bit slower. In any case, this search function is relatively time consuming, making it best suited for use with timeconsuming objective functions.Custom
enables you to write your own search function.options = optimoptions("patternsearch",SearchFcn=@myfun);
To see a template that you can use to write your own search function, enter
edit searchfcntemplate
The following section describes the structure of the search function.
Structure of the Search Function
Your search function must have the following calling syntax.
function [successSearch,xBest,fBest,funccount] = ... searchfcntemplate(fun,x,A,b,Aeq,beq,lb,ub, ... optimValues,options)
The search function has the following input arguments:
fun
— Objective functionx
— Current pointA,b
— Linear inequality constraintsAeq,beq
— Linear equality constraintslb,ub
— Lower and upper bound constraintsoptimValues
— Structure that enables you to set search options. The structure contains the following fields:x
— Current pointfval
— Objective function value atx
iteration
— Current iteration numberfunccount
— Counter for user function evaluationscale
— Scale factor used to scale the design pointsproblemtype
— Flag passed to the search routines, indicating whether the problem is'unconstrained'
,'boundconstraints'
, or'linearconstraints'
. This field is a subproblem type for nonlinear constrained problems.meshsize
— Current mesh size used in search stepmethod
— Method used in last iteration
options
— Pattern search options
The function has the following output arguments:
successSearch
— A Boolean identifier indicating whether the search is successful or notxBest,fBest
— Best point and best function value found by search methodfunccount
— Number of user function evaluation in search method
See Search and Poll for an example.
Complete Search
The UseCompleteSearch
option applies when you set
SearchFcn
to "GPSPositiveBasis2N"
,
"GPSPositiveBasisNp1"
,
"GSSPositiveBasis2N"
,
"GSSPositiveBasisNp1"
,
"MADSPositiveBasis2N"
,
"MADSPositiveBasisNp1"
, or
"searchlhs"
. UseCompleteSearch
can have
the values true
or false
.
For search functions that are poll algorithms,
UseCompleteSearch
has the same meaning as the poll option
UseCompletePoll
. For the meaning of
UseCompleteSearch
for Latin hypercube search, see the
"searchlhs"
entry in Search Options.
Mesh Options
Mesh options control the mesh that the pattern search uses. The following options are available.
InitialMeshSize
specifies the size of the initial mesh, which is the length of the shortest vector from the initial point to a mesh point.InitialMeshSize
must be a positive scalar. The default is1.0
.MaxMeshSize
specifies a maximum size for the mesh. When the maximum size is reached, the mesh size does not increase after a successful iteration.MaxMeshSize
must be a positive scalar, and is only used when a GPS or GSS algorithm is selected as the Poll or Search method. The default value isInf
. MADS uses a maximum size of1
.AccelerateMesh
specifies whether, when the mesh size is small, theMeshContractionFactor
is multiplied by0.5
after each unsuccessful iteration.AccelerateMesh
can have the valuestrue
(use accelerator) orfalse
(do not use accelerator), the default.AccelerateMesh
applies only to the GPS and GSS poll algorithms and to the"classic"
algorithm..MeshRotate
applies only when thePollMethod
is"GPSPositiveBasisNp1"
or"GSSPositiveBasisNp1"
.MeshRotate
="On"
specifies that the mesh vectors are multiplied by –1 when the mesh size is less than 1/100 of theMeshTolerance
option after an unsuccessful poll. In other words, after the first unsuccessful poll with small mesh size, instead of polling in directions e_{i} (unit positive directions) and –Σe_{i}, the algorithm polls in directions –e_{i} and Σe_{i}.MeshRotate
can have the values"Off"
or"On"
(the default).MeshRotate
is especially useful for discontinuous functions.When the problem has equality constraints,
MeshRotate
is disabled.
ScaleMesh
specifies whether the algorithm scales the mesh points by carefully multiplying the pattern vectors by constants proportional to the logarithms of the absolute values of components of the current point (or, for unconstrained problems, of the initial point).ScaleMesh
can have the valuesfalse
ortrue
(the default). When the problem has equality constraints for the"classic"
algorithm,ScaleMesh
is disabled.MeshExpansionFactor
specifies the factor by which the mesh size is increased after a successful poll. The default value is2.0
, which means that the size of the mesh is multiplied by2.0
after a successful poll.MeshExpansionFactor
must be a positive scalar and is only used when a GPS or GSS method is selected as the Poll or Search method and theAlgorithm
option is"classic"
. MADS uses aMeshExpansionFactor
of4.0
. See Mesh Expansion and Contraction for more information.MeshContractionFactor
specifies the factor by which the mesh size is decreased after an unsuccessful poll. The default value is0.5
, which means that the size of the mesh is multiplied by0.5
after an unsuccessful poll.MeshContractionFactor
must be a positive scalar and is only used when a GPS or GSS method is selected as the Poll or Search method and theAlgorithm
option is"classic"
. MADS uses aMeshContractionFactor
of0.25
. See Mesh Expansion and Contraction for more information.
Constraint Parameters
For information on the meaning of penalty parameters, see Nonlinear Constraint Solver Algorithm for Pattern Search.
InitialPenalty
— Specifies an initial value of the penalty parameter that is used by the nonlinear constraint algorithm.InitialPenalty
must be greater than or equal to1
, and has a default of10
.PenaltyFactor
— Increases the penalty parameter when the problem is not solved to required accuracy and constraints are not satisfied.PenaltyFactor
must be greater than1
, and has a default of100
.
TolBind
specifies the tolerance for the
distance from the current point to the boundary of the feasible region with respect
to linear constraints. This means TolBind
specifies when a linear constraint is active.
TolBind
is not a stopping criterion.
Active linear constraints change the pattern of points
patternsearch
uses for polling or searching. The default
value of TolBind
is
1e3
.
Cache Options
The pattern search algorithm can keep a record of the points it has already polled, so that it does not have to poll the same point more than once. If the objective function requires a relatively long time to compute, the cache option can speed up the algorithm. The memory allocated for recording the points is called the cache. This option should only be used for deterministic objective functions, and not for stochastic ones.
Cache
specifies whether a cache is used.
The options are "On"
and "Off"
, the default.
When you set Cache
to
"On"
, the algorithm does not evaluate the objective function
at any mesh points that are within CacheTol
of a point in the cache.
CacheTol
specifies how close a mesh point
must be to a point in the cache for the algorithm to omit polling it.
CacheTol
must be a positive scalar.
The default value is eps
.
CacheSize
specifies the size of the cache.
CacheSize
must be a positive scalar.
The default value is 1e4
.
Note
Cache
does not work when you run the solver in parallel.
See Use Cache for more information.
Stopping Criteria
Stopping criteria determine what causes the pattern search algorithm to stop. Pattern search uses the following criteria:
MeshTolerance
specifies the minimum tolerance for mesh size.
The GPS and GSS algorithms stop if the mesh size becomes smaller than
MeshTolerance
. MADS 2N stops when the mesh size becomes
smaller than MeshTolerance^2
. MADS Np1 stops when the mesh size
becomes smaller than (MeshTolerance/nVar)^2
, where
nVar
is the number of elements of x0
. The
default value of MeshTolerance
is 1e6
.
MaxIterations
specifies the maximum number of iterations the
algorithm performs. The algorithm stops if the number of iterations reaches
MaxIterations
. The default value is 100 times the number of
independent variables.
MaxFunctionEvaluations
specifies the maximum number of
evaluations of the objective function. The algorithm stops if the number of function
evaluations reaches MaxFunctionEvaluations
. The default value is
2000 times the number of independent variables.
MaxTime
specifies the maximum time in seconds the pattern
search algorithm runs before stopping. This also includes any specified pause time
for pattern search algorithms.
StepTolerance
specifies the minimum distance between the
current points at two consecutive iterations. Does not apply to MADS polling. After
an unsuccessful poll, the algorithm stops if the distance between two consecutive
points is less than StepTolerance
and the mesh size is smaller
than StepTolerance
. The default value is
1e6
.
FunctionTolerance
specifies the minimum tolerance for the
objective function. Does not apply to MADS polling. After an unsuccessful poll, the
algorithm stops if the difference between the function value at the previous best
point and function value at the current best point is less than
FunctionTolerance
, and if the mesh size is also smaller than
StepTolerance
. The default value is
1e6
.
See Setting Solver Tolerances for an example.
ConstraintTolerance
is not used as stopping criterion. It is
used to determine the feasibility with respect to nonlinear constraints. The default
value is 1e6
.
Output Function Options
OutputFcn
specifies functions that the pattern search algorithm
calls at each iteration. For an output function file myfun.m
,
set
options = optimoptions("patternsearch",OutputFcn=@myfun);
For multiple output functions, enter a cell array of function handles:
options = optimoptions('patternsearch",... OutputFcn={@myfun1,@myfun2,...});
To see a template that you can use to write your own output function, enter
edit psoutputfcntemplate
at the MATLAB^{®} command prompt.
To pass extra parameters in the output function, use Anonymous Functions.
Structure of the Output Function
Your output function must have the following calling syntax:
[stop,options,optchanged] = myfun(optimvalues,options,flag)
MATLAB passes the optimvalues
,
options
, and flag
data to your output
function, and the output function returns stop
,
options
, and optchanged
data.
The output function has the following input arguments.
optimvalues
— Structure containing information about the current state of the solver. The structure contains the following fields:x
— Current pointiteration
— Iteration numberfval
— Objective function value atx
meshsize
— Current mesh sizefunccount
— Number of function evaluationsmethod
— Method used in last iteration, such as'Update multipliers'
or'Increase penalty'
for a nonlinearly constrained problem, or'Successful Poll'
,'Refine Mesh'
, or'Successful Search'
, possibly with a'\Rotate'
suffix, for a problem without nonlinear constraintsTolFun
— Absolute value of change in function value in last iterationTolX
— Norm of change inx
in last iterationnonlinineq
— Nonlinear inequality constraint function values atx
, displayed only when a nonlinear constraint function is specifiednonlineq
— Nonlinear equality constraint function values atx
, displayed only when a nonlinear constraint function is specified
options
— Optionsflag
— Current state in which the output function is called. The possible values forflag
are'init'
— Initialization state'iter'
— Iteration state'interrupt'
— Iteration of a subproblem of a nonlinearly constrained problemWhen
flag
is'interrupt'
, the values ofoptimvalues
fields apply to the subproblem iterations.When
flag
is'interrupt'
,patternsearch
does not accept changes inoptions
, and ignoresoptchanged
.
'done'
— Final state
Passing Extra Parameters explains how to provide additional parameters to the output function.
The output function returns the following arguments to
patternsearch
:
stop
— Provides a way to stop the algorithm at the current iteration.stop
can have the following values.false
— The algorithm continues to the next iteration.true
— The algorithm terminates at the current iteration.
options
—patternsearch
options.optchanged
— Boolean flag indicating changes tooptions
. To changeoptions
for subsequent iterations, setoptchanged
totrue
.
Display to Command Window Options
Display
specifies how much information is displayed at the
command line while the pattern search is running. The available options are
"final"
(default) — The reason for stopping is displayed."off"
or the equivalent"none"
— No output is displayed."iter"
— Information is displayed for each iteration."diagnose"
— Information is displayed for each iteration. In addition, the diagnostic lists some problem information and the options that are changed from the defaults.
Both "iter"
and "diagnose"
display the
following information:
Iter
— Iteration numberFunEval
— Cumulative number of function evaluationsMeshSize
— Current mesh sizeFunVal
— Objective function value of the current pointMethod
— Outcome of the current poll (with no nonlinear constraint function specified). With a nonlinear constraint function,Method
displays the update method used after a subproblem is solved.Max Constraint
— Maximum nonlinear constraint violation (displayed only when a nonlinear constraint function has been specified)
Vectorized and Parallel Options
You can choose to have your objective and constraint functions evaluated in
serial, parallel, or in a vectorized fashion. Set the
UseVectorized
or UseParallel
options to
true
to use vectorized or parallel computation.
Note
To use vectorized or parallel polling for the "classic"
algorithm, you must set UseCompletePoll
to
true
. Similarly for the "classic"
algorithm, set UseCompleteSearch
to true
for vectorized or parallel searching.
Beginning in R2019a, when you set the
UseParallel
option to true
,
patternsearch
internally overrides the
UseCompletePoll
setting to true
so that the function
polls in parallel.
When
UseVectorized
isfalse
,patternsearch
calls the objective function on one point at a time as it loops through the mesh points. (This assumesUseParallel
is at its default value offalse
.)UseVectorized
istrue
,patternsearch
calls the objective function on all the points in the mesh at once, i.e., in a single call to the objective function.If there are nonlinear constraints, the objective function and the nonlinear constraints all need to be vectorized in order for the algorithm to compute in a vectorized manner.
For details and an example, see Vectorize the Objective and Constraint Functions.
When
UseParallel
istrue
,patternsearch
calls the objective function in parallel, using the parallel environment you established (see How to Use Parallel Processing in Global Optimization Toolbox). At the command line, set"UseParallel"
tofalse
to compute serially.
Note
You cannot simultaneously use vectorized and parallel computations. If you set
UseParallel
to true
and
UseVectorized
to true
,
patternsearch
evaluates your objective and constraint
functions in a vectorized manner, not in parallel.
How Objective and Constraint Functions Are Evaluated
Assume UseCompletePoll =
true  UseVectorized =
false  UseVectorized =
true 

UseParallel = false  Serial  Vectorized 
UseParallel = true  Parallel  Vectorized 
Options Table for Pattern Search Algorithms
Option Availability Table for All Algorithms
Option  Description  Algorithm Availability 

AccelerateMesh  Accelerate mesh size contraction.  GPS and GSS, 
Cache  With Note
 All 
CacheSize  Size of the cache, in number of points.  All 
CacheTol  Positive scalar specifying how close the current mesh point
must be to a point in the cache in order for
 All 
ConstraintTolerance  Tolerance on nonlinear constraints.  All 
Display  Level of display to Command Window.  All 
FunctionTolerance  Tolerance on function value.  All 
InitialMeshSize  Initial mesh size used in pattern search algorithms.  All 
InitialPenalty  Initial value of the penalty parameter.  All 
MaxFunctionEvaluations  Maximum number of objective function evaluations.  All 
MaxIterations  Maximum number of iterations.  All 
MaxMeshSize  Maximum mesh size used in a poll/search step.  GPS and GSS 
MaxTime  Total time (in seconds) allowed for optimization. Also includes any specified pause time for pattern search algorithms.  All 
MeshContractionFactor  Mesh contraction factor, used when iteration is unsuccessful.  GPS and GSS, 
MeshExpansionFactor  Mesh expansion factor, expands mesh when iteration is successful.  GPS and GSS, 
MeshRotate  Rotate the pattern before declaring a point to be optimum.  GPS Np1 and GSS Np1 
MeshTolerance  Tolerance on mesh size.  All 
OutputFcn  Userspecified function that a pattern search calls at each iteration.  All 
PenaltyFactor  Penalty update parameter.  All 
PlotFcn  Specifies function to plot at run time.  All 
PlotInterval  Specifies that plot functions will be called at every interval.  All 
PollOrderAlgorithm  Order in which search directions are polled.  GPS and GSS, 
PollMethod  Polling strategy used in pattern search. 

ScaleMesh  Automatic scaling of variables.  All 
SearchFcn  Specifies search method used in pattern search.  All 
StepTolerance  Tolerance on independent variable.  All 
TolBind  Binding tolerance used to determine if linear constraint is active.  All 
UseCompletePoll  Complete poll around current iterate. Evaluate all the points in a poll step. 

UseCompleteSearch  Complete search around current iterate when the search method is a poll method. Evaluate all the points in a search step. 

UseParallel  When  All 
UseVectorized  Specifies whether objective and constraint functions are vectorized.  All 