# Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English verison of the page.

# ga

Find minimum of function using genetic algorithm

## Syntax

```x = ga(fitnessfcn,nvars) x = ga(fitnessfcn,nvars,A,b) x = ga(fitnessfcn,nvars,A,b,Aeq,beq) x = ga(fitnessfcn,nvars,A,b,Aeq,beq,LB,UB) x = ga(fitnessfcn,nvars,A,b,Aeq,beq,LB,UB,nonlcon) x = ga(fitnessfcn,nvars,A,b,Aeq,beq,LB,UB,nonlcon,options) x = ga(fitnessfcn,nvars,A,b,[],[],LB,UB,nonlcon,IntCon) x = ga(fitnessfcn,nvars,A,b,[],[],LB,UB,nonlcon,IntCon,options) x = ga(problem) [x,fval] = ga(fitnessfcn,nvars,...) [x,fval,exitflag] = ga(fitnessfcn,nvars,...) [x,fval,exitflag,output] = ga(fitnessfcn,nvars,...) [x,fval,exitflag,output,population] = ga(fitnessfcn,nvars,...) [x,fval,exitflag,output,population,scores] = ga(fitnessfcn,nvars,...) ```

## Description

`x = ga(fitnessfcn,nvars)` finds a local unconstrained minimum, `x`, to the objective function, `fitnessfcn`. `nvars` is the dimension (number of design variables) of `fitnessfcn`.

### Note

Passing Extra Parameters (Optimization Toolbox) explains how to pass extra parameters to the objective function and nonlinear constraint functions, if necessary.

`x = ga(fitnessfcn,nvars,A,b)` finds a local minimum `x` to `fitnessfcn`, subject to the linear inequalities `A*x` ≤ `b`. `ga` evaluates the matrix product `A*x` as if `x` is transposed (`A*x'`).

`x = ga(fitnessfcn,nvars,A,b,Aeq,beq)` finds a local minimum `x` to `fitnessfcn`, subject to the linear equalities `Aeq*x` = `beq` as well as `A*x` ≤ `b`. (Set `A=[]` and `b=[]` if no linear inequalities exist.) `ga` evaluates the matrix product `Aeq*x` as if `x` is transposed (`Aeq*x'`).

`x = ga(fitnessfcn,nvars,A,b,Aeq,beq,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`. (Set `Aeq=[]` and `beq=[]` if no linear equalities exist.)

`x = ga(fitnessfcn,nvars,A,b,Aeq,beq,LB,UB,nonlcon)` subjects the minimization to the constraints defined in `nonlcon`. The function `nonlcon` accepts `x` and returns vectors `C` and `Ceq`, representing the nonlinear inequalities and equalities respectively. `ga` minimizes the `fitnessfcn` such that `C(x) `` 0` and `Ceq(x) = 0`. (Set `LB=[]` and `UB=[]` if no bounds exist.)

`x = ga(fitnessfcn,nvars,A,b,Aeq,beq,LB,UB,nonlcon,options)` minimizes with the default optimization parameters replaced by values in `options`. (Set `nonlcon=[]` if no nonlinear constraints exist.) Create `options` using `optimoptions` (recommended) or `gaoptimset`.

`x = ga(fitnessfcn,nvars,A,b,[],[],LB,UB,nonlcon,IntCon)` requires that the variables listed in `IntCon` take integer values.

### Note

When there are integer constraints, `ga` does not accept linear or nonlinear equality constraints, only inequality constraints.

`x = ga(fitnessfcn,nvars,A,b,[],[],LB,UB,nonlcon,IntCon,options)` minimizes with integer constraints and with the default optimization parameters replaced by values in the `options` structure.

`x = ga(problem)` finds the minimum for `problem`, where `problem` is a structure.

```[x,fval] = ga(fitnessfcn,nvars,...)``` returns `fval`, the value of the fitness function at `x`.

```[x,fval,exitflag] = ga(fitnessfcn,nvars,...)``` returns `exitflag`, an integer identifying the reason the algorithm terminated.

```[x,fval,exitflag,output] = ga(fitnessfcn,nvars,...)``` returns `output`, a structure that contains output from each generation and other information about the performance of the algorithm.

```[x,fval,exitflag,output,population] = ga(fitnessfcn,nvars,...)``` returns the matrix, `population`, whose rows are the final population.

```[x,fval,exitflag,output,population,scores] = ga(fitnessfcn,nvars,...)``` returns `scores` the scores of the final population.

## Input Arguments

`fitnessfcn`

Handle to the fitness function or name of the fitness function. The fitness function should accept a row vector of length `nvars` and return a scalar value.

When the `'UseVectorized'` option is `true`, `fitnessfcn` should accept a `pop`-by-`nvars` matrix, where `pop` is the current population size. In this case `fitnessfcn` should return a vector the same length as `pop` containing the fitness function values. `fitnessfcn` should not assume any particular size for `pop`, since `ga` can pass a single member of a population even in a vectorized calculation.

`nvars`

Positive integer representing the number of variables in the problem.

`A`

Matrix for linear inequality constraints of the form

`A*x` ≤ `b`.

If the problem has `m` linear inequality constraints and `nvars` variables, then

• `A` is a matrix of size `m`-by-`nvars`.

• `b` is a vector of length `m`.

`ga` evaluates the matrix product `A*x` as if `x` is transposed (`A*x'`).

### Note

`ga` does not enforce linear constraints to be satisfied when the `PopulationType` option is `'bitString'` or `'custom'`.

`b`

Vector for linear inequality constraints of the form

`A*x` ≤ `b`.

If the problem has `m` linear inequality constraints and `nvars` variables, then

• `A` is a matrix of size `m`-by-`nvars`.

• `b` is a vector of length `m`.

`Aeq`

Matrix for linear equality constraints of the form

`Aeq*x` = `beq`.

If the problem has `m` linear equality constraints and `nvars` variables, then

• `Aeq` is a matrix of size `m`-by-`nvars`.

• `beq` is a vector of length `m`.

`ga` evaluates the matrix product `Aeq*x` as if `x` is transposed (`Aeq*x'`).

### Note

`ga` does not enforce linear constraints to be satisfied when the `PopulationType` option is `'bitString'` or `'custom'`.

`beq`

Vector for linear equality constraints of the form

`Aeq*x` = `beq`.

If the problem has `m` linear equality constraints and `nvars` variables, then

• `Aeq` is a matrix of size `m`-by-`nvars`.

• `beq` is a vector of length `m`.

`LB`

Vector of lower bounds. `ga` enforces that iterations stay above `LB`. Set `LB(i)` = –`Inf` if `x(i)`is unbounded below.

### Note

`ga` does not enforce bounds to be satisfied when the `PopulationType` option is `'bitString'` or `'custom'`.

`UB`

Vector of upper bounds. `ga` enforces that iterations stay below `UB`. Set `UB(i)` = `Inf` if `x(i)` is unbounded above.

`nonlcon`

Function handle that returns two outputs:

`[c,ceq] = nonlcon(x)`

`ga` attempts to achieve `c` ≤ `0` and `ceq` = `0`. `c` and `ceq` are row vectors when there are multiple constraints. Set unused outputs to `[]`.

You can write `nonlcon` as a function handle to a file, such as

`nonlcon = @constraintfile`

where `constraintfile.m` is a file on your MATLAB® path.

To learn how to use vectorized constraints, see Vectorized Constraints.

### Note

`ga` does not enforce nonlinear constraints to be satisfied when the `PopulationType` option is set to `'bitString'` or `'custom'`.

If `IntCon` is not empty, the second output of `nonlcon` (`ceq`) must be an empty entry (`[]`).

For information on how `ga` uses `nonlcon`, see Nonlinear Constraint Solver Algorithms.

`options`

Optimization options, specified as the output of `optimoptions` or a structure such as `gaoptimset` returns.

Create `options` by using `optimoptions` (recommended), or `gaoptimset`, or by exporting options from the Optimization app. For details, see Importing and Exporting Your Work (Optimization Toolbox).

`optimoptions` hides the options listed in italics. See Options that optimoptions Hides.

• Values in `{}` denote the default value.

• `{}*` represents the default when there are linear constraints, and for `MutationFcn` also when there are bounds.

• I* indicates that `ga` handles options for integer constraints differently; this notation does not apply to `gamultiobj`.

• NM indicates that the option does not apply to `gamultiobj`.

Options for `ga`, Integer `ga`, and `gamultiobj`

OptionDescriptionValues
`ConstraintTolerance`

Determines the feasibility with respect to nonlinear constraints. Also, `max(sqrt(eps),ConstraintTolerance)` determines feasibility with respect to linear constraints.

For `gaoptimset`, use `TolCon`.

Positive scalar | `{1e-3}`

`CreationFcn`

I* Handle to the function that creates the initial population. See Population Options.

`{@gacreationuniform}` | `{@gacreationlinearfeasible}*` | Custom creation function

`CrossoverFcn`

I* Handle to the function that the algorithm uses to create crossover children. See Crossover Options.

`{@crossoverscattered}` for `ga`, `{@crossoverintermediate}*` for `gamultiobj` | `@crossoverheuristic` | `@crossoversinglepoint` | `@crossovertwopoint` | `@crossoverarithmetic` | Custom crossover function

`CrossoverFraction`

The fraction of the population at the next generation, not including elite children, that is created by the crossover function.

Positive scalar | `{0.8}`

`Display`

Level of display.

`'off'` | `'iter'` | `'diagnose'` | `{'final'}`

`DistanceMeasureFcn`

Handle to the function that computes distance measure of individuals. The value applies to decision variable or design space (genotype) or to function space (phenotype). For `gamultiobj` only. See Multiobjective Options.

`{@distancecrowding,'phenotype'}` | `@distancecrowding,'genotype'` | Custom distance function

`EliteCount`

NM Positive integer specifying how many individuals in the current generation are guaranteed to survive to the next generation. Not used in `gamultiobj`.

Positive integer | `{ceil(0.05*PopulationSize)}` | ```{0.05*(default PopulationSize)}``` for mixed-integer problems

`FitnessLimit`

NM If the fitness function attains the value of `FitnessLimit`, the algorithm halts.

Scalar | `{-Inf}`

`FitnessScalingFcn`

Handle to the function that scales the values of the fitness function. Option unavailable for `gamultiobj`.

`{@fitscalingrank}` | `@fitscalingshiftlinear` | `@fitscalingprop` | `@fitscalingtop` | Custom fitness scaling function

`FunctionTolerance`

The algorithm stops if the average relative change in the best fitness function value over `MaxStallGenerations` generations is less than or equal to `FunctionTolerance`. If `StallTest` is `'geometricWeighted'`, then the algorithm stops if the weighted average relative change is less than or equal to `FunctionTolerance`.

For `gaoptimset`, use `TolFun`.

Positive scalar | `{1e-6}` for `ga`, `{1e-4}` for `gamultiobj`

`HybridFcn`

I* Handle to a function that continues the optimization after `ga` terminates.

Alternatively, a cell array specifying the hybrid function and its options structure. See ga Hybrid Function.

For `gamultiobj`, the only hybrid function is `@fgoalattain`. See gamultiobj Hybrid Function.

Function handle |``` @fminsearch | @patternsearch | @fminunc | @fmincon | {[]}```

or

1-by-2 cell array | `{@solver, hybridoptions}`, where ```solver = fminsearch```, `patternsearch`, `fminunc`, or `fmincon` `{[]}`

InitialPenalty

NM I* Initial value of penalty parameter

Positive scalar | `{10}`

`InitialPopulationMatrix`

Initial population used to seed the genetic algorithm. Has up to `PopulationSize` rows and `N` columns, where `N` is the number of variables. You can pass a partial population, meaning one with fewer than `PopulationSize` rows. In that case, the genetic algorithm uses `CreationFcn` to generate the remaining population members. See Population Options

For `gaoptimset`, use `InitialPopulation`.

Matrix | `{[]}`

`InitialPopulationRange`

Matrix or vector specifying the range of the individuals in the initial population. Applies to `gacreationuniform` creation function. `ga` shifts and scales the default initial range to match any finite bounds.

For `gaoptimset`, use `PopInitRange`.

Matrix or vector | `{[-10;10]}` for unbounded components, `{[-1e4+1;1e4+1]}` for unbounded components of integer-constrained problems, `{[lb;ub]}` for bounded components, with the default range modified to match one-sided bounds.

`InitialScoresMatrix`

I* Initial scores used to determine fitness. Has up to `PopulationSize` rows and has `Nf` columns, where `Nf` is the number of fitness functions (`1` for `ga`, greater than `1` for `gamultiobj`). You can pass a partial scores matrix, meaning one with fewer than `PopulationSize` rows. In that case, the solver fills in the scores when it evaluates the fitness functions.

For `gaoptimset`, use `InitialScores`.

Column vector for single objective | matrix for multiobjective | `{[]}`

`MaxGenerations`

Maximum number of iterations before the algorithm halts.

For `gaoptimset`, use `Generations`.

Positive integer |`{100*numberOfVariables}` for `ga`, `{200*numberOfVariables}` for `gamultiobj`

`MaxStallGenerations`

The algorithm stops if the average relative change in the best fitness function value over `MaxStallGenerations` generations is less than or equal to `FunctionTolerance`. If `StallTest` is `'geometricWeighted'`, then the algorithm stops if the weighted average relative change is less than or equal to `FunctionTolerance`.

For `gaoptimset`, use `StallGenLimit`.

Positive integer | `{50}` for `ga`, `{100}` for `gamultiobj`

`MaxStallTime`

NM The algorithm stops if there is no improvement in the objective function for `MaxStallTime` seconds, as measured by `tic` and `toc`.

For `gaoptimset`, use `StallTimeLimit`.

Positive scalar `| {Inf}`

`MaxTime`

The algorithm stops after running after `MaxTime` seconds, as measured by `tic` and `toc`. This limit is enforced after each iteration, so `ga` can exceed the limit when an iteration takes substantial time.

For `gaoptimset`, use `TimeLimit`.

Positive scalar | `{Inf}`

MigrationDirection

Direction of migration. See Migration Options

`'both'` | `{'forward'}`

MigrationFraction

Scalar between 0 and 1 specifying the fraction of individuals in each subpopulation that migrates to a different subpopulation. See Migration Options

Scalar | `{0.2}`

MigrationInterval

Positive integer specifying the number of generations that take place between migrations of individuals between subpopulations. See Migration Options.

Positive integer | `{20}`

`MutationFcn`

I* Handle to the function that produces mutation children. See Mutation Options.

`{@mutationgaussian}` for `ga`, `{@mutationadaptfeasible}*` for `gamultiobj` | `@mutationuniform` | Custom mutation function

`NonlinearConstraintAlgorithm`

Nonlinear constraint algorithm. See Nonlinear Constraint Solver Algorithms. Option unchangeable for `gamultiobj`.

For `gaoptimset`, use `NonlinConAlgorithm`.

`{'auglag'}` for `ga`, `{'penalty'}` for `gamultiobj`

`OutputFcn`

Functions that `ga` calls at each iteration. See Output Function Options.

For `gaoptimset`, use `OutputFcns`.

Function handle or cell array of function handles | `{[]}`

`ParetoFraction`

I* Scalar between 0 and 1 specifying the fraction of individuals to keep on the first Pareto front while the solver selects individuals from higher fronts, for `gamultiobj` only.

Scalar | `{0.35}`

PenaltyFactor

NM I* Penalty update parameter.

Positive scalar | `{100}`

`PlotFcn`

Function handle or cell array of function handles that plot data computed by the algorithm. See Plot Options.

For `gaoptimset`, use `PlotFcns`.

`ga` or `gamultiobj`: ```{[]} | @gaplotdistance | @gaplotgenealogy | @gaplotselection | @gaplotscorediversity | @gaplotscores | @gaplotstopping | @gaplotmaxconstr | ```Custom plot function

`ga` only: ```@gaplotbestf | @gaplotbestindiv | @gaplotexpectation | @gaplotrange```

`gamultiobj` only: ```@gaplotpareto | @gaplotparetodistance | @gaplotrankhist | @gaplotspread```

PlotInterval

Positive integer specifying the number of generations between consecutive calls to the plot functions.

Positive integer | `{1}`

`PopulationSize`

Size of the population.

Positive integer | `{50}` when ```numberOfVariables <= 5```, `{200}` otherwise | `{min(max(10*nvars,40),100)}` for mixed-integer problems

`PopulationType`

Data type of the population. Must be `'doubleVector'` for mixed integer problems.

`'bitstring'` | `'custom'` | `{'doubleVector'}`

`ga` ignores all constraints when `PopulationType` is set to `'bitString'` or `'custom'`. See Population Options.

`SelectionFcn`

I* Handle to the function that selects parents of crossover and mutation children.

`gamultiobj` uses only `@selectiontournament`.

`{@selectionstochunif}` for `ga`, `{@selectiontournament}` for `gamultiobj` | `@selectionremainder` | `@selectionuniform` | `@selectionroulette` | Custom selection function

StallTest

NM Stopping test type.

`'geometricWeighted'` | `{'averageChange'}`

`UseParallel`

Compute fitness and nonlinear constraint functions in parallel. See Vectorize and Parallel Options (User Function Evaluation) and How to Use Parallel Processing.

`true` | `{false}`

`UseVectorized`

Specifies whether functions are vectorized. See Vectorize and Parallel Options (User Function Evaluation) and Vectorize the Fitness Function.

For `gaoptimset`, use `Vectorized` with the values `'on'` or `'off'`.

`true` | `{false}`

`IntCon`

Vector of positive integers taking values from `1` to `nvars`. Each value in `IntCon` represents an `x` component that is integer-valued.

### Note

When `IntCon` is nonempty, `Aeq` and `beq` must be an empty entry (`[]`), and `nonlcon` must return empty for `ceq`. For more information on integer programming, see Mixed Integer Optimization.

`problem`

Structure containing the following fields:

 `fitnessfcn` Fitness function `nvars` Number of design variables `Aineq` `A` matrix for linear inequality constraints `Bineq` `b` vector for linear inequality constraints `Aeq` `Aeq` matrix for linear equality constraints `Beq` `beq` vector for linear equality constraints `lb` Lower bound on `x` `ub` Upper bound on `x` `nonlcon` Nonlinear constraint function `rngstate` Optional field to reset the state of the random number generator `intcon` Index vector of integer variables `solver` `'ga'` `options` Options created using `optimoptions`, `gaoptimset` or the Optimization app

Create `problem` by exporting a problem from the Optimization app, as described in Importing and Exporting Your Work (Optimization Toolbox).

## Output Arguments

`x`

Best point that `ga` located during its iterations.

`fval`

Fitness function evaluated at `x`.

`exitflag`

Integer giving the reason `ga` stopped iterating:

Exit FlagMeaning
`1`

Without nonlinear constraints — Average cumulative change in value of the fitness function over `MaxStallGenerations` generations is less than `FunctionTolerance`, and the constraint violation is less than `ConstraintTolerance`.

With nonlinear constraints — Magnitude of the complementarity measure (see Complementarity Measure) is less than `sqrt(ConstraintTolerance)`, the subproblem is solved using a tolerance less than `FunctionTolerance`, and the constraint violation is less than `ConstraintTolerance`.

`3`

Value of the fitness function did not change in `MaxStallGenerations` generations and the constraint violation is less than `ConstraintTolerance`.

`4`

Magnitude of step smaller than machine precision and the constraint violation is less than `ConstraintTolerance`.

`5`

Minimum fitness limit `FitnessLimit` reached and the constraint violation is less than `ConstraintTolerance`.

`0`

Maximum number of generations `MaxGenerations` exceeded.

`-1`

Optimization terminated by an output function or plot function.

`-2`

No feasible point found.

`-4`

Stall time limit `MaxStallTime` exceeded.

`-5`

Time limit `MaxTime` exceeded.

When there are integer constraints, `ga` uses the penalty fitness value instead of the fitness value for stopping criteria.

`output`

Structure containing output from each generation and other information about algorithm performance. The `output` structure contains the following fields:

• `problemtype` — Problem type, one of:

• `'unconstrained'`

• `'boundconstraints'`

• `'linearconstraints'`

• `'nonlinearconstr'`

• `'integerconstraints'`

• `rngstate` — State of the MATLAB random number generator, just before the algorithm started. You can use the values in `rngstate` to reproduce the output of `ga`. See Reproduce Results.

• `generations` — Number of generations computed.

• `funccount` — Number of evaluations of the fitness function.

• `message` — Reason the algorithm terminated.

• `maxconstraint` — Maximum constraint violation, if any.

`population`

Matrix whose rows contain the members of the final population.

`scores`

Column vector of the fitness values (scores for `integerconstraints` problems) of the final population.

## Examples

Given the following inequality constraints and lower bounds

use this code to find the minimum of the `lincontest6` function, which is provided in your software:

```A = [1 1; -1 2; 2 1]; b = [2; 2; 3]; lb = zeros(2,1); [x,fval,exitflag] = ga(@lincontest6,... 2,A,b,[],[],lb) Optimization terminated: average change in the fitness value less than options.FunctionTolerance. x = 0.6700 1.3310 fval = -8.2218 exitflag = 1```

Optimize a function where some variables must be integers:

```fun = @(x) (x(1) - 0.2)^2 + ... (x(2) - 1.7)^2 + (x(3) - 5.1)^2; x = ga(fun,3,[],[],[],[],[],[],[], ... [2 3]) % variables 2 and 3 are integers Optimization terminated: average change in the penalty fitness value less than options.FunctionTolerance and constraint violation is less than options.ConstraintTolerance. x = 0.2000 2.0000 5.0000```

collapse all

### Complementarity Measure

In the nonlinear constraint solver, the complementarity measure is the norm of the vector whose elements are ciλi, where ci is the nonlinear inequality constraint violation, and λi is the corresponding Lagrange multiplier.

## Tips

• To write a function with additional parameters to the independent variables that can be called by `ga`, see Passing Extra Parameters (Optimization Toolbox).

• For problems that use the population type ```Double Vector``` (the default), `ga` does not accept functions whose inputs are of type `complex`. To solve problems involving complex data, write your functions so that they accept real vectors, by separating the real and imaginary parts.

## Algorithms

For a description of the genetic algorithm, see How the Genetic Algorithm Works.

For a description of the mixed integer programming algorithm, see Integer ga Algorithm.

For a description of the nonlinear constraint algorithm, see Nonlinear Constraint Solver Algorithms.

## Alternatives

For problems without integer constraints, consider using `patternsearch` instead of `ga`.

## References

[1] Goldberg, David E., Genetic Algorithms in Search, Optimization & Machine Learning, Addison-Wesley, 1989.

[2] A. R. Conn, N. I. M. Gould, and Ph. L. Toint. “A Globally Convergent Augmented Lagrangian Algorithm for Optimization with General Constraints and Simple Bounds”, SIAM Journal on Numerical Analysis, Volume 28, Number 2, pages 545–572, 1991.

[3] A. R. Conn, N. I. M. Gould, and Ph. L. Toint. “A Globally Convergent Augmented Lagrangian Barrier Algorithm for Optimization with General Inequality Constraints and Simple Bounds”, Mathematics of Computation, Volume 66, Number 217, pages 261–288, 1997.