Note: This page has been translated by MathWorks. Click here to see

To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

There are two ways to specify options for pattern search, depending
on whether you are using the Optimization app or calling the function `patternsearch`

at
the command line:

If you are using the Optimization app, you specify the options by selecting an option from a drop-down list or by entering the value of the option in the text field.

If you are calling

`patternsearch`

from the command line, you specify the options by creating an`options`

object using the function`optimoptions`

, as follows:options = optimoptions('patternsearch','Param1',value1,'Param2',value2,...);

See Set Options for examples.

In this section, each option is listed in two ways:

By its label, as it appears in the Optimization app

By its field name in the

`options`

object

For example:

**Poll method**refers to the label of the option in the Optimization app.`PollMethod`

refers to the corresponding field of the`options`

object.

Plot options enable you to plot data from the pattern search
while it is running. When you select plot functions and run the pattern
search, a plot window displays the plots on separate axes. You can
stop the algorithm at any time by clicking the **Stop** button
on the plot window.

For `patternsearch`

, **Plot interval**
(

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

You can select any of the following plots in the **Plot functions**
pane for `patternsearch`

or `paretosearch`

with a single objective function.

**Best function value**(`'psplotbestf'`

) plots the best objective function value.**Function count**(`'psplotfuncount'`

) plots the number of function evaluations.**Mesh size**(`'psplotmeshsize'`

) plots the mesh size.**Best point**(`'psplotbestx'`

) plots the current best point.**Max constraint**(`'psplotmaxconstr'`

) plots the maximum nonlinear constraint violation.**Custom**enables you to use your own plot function. To specify the plot function using the Optimization app,Select

**Custom function**.Enter

`@myfun`

in the text box, where`myfun`

is the name of your function.

Structure of the Plot Functions describes the structure of a plot function.

For `paretosearch`

with multiple objective functions, you can
select the `'psplotfuncount'`

option, or a custom function that you
pass as a function handle, or any of the following functions.

`'psplotdistance'`

— Plot the distance metric. See paretosearch Algorithm.`'psplotmaxconstr'`

— Plot the maximum nonlinear constraint violation.`'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.

To display a plot when calling `patternsearch`

or
`paretosearch`

from the command line, set the
`PlotFcn`

option to be a built-in plot function name or a
handle to the plot function. 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 (listed in parentheses
in the preceding list).

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.

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 (Optimization Toolbox) 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 control how the pattern search polls the mesh points at each iteration.

**Poll method** (`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`

,`GPS Positive basis 2N`

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

`GSS Positive basis 2N`

pattern (`'GSSPositiveBasis2N'`

) is similar to`GPS Positive basis 2N`

, but adjusts the basis vectors to account for linear constraints.`GSS Positive basis 2N`

is more efficient than`GPS Positive basis 2N`

when the current point is near a linear constraint boundary.The

`MADS Positive basis 2N`

pattern (`'MADSPositiveBasis2N'`

) 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`GPS Positive basis 2N`

pattern is formed using the positive and negative of the linearly independent identity, however, with the`MADS Positive basis 2N`

, the pattern is generated using a random permutation of an*N*-by-*N*linearly independent lower triangular matrix that is regenerated at each iteration.The

`GPS Positive basis NP1`

pattern (`'GPSPositiveBasisNp1'`

)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

`GSS Positive basis Np1`

pattern (`'GSSPositiveBasisNp1'`

) is similar to`GPS Positive basis Np1`

, but adjusts the basis vectors to account for linear constraints.`GSS Positive basis Np1`

is more efficient than`GPS Positive basis Np1`

when the current point is near a linear constraint boundary.The

`MADS Positive basis Np1`

pattern (`'MADSPositiveBasisNp1'`

) 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`MADS Positive basis N+1`

is selected.For

`paretosearch`

only, the default`'GSSPositiveBasis2Np2'`

pattern uses the GSS`2N`

patterns, and also uses the`[1 1 ... 1]`

and`[-1 -1 ... -1]`

patterns.

**Complete poll** `(UseCompletePoll)`

specifies
whether all the points in the current mesh must be polled at each
iteration. **Complete Poll** can have the values `On`

or `Off`

.

If you set

**Complete poll**to**on**(`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

**Complete poll**to**off**(`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`

.

**Polling order** (`PollOrderAlgorithm`

)
specifies the order in which the algorithm searches the points in
the current mesh. The options are

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

— The algorithm polls the mesh points in*consecutive*order, that is, the order of the pattern vectors as described in Poll Method.

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 specify 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. Please
note, if you have selected the same **Search method** and **Poll
method**, only the option selected in the Poll method will
be used, although both will be used when the options selected are
different.

**Complete search** (`UseCompleteSearch`

)
applies when you set **Search method** to ```
GPS
Positive basis Np1
```

, `GPS Positive basis 2N`

, ```
GSS
Positive basis Np1
```

, `GSS Positive basis 2N`

, ```
MADS
Positive basis Np1
```

, `MADS Positive basis 2N`

,
or `Latin hypercube`

. **Complete search** can
have the values **on** (`true`

)
or **off** (`false`

).

For `GPS Positive basis Np1`

, ```
MADS
Positive basis Np1, GPS Positive basis 2N
```

, or ```
MADS
Positive basis 2N
```

, **Complete search** has
the same meaning as the poll option **Complete poll**.

**Search method** (`SearchFcn`

)
specifies the optional search step. The options are

`None`

(`[]`

) (the default) specifies no search step.`GPS Positive basis 2N`

(`'GPSPositiveBasis2N'`

)`GPS Positive basis Np1`

(`'GPSPositiveBasisNp1'`

)`GSS Positive basis 2N`

(`'GSSPositiveBasis2N'`

)`GSS Positive basis Np1`

(`'GSSPositiveBasisNp1'`

)`MADS Positive basis 2N`

(`'MADSPositiveBasis2N'`

)`MADS Positive basis Np1`

(`'MADSPositiveBasisNp1'`

)`Genetic Algorithm`

(`'searchga'`

) specifies a search using the genetic algorithm. If you select`Genetic Algorithm`

, two other options appear:**Iteration limit**— Positive integer specifying the number of iterations of the pattern search for which the genetic algorithm search is performed. The default for**Iteration limit**is 1.**Options**— Options for the genetic algorithm, which you can set using`optimoptions`

.

To change the default values of

**Iteration limit**and**Options**at the command line, use the syntaxoptions = optimoptions('patternsearch','SearchFcn',... {@searchga,iterlim,optionsGA})

where

`iterlim`

is the value of**Iteration limit**and`optionsGA`

is the genetic algorithm options object. If you do not specify any`searchga`

options, then`searchga`

uses the same`UseParallel`

and`UseVectorized`

option settings as`patternsearch`

.### Note

If you set

**Search method**to`Genetic algorithm`

or`Nelder-Mead`

, we recommend that you leave**Iteration limit**set to the default value`1`

, because performing these searches more than once is not likely to improve results.`Latin hypercube`

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

**Complete search**:If you set

**Complete search**to**on**(`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

**Complete search**to**off**(`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.

If you select

`Latin hypercube`

, two other options appear:**Iteration limit**— Positive integer specifying the number of iterations of the pattern search for which the Latin hypercube search is performed. The default for**Iteration limit**is 1.**Design level**— The**Design level**is the number of points`patternsearch`

searches, a positive integer. The default for**Design level**is 15 times the number of dimensions.

To change the default values of

**Iteration limit**and**Design level**at the command line, use the syntaxoptions = optimoptions('patternsearch','SearchFcn', {@searchlhs,iterlim,level})

where

`iterlim`

is the value of**Iteration limit**and`level`

is the value of**Design level**.`Nelder-Mead`

(`'searchneldermead'`

) specifies a search using`fminsearch`

, which uses the Nelder-Mead algorithm. If you select`Nelder-Mead`

, two other options appear:**Iteration limit**— Positive integer specifying the number of iterations of the pattern search for which the Nelder-Mead search is performed. The default for**Iteration limit**is 1.**Options**— Options for the function`fminsearch`

, which you can create using the function`optimset`

.

To change the default values of

**Iteration limit**and**Options**at the command line, use the syntaxoptions = optimoptions('patternsearch','SearchFcn',... {@searchneldermead,iterlim,optionsNM})

where

`iterlim`

is the value of**Iteration limit**and`optionsNM`

is the options for the search function.`Custom`

enables you to write your own search function. To specify the search function using the Optimization app,Set

**Search function**to`Custom`

.Set

**Function name**to`@myfun`

, where`myfun`

is the name of your function.

If you are using

`patternsearch`

at the command line, setoptions = 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.

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 Using a Search Method for an example.

Mesh options control the mesh that the pattern search uses. The following options are available.

**Initial size** (`InitialMeshSize`

)
specifies the size of the initial mesh, which is the length of the
shortest vector from the initial point to a mesh point. **Initial
size** should be a positive scalar. The default is `1.0`

.

**Max size** (`MaxMeshSize`

)
specifies a maximum size for the mesh. When the maximum size is reached,
the mesh size does not increase after a successful iteration. **Max
size** 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`

.

**Accelerator** (`AccelerateMesh`

)
specifies whether, when the mesh size is small, the **Contraction
factor** is multiplied by `0.5`

after each
unsuccessful iteration. **Accelerator** can have
the values `On`

or `Off`

, the default. **Accelerator** applies
to the GPS and GSS algorithms.

**Rotate** (`MeshRotate`

)
is only applied when **Poll method** is set to ```
GPS
Positive basis Np1
```

or `GSS Positive basis Np1`

.
It specifies whether the mesh vectors are multiplied by –1
when the mesh size is less than 1/100 of the mesh tolerance (minimum
mesh size `MeshTolerance`

) 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 –Σ

`Off`

or `On`

(the
default). When the problem has equality constraints, **Rotate** is especially useful for discontinuous
functions.

Changing the setting of **Rotate** has no effect
on the poll when **Poll method** is set to ```
GPS
Positive basis 2N
```

, `GSS Positive basis 2N`

, ```
MADS
Positive basis 2N
```

, or `MADS Positive basis Np1`

.

**Scale** `(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). **Scale** can have
the values `Off`

or `On`

(the default).
When the problem has equality constraints, **Scale** is
disabled.

**Expansion factor **`(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. **Expansion factor** 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 factor of `4.0`

.

**Contraction factor** `(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. **Contraction factor** 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 factor of `0.25`

.

See Mesh Expansion and Contraction for more information.

For information on the meaning of penalty parameters, see Nonlinear Constraint Solver Algorithm.

**Initial penalty**(`InitialPenalty`

) — Specifies an initial value of the penalty parameter that is used by the nonlinear constraint algorithm.**Initial penalty**must be greater than or equal to`1`

, and has a default of`10`

.**Penalty factor**(`PenaltyFactor`

) — Increases the penalty parameter when the problem is not solved to required accuracy and constraints are not satisfied.**Penalty factor**must be greater than`1`

, and has a default of`100`

.

**Bind tolerance** (`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 `Bind tolerance`

specifies when a linear constraint is active. `Bind tolerance`

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

uses for polling or searching. The default
value of `Bind tolerance`

is `1e-3`

.

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, but not for stochastic ones.

**Cache** (`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 **Tolerance** of a point in
the cache.

**Tolerance** (`CacheTol`

)
specifies how close a mesh point must be to a point in the cache for
the algorithm to omit polling it. **Tolerance** must
be a positive scalar. The default value is `eps`

.

**Size** (`CacheSize`

) specifies
the size of the cache. **Size** must be a positive
scalar. The default value is `1e4`

.

See Use Cache for more information.

Stopping criteria determine what causes the pattern search algorithm to stop. Pattern search uses the following criteria:

**Mesh tolerance** (`MeshTolerance`

)
specifies the minimum tolerance for mesh size. The GPS and GSS algorithms
stop if the mesh size becomes smaller than **Mesh tolerance**.
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`

.

**Max iteration** (`MaxIterations`

)
specifies the maximum number of iterations the algorithm performs.
The algorithm stops if the number of iterations reaches **Max
iteration**. You can select either

**100*numberOfVariables**— Maximum number of iterations is 100 times the number of independent variables (the default).**Specify**— A positive integer for the maximum number of iterations

**Max function evaluations** (`MaxFunctionEvaluations`

)
specifies the maximum number of evaluations of the objective function.
The algorithm stops if the number of function evaluations reaches **Max
function evaluations**. You can select either

**2000*numberOfVariables**— Maximum number of function evaluations is 2000 times the number of independent variables.**Specify**— A positive integer for the maximum number of function evaluations

**Time limit** (`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.

**X tolerance** (`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 **X tolerance** and the mesh
size is smaller than **X tolerance**. The default
value is `1e-6`

.

**Function tolerance** (`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 **Function
tolerance**, and if the mesh size is also smaller than **X
tolerance**. The default value is `1e-6`

.

See Setting Solver Tolerances for an example.

**Constraint tolerance** (`ConstraintTolerance`

)
— The **Constraint tolerance** is not used
as stopping criterion. It is used to determine the feasibility with
respect to nonlinear constraints.

Output functions are functions that the pattern search algorithm calls at each generation. To specify the output function using the Optimization app,

Select

**Custom function**.Enter

`@myfun`

in the text box, where`myfun`

is the name of your function. Write`myfun`

with appropriate syntax.To pass extra parameters in the output function, use Anonymous Functions (Optimization Toolbox).

For multiple output functions, enter a cell array of output function handles:

`{@myfun1,@myfun2,...}`

.

At the command line, 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.

Your output function must have the following calling syntax:

[stop,options,optchanged] = myfun(optimvalues,options,flag)

MATLAB passes the `optimvalues`

, `state`

,
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 (Optimization Toolbox) 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`

.

**Level of display** (`'Display'`

)
specifies how much information is displayed at the command line while
the pattern search is running. The available options are

`Off`

(`'off'`

) — No output is displayed.`Iterative`

(`'iter'`

) — Information is displayed for each iteration.`Diagnose`

(`'diagnose'`

) — Information is displayed for each iteration. In addition, the diagnostic lists some problem information and the options that are changed from the defaults.`Final`

(`'final'`

) — The reason for stopping is displayed.

Both `Iterative`

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)

The default value of **Level of display** is

`Off`

in the Optimization app`'final'`

in options created using`optimoptions`

You can choose to have your objective and constraint functions
evaluated in serial, parallel, or in a vectorized fashion. These options
are available in the **User function evaluation** section
of the **Options** pane of the Optimization app,
or by setting the `'UseVectorized'`

and `'UseParallel'`

options
with `optimoptions`

.

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

**Evaluate objective and constraint functions**(`'UseVectorized'`

) is**in serial**(`false`

),`patternsearch`

calls the objective function on one point at a time as it loops through the mesh points. (At the command line, this assumes`'UseParallel'`

is at its default value of`false`

.)When

**Evaluate objective and constraint functions**(`'UseVectorized'`

) is**vectorized**(`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

**Evaluate objective and constraint functions**(`'UseParallel'`

) is**in parallel**(`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.

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 |

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

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