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 that optimoptions returns. To see why optimoptions 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.
"nups-gps" — Use the Nonuniform Pattern Search algorithm restricted to the GPS (generalized pattern search) polling algorithm (no OrthoMADS (orthogonal mesh adaptive direct search) polling).
"nups-mads" — 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 built-in 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 built-in 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. Right-click 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 for patternsearch:
- x — Current point
- iteration — Iteration number
- fval — Objective function value
- meshsize — Current mesh size
- funccount — Number of function evaluations
- method — Method used in last iteration
- TolFun — Tolerance on function value in last iteration
- TolX — Tolerance on x value in last iteration
- nonlinineq — Nonlinear inequality constraints, displayed only when a nonlinear constraint function is specified
- nonlineq — Nonlinear equality constraints, displayed only when a nonlinear constraint function is specified
The structure contains the following fields for paretosearch:
- x — Current point
- fval — Objective function value
- iteration — Iteration number
- funccount — Number of function evaluations
- nonlinineq — Nonlinear inequality constraints, displayed only when a nonlinear constraint function is specified
- nonlineq — 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 for flag 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.

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.

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 N-by-N 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 to true, 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 to false, 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, the MinPollFraction option specifies the fraction of poll directions that are investigated during a poll, instead of the binary value of UseCompletePoll. To specify a complete poll, set MinPollFraction to 1. To specify that the poll stops as soon as it finds a point that improves all objective functions, set MinPollFraction to 0.

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 built-in 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 \| `{1e-4}`
`MinPollFraction`	Minimum fraction of the pattern to poll.	Scalar from 0 through 1 \| `{0}`
`InitialPoints`	Initial points for `paretosearch`. Use one of these data types: Matrix with `nvars` columns, where each row represents one initial point. Structure containing the following fields (all fields are optional except `X0`): `X0` — Matrix with `nvars` columns, where each row represents one initial point. `Fvals` — Matrix with `numObjectives` columns, where each row represents the objective function values at the corresponding point in `X0`. `Cineq` — Matrix with `numIneq` columns, where each row represents the nonlinear inequality constraint values at the corresponding point in `X0`. If there are missing entries in the `Fvals` or `Cineq` fields, `paretosearch` computes the missing values.	Matrix with `nvars` columns \| structure \| `{[]}`

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 built-in 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 for iterlim is 1. The recommendation is not to change this value, because performing these time-consuming searches more than once is not likely to improve results.
- optionsGA — Options for the genetic algorithm, which you can set using optimoptions. If you do not specify any searchga options, then searchga uses the same UseParallel and UseVectorized option settings as patternsearch.
"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] minus rand(1,k), divided by k. (k is the number of points.) This yields k points, with each component close to evenly spaced. The resulting points are then scaled to fit any bounds. Latin hypercube uses default bounds of -1 and 1.
The way the search is performed depends on the setting for the UseCompleteSearch option.
- If you set UseCompleteSearch to true, 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 to false (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 for iterlim is 1.
- level — The level is the number of points patternsearch searches, a positive integer. The default for level is 15 times the number of dimensions.
"searchneldermead" specifies a search using fminsearch, which uses the Nelder-Mead algorithm. You can modify the Nelder-Mead 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 Nelder-Mead search is performed. The default for iterlim is 1.
- optionsNM — Options for fminsearch, which you can create using the optimset function.
"rbfsurrogate" specifies a search using a radial basis function surrogate, similar to the surrogateopt surrogate (see Surrogate Optimization Algorithm). The surrogate is formed from the most recent N+1 or more evaluation points, where N is the number of variables (size of x0). 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 least N+1 points, so after a reset, the search does not run until the algorithm evaluates at least N+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 time-consuming 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 function
x — Current point
A,b — Linear inequality constraints
Aeq,beq — Linear equality constraints
lb,ub — Lower and upper bound constraints
optimValues — Structure that enables you to set search options. The structure contains the following fields:
- x — Current point
- fval — Objective function value at x
- iteration — Current iteration number
- funccount — Counter for user function evaluation
- scale — Scale factor used to scale the design points
- problemtype — 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 step
- method — 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 not
xBest,fBest — Best point and best function value found by search method
funccount — 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 is 1.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 is Inf. MADS uses a maximum size of 1.
AccelerateMesh specifies whether, when the mesh size is small, the MeshContractionFactor is multiplied by 0.5 after each unsuccessful iteration. AccelerateMesh can have the values true (use accelerator) or false (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 the PollMethod 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 the MeshTolerance 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 values false or true (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 is 2.0, which means that the size of the mesh is multiplied by 2.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 the Algorithm option is "classic". MADS uses a MeshExpansionFactor of 4.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 is 0.5, which means that the size of the mesh is multiplied by 0.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 the Algorithm option is "classic". MADS uses a MeshContractionFactor of 0.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 to 1, and has a default of 10.
PenaltyFactor — Increases the penalty parameter when the problem is not solved to required accuracy and constraints are not satisfied. PenaltyFactor must be greater than 1, and has a default of 100.

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 1e-3.

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 1e-6.

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 1e-6.

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 1e-6.

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 1e-6.

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 point
- iteration — Iteration number
- fval — Objective function value at x
- meshsize — Current mesh size
- funccount — Number of function evaluations
- method — 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 constraints
- TolFun — Absolute value of change in function value in last iteration
- TolX — Norm of change in x in last iteration
- nonlinineq — Nonlinear inequality constraint function values at x, displayed only when a nonlinear constraint function is specified
- nonlineq — Nonlinear equality constraint function values at x, displayed only when a nonlinear constraint function is specified
options — Options
flag — Current state in which the output function is called. The possible values for flag are
- 'init' — Initialization state
- 'iter' — Iteration state
- 'interrupt' — Iteration of a subproblem of a nonlinearly constrained problem
  - When flag is 'interrupt', the values of optimvalues fields apply to the subproblem iterations.
  - When flag is 'interrupt', patternsearch does not accept changes in options, and ignores optchanged.
- '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 to options. To change options for subsequent iterations, set optchanged to true.

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 number
FunEval — Cumulative number of function evaluations
MeshSize — Current mesh size
FunVal — Objective function value of the current point
Method — 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 is false, patternsearch calls the objective function on one point at a time as it loops through the mesh points. (This assumes UseParallel is at its default value of false.)
UseVectorized is true, 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 is true, 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" to false 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, `"classic"` algorithm
`Cache`	With `Cache` set to `"on"`, `patternsearch` keeps a history of the mesh points it polls and does not poll points close to them again at subsequent iterations. Use this option if `patternsearch` runs slowly because it is taking a long time to compute the objective function. If the objective function is stochastic, it is advised not to use this option. Note `Cache` does not work when you run the solver in parallel.	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 `patternsearch` to avoid polling it. Available if `"Cache"` option is set to `"on"`.	All
`ConstraintTolerance`	Tolerance on 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, `"classic"` algorithm
`MeshExpansionFactor`	Mesh expansion factor, expands mesh when iteration is successful.	GPS and GSS, `"classic"` algorithm
`MeshRotate`	Rotate the pattern before declaring a point to be optimum.	GPS Np1 and GSS Np1
`MeshTolerance`	Tolerance on mesh size.	All
`OutputFcn`	User-specified 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, `"classic"` algorithm
`PollMethod`	Polling strategy used in pattern search.	`"classic"` algorithm
`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.	`"classic"` algorithm
`UseCompleteSearch`	Complete search around current iterate when the search method is a poll method. Evaluate all the points in a search step.	`"classic"` algorithm
`UseParallel`	When `true`, compute objective functions of a poll or search in parallel. Disable by setting to `false`.	All
`UseVectorized`	Specifies whether objective and constraint functions are vectorized.	All