## 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
`@`

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

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

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

#### 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

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.