Main Content

particleswarm

Particle swarm optimization

Description

example

x = particleswarm(fun,nvars) attempts to find a vector x that achieves a local minimum of fun. nvars is the dimension (number of design variables) of fun.

Note

Passing Extra Parameters explains how to pass extra parameters to the objective function, if necessary.

example

x = particleswarm(fun,nvars,lb,ub) defines a set of lower and upper bounds on the design variables, x, so that a solution is found in the range lb  x  ub.

example

x = particleswarm(fun,nvars,lb,ub,options) minimizes with the default optimization parameters replaced by values in options. Set lb = [] and ub = [] if no bounds exist.

x = particleswarm(problem) finds the minimum for problem, a structure described in problem.

example

[x,fval,exitflag,output,points] = particleswarm(___) also returns the following, using any of the input argument combinations in the previous syntaxes:

  • fval, a scalar that is the objective function value fun(x)

  • exitflag, a value that describes the exit condition

  • output, a structure that contains information about the optimization process

  • points, a structure that contains the final swarm positions in points.X and the associated objective function values in points.Fval

Examples

collapse all

Minimize a simple function of two variables.

Define the objective function.

fun = @(x)x(1)*exp(-norm(x)^2);

Call particleswarm to minimize the function.

rng default  % For reproducibility
nvars = 2;
x = particleswarm(fun,nvars)
Optimization ended: relative change in the objective value 
over the last OPTIONS.MaxStallIterations iterations is less than OPTIONS.FunctionTolerance.

x =

  629.4474  311.4814

This solution is far from the true minimum, as you see in a function plot.

fsurf(@(x,y)x.*exp(-(x.^2+y.^2)))

Usually, it is best to set bounds. See Minimize a Simple Function with Bounds.

Minimize a simple function of two variables with bound constraints.

Define the objective function.

fun = @(x)x(1)*exp(-norm(x)^2);

Set bounds on the variables.

lb = [-10,-15];
ub = [15,20];

Call particleswarm to minimize the function.

rng default  % For reproducibility
nvars = 2;
x = particleswarm(fun,nvars,lb,ub)
Optimization ended: relative change in the objective value 
over the last OPTIONS.MaxStallIterations iterations is less than OPTIONS.FunctionTolerance.
x = 1×2

   -0.7071   -0.0000

Use a larger population and a hybrid function to try to get a better solution.

Specify the objective function and bounds.

fun = @(x)x(1)*exp(-norm(x)^2);
lb = [-10,-15];
ub = [15,20];

Specify the options.

options = optimoptions('particleswarm','SwarmSize',100,'HybridFcn',@fmincon);

Call particleswarm to minimize the function.

rng default  % For reproducibility
nvars = 2;
x = particleswarm(fun,nvars,lb,ub,options)
Optimization ended: relative change in the objective value 
over the last OPTIONS.MaxStallIterations iterations is less than OPTIONS.FunctionTolerance.
x = 1×2

   -0.7071   -0.0000

Return the optional output arguments to examine the solution process in more detail.

Define the problem.

fun = @(x)x(1)*exp(-norm(x)^2);
lb = [-10,-15];
ub = [15,20];
options = optimoptions('particleswarm','SwarmSize',50,'HybridFcn',@fmincon);

Call particleswarm with all outputs to minimize the function and get information about the solution process.

rng default  % For reproducibility
nvars = 2;
[x,fval,exitflag,output,points] = particleswarm(fun,nvars,lb,ub,options)
Optimization ended: relative change in the objective value 
over the last OPTIONS.MaxStallIterations iterations is less than OPTIONS.FunctionTolerance.
x = 1×2

   -0.7071   -0.0000

fval = -0.4289
exitflag = 1
output = struct with fields:
      rngstate: [1x1 struct]
    iterations: 43
     funccount: 2203
       message: 'Optimization ended: relative change in the objective value ...'
    hybridflag: 1

points = struct with fields:
       X: [50x2 double]
    Fval: [50x1 double]

Input Arguments

collapse all

Objective function, specified as a function handle or function name. Write the objective function to accept a row vector of length nvars and return a scalar value.

When the 'UseVectorized' option is true, write fun to accept a pop-by-nvars matrix, where pop is the current population size. In this case, fun returns a vector the same length as pop containing the fitness function values. Ensure that fun does not assume any particular size for pop, since particleswarm can pass a single member of a population even in a vectorized calculation.

Example: fun = @(x)(x-[4,2]).^2

Data Types: char | function_handle | string

Number of variables, specified as a positive integer. The solver passes row vectors of length nvars to fun.

Example: 4

Data Types: double

Lower bounds, specified as a real vector or array of doubles. lb represents the lower bounds element-wise in lb  x  ub.

Internally, particleswarm converts an array lb to the vector lb(:).

Example: lb = [0;-Inf;4] means x(1) ≥ 0, x(3) ≥ 4.

Data Types: double

Upper bounds, specified as a real vector or array of doubles. ub represents the upper bounds element-wise in lb  x  ub.

Internally, particleswarm converts an array ub to the vector ub(:).

Example: ub = [Inf;4;10] means x(2) ≤ 4, x(3) ≤ 10.

Data Types: double

Options for particleswarm, specified as the output of the optimoptions function.

Some options are absent from the optimoptions display. These options are listed in italics. For details, see View Optimization Options.

CreationFcn

Function that creates the initial swarm. Specify as 'pswcreationuniform' or a function handle. Default is 'pswcreationuniform'. See Swarm Creation.

Display

Level of display returned to the command line.

  • 'off' or 'none' displays no output.

  • 'final' displays just the final output (default).

  • 'iter' gives iterative display.

DisplayIntervalInterval for iterative display. The iterative display prints one line for every DisplayInterval iterations. Default is 1.
FunctionToleranceNonnegative scalar with default 1e-6. Iterations end when the relative change in best objective function value over the last MaxStallIterations iterations is less than options.FunctionTolerance.
FunValCheck

Check whether objective function and constraints values are valid. 'on' displays an error when the objective function or constraints return a value that is complex, Inf, or NaN. The default, 'off', displays no error.

HybridFcn

Function that continues the optimization after particleswarm terminates. Specify as a name or a function handle. Possible values:

  • 'fmincon'

  • 'fminsearch'

  • 'fminunc'

  • 'patternsearch'

Can also be a cell array specifying the hybrid function and its options, such as {@fmincon,fminconopts}. Default is []. See Hybrid Function.

See When to Use a Hybrid Function.

InertiaRangeTwo-element real vector with same sign values in increasing order. Gives the lower and upper bound of the adaptive inertia. To obtain a constant (nonadaptive) inertia, set both elements of InertiaRange to the same value. Default is [0.1,1.1]. See Particle Swarm Optimization Algorithm.
InitialPoints

Initial population or partial population of particles, specified as a matrix or a structure.

  • A matrix has size M-by-nvars. Each row represents one particle. If M < SwarmSize, then particleswarm creates more particles so that the total number is SwarmSize. If M > SwarmSize, then particleswarm uses the first SwarmSize rows.

  • A structure must have the field X, which represents the matrix of initial points.

  • If the structure has more than one field, the structure must include the field Fval, which contains a vector of objective function values for the points InitialPoints.X.

InitialSwarmSpan

Initial range of particle positions that @pswcreationuniform creates. Can be a positive scalar or a vector with nvars elements, where nvars is the number of variables. The range for any particle component is -InitialSwarmSpan/2,InitialSwarmSpan/2, shifted and scaled if necessary to match any bounds. Default is 2000.

InitialSwarmSpan also affects the range of initial particle velocities. See Initialization.

MaxIterationsMaximum number of iterations particleswarm takes. Default is 200*nvars, where nvars is the number of variables.
MaxStallIterationsPositive integer with default 20. Iterations end when the relative change in best objective function value over the last MaxStallIterations iterations is less than options.FunctionTolerance.
MaxStallTimeMaximum number of seconds without an improvement in the best known objective function value. Positive scalar with default Inf.
MaxTimeMaximum time in seconds that particleswarm runs. Default is Inf.
MinNeighborsFractionMinimum adaptive neighborhood size, a scalar from 0 to 1. Default is 0.25. See Particle Swarm Optimization Algorithm.
ObjectiveLimitMinimum objective value, a stopping criterion. Scalar, with default -Inf.
OutputFcnFunction handle or cell array of function handles. Output functions can read iterative data, and stop the solver. Default is []. See Output Function and Plot Function.
PlotFcnFunction name, function handle, or cell array of function handles. For custom plot functions, pass function handles. Plot functions can read iterative data, plot each iteration, and stop the solver. Default is []. Available built-in plot function: 'pswplotbestf'. See Output Function and Plot Function.
SelfAdjustmentWeightWeighting of each particle’s best position when adjusting velocity. Finite scalar with default 1.49. See Particle Swarm Optimization Algorithm.
SocialAdjustmentWeightWeighting of the neighborhood’s best position when adjusting velocity. Finite scalar with default 1.49. See Particle Swarm Optimization Algorithm.
SwarmSizeNumber of particles in the swarm, an integer greater than 1. Default is min(100,10*nvars), where nvars is the number of variables.
UseParallelCompute objective function in parallel when true. Default is false. See Parallel or Vectorized Function Evaluation.
UseVectorizedCompute objective function in vectorized fashion when true. Default is false. See Parallel or Vectorized Function Evaluation.

Optimization problem, specified as a structure with the following fields.

solver'particleswarm'
objectiveFunction handle to the objective function, or name of the objective function.
nvarsNumber of variables in problem.
lbVector or array of lower bounds.
ubVector or array of upper bounds.
optionsOptions created by optimoptions.
rngstateOptional state of the random number generator at the beginning of the solution process.

Data Types: struct

Output Arguments

collapse all

Solution, returned as a real vector that minimizes the objective function subject to any bound constraints.

Objective value, returned as the real scalar fun(x).

Algorithm stopping condition, returned as an integer identifying the reason the algorithm stopped. The following lists the values of exitflag and the corresponding reasons particleswarm stopped.

1

Relative change in the objective value over the last options.MaxStallIterations iterations is less than options.FunctionTolerance.

0

Number of iterations exceeded options.MaxIterations.

-1

Iterations stopped by output function or plot function.

-2

Bounds are inconsistent: for some i, lb(i) > ub(i).

-3

Best objective function value is below options.ObjectiveLimit.

-4

Best objective function value did not change within options.MaxStallTime seconds.

-5

Run time exceeded options.MaxTime seconds.

Solution process summary, returned as a structure containing information about the optimization process.

iterations

Number of solver iterations

funccount

Number of objective function evaluations.

message

Reason the algorithm stopped.

hybridflag

Exit flag from the hybrid function. Relates to the HybridFcn options.

rngstate

State of the default random number generator just before the algorithm started.

Final swarm positions and objective function values, returned as a structure with these fields:

  • X — Positions of the final swarm, returned as a matrix. Each row of the matrix represents one point.

  • Fval — Objective function values of the final swarm. For each i, an index of a member of the final swarm, points.Fval(i) = fun(points.X(i)).

To continue an optimization, you can pass points as the InitialPoints option. However, this approach is not the same as running an optimization for a longer time from the beginning, because many aspects of the algorithm are not identical when the optimization restarts from a final population. See Particle Swarm Optimization Algorithm.

Data Types: struct

Limitations

  • The problem-based Optimize Live Editor task currently does not support specifying multiple initial points or initial objective function values. To specify initial points, use the solver-based task, or use the command line.

Algorithms

For a description of the particle swarm optimization algorithm, see Particle Swarm Optimization Algorithm.

Alternative Functionality

App

The Optimize Live Editor task provides a visual interface for particleswarm.

Extended Capabilities

Version History

Introduced in R2014b

expand all