Main Content

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`

.

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.

Set a custom creation function using `optimoptions`

to set the
`CreationFcn`

option to
`@`

, where
`customcreation`

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

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.

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.

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');

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

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.

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

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.

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.

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.

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