Documentation

patternsearch

Find minimum of function using pattern search

Syntax

  • x = patternsearch(fun,x0)
    example
  • x = patternsearch(fun,x0,A,b)
    example
  • x = patternsearch(fun,x0,A,b,Aeq,beq)
  • x = patternsearch(fun,x0,A,b,Aeq,beq,lb,ub)
    example
  • x = patternsearch(fun,x0,A,b,Aeq,beq,lb,ub,nonlcon)
    example
  • x = patternsearch(fun,x0,A,b,Aeq,beq,lb,ub,nonlcon,options)
    example
  • x = patternsearch(problem)
  • [x,fval] = patternsearch(___)
    example
  • [x,fval,exitflag,output] = patternsearch(___)
    example

Description

example

x = patternsearch(fun,x0) finds a local minimum, x, to the function handle fun that computes the values of the objective function. x0 is a real vector specifying an initial point for the pattern search algorithm.

    Note:   Passing Extra Parameters explains how to pass extra parameters to the objective function and nonlinear constraint functions, if necessary.

example

x = patternsearch(fun,x0,A,b) minimizes fun subject to the linear inequalities A*x ≤ b. See Linear Inequality Constraints.

x = patternsearch(fun,x0,A,b,Aeq,beq) minimizes fun subject to the linear equalities Aeq*x = beq and A*x ≤ b. If no linear inequalities exist, set A = [] and b = [].

example

x = patternsearch(fun,x0,A,b,Aeq,beq,lb,ub) defines a set of lower and upper bounds on the design variables in x, so that the solution is always in the range lb  x  ub. If no linear equalities exist, set Aeq = [] and beq = []. If x(i) has no lower bound, set lb(i) = -Inf. If x(i) has no upper bound, set ub(i) = Inf.

example

x = patternsearch(fun,x0,A,b,Aeq,beq,lb,ub,nonlcon) subjects the minimization to the nonlinear inequalities c(x) or equalities ceq(x) defined in nonlcon. patternsearch optimizes fun such that c(x) ≤ 0 and ceq(x) = 0. If no bounds exist, set lb = [], ub = [], or both.

example

x = patternsearch(fun,x0,A,b,Aeq,beq,lb,ub,nonlcon,options) minimizes fun with the optimization options specified in options. Use psoptimset to set these options. If there are no nonlinear inequality or equality constraints, set nonlcon = [].

x = patternsearch(problem) finds the minimum for problem, where problem is a structure described in Input Arguments. Create the problem structure by exporting a problem from Optimization app, as described in Exporting Your Work.

example

[x,fval] = patternsearch(___), for any syntax, returns the value of the objective function fun at the solution x.

example

[x,fval,exitflag,output] = patternsearch(___) additionally returns exitflag, a value that describes the exit condition of patternsearch, and a structure output with information about the optimization process.

Examples

collapse all

Unconstrained Pattern Search Minimization

Minimize an unconstrained problem using the patternsearch solver.

Create the following two-variable objective function. On your MATLAB® path, save the following code to a file named psobj.m.

function y = psobj(x)

y = exp(-x(1)^2-x(2)^2)*(1+5*x(1) + 6*x(2) + 12*x(1)*cos(x(2)));

Set the objective function to @psobj.

fun = @psobj;

Find the minimum, starting at the point [0,0].

x0 = [0,0];
x = patternsearch(fun,x0)
Optimization terminated: mesh size less than options.TolMesh.

x =

   -0.7037   -0.1860

Pattern Search with a Linear Inequality Constraint

Minimize a function subject to some linear inequality constraints.

Create the following two-variable objective function. On your MATLAB path, save the following code to a file named psobj.m.

function y = psobj(x)

y = exp(-x(1)^2-x(2)^2)*(1+5*x(1) + 6*x(2) + 12*x(1)*cos(x(2)));

Set the objective function to @psobj.

fun = @psobj;

Set the two linear inequality constraints.

A = [-3,-2;
    -4,-7];
b = [-1;-8];

Find the minimum, starting at the point [0.5,-0.5].

x0 = [0.5,-0.5];
x = patternsearch(fun,x0,A,b)
Optimization terminated: mesh size less than options.TolMesh.

x =

    5.2824   -1.8758

Pattern Search with Bounds

Find the minimum of a function that has only bound constraints.

Create the following two-variable objective function. On your MATLAB path, save the following code to a file named psobj.m.

function y = psobj(x)

y = exp(-x(1)^2-x(2)^2)*(1+5*x(1) + 6*x(2) + 12*x(1)*cos(x(2)));

Set the objective function to @psobj.

fun = @psobj;

Find the minimum when 0 ≤ x(1) ≤ ∞ and –∞ ≤ x(2) ≤ –3.

lb = [0,-Inf];
ub = [Inf,-3];
A = [];
b = [];
Aeq = [];
beq = [];

Find the minimum, starting at the point [1,-5].

x0 = [1,-5];
x = patternsearch(fun,x0,A,b,Aeq,beq,lb,ub)
Optimization terminated: mesh size less than options.TolMesh.

x =

    0.1880   -3.0000

Pattern Search with Nonlinear Constraints

Find the minimum of a function subject to a nonlinear inequality constraint.

Create the following two-variable objective function. On your MATLAB path, save the following code to a file named psobj.m.

function y = psobj(x)

y = exp(-x(1)^2-x(2)^2)*(1+5*x(1) + 6*x(2) + 12*x(1)*cos(x(2)));

Set the objective function to @psobj.

fun = @psobj;

Create the nonlinear constraint

xy2+(x+2)2+(y2)222.

To do so, on your MATLAB path, save the following code to a file named ellipsetilt.m.

function [c,ceq] = ellipsetilt(x)
ceq = [];
c = x(1)*x(2)/2 + (x(1)+2)^2 + (x(2)-2)^2/2 - 2;

Start patternsearch from the initial point [-2,-2].

x0 = [-2,-2];
A = [];
b = [];
Aeq = [];
beq = [];
lb = [];
ub = [];
nonlcon = @ellipsetilt;
x = patternsearch(fun,x0,A,b,Aeq,beq,lb,ub,nonlcon)
Optimization terminated: mesh size less than options.TolMesh
 and constraint violation is less than options.TolCon.

x =

   -1.5144    0.0874

Pattern Search with Nondefault Options

Set options to observe the progress of the patternsearch solution process.

Create the following two-variable objective function. On your MATLAB path, save the following code to a file named psobj.m.

function y = psobj(x)

y = exp(-x(1)^2-x(2)^2)*(1+5*x(1) + 6*x(2) + 12*x(1)*cos(x(2)));

Set the objective function to @psobj.

fun = @psobj;

Set options to give iterative display and to plot the objective function at each iteration.

options = psoptimset('Display','iter','PlotFcns',@psplotbestf);

Find the unconstrained minimum of the objective starting from the point [0,0].

x0 = [0,0];
A = [];
b = [];
Aeq = [];
beq = [];
lb = [];
ub = [];
nonlcon = [];
x = patternsearch(fun,x0,A,b,Aeq,beq,lb,ub,nonlcon,options)

Iter     f-count          f(x)      MeshSize     Method
    0        1              1             1      
    1        4       -5.88607             2     Successful Poll
    2        8       -5.88607             1     Refine Mesh
    3       12       -5.88607           0.5     Refine Mesh
    4       16       -5.88607          0.25     Refine Mesh

(output trimmed)

   63      218       -7.02545     1.907e-06     Refine Mesh
   64      221       -7.02545     3.815e-06     Successful Poll
   65      225       -7.02545     1.907e-06     Refine Mesh
   66      229       -7.02545     9.537e-07     Refine Mesh
Optimization terminated: mesh size less than options.TolMesh.

x =

   -0.7037   -0.1860

Obtain Function Value And Minimizing Point

Find a minimum value of a function and report both the location and value of the minimum.

Create the following two-variable objective function. On your MATLAB path, save the following code to a file named psobj.m.

function y = psobj(x)

y = exp(-x(1)^2-x(2)^2)*(1+5*x(1) + 6*x(2) + 12*x(1)*cos(x(2)));

Set the objective function to @psobj.

fun = @psobj;

Find the unconstrained minimum of the objective, starting from the point [0,0]. Return both the location of the minimum, x, and the value of fun(x).

x0 = [0,0];
[x,fval] = patternsearch(fun,x0)
Optimization terminated: mesh size less than options.TolMesh.

x =

   -0.7037   -0.1860


fval =

   -7.0254

Obtain All Outputs

To examine the patternsearch solution process, obtain all outputs.

Create the following two-variable objective function. On your MATLAB path, save the following code to a file named psobj.m.

function y = psobj(x)

y = exp(-x(1)^2-x(2)^2)*(1+5*x(1) + 6*x(2) + 12*x(1)*cos(x(2)));

Set the objective function to @psobj.

fun = @psobj;

Find the unconstrained minimum of the objective, starting from the point [0,0]. Return the solution, x, the objective function value at the solution, fun(x), the exit flag, and the output structure.

x0 = [0,0];
[x,fval,exitflag,output] = patternsearch(fun,x0)
Optimization terminated: mesh size less than options.TolMesh.

x =

   -0.7037   -0.1860


fval =

   -7.0254


exitflag =

     1


output = 

         function: @psobj
      problemtype: 'unconstrained'
       pollmethod: 'gpspositivebasis2n'
    maxconstraint: []
     searchmethod: []
       iterations: 66
        funccount: 229
         meshsize: 9.5367e-07
         rngstate: [1x1 struct]
          message: 'Optimization terminated: mesh size less than options.TolMesh.'

The exitflag is 1, indicating convergence to a local minimum.

The output structure includes information such as how many iterations patternsearch took, and how many function evaluations. Compare this output structure with the results from Pattern Search with Nondefault Options. In that example, you obtain some of this information, but did not obtain, for example, the number of function evaluations.

Related Examples

Input Arguments

collapse all

fun — Function to be minimizedfunction handle | function name

Function to be minimized, specified as a function handle or function name. The fun function accepts a vector x and returns a real scalar f, which is the objective function evaluated at x.

You can specify fun as a function handle for a file

x = patternsearch(@myfun,x0)

Here, myfun is a MATLAB function such as

function f = myfun(x)
f = ...            % Compute function value at x

fun can also be a function handle for an anonymous function

x = patternsearch(@(x)norm(x)^2,x0,A,b);

Example: fun = @(x)sin(x(1))*cos(x(2))

Data Types: char | function_handle

x0 — Initial pointreal vector

Initial point, specified as a real vector. patternsearch uses the number of elements in x0 to determine the number of variables that fun accepts.

Example: x0 = [1,2,3,4]

Data Types: double

A — Linear inequality constraintsreal matrix

Linear inequality constraints, specified as a real matrix. A is an M-by-N matrix, where M is the number of inequalities, and N is the number of variables (number of elements in x0).

A encodes the M linear inequalities

A*x <= b,

where x is the column vector of N variables x(:), and b is a column vector with M elements.

For example, to specify

x1 + 2x2 ≤ 10
3x1 + 4x2 ≤ 20
5x1 + 6x2 ≤ 30,

give these constraints:

A = [1,2;3,4;5,6];
b = [10;20;30];

Example: To specify that the control variables sum to 1 or less, give the constraints A = ones(1,N) and b = 1

Data Types: double

b — Linear inequality constraintsreal vector

Linear inequality constraints, specified as a real vector. b is an M-element vector related to the A matrix. If you pass b as a row vector, solvers internally convert b to the column vector b(:).

b encodes the M linear inequalities

A*x <= b,

where x is the column vector of N variables x(:), and A is a matrix of size M-by-N.

For example, to specify

x1 + 2x2 ≤ 10
3x1 + 4x2 ≤ 20
5x1 + 6x2 ≤ 30,

give these constraints:

A = [1,2;3,4;5,6];
b = [10;20;30];

Example: To specify that the control variables sum to 1 or less, give the constraints A = ones(1,N) and b = 1

Data Types: double

Aeq — Linear equality constraintsreal matrix

Linear equality constraints, specified as a real matrix. Aeq is an Me-by-N matrix, where Me is the number of equalities, and N is the number of variables (number of elements in x0).

Aeq encodes the Me linear equalities

Aeq*x = beq,

where x is the column vector of N variables x(:), and beq is a column vector with Me elements.

For example, to specify

x1 + 2x2 + 3x3 ≤ 10
2x1 + 4x2 + x3 ≤ 20,

give these constraints:

A = [1,2,3;2,4,1];
b = [10;20];

Example: To specify that the control variables sum to 1, give the constraints Aeq = ones(1,N) and beq = 1

Data Types: double

beq — Linear equality constraintsreal vector

Linear equality constraints, specified as a real vector. beq is an Me-element vector related to the Aeq matrix. If you pass beq as a row vector, solvers internally convert beq to the column vector beq(:).

beq encodes the Me linear equalities

Aeq*x = beq,

where x is the column vector of N variables x(:), and Aeq is a matrix of size Meq-by-N.

For example, to specify

x1 + 2x2 + 3x3 ≤ 10
2x1 + 4x2 + x3 ≤ 20,

give these constraints:

A = [1,2,3;2,4,1];
b = [10;20];

Example: To specify that the control variables sum to 1, give the constraints Aeq = ones(1,N) and beq = 1

Data Types: double

lb — Lower boundsreal vector | real array

Lower bounds, specified as a real vector or real array. If the number of elements in x0 is equal to that of lb, then lb specifies that

x(i) >= lb(i)

for all i.

If numel(lb) < numel(x0), then lb specifies that

x(i) >= lb(i)

for

1 <= i <= numel(lb)

In this case, solvers issue a warning.

Example: To specify that all control variables are positive, lb = zeros(size(x0))

Data Types: double

ub — Upper boundsreal vector | real array

Upper bounds, specified as a real vector or real array. If the number of elements in x0 is equal to that of ub, then ub specifies that

x(i) <= ub(i)

for all i.

If numel(ub) < numel(x0), then ub specifies that

x(i) <= ub(i)

for

1 <= i <= numel(ub)

In this case, solvers issue a warning.

Example: To specify that all control variables are less than one, ub = ones(size(x0))

Data Types: double

nonlcon — Nonlinear constraintsfunction handle | function name

Nonlinear constraints, specified as a function handle or function name. nonlcon is a function that accepts a vector or array x and returns two arrays, c(x) and ceq(x).

  • c(x) is the array of nonlinear inequality constraints at x. patternsearch attempts to satisfy

    c(x) <= 0

    for all entries of c.

  • ceq(x) is the array of nonlinear equality constraints at x. patternsearch attempts to satisfy

    ceq(x) = 0

    for all entries of ceq.

For example,

x = patternsearch(@myfun,x0,A,b,Aeq,beq,lb,ub,@mycon)

where mycon is a MATLAB function such as

function [c,ceq] = mycon(x)
c = ...     % Compute nonlinear inequalities at x.
ceq = ...   % Compute nonlinear equalities at x.
For more information, see Nonlinear Constraints .

Data Types: char | function_handle

options — Optimization optionsstructure such as the one returned by psoptimset

Optimization options, specified as a structure such as the one returned by psoptimset. For details, see Pattern Search Options.

OptionDescriptionValues
Cache

With Cache set to 'on', patternsearch keeps a history of the mesh points it polls. At subsequent iterations, patternsearch does not poll points close to those it already polled. Use this option if patternsearch runs slowly while computing the objective function. If the objective function is stochastic, do not to use this option.

'on' | {'off'}
CacheSize

Size of the history.

Positive scalar | {1e4}

CacheTol

Largest distance from the current mesh point to any point in the history in order for patternsearch to avoid polling the current point. Use if 'Cache' option is set to 'on'.

Positive scalar | {eps}

CompletePoll

Complete poll around current point. See How Pattern Search Polling Works.

'on' | {'off'}
CompleteSearch

Complete search around current point when the search method is a poll method. See Searching and Polling.

'on' | {'off'}
Display

Level of display.

'off' | 'iter' | 'diagnose' | {'final'}
InitialMeshSize

Initial mesh size for pattern algorithm. See How Pattern Search Polling Works.

Positive scalar | {1.0}

InitialPenalty

Initial value of the penalty parameter. See Nonlinear Constraint Solver Algorithm.

Positive scalar | {10}

MaxFunEvals

Maximum number of objective function evaluations.

Positive integer | {2000*numberOfVariables}

MaxIter

Maximum number of iterations.

Positive integer | {100*numberOfVariables}

MaxMeshSize

Maximum mesh size used in a poll or search step. See How Pattern Search Polling Works.

Positive scalar | {Inf}

MeshAccelerator

Accelerate convergence near a minimum. patternsearch contracts by an extra factor of 1/2.

'on' | {'off'}
MeshContraction

Mesh contraction factor for unsuccessful iteration.

Positive scalar | {0.5}
MeshExpansion

Mesh expansion factor for successful iteration.

Positive scalar | {2.0}

MeshRotate

Rotate the pattern before declaring a point to be optimum. See Mesh Options.

'off' | {'on'}
OutputFcns

Specifies a user-defined function that an optimization function calls at each iteration.

Function handle or cell array of function handles | {[]}

PenaltyFactor

Penalty update parameter. See Nonlinear Constraint Solver Algorithm.

Positive scalar | {100}

PlotFcns

Specifies plots of output from the pattern search.

{[]} | @psplotbestf | @psplotmeshsize | @psplotfuncount | @psplotbestx | custom plot function

PlotInterval

Specifies that plot functions will be called at every interval.

{1} | positive integer

PollingOrder

Order of poll directions in pattern search .

'Random' | 'Success' | {'Consecutive'}

PollMethod

Polling strategy used in pattern search.

{'GPSPositiveBasis2N'} | 'GPSPositiveBasisNp1' | 'GSSPositiveBasis2N' | 'GSSPositiveBasisNp1' | 'MADSPositiveBasis2N' | 'MADSPositiveBasisNp1'

ScaleMesh

Automatic scaling of variables.

{'on'} | 'off'
SearchMethod

Type of search used in pattern search.

{[]} | @GPSPositiveBasis2N | @GPSPositiveBasisNp1 | @GSSPositiveBasis2N | @GSSPositiveBasisNp1 | @MADSPositiveBasis2N | @MADSPositiveBasisNp1 | @searchga | @searchlhs | @searchneldermead | custom search function
TimeLimit

Total time (in seconds) allowed for optimization.

Positive scalar | {Inf}

TolBind

Binding tolerance. See Constraint Parameters.

Positive scalar | {1e-3}

TolCon

Tolerance on constraints.

Positive scalar | {1e-6}

TolFun

Tolerance on function. Iterations stop if the change in function value is less than TolFun and the mesh size is less than TolX. Does not apply to MADS polling.

Positive scalar | {1e-6}

TolMesh

Tolerance on mesh size.

Positive scalar | {1e-6}

TolX

Tolerance on variable. Iterations stop if both the change in position and the mesh size are less than TolX. Does not apply to MADS polling.

Positive scalar | {1e-6}

UseParallel

Compute objective and nonlinear constraint functions in parallel. See Vectorize and Parallel Options (User Function Evaluation) and How to Use Parallel Processing.

true | {false}

Vectorized

Specifies whether functions are vectorized. See Vectorize and Parallel Options (User Function Evaluation) and Vectorize the Objective and Constraint Functions.

'on' | {'off'}

Example: options = psoptimset('MaxIter',150,'TolMesh',1e-4)

Data Types: struct

problem — Problem structurestructure

Problem structure, specified as a structure with the following fields:

  • objective — Objective function

  • x0 — Starting point

  • Aineq — Matrix for linear inequality constraints

  • bineq — Vector for linear inequality constraints

  • Aeq — Matrix for linear equality constraints

  • beq — Vector for linear equality constraints

  • lb — Lower bound for x

  • ub — Upper bound for x

  • nonlcon — Nonlinear constraint function

  • solver'patternsearch'

  • options — Options structure created with psoptimset

  • rngstate — Optional field to reset the state of the random number generator

Create the structure problem by exporting a problem from the Optimization app, as described in Importing and Exporting Your Work.

    Note   All fields in problem are required.

Data Types: struct

Output Arguments

collapse all

x — Solutionreal vector

Solution, returned as a real vector. The size of x is the same as the size of x0. When exitflag is positive, x is typically a local solution to the problem.

fval — Objective function value at the solutionreal number

Objective function value at the solution, returned as a real number. Generally, fval = fun(x).

exitflag — Reason patternsearch stoppedinteger

Reason patternsearch stopped, returned as an integer.

Exit FlagMeaning

1

Without nonlinear constraints — The magnitude of the mesh size is less than the specified tolerance, and the constraint violation is less than TolCon.

With nonlinear constraints — The magnitude of the complementarity measure (defined after this table) is less than sqrt(TolCon), the subproblem is solved using a mesh finer than TolMesh, and the constraint violation is less than TolCon.

2

The change in x and the mesh size are both less than the specified tolerance, and the constraint violation is less than TolCon.

3

The change in fval and the mesh size are both less than the specified tolerance, and the constraint violation is less than TolCon.

4

The magnitude of the step is smaller than machine precision, and the constraint violation is less than TolCon.

0

The maximum number of function evaluations or iterations is reached.

-1

Optimization terminated by an output function or plot function.

-2

No feasible point found.

In the nonlinear constraint solver, the complementarity measure is the norm of the vector whose elements are ciλi, where ci is the nonlinear inequality constraint violation, and λi is the corresponding Lagrange multiplier.

output — Information about the optimization processstructure

Information about the optimization process, returned as a structure with these fields:

  • function — Objective function.

  • problemtype — String describing the type of problem:

    • 'unconstrained'

    • 'boundconstraints'

    • 'linearconstraints'

    • 'nonlinearconstr'

  • pollmethod — Polling technique.

  • searchmethod — Search technique used, if any.

  • iterations — Total number of iterations.

  • funccount — Total number of function evaluations.

  • meshsize — Mesh size at x.

  • maxconstraint — Maximum constraint violation, if any.

  • rngstate — State of the MATLAB random number generator, just before the algorithm started. You can use the values in rngstate to reproduce the output when you use a random search method or random poll method. See Reproduce Results, which discusses the identical technique for ga.

  • message — Reason why the algorithm terminated.

More About

expand all

Algorithms

By default, patternsearch looks for a minimum based on an adaptive mesh that, in the absence of linear constraints, is aligned with the coordinate directions. See What Is Direct Search? and How Pattern Search Polling Works.

References

[1] Audet, Charles, and J. E. Dennis Jr. "Analysis of Generalized Pattern Searches." SIAM Journal on Optimization. Volume 13, Number 3, 2003, pp. 889–903.

[2] Conn, A. R., N. I. M. Gould, and Ph. L. Toint. "A Globally Convergent Augmented Lagrangian Barrier Algorithm for Optimization with General Inequality Constraints and Simple Bounds." Mathematics of Computation. Volume 66, Number 217, 1997, pp. 261–288.

[3] Abramson, Mark A. Pattern Search Filter Algorithms for Mixed Variable General Constrained Optimization Problems. Ph.D. Thesis, Department of Computational and Applied Mathematics, Rice University, August 2002.

[4] Abramson, Mark A., Charles Audet, J. E. Dennis, Jr., and Sebastien Le Digabel. "ORTHOMADS: A deterministic MADS instance with orthogonal directions." SIAM Journal on Optimization. Volume 20, Number 2, 2009, pp. 948–966.

[5] Kolda, Tamara G., Robert Michael Lewis, and Virginia Torczon. "Optimization by direct search: new perspectives on some classical and modern methods." SIAM Review. Volume 45, Issue 3, 2003, pp. 385–482.

[6] Kolda, Tamara G., Robert Michael Lewis, and Virginia Torczon. "A generating set direct search augmented Lagrangian algorithm for optimization with a combination of general and linear constraints." Technical Report SAND2006-5315, Sandia National Laboratories, August 2006.

[7] Lewis, Robert Michael, Anne Shepherd, and Virginia Torczon. "Implementing generating set search methods for linearly constrained minimization." SIAM Journal on Scientific Computing. Volume 29, Issue 6, 2007, pp. 2507–2530.

See Also

|

Introduced before R2006a

Was this topic helpful?