particleswarm

Particle swarm optimization

Syntax

x = particleswarm(fun,nvars)

x = particleswarm(fun,nvars,lb,ub)

x = particleswarm(fun,nvars,lb,ub,options)

x = particleswarm(problem)

[x,fval,exitflag,output,points]
= particleswarm(___)

Description

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.

example

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

[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

example

Examples

collapse all

Minimize a Simple Function

Open Script

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

Open Live Script

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

Minimize Using Nondefault Options

Open Live Script

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

Examine the Solution Process

Open Live Script

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

`fun` — Objective function
function handle | function name

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

`nvars` — Number of variables
positive integer

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

Example: 4

Data Types: double

`lb` — Lower bounds
`[]` (default) | real vector or array

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

`ub` — Upper bounds
`[]` (default) | real vector or array

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` — Options for `particleswarm`
options created using `optimoptions`

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.
DisplayInterval	Interval for iterative display. The iterative display prints one line for every `DisplayInterval` iterations. Default is `1`.
`FunctionTolerance`	Nonnegative 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.
`InertiaRange`	Two-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.
`MaxIterations`	Maximum number of iterations `particleswarm` takes. Default is `200*nvars`, where `nvars` is the number of variables.
`MaxStallIterations`	Positive 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`.
`MaxStallTime`	Maximum number of seconds without an improvement in the best known objective function value. Positive scalar with default `Inf`.
`MaxTime`	Maximum time in seconds that `particleswarm` runs. Default is `Inf`.
`MinNeighborsFraction`	Minimum adaptive neighborhood size, a scalar from `0` to `1`. Default is `0.25`. See Particle Swarm Optimization Algorithm.
`ObjectiveLimit`	Minimum objective value, a stopping criterion. Scalar, with default `-Inf`.
`OutputFcn`	Function 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.
`PlotFcn`	Function 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.
`SelfAdjustmentWeight`	Weighting of each particle’s best position when adjusting velocity. Finite scalar with default `1.49`. See Particle Swarm Optimization Algorithm.
`SocialAdjustmentWeight`	Weighting of the neighborhood’s best position when adjusting velocity. Finite scalar with default `1.49`. See Particle Swarm Optimization Algorithm.
`SwarmSize`	Number of particles in the swarm, an integer greater than `1`. Default is `min(100,10*nvars)`, where `nvars` is the number of variables.
`UseParallel`	Compute objective function in parallel when `true`. Default is `false`. See Parallel or Vectorized Function Evaluation.
`UseVectorized`	Compute objective function in vectorized fashion when `true`. Default is `false`. See Parallel or Vectorized Function Evaluation.

`problem` — Optimization problem
structure

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

`solver`	`'particleswarm'`
`objective`	Function handle to the objective function, or name of the objective function.
`nvars`	Number of variables in problem.
`lb`	Vector or array of lower bounds.
`ub`	Vector or array of upper bounds.
`options`	Options created by `optimoptions`.
`rngstate`	Optional state of the random number generator at the beginning of the solution process.

Data Types: struct

Output Arguments

collapse all

`x` — Solution
real vector

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

`fval` — Objective value
real scalar

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

`exitflag` — Algorithm stopping condition
integer

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.

`output` — Solution process summary
structure

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.

`points` — Final swarm positions and objective function values
structure

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

Automatic Parallel Support
Accelerate code by automatically running computation in parallel using Parallel Computing Toolbox™.

To run in parallel, set the 'UseParallel' option to true.

options = optimoptions('solvername','UseParallel',true)

For more information, see How to Use Parallel Processing in Global Optimization Toolbox.

Version History

Introduced in R2014b

expand all

R2023b: Specify and obtain `particleswarm` initial points, final positions, and objective function values

particleswarm can now return the output points, a structure containing the final positions and associated objective function values of the swarm. You can now provide the positions and objective function values for the initial swarm using the InitialPoints option. You can still provide the initial swarm positions using the InitialSwarmMatrix option or the InitialSwarm option. In these cases, particleswarm passes the initial swarm matrix as the InitialPoints option.

particleswarm

Syntax

Description

Examples

Minimize a Simple Function

Minimize a Simple Function with Bounds

Minimize Using Nondefault Options

Examine the Solution Process

Input Arguments

`fun` — Objective function
function handle | function name

`nvars` — Number of variables
positive integer

`lb` — Lower bounds
`[]` (default) | real vector or array

`ub` — Upper bounds
`[]` (default) | real vector or array

`options` — Options for `particleswarm`
options created using `optimoptions`

`problem` — Optimization problem
structure

Output Arguments

`x` — Solution
real vector

`fval` — Objective value
real scalar

`exitflag` — Algorithm stopping condition
integer

`output` — Solution process summary
structure

`points` — Final swarm positions and objective function values
structure

Limitations

Algorithms

Alternative Functionality

App

Extended Capabilities

Automatic Parallel Support
Accelerate code by automatically running computation in parallel using Parallel Computing Toolbox™.

Version History

R2023b: Specify and obtain `particleswarm` initial points, final positions, and objective function values

See Also

Topics

particleswarm

Syntax

Description

Examples

Minimize a Simple Function

Minimize a Simple Function with Bounds

Minimize Using Nondefault Options

Examine the Solution Process

Input Arguments

fun — Objective function function handle | function name

nvars — Number of variables positive integer

lb — Lower bounds [] (default) | real vector or array

ub — Upper bounds [] (default) | real vector or array

options — Options for particleswarm options created using optimoptions

problem — Optimization problem structure

Output Arguments

x — Solution real vector

fval — Objective value real scalar

exitflag — Algorithm stopping condition integer

output — Solution process summary structure

points — Final swarm positions and objective function values structure

Limitations

Algorithms

Alternative Functionality

App

Extended Capabilities

Automatic Parallel Support Accelerate code by automatically running computation in parallel using Parallel Computing Toolbox™.

Version History

R2023b: Specify and obtain particleswarm initial points, final positions, and objective function values

See Also

Topics

`fun` — Objective function
function handle | function name

`nvars` — Number of variables
positive integer

`lb` — Lower bounds
`[]` (default) | real vector or array

`ub` — Upper bounds
`[]` (default) | real vector or array

`options` — Options for `particleswarm`
options created using `optimoptions`

`problem` — Optimization problem
structure

`x` — Solution
real vector

`fval` — Objective value
real scalar

`exitflag` — Algorithm stopping condition
integer

`output` — Solution process summary
structure

`points` — Final swarm positions and objective function values
structure

Automatic Parallel Support
Accelerate code by automatically running computation in parallel using Parallel Computing Toolbox™.

R2023b: Specify and obtain `particleswarm` initial points, final positions, and objective function values