# particleswarm

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] = particleswarm(___)``````

## Description

example

````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`. NotePassing Extra Parameters explains how to pass extra parameters to the objective function, if necessary. ```

example

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

example

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

example

``````[x,fval,exitflag,output] = particleswarm(___)```, for any input arguments described above, returns:A scalar `fval`, which is the objective function value `fun(x)`A value `exitflag` describing the exit conditionA structure `output` containing information about the optimization process```

## Examples

collapse all

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

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

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] = 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: [1x1 struct] iterations: 43 funccount: 2203 message: 'Optimization ended: relative change in the objective value ...' hybridflag: 1 ```

## Input Arguments

collapse all

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`

Number of variables, specified as a positive integer. The solver passes row vectors of length `nvars` to `fun`.

Example: `4`

Data Types: `double`

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`

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 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 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. `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. `InitialSwarmMatrix` Initial population or partial population of particles. `M`-by-`nvars` matrix, where 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. `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` Maximum number of seconds without an improvement in the best known objective function value. Positive scalar with default `Inf`. `MaxTime` Maximum time in seconds that `particleswarm` runs. Default is `Inf`. `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` Compute objective function in parallel when `true`. Default is `false`. See Parallel or Vectorized Function Evaluation. `UseVectorized` Compute objective function in vectorized fashion when `true`. Default is `false`. See Parallel or Vectorized Function Evaluation.

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

collapse all

Solution, returned as a real vector that minimizes the objective function subject to any bound constraints.

Objective value, returned as the real scalar `fun(x)`.

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.

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.

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

## Version History

Introduced in R2014b