Particle Swarm Options

Specifying Options for particleswarm

Create options using the optimoptions function as follows.

options = optimoptions('particleswarm',...
    'Param1',value1,'Param2',value2,...);

For an example, see Optimize Using Particle Swarm.

Each option in this section is listed by its field name in options. For example, Display refers to the corresponding field of options.

Swarm Creation

By default, particleswarm calls the 'pswcreationuniform' swarm creation function. This function works as follows.

If an InitialSwarmMatrix option exists, 'pswcreationuniform' takes the first SwarmSize rows of the InitialSwarmMatrix matrix as the swarm. If the number of rows of the InitialSwarmMatrix matrix is smaller than SwarmSize, then 'pswcreationuniform' continues to the next step.
'pswcreationuniform' creates enough particles so that there are SwarmSize in total. 'pswcreationuniform' creates particles that are randomly, uniformly distributed. The range for any swarm component is -InitialSwarmSpan/2,InitialSwarmSpan/2, shifted and scaled if necessary to match any bounds.

After creation, particleswarm checks that all particles satisfy any bounds, and truncates components if necessary. If the Display option is 'iter' and a particle needed truncation, then particleswarm notifies you.

Custom Creation Function

Set a custom creation function using optimoptions to set the CreationFcn option to @customcreation, where customcreation is the name of your creation function file. A custom creation function has this syntax.

swarm = customcreation(problem)

The creation function should return a matrix of size SwarmSize-by-nvars, where each row represents the location of one particle. See problem for details of the problem structure. In particular, you can obtain SwarmSize from problem.options.SwarmSize, and nvars from problem.nvars.

For an example of a creation function, see the code for pswcreationuniform.

edit pswcreationuniform

Display Settings

The Display option specifies how much information is displayed at the command line while the algorithm is running.

'off' or 'none' — No output is displayed.
'iter' — Information is displayed at each iteration.
'final' (default) — The reason for stopping is displayed.

iter displays:

Iteration — Iteration number
f-count — Cumulative number of objective function evaluations
Best f(x) — Best objective function value
Mean f(x) — Mean objective function value over all particles
Stall Iterations — Number of iterations since the last change in Best f(x)

The DisplayInterval option sets the number of iterations that are performed before the iterative display updates. Give a positive integer.

Algorithm Settings

The details of the particleswarm algorithm appear in Particle Swarm Optimization Algorithm. This section describes the tuning parameters.

The main step in the particle swarm algorithm is the generation of new velocities for the swarm:

For u1 and u2 uniformly (0,1) distributed random vectors of length nvars, update the velocity

v = W*v + y1*u1.*(p-x) + y2*u2.*(g-x).

The variables W = inertia, y1 = SelfAdjustmentWeight, and y2 = SocialAdjustmentWeight.

This update uses a weighted sum of:

The previous velocity v
x-p, the difference between the current position x and the best position p the particle has seen
x-g, the difference between the current position x and the best position g in the current neighborhood

Based on this formula, the options have the following effect:

Larger absolute value of inertia W leads to the new velocity being more in the same line as the old, and with a larger absolute magnitude. A large absolute value of W can destabilize the swarm. The value of W stays within the range of the two-element vector InertiaRange.
Larger values of y1 = SelfAdjustmentWeight make the particle head more toward the best place it has visited.
Larger values of y2 = SocialAdjustmentWeight make the particle head more toward the best place in the current neighborhood.

Large values of inertia, SelfAdjustmentWeight, or SocialAdjustmentWeight can destabilize the swarm.

The MinNeighborsFraction option sets both the initial neighborhood size for each particle, and the minimum neighborhood size; see Particle Swarm Optimization Algorithm. Setting MinNeighborsFraction to 1 has all members of the swarm use the global minimum point as their societal adjustment target.

See Optimize Using Particle Swarm for an example that sets a few of these tuning options.

Hybrid Function

A hybrid function is another minimization function that runs after the particle swarm algorithm terminates. You can specify a hybrid function in the HybridFcn option. The choices are

[] — No hybrid function.
'fminsearch' — Use the MATLAB^® function fminsearch to perform unconstrained minimization.
'patternsearch' — Use a pattern search to perform constrained or unconstrained minimization.
'fminunc' — Use the Optimization Toolbox™ function fminunc to perform unconstrained minimization.
'fmincon' — Use the Optimization Toolbox function fmincon to perform constrained minimization.

Note

Ensure that your hybrid function accepts your problem constraints. Otherwise, particleswarm throws an error.

You can set separate options for the hybrid function. Use optimset for fminsearch, or optimoptions for fmincon, patternsearch, or fminunc. For example:

hybridopts = optimoptions('fminunc',...
    'Display','iter','Algorithm','quasi-newton');

Include the hybrid options in the particleswarm options as follows:

options = optimoptions(options,'HybridFcn',{@fminunc,hybridopts});

hybridopts must exist before you set options.

For an example that uses a hybrid function, see Optimize Using Particle Swarm. See When to Use a Hybrid Function.

Output Function and Plot Function

Output functions are functions that particleswarm calls at each iteration. Output functions can halt particleswarm, or can perform other tasks. To specify an output function,

options = optimoptions(@particleswarm,'OutputFcn',@outfun)

where outfun is a function with syntax specified in Structure of the Output Function or Plot Function. If you have several output functions, pass them as a cell array of function handles:

options = optimoptions(@particleswarm,...
    'OutputFcn',{@outfun1,@outfun2,@outfun3})

Similarly, plot functions are functions that particleswarm calls at each iteration. The difference between an output function and a plot function is that a plot function has built-in plotting enhancements, such as buttons that appear on the plot window to pause or stop particleswarm. The lone built-in plot function 'pswplotbestf' plots the best objective function value against iterations. To specify it,

options = optimoptions(@particleswarm,'PlotFcn','pswplotbestf')

To create a custom plot function, write a function with syntax specified in Structure of the Output Function or Plot Function. To specify a custom plot function, use a function handle. If you have several plot functions, pass them as a cell array of function handles:

options = optimoptions(@particleswarm,...
    'PlotFcn',{@plotfun1,@plotfun2,@plotfun3})

For an example of a custom output function, see Particle Swarm Output Function.

Structure of the Output Function or Plot Function

An output function has the following calling syntax:

stop = myfun(optimValues,state)

If your function sets stop to true, iterations end. Set stop to false to have particleswarm continue to calculate.

The function has the following input arguments:

optimValues — Structure containing information about the swarm in the current iteration. Details are in optimValues Structure.
state — String giving the state of the current iteration.
- 'init' — The solver has not begun to iterate. Your output function or plot function can use this state to open files, or set up data structures or plots for subsequent iterations.
- 'iter' — The solver is proceeding with its iterations. Typically, this is where your output function or plot function performs its work.
- 'done' — The solver reached a stopping criterion. Your output function or plot function can use this state to clean up, such as closing any files it opened.

Passing Extra Parameters explains how to provide additional parameters to output functions or plot functions.

Note

Plot functions do not support the subplot statement, because the plot function framework manages the axes. To specify multiple subplots, write separate plot functions and pass them to the solver as a cell array:

options = optimoptions("solvername",PlotFcn={@plot1,@plot2,@plot3});

Output functions support subplot, so you can include multiple plots in one function by using an output function instead of a plot function.

optimValues Structure

particleswarm passes the optimValues structure to your output functions or plot functions. The optimValues structure has the following fields.

Field	Contents
`funccount`	Total number of objective function evaluations.
`bestx`	Best solution point found, corresponding to the best objective function value `bestfval`.
`bestfval`	Best (lowest) objective function value found.
`iteration`	Iteration number.
`meanfval`	Mean objective function among all particles at the current iteration.
`stalliterations`	Number of iterations since the last change in `bestfval`.
`swarm`	Matrix containing the particle positions. Each row contains the position of one particle, and the number of rows is equal to the swarm size.
`swarmfvals`	Vector containing the objective function values of particles in the swarm. For particle `i`, `swarmfvals(i) = fun(swarm(i,:))`, where `fun` is the objective function.

Parallel or Vectorized Function Evaluation

For increased speed, you can set your options so that particleswarm evaluates the objective function for the swarm in parallel or in a vectorized fashion. You can use only one of these options. If you set UseParallel to true and UseVectorized to true, then the computations are done in a vectorized fashion, and not in parallel.

Parallel particleswarm
Vectorized particleswarm

Parallel particleswarm

If you have a Parallel Computing Toolbox™ license, you can distribute the evaluation of the objective functions to the swarm among your processors or cores. Set the UseParallel option to true.

Parallel computation is likely to be faster than serial when your objective function is computationally expensive, or when you have many particles and processors. Otherwise, communication overhead can cause parallel computation to be slower than serial computation.

For details, see Parallel Computing.

Vectorized particleswarm

If your objective function can evaluate all the particles at once, you can usually save time by setting the UseVectorized option to true. Your objective function should accept an M-by-N matrix, where each row represents one particle, and return an M-by-1 vector of objective function values. This option works the same way as the patternsearch and ga UseVectorized options. For patternsearch details, see Vectorize the Objective and Constraint Functions.

Stopping Criteria

particleswarm stops iterating when any of the following occur.

Stopping Option	Stopping Test	Exit Flag
`MaxStallIterations` and `FunctionTolerance`	Relative change in the best objective function value `g` over the last `MaxStallIterations` iterations is less than `FunctionTolerance`.	`1`
`MaxIterations`	Number of iterations reaches `MaxIterations`.	`0`
`OutputFcn` or `PlotFcn`	`OutputFcn` or `PlotFcn` can halt the iterations.	`-1`
`ObjectiveLimit`	Best objective function value `g` of a feasible point is less than `ObjectiveLimit`.	`-3`
`MaxStallTime`	Best objective function value `g` did not change in the last `MaxStallTime` seconds.	`-4`
`MaxTime`	Function run time exceeds `MaxTime` seconds.	`-5`

Also, if you set the FunValCheck option to 'on', and the swarm has particles with NaN, Inf, or complex objective function values, particleswarm stops and issues an error.