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.