This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English version of the page.

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.

Pattern Search Options

Optimization App vs. Command Line

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

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 (PlotInterval) specifies the number of iterations between consecutive calls to the plot function.

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.

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:

  • 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

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

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

  • The default pattern for patternsearch, GPS Positive basis 2N ('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 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 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 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.

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

OptionDefinitionAllowed and {Default} Values
ParetoSetSizeNumber of points in the Pareto set.Positive integer | {max(60,number of objectives) }
ParetoSetChangeToleranceTolerance 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}
MinPollFractionMinimum 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

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 syntax

    options = 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 syntax

    options = 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 syntax

    options = 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, set

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

Mesh Options

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 ei (unit positive directions) and –Σei, the algorithm polls in directions –ei and Σei. Rotate can have the values Off or On (the default). When the problem has equality constraints, Rotate is disabled.

Rotate is especially useful for discontinuous functions.

Note

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.

Constraint Parameters

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.

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

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 Function Options

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.

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

  • optionspatternsearch options.

  • optchanged — Boolean flag indicating changes to options. To change options for subsequent iterations, set optchanged to true.

Display to Command Window Options

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

Vectorized and Parallel Options (User Function Evaluation)

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.

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.

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

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 = trueUseVectorized = falseUseVectorized = true
UseParallel = falseSerialVectorized
UseParallel = trueParallelVectorized

Options Table for Pattern Search Algorithms

Option Availability Table for All Algorithms

OptionDescriptionAlgorithm Availability
AccelerateMesh

Accelerate mesh size contraction.

GPS and GSS

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.

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