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

. These options do not appear in the listing that`italics`

`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**)

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

option specifies the
number of iterations between consecutive calls to the plot function.*PlotInterval*

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

### 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 2*N* and the Positive basis
*N*+1:

The default pattern for

`patternsearch`

,`'GPSPositiveBasis2N'`

, consists of the following 2*N*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 2*N*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 2*N*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.

`UseCompletePoll`

specifies whether all the points in the current
mesh must be polled at each iteration. `UseCompletePoll`

can have
the values `true`

or `false`

.

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

The values for `SearchFcn`

are listed below.

`[]`

, the default, specifies no search step.Any built-in poll algorithm:

`'GPSPositiveBasis2N'`

,`'GPSPositiveBasisNp1'`

,`'GSSPositiveBasis2N'`

,`'GSSPositiveBasisNp1'`

,`'MADSPositiveBasis2N'`

, or`'MADSPositiveBasisNp1'`

.`'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.

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

.specifies a maximum size for the mesh. When the maximum size is reached, the mesh size does not increase after a successful iteration.`MaxMeshSize`

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

.specifies whether, when the mesh size is small, the`AccelerateMesh`

`MeshContractionFactor`

is multiplied by`0.5`

after each unsuccessful iteration.can have the values`AccelerateMesh`

`true`

(use accelerator) or`false`

(do not use accelerator), the default.applies to the GPS and GSS algorithms.`AccelerateMesh`

applies only when the`MeshRotate`

`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*(unit positive directions) and –Σ_{i}*e*, the algorithm polls in directions –_{i}*e*and Σ_{i}*e*._{i}can have the values`MeshRotate`

`'Off'`

or`'On'`

(the default).is especially useful for discontinuous functions.`MeshRotate`

When the problem has equality constraints,

is disabled.`MeshRotate`

`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,`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. 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. 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.

— Specifies an initial value of the penalty parameter that is used by the nonlinear constraint algorithm.`InitialPenalty`

must be greater than or equal to`InitialPenalty`

`1`

, and has a default of`10`

.— Increases the penalty parameter when the problem is not solved to required accuracy and constraints are not satisfied.`PenaltyFactor`

must be greater than`PenaltyFactor`

`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

*specifies when a linear constraint is active.*

`TolBind`

*is not a stopping criterion. Active linear constraints change the pattern of points*

`TolBind`

`patternsearch`

uses for polling or searching. The default
value of *is*

`TolBind`

`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 *to*

`Cache`

`'On'`

, the algorithm does not evaluate the objective function
at any mesh points that are within *of a point in the cache.*

`CacheTol`

* CacheTol* specifies how close a mesh point
must be to a point in the cache for the algorithm to omit polling it.

*must be a positive scalar. The default value is*

`CacheTol`

`eps`

.* CacheSize* specifies the size of the cache.

*must be a positive scalar. The default value is*

`CacheSize`

`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 problemWhen

`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**

You must set `UseCompletePoll`

to `true`

for
`patternsearch`

to use vectorized or parallel polling.
Similarly, 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 it 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 |

`Cache` | With
| 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` | 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 |

`PollMethod` | Polling strategy used in pattern search. | All |

`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. | All |

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

`UseParallel` | When | All |

`UseVectorized` | Specifies whether objective and constraint functions are vectorized. | All |