particleswarm

R2026b

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.

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.

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.

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

Examples

Minimize a Simple Function

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 = 1×2

  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

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

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

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: [1×1 struct]
    iterations: 43
     funccount: 2203
       message: 'Optimization ended: relative change in the objective value ↵over the last OPTIONS.MaxStallIterations iterations is less than OPTIONS.FunctionTolerance.↵FMINCON: Initial point is a local minimum that satisfies the constraints.↵↵Optimization completed because at the initial point, the objective function is non-decreasing ↵in feasible directions to within the value of the optimality tolerance, and ↵constraints are satisfied to within the value of the constraint tolerance.↵↵<stopping criteria details>↵↵Optimization completed: The final point is the initial point.↵The first-order optimality measure, 2.118144e-07, is less than options.OptimalityTolerance =↵1.000000e-06, and the maximum constraint violation, 0.000000e+00, is less than↵options.ConstraintTolerance = 1.000000e-06.↵'
    hybridflag: 1

points = struct with fields:
       X: [50×2 double]
    Fval: [50×1 double]

Input Arguments

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	The algorithm stops if there is no improvement in the best known objective function value for MaxStallTime, a duration measured by tic and toc. If you specify a scalar value, the value becomes a duration with the unit seconds. Default: Inf.
MaxTime	Maximum amount of time that the algorithm runs as measured by tic and toc, a duration or Inf. The default is Inf, which disables this stopping criterion. The limit is enforced after each iteration, so the solver can exceed the limit. If you specify a scalar value, the value becomes a duration with the unit seconds.
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	Option for using parallel computing to evaluate the objective function. Option for using parallel computing, specified as one of these values: "auto" — If a parallel pool is open or automatic pool creation is enabled, compute in parallel. Otherwise, compute serially. "on" — Compute in parallel. If no parallel pool is open, the solver starts one using your default cluster profile. "off" — Compute serially. The default is "off". To use a parallel pool to run computations in MATLAB®, you must have Parallel Computing Toolbox™. The values true and false are also accepted for backward compatibility. true maps to "auto" and false maps to "off". 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

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 "auto" or "on".

options = optimoptions("solvername",UseParallel="auto")

For more information, see Parallel Computing in Global Optimization Toolbox.

Version History

Introduced in R2014b

R2026b: Enhanced control over parallel execution with UseParallel argument

The UseParallel name-value argument accepts the value "off", "auto", or "on" instead of true or false. This change gives you more control over when to use a parallel pool for parallel execution.

Specifying the UseParallel name-value argument as true or false is not recommended.

This table shows how to update your code depending on the task you are performing.

Task	Recommended	Not Recommended
Write code that runs on the MATLAB client.	optimoptions("particleswarm",UseParallel="off")	optimoptions("particleswarm",UseParallel=false)
Write portable code that runs on a parallel pool and, if a pool is not available, runs on the MATLAB client.	optimoptions("particleswarm",UseParallel="auto")	optimoptions("particleswarm",UseParallel=true)
Write code that runs on a parallel pool and issues an error if a pool is not available.	optimoptions("particleswarm",UseParallel="on")	N/A

There are no plans to remove support for the values true and false.

R2026b: Specify MaxTime and MaxStallTime options as duration

Specify the MaxTime and MaxStallTime options as duration, or as scalar that is interpreted as a duration in seconds. For example,

options.MaxTime = minutes(3);

Previously, these options were scalars representing the number of seconds.

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.