## Genetic Algorithm Options

### Options for Genetic Algorithm

Set options for `ga`

by using
`optimoptions`

.

options = optimoptions('ga','Option1','value1','Option2','value2');

Some options are listed in

. These options do not appear in the listing that`italics`

`optimoptions`

returns. To see why '`optimoptions`

hides these option values, see Options that optimoptions Hides.Ensure that you pass options to the solver. Otherwise,

`patternsearch`

uses the default option values.[x,fval] = ga(fun,x0,A,b,Aeq,beq,lb,ub,nonlcon,

**options**)

### Plot Options

`PlotFcn`

specifies the plot function or functions called at each
iteration by `ga`

or `gamultiobj`

. Set the
`PlotFcn`

option to be a built-in plot function name or a
handle to the plot function. You can stop the algorithm at any time by clicking the
**Stop** button on the plot window. For example, to display
the best function value, set `options`

as follows:

options = optimoptions('ga','PlotFcn','gaplotbestf');

To display multiple plots, use a cell array of built-in plot function names or a cell array of function handles:

options = optimoptions('patternsearch',... 'PlotFcn', {@plotfun1, @plotfun2, ...});

where `@plotfun1`

, `@plotfun2`

, and so on are
function handles to the plot functions. If you specify more than one plot function,
all plots appear as subplots in the same window. Right-click any subplot to obtain a
larger version in a separate figure window.

Available plot functions for `ga`

or for
`gamultiobj`

:

`'gaplotscorediversity'`

plots a histogram of the scores at each generation.`'gaplotstopping'`

plots stopping criteria levels.`'gaplotgenealogy'`

plots the genealogy of individuals. Lines from one generation to the next are color-coded as follows:Red lines indicate mutation children.

Blue lines indicate crossover children.

Black lines indicate elite individuals.

`'gaplotscores'`

plots the scores of the individuals at each generation.`'gaplotdistance'`

plots the average distance between individuals at each generation.`'gaplotselection'`

plots a histogram of the parents.`'gaplotmaxconstr'`

plots the maximum nonlinear constraint violation at each generation. For`ga`

, available only when the`NonlinearConstraintAlgorithm`

option is`'auglag'`

(default for non-integer problems). Therefore, not available for integer-constrained problems, as they use the`'penalty'`

nonlinear constraint algorithm.You can also create and use your own plot function. Structure of the Plot Functions describes the structure of a custom plot function. Pass any custom function as a function handle.

The following plot functions are available for `ga`

only:

`'gaplotbestf'`

plots the best score value and mean score versus generation.`'gaplotbestindiv'`

plots the vector entries of the individual with the best fitness function value in each generation.`'gaplotexpectation'`

plots the expected number of children versus the raw scores at each generation.`'gaplotrange'`

plots the minimum, maximum, and mean score values in each generation.

The following plot functions are available for `gamultiobj`

only:

`'gaplotpareto'`

plots the Pareto front for the first two or three objective functions.`'gaplotparetodistance'`

plots a bar chart of the distance of each individual from its neighbors.`'gaplotrankhist'`

plots a histogram of the ranks of the individuals. Individuals of rank 1 are on the Pareto frontier. Individuals of rank 2 are lower than at least one rank 1 individual, but are not lower than any individuals from other ranks, etc.`'gaplotspread'`

plots the average spread as a function of iteration number.

#### Structure of the Plot Functions

The first line of a plot function has this form:

function state = plotfun(options,state,flag)

The input arguments to the function are

`options`

— Structure containing all the current options settings.`state`

— Structure containing information about the current generation. The State Structure describes the fields of`state`

.`flag`

— Description of the stage the algorithm is currently in. For details, see Output Function Options.

Passing Extra Parameters explains how to provide additional parameters to the function.

The output argument `state`

is a state structure as well.
Pass the input argument, modified if you like; see Changing the State Structure. To stop the iterations, set
`state.StopFlag`

to a nonempty character vector, such as
`'y'`

.

#### The State Structure

**ga. **The state structure for `ga`

, which is an input
argument to plot, mutation, and output functions, contains the following
fields:

`Generation`

— Current generation number.`StartTime`

— Time when genetic algorithm started, returned by`tic`

.`StopFlag`

— Reason for stopping, a character vector.`LastImprovement`

— Generation at which the last improvement in fitness value occurred.`LastImprovementTime`

— Time at which last improvement occurred.`Best`

— Vector containing the best score in each generation.`how`

— The`'augLag'`

nonlinear constraint algorithm reports one of the following actions:`'Infeasible point'`

,`'Update multipliers'`

, or`'Increase penalty'`

; see Augmented Lagrangian Genetic Algorithm.`FunEval`

— Cumulative number of function evaluations.`Expectation`

— Expectation for selection of individuals.`Selection`

— Indices of individuals selected for elite, crossover, and mutation.`Population`

— Population in the current generation.`Score`

— Scores of the current population.`NonlinIneq`

— Nonlinear inequality constraints at current point, present only when a nonlinear constraint function is specified, there are no integer variables,`flag`

is not`'interrupt'`

, and`NonlinearConstraintAlgorithm`

is`'auglag'`

.`NonlinEq`

— Nonlinear equality constraints at current point, present only when a nonlinear constraint function is specified, there are no integer variables,`flag`

is not`'interrupt'`

, and`NonlinearConstraintAlgorithm`

is`'auglag'`

.`EvalElites`

— Logical value indicating whether`ga`

evaluates the fitness function of elite individuals. Initially, this value is`true`

. In the first generation, if the elite individuals evaluate to their previous values (which indicates that the fitness function is deterministic), then this value becomes`false`

by default for subsequent iterations. When`EvalElites`

is`false`

,`ga`

does not reevaluate the fitness function of elite individuals. You can override this behavior in a custom plot function or custom output function by changing the output`state.EvalElites`

.`HaveDuplicates`

— Logical value indicating whether`ga`

adds duplicate individuals for the initial population.`ga`

uses a small relative tolerance to determine whether an individual is duplicated or unique. If`HaveDuplicates`

is`true`

, then`ga`

locates the unique individuals and evaluates the fitness function only once for each unique individual.`ga`

copies the fitness and constraint function values to duplicate individuals.`ga`

repeats the test in each generation until all individuals are unique. The test takes order`n*m*log(m)`

operations, where`m`

is the population size and`n`

is`nvars`

. To override this test in a custom plot function or custom output function, set the output`state.HaveDuplicates`

to`false`

.

**gamultiobj. **The state structure for `gamultiobj`

, which is an input
argument to plot, mutation, and output functions, contains the following
fields:

`Population`

— Population in the current generation`Score`

— Scores of the current population, a`Population`

-by-`nObjectives`

matrix, where`nObjectives`

is the number of objectives`Generation`

— Current generation number`StartTime`

— Time when genetic algorithm started, returned by`tic`

`StopFlag`

— Reason for stopping, a character vector`FunEval`

— Cumulative number of function evaluations`Selection`

— Indices of individuals selected for elite, crossover, and mutation`Rank`

— Vector of the ranks of members in the population`Distance`

— Vector of distances of each member of the population to the nearest neighboring member`AverageDistance`

— Standard deviation (not average) of`Distance`

`Spread`

— Vector where the entries are the spread in each generation`mIneq`

— Number of nonlinear inequality constraints`mEq`

— Number of nonlinear equality constraints`mAll`

— Total number of nonlinear constraints,`mAll`

=`mIneq`

+`mEq`

`C`

— Nonlinear inequality constraints at current point, a`PopulationSize`

-by-`mIneq`

matrix`Ceq`

— Nonlinear equality constraints at current point, a`PopulationSize`

-by-`mEq`

matrix`isFeas`

— Feasibility of population, a logical vector with`PopulationSize`

elements`maxLinInfeas`

— Maximum infeasibility with respect to linear constraints for the population

### Population Options

Population options let you specify the parameters of the population that the genetic algorithm uses.

`PopulationType`

specifies the type of input to the fitness
function. Types and their restrictions are:

`'doubleVector'`

— Use this option if the individuals in the population have type`double`

. Also, the recommended data type for mixed integer programming is`'doubleVector'`

, using the technique in Mixed Integer ga Optimization.`'doubleVector'`

is the default data type.`'bitstring'`

— You can use this option if the individuals in the population have components that are`0`

or`1`

.**Caution**The individuals in a

`Bit string`

population are vectors of type`double`

, not strings or characters.For

`CreationFcn`

and`MutationFcn`

, use`'gacreationuniform'`

and`'mutationuniform'`

or handles to custom functions. For`CrossoverFcn`

, use`'crossoverscattered'`

,`'crossoversinglepoint'`

,`'crossovertwopoint'`

, or a handle to a custom function.The

`'bitstring'`

data type can be awkward to use.`ga`

ignores all constraints, including bounds, linear constraints, and nonlinear constraints. You cannot use a`HybridFcn`

. To use binary variables most easily in`ga`

, see Mixed Integer ga Optimization.`'custom'`

— Indicates a custom population type. In this case, you must also use a custom`CrossoverFcn`

and`MutationFcn`

. You must provide either a custom creation function or an`InitialPopulationMatrix`

. You cannot use a`HybridFcn`

, and`ga`

ignores all constraints, including bounds, linear constraints, and nonlinear constraints.

`PopulationSize`

specifies how many individuals there are in each
generation. With a large population size, the genetic algorithm searches the
solution space more thoroughly, thereby reducing the chance that the algorithm
returns a local minimum that is not a global minimum. However, a large population
size also causes the algorithm to run more slowly. The default is ```
'50 when
numberOfVariables <= 5, else 200'
```

.

If you set `PopulationSize`

to a vector, the genetic algorithm
creates multiple subpopulations, the number of which is the length of the vector.
The size of each subpopulation is the corresponding entry of the vector. Note that
this option is not useful. See Migration Options.

`CreationFcn`

specifies the function that creates the initial
population for `ga`

. Choose from:

`[]`

uses the default creation function for your problem type.`'gacreationuniform'`

creates a random initial population with a uniform distribution. This is the default when there are no linear constraints, or when there are integer constraints. The uniform distribution is in the initial population range (`InitialPopulationRange`

). The default values for`InitialPopulationRange`

are`[-10;10]`

for every component, or`[-9999;10001]`

when there are integer constraints. These bounds are shifted and scaled to match any existing bounds`lb`

and`ub`

.**Caution**Do not use

`'gacreationuniform'`

when you have linear constraints. Otherwise, your population might not satisfy the linear constraints.`'gacreationlinearfeasible'`

is the default when there are linear constraints and no integer constraints. This choice creates a random initial population that satisfies all bounds and linear constraints. If there are linear constraints,`'gacreationlinearfeasible'`

creates many individuals on the boundaries of the constraint region, and creates a well-dispersed population.`'gacreationlinearfeasible'`

ignores`InitialPopulationRange`

.`'gacreationlinearfeasible'`

calls`linprog`

to create a feasible population with respect to bounds and linear constraints.For an example showing its behavior, see Custom Plot Function and Linear Constraints in ga.

`'gacreationnonlinearfeasible'`

is the default creation function for the`'penalty'`

nonlinear constraint algorithm. For details, see Constraint Parameters.`'gacreationuniformint'`

is the default creation function for`ga`

when the problem has integer constraints. This function applies an artificial bound to unbounded components, generates individuals uniformly at random within the bounds, and then enforces integer constraints.**Note**When your problem has integer constraints,

`ga`

and`gamultiobj`

enforce that integer constraints, bounds, and all linear constraints are feasible at each iteration. For nondefault mutation, crossover, creation, and selection functions,`ga`

and`gamultiobj`

apply extra feasibility routines after the functions operate.`'gacreationsobol'`

is the default creation function for`gamultiobj`

when the problem has integer constraints. The creation function uses a quasirandom Sobol sequence to generate a well-dispersed initial population. The population is feasible with respect to bounds, linear constraints, and integer constraints.A function handle lets you write your own creation function, which must generate data of the type that you specify in

`PopulationType`

. For example,options = optimoptions('ga','CreationFcn',@myfun);

Your creation function must have the following calling syntax.

`function Population = myfun(GenomeLength, FitnessFcn, options)`

The input arguments to the function are:

`Genomelength`

— Number of independent variables for the fitness function`FitnessFcn`

— Fitness function`options`

— Options

The function returns

`Population`

, the initial population for the genetic algorithm.Passing Extra Parameters explains how to provide additional parameters to the function.

**Caution**When you have bounds or linear constraints, ensure that your creation function creates individuals that satisfy these constraints. Otherwise, your population might not satisfy the constraints.

`InitialPopulationMatrix`

specifies an initial population for the
genetic algorithm. The default value is `[]`

, in which case
`ga`

uses the default `CreationFcn`

to
create an initial population. If you enter a nonempty array in the
`InitialPopulationMatrix`

, the array must have no more than
`PopulationSize`

rows, and exactly `nvars`

columns, where `nvars`

is the number of variables, the second input
to `ga`

or `gamultiobj`

. If you have a
*partial* initial population, meaning fewer than
`PopulationSize`

rows, then the genetic algorithm calls
`CreationFcn`

to generate the remaining individuals.

`InitialScoreMatrix`

specifies initial scores for the initial
population. The initial scores can also be partial. If your problem has nonlinear
constraints then the algorithm does not use
`InitialScoreMatrix`

.

`InitialPopulationRange`

specifies the range of the vectors in
the initial population that is generated by the `gacreationuniform`

creation function. You can set `InitialPopulationRange`

to be a
matrix with two rows and `nvars`

columns, each column of which has
the form `[lb;ub]`

, where `lb`

is the lower bound
and `ub`

is the upper bound for the entries in that coordinate. If
you specify `InitialPopulationRange`

to be a 2-by-1 vector, each
entry is expanded to a constant row of length `nvars`

. If you do
not specify an `InitialPopulationRange`

, the default is
`[-10;10]`

(`[-1e4+1;1e4+1]`

for
integer-constrained problems), modified to match any existing bounds.
`'gacreationlinearfeasible'`

ignores
`InitialPopulationRange`

. See Set Initial Range for an example.

### Fitness Scaling Options

Fitness scaling converts the raw fitness scores that are returned by the fitness function to values in a range that is suitable for the selection function.

`FitnessScalingFcn`

specifies the function that performs the
scaling. The options are

`'fitscalingrank'`

— The default fitness scaling function,`'fitscalingrank'`

, scales the raw scores based on the rank of each individual instead of its score. The rank of an individual is its position in the sorted scores. An individual with rank*r*has scaled score proportional to $$1/\sqrt{r}$$. So the scaled score of the most fit individual is proportional to 1, the scaled score of the next most fit is proportional to $$1/\sqrt{2}$$, and so on. Rank fitness scaling removes the effect of the spread of the raw scores. The square root makes poorly ranked individuals more nearly equal in score, compared to rank scoring. For more information, see Fitness Scaling.`'fitscalingprop'`

— Proportional scaling makes the scaled value of an individual proportional to its raw fitness score.`'fitscalingtop'`

— Top scaling scales the top individuals equally. You can modify the top scaling using an additional parameter:options = optimoptions('ga',... 'FitnessScalingFcn',{@fitscalingtop,quantity})

`quantity`

specifies the number of individuals that are assigned positive scaled values.`quantity`

can be an integer from 1 through the population size or a fraction from 0 through 1 specifying a fraction of the population size. The default value is`0.4`

. Each of the individuals that produce offspring is assigned an equal scaled value, while the rest are assigned the value 0. The scaled values have the form [01/n 1/n 0 0 1/n 0 0 1/n ...].`'fitscalingshiftlinear'`

— Shift linear scaling scales the raw scores so that the expectation of the fittest individual is equal to a constant called`rate`

multiplied by the average score. You can modify the`rate`

parameter:options = optimoptions('ga','FitnessScalingFcn',... {@fitscalingshiftlinear, rate})

The default value of

`rate`

is`2`

.A function handle lets you write your own scaling function.

options = optimoptions('ga','FitnessScalingFcn',@myfun);

Your scaling function must have the following calling syntax:

`function expectation = myfun(scores, nParents)`

The input arguments to the function are:

`scores`

— A vector of scalars, one for each member of the population`nParents`

— The number of parents needed from this population

The function returns

`expectation`

, a column vector of scalars of the same length as`scores`

, giving the scaled values of each member of the population. The sum of the entries of`expectation`

must equal`nParents`

.Passing Extra Parameters explains how to provide additional parameters to the function.

See Fitness Scaling for more information.

### Selection Options

Selection options specify how the genetic algorithm chooses parents for the next generation.

The `SelectionFcn`

option specifies the selection
function.

`gamultiobj`

uses only the
`'selectiontournament'`

selection function.

For `ga`

the options are:

`'selectionstochunif'`

— The`ga`

default selection function,`'selectionstochunif'`

, lays out a line in which each parent corresponds to a section of the line of length proportional to its scaled value. The algorithm moves along the line in steps of equal size. At each step, the algorithm allocates a parent from the section it lands on. The first step is a uniform random number less than the step size.`'selectionremainder'`

— Remainder selection assigns parents deterministically from the integer part of each individual's scaled value and then uses roulette selection on the remaining fractional part. For example, if the scaled value of an individual is 2.3, that individual is listed twice as a parent because the integer part is 2. After parents have been assigned according to the integer parts of the scaled values, the rest of the parents are chosen stochastically. The probability that a parent is chosen in this step is proportional to the fractional part of its scaled value.`'selectionuniform'`

— Uniform selection chooses parents using the expectations and number of parents. Uniform selection is useful for debugging and testing, but is not a very effective search strategy.`'selectionroulette'`

— Roulette selection chooses parents by simulating a roulette wheel, in which the area of the section of the wheel corresponding to an individual is proportional to the individual's expectation. The algorithm uses a random number to select one of the sections with a probability equal to its area.`'selectiontournament'`

— Tournament selection chooses each parent by choosing`size`

players at random and then choosing the best individual out of that set to be a parent.`size`

must be at least 2. The default value of`size`

is`4`

. Set`size`

to a different value as follows:options = optimoptions('ga','SelectionFcn',... {@selectiontournament,size})

When

`NonlinearConstraintAlgorithm`

is`Penalty`

,`ga`

uses`'selectiontournament'`

with size`2`

.**Note**When your problem has integer constraints,

`ga`

and`gamultiobj`

enforce that integer constraints, bounds, and all linear constraints are feasible at each iteration. For nondefault mutation, crossover, creation, and selection functions,`ga`

and`gamultiobj`

apply extra feasibility routines after the functions operate.A function handle enables you to write your own selection function.

options = optimoptions('ga','SelectionFcn',@myfun);

Your selection function must have the following calling syntax:

`function parents = myfun(expectation, nParents, options)`

`ga`

provides the input arguments`expectation`

,`nParents`

, and`options`

. Your function returns the indices of the parents.The input arguments to the function are:

`expectation`

For

`ga`

,`expectation`

is a column vector of the scaled fitness of each member of the population. The scaling comes from the Fitness Scaling Options.**Tip**You can ensure that you have a column vector by using

`expectation(:,1)`

. For example,`edit selectionstochunif`

or any of the other built-in selection functions.For

`gamultiobj`

,`expectation`

is a matrix whose first column is the negative of the rank of the individuals, and whose second column is the distance measure of the individuals. See Multiobjective Options.

`nParents`

— Number of parents to select.`options`

— Genetic algorithm`options`

.

The function returns

`parents`

, a row vector of length`nParents`

containing the indices of the parents that you select.Passing Extra Parameters explains how to provide additional parameters to the function.

See Selection for more information.

### Reproduction Options

Reproduction options specify how the genetic algorithm creates children for the next generation.

`EliteCount`

specifies the number of individuals that are
guaranteed to survive to the next generation. Set `EliteCount`

to
be a positive integer less than or equal to the population size. The default value
is `ceil(0.05*PopulationSize)`

for continuous problems, and
`0.05*(default PopulationSize)`

for mixed-integer
problems.

`CrossoverFraction`

specifies the fraction of the next
generation, other than elite children, that are produced by crossover. Set
`CrossoverFraction`

to be a fraction between
`0`

and `1`

. The default value is
`0.8`

.

See "Setting the Crossover Fraction" in Vary Mutation and Crossover for an example.

### Mutation Options

Mutation options specify how the genetic algorithm makes small random changes in
the individuals in the population to create mutation children. Mutation provides
genetic diversity and enables the genetic algorithm to search a broader space.
Specify the mutation function in the `MutationFcn`

option.

`MutationFcn`

options:

`'mutationgaussian'`

— The default mutation function for`ga`

for unconstrained problems,`'mutationgaussian'`

, adds a random number taken from a Gaussian distribution with mean 0 to each entry of the parent vector. The standard deviation of this distribution is determined by the parameters`scale`

and`shrink`

, and by the`InitialPopulationRange`

option. Set`scale`

and`shrink`

as follows:options = optimoptions('ga','MutationFcn', ... {@mutationgaussian, scale, shrink})

The

`scale`

parameter determines the standard deviation at the first generation. If you set`InitialPopulationRange`

to be a 2-by-1 vector`v`

, the initial standard deviation is the same at all coordinates of the parent vector, and is given by`scale`

`*(v(2)-v(1))`

.If you set

`InitialPopulationRange`

to be a vector`v`

with two rows and`nvars`

columns, the initial standard deviation at coordinate`i`

of the parent vector is given by`scale`

`*(v(i,2) - v(i,1))`

.The

`shrink`

parameter controls how the standard deviation shrinks as generations go by. If you set`InitialPopulationRange`

to be a 2-by-1 vector, the standard deviation at the*k*th generation,*σ*_{k}, is the same at all coordinates of the parent vector, and is given by the recursive formula$${\sigma}_{k}={\sigma}_{k-1}\left(1-\text{Shrink}\frac{k}{\text{Generations}}\right).$$

If you set

`InitialPopulationRange`

to be a vector with two rows and`nvars`

columns, the standard deviation at coordinate*i*of the parent vector at the*k*th generation,*σ*, is given by the recursive formula_{i,k}$${\sigma}_{i,k}={\sigma}_{i,k-1}\left(1-\text{Shrink}\frac{k}{\text{Generations}}\right).$$

If you set

`shrink`

to`1`

, the algorithm shrinks the standard deviation in each coordinate linearly until it reaches 0 at the last generation is reached. A negative value of`shrink`

causes the standard deviation to grow.

The default value of both

`scale`

and`shrink`

is 1.**Caution**Do not use

`mutationgaussian`

when you have bounds or linear constraints. Otherwise, your population will not necessarily satisfy the constraints. Instead, use`'mutationadaptfeasible'`

or a custom mutation function that satisfies linear constraints.`'mutationuniform'`

— Uniform mutation is a two-step process. First, the algorithm selects a fraction of the vector entries of an individual for mutation, where each entry has a probability`rate`

of being mutated. The default value of`rate`

is`0.01`

. In the second step, the algorithm replaces each selected entry by a random number selected uniformly from the range for that entry.To change the default value of

`rate`

,options = optimoptions('ga','MutationFcn', {@mutationuniform, rate})

**Caution**Do not use

`mutationuniform`

when you have bounds or linear constraints. Otherwise, your population will not necessarily satisfy the constraints. Instead, use`'mutationadaptfeasible'`

or a custom mutation function that satisfies linear constraints.`'mutationadaptfeasible'`

, the default mutation function for`gamultiobj`

and for`ga`

when there are noninteger constraints, randomly generates directions that are adaptive with respect to the last successful or unsuccessful generation. The mutation chooses a direction and step length that satisfies bounds and linear constraints.`'mutationpower'`

is the default mutation function for`ga`

and`gamultiobj`

when the problem has integer constraints. Power mutation mutates a parent,`x`

, via the following. For each component of the parent, the`i`

th component of the child is given by:`mutationChild(i) = x(i) - s(x(i) - lb(i))`

if`t < r`

`= x(i) + s(ub(i) - x(i))`

if`t >= r`

.Here,

`t`

is the scaled distance of`x(i)`

from the`i`

th component of the lower bound,`lb(i)`

.`s`

is a random variable drawn from a power distribution and`r`

is a random number drawn from a uniform distribution.This function can handle

`lb(i) = ub(i)`

. New children are generated with the`i`

th component set to`lb(i)`

, which equals`ub(i)`

. For more information on this crossover function see section 2.1 of the following reference:Kusum Deep, Krishna Pratap Singsh, M. L. Kansal, C. Mohan.

*A real coded genetic algorithm for solving integer and mixed integer optimization problems.*Applied Mathematics and Computation, 212 (2009), 505–518.**Note**When your problem has integer constraints,

`ga`

and`gamultiobj`

enforce that integer constraints, bounds, and all linear constraints are feasible at each iteration. For nondefault mutation, crossover, creation, and selection functions,`ga`

and`gamultiobj`

apply extra feasibility routines after the functions operate.`'mutationpositivebasis'`

— This mutation function is similar to orthogonal MADS steps, modified for linear constraints and bounds.A function handle enables you to write your own mutation function.

options = optimoptions('ga','MutationFcn',@myfun);

Your mutation function must have this calling syntax:

`function mutationChildren = myfun(parents, options, nvars, FitnessFcn, state, thisScore, thisPopulation)`

The arguments to the function are

`parents`

— Row vector of parents chosen by the selection function`options`

— Options`nvars`

— Number of variables`FitnessFcn`

— Fitness function`state`

— Structure containing information about the current generation. The State Structure describes the fields of`state`

.`thisScore`

— Vector of scores of the current population`thisPopulation`

— Matrix of individuals in the current population

The function returns

`mutationChildren`

—the mutated offspring—as a matrix where rows correspond to the children. The number of columns of the matrix is`nvars`

.Passing Extra Parameters explains how to provide additional parameters to the function.

**Caution**When you have bounds or linear constraints, ensure that your mutation function creates individuals that satisfy these constraints. Otherwise, your population will not necessarily satisfy the constraints.

### Crossover Options

Crossover options specify how the genetic algorithm combines two individuals, or parents, to form a crossover child for the next generation.

`CrossoverFcn`

specifies the function that performs the
crossover. You can choose from the following functions:

`'crossoverscattered'`

, the default crossover function for problems without linear constraints, creates a random binary vector and selects the genes where the vector is a 1 from the first parent, and the genes where the vector is a 0 from the second parent, and combines the genes to form the child. For example, if`p1`

and`p2`

are the parentsp1 = [a b c d e f g h] p2 = [1 2 3 4 5 6 7 8]

and the binary vector is [1 1 0 0 1 0 0 0], the function returns the following child:

child1 = [a b 3 4 e 6 7 8]

**Caution**When your problem has linear constraints,

`'crossoverscattered'`

can give a poorly distributed population. In this case, use a different crossover function, such as`'crossoverintermediate'`

.`'crossoversinglepoint'`

chooses a random integer n between 1 and`nvars`

and thenSelects vector entries numbered less than or equal to n from the first parent.

Selects vector entries numbered greater than n from the second parent.

Concatenates these entries to form a child vector.

For example, if

`p1`

and`p2`

are the parentsp1 = [a b c d e f g h] p2 = [1 2 3 4 5 6 7 8]

and the crossover point is 3, the function returns the following child.

child = [a b c 4 5 6 7 8]

**Caution**When your problem has linear constraints,

`'crossoversinglepoint'`

can give a poorly distributed population. In this case, use a different crossover function, such as`'crossoverintermediate'`

.`'crossovertwopoint'`

selects two random integers`m`

and`n`

between`1`

and`nvars`

. The function selectsVector entries numbered less than or equal to

`m`

from the first parentVector entries numbered from

`m+1`

to`n`

, inclusive, from the second parentVector entries numbered greater than

`n`

from the first parent.

The algorithm then concatenates these genes to form a single gene. For example, if

`p1`

and`p2`

are the parentsp1 = [a b c d e f g h] p2 = [1 2 3 4 5 6 7 8]

and the crossover points are 3 and 6, the function returns the following child.

child = [a b c 4 5 6 g h]

**Caution**When your problem has linear constraints,

`'crossovertwopoint'`

can give a poorly distributed population. In this case, use a different crossover function, such as`'crossoverintermediate'`

.`'crossoverintermediate'`

, the default crossover function when there are linear constraints, creates children by taking a weighted average of the parents. You can specify the weights by a single parameter,`ratio`

, which can be a scalar or a row vector of length`nvars`

. The default value of`ratio`

is a vector of all 1's. Set the`ratio`

parameter as follows.options = optimoptions('ga','CrossoverFcn', ... {@crossoverintermediate, ratio});

`'crossoverintermediate'`

creates the child from`parent1`

and`parent2`

using the following formula.child = parent1 + rand *

**Ratio*** ( parent2 - parent1)If all the entries of

`ratio`

lie in the range [0, 1], the children produced are within the hypercube defined by placing the parents at opposite vertices. If`ratio`

is not in that range, the children might lie outside the hypercube. If`ratio`

is a scalar, then all the children lie on the line between the parents.`'crossoverlaplace'`

is the default crossover function when the problem has integer constraints. The Laplace crossover generates children using either of the following formulae (chosen at random):`xOverKid = p1 + bl*abs(p1 – p2)`

`xOverKid = p2 + bl*abs(p1 – p2)`

Here,

`p1`

,`p2`

are the parents of`xOverKid`

and`bl`

is a random number generated from a Laplace distribution. For more information on this crossover function see section 2.1 of the following reference:Kusum Deep, Krishna Pratap Singsh, M. L. Kansal, C. Mohan.

*A real coded genetic algorithm for solving integer and mixed integer optimization problems.*Applied Mathematics and Computation, 212 (2009), 505–518.`'crossoverheuristic'`

returns a child that lies on the line containing the two parents, a small distance away from the parent with the better fitness value in the direction away from the parent with the worse fitness value. You can specify how far the child is from the better parent by the parameter`ratio`

. The default value of`ratio`

is 1.2. Set the`ratio`

parameter as follows.options = optimoptions('ga','CrossoverFcn',... {@crossoverheuristic,ratio});

If

`parent1`

and`parent2`

are the parents, and`parent1`

has the better fitness value, the function returns the childchild = parent2 + ratio * (parent1 - parent2);

**Caution**When your problem has linear constraints,

`'crossoverheuristic'`

can give a poorly distributed population. In this case, use a different crossover function, such as`'crossoverintermediate'`

.`'crossoverarithmetic'`

creates children that are the weighted arithmetic mean of two parents. Children are always feasible with respect to linear constraints and bounds.**Note**`ga`

and`gamultiobj`

enforce that integer constraints, bounds, and all linear constraints are feasible at each iteration. For nondefault mutation, crossover, creation, and selection functions,`ga`

and`gamultiobj`

apply extra feasibility routines after the functions operate.A function handle enables you to write your own crossover function.

options = optimoptions('ga','CrossoverFcn',@myfun);

Your crossover function must have the following calling syntax.

`xoverKids = myfun(parents, options, nvars, FitnessFcn, ... unused,thisPopulation)`

The arguments to the function are

`parents`

— Row vector of parents chosen by the selection function`options`

— options`nvars`

— Number of variables`FitnessFcn`

— Fitness function`unused`

— Placeholder not used`thisPopulation`

— Matrix representing the current population. The number of rows of the matrix is`PopulationSize`

and the number of columns is`nvars`

.

The function returns

`xoverKids`

—the crossover offspring—as a matrix where rows correspond to the children. The number of columns of the matrix is`nvars`

.Passing Extra Parameters explains how to provide additional parameters to the function.

**Caution**When you have bounds or linear constraints, ensure that your crossover function creates individuals that satisfy these constraints. Otherwise, your population will not necessarily satisfy the constraints.

### Migration Options

**Note**

*Subpopulations* refer to a form of parallel processing
for the genetic algorithm. `ga`

currently does not support
this form. In subpopulations, each worker hosts a number of individuals. These
individuals are a subpopulation. The worker evolves the subpopulation
independently of other workers, except when migration causes some individuals to
travel between workers.

Because `ga`

does not currently support this form of
parallel processing, there is no benefit to setting
`PopulationSize`

to a vector, or to setting the
`MigrationDirection`

, `MigrationInterval`

,
or `MigrationFraction`

options.

Migration options specify how individuals move between subpopulations. Migration
occurs if you set `PopulationSize`

to be a vector of length greater
than 1. When migration occurs, the best individuals from one subpopulation replace
the worst individuals in another subpopulation. Individuals that migrate from one
subpopulation to another are copied. They are not removed from the source
subpopulation.

You can control how migration occurs by the following three options:

`MigrationDirection`

— Migration can take place in one or both directions.If you set

`MigrationDirection`

to`'forward'`

, migration takes place toward the last subpopulation. That is, the*n*th subpopulation migrates into the (*n*+1)th subpopulation.If you set

`MigrationDirection`

to`'both'`

, the*n*^{th}subpopulation migrates into both the (*n*–1)th and the (*n*+1)th subpopulation.

Migration wraps at the ends of the subpopulations. That is, the last subpopulation migrates into the first, and the first may migrate into the last.

`MigrationInterval`

— Specifies how many generation pass between migrations. For example, if you set`MigrationInterval`

to`20`

, migration takes place every 20 generations.`MigrationFraction`

— Specifies how many individuals move between subpopulations.`MigrationFraction`

specifies the fraction of the smaller of the two subpopulations that moves. For example, if individuals migrate from a subpopulation of 50 individuals into a subpopulation of 100 individuals and you set`MigrationFraction`

to`0.1`

, the number of individuals that migrate is 0.1*50=5.

### Constraint Parameters

Constraint parameters refer to the nonlinear constraint solver. For details on the algorithm, see Nonlinear Constraint Solver Algorithms for Genetic Algorithm.

Choose between the nonlinear constraint algorithms by setting the
`NonlinearConstraintAlgorithm`

option to
`'auglag'`

(Augmented Lagrangian) or
`'penalty'`

(Penalty algorithm).

#### Augmented Lagrangian Genetic Algorithm

— Specifies an initial value of the penalty parameter that is used by the nonlinear constraint algorithm.`InitialPenalty`

must be greater than or equal to`InitialPenalty`

`1`

, and has a default of`10`

.— Increases the penalty parameter when the problem is not solved to required accuracy and constraints are not satisfied.`PenaltyFactor`

must be greater than`PenaltyFactor`

`1`

, and has a default of`100`

.

#### Penalty Algorithm

The penalty algorithm uses the
`'gacreationnonlinearfeasible'`

creation function by
default. This creation function uses `fmincon`

to find
feasible individuals. `'gacreationnonlinearfeasible'`

starts
`fmincon`

from a variety of initial points within the
bounds from the `InitialPopulationRange`

option. Optionally,
`'gacreationnonlinearfeasible'`

can run
`fmincon`

in parallel on the initial points.

You can specify tuning parameters for
`'gacreationnonlinearfeasible'`

using the following
name-value pairs.

Name | Value |
---|---|

`SolverOpts` | `fmincon` options, created using
`optimoptions` or
`optimset` . |

`UseParallel` | When `true` , run
`fmincon` in parallel on initial points;
default is `false` . |

`NumStartPts` | Number of start points, a positive integer up to
`sum(PopulationSize)` in value. |

Include the name-value pairs in a cell array along with
`@gacreationnonlinearfeasible`

.

`options = optimoptions('ga','CreationFcn',{``@gacreationnonlinearfeasible`

,...
'UseParallel',true,'NumStartPts',20});

### Multiobjective Options

Multiobjective options define parameters characteristic of the
`gamultiobj`

algorithm. You can specify the following
parameters:

`ParetoFraction`

— Sets the fraction of individuals to keep on the first Pareto front while the solver selects individuals from higher fronts. This option is a scalar between 0 and 1.**Note**The fraction of individuals on the first Pareto front can exceed

`ParetoFraction`

. This occurs when there are too few individuals of other ranks in step 6 of Iterations.`DistanceMeasureFcn`

— Defines a handle to the function that computes distance measure of individuals, computed in decision variable space (genotype, also termed design variable space) or in function space (phenotype). For example, the default distance measure function is`'distancecrowding'`

in function space, which is the same as`{@distancecrowding,'phenotype'}`

.“Distance” measures a crowding of each individual in a population. Choose between the following:

`'distancecrowding'`

, or the equivalent`{@distancecrowding,'phenotype'}`

— Measure the distance in fitness function space.`{@distancecrowding,'genotype'}`

— Measure the distance in decision variable space.`@distancefunction`

— Write a custom distance function using the following template.function distance = distancefunction(pop,score,options) % Uncomment one of the following two lines, or use a combination of both % y = score; % phenotype % y = pop; % genotype popSize = size(y,1); % number of individuals numData = size(y,2); % number of dimensions or fitness functions distance = zeros(popSize,1); % allocate the output % Compute distance here

`gamultiobj`

passes the population in`pop`

, the computed scores for the population in`scores`

, and the options in`options`

. Your distance function returns the distance from each member of the population to a reference, such as the nearest neighbor in some sense. For an example, edit the built-in file`distancecrowding.m`

.

### Hybrid Function Options

`ga`

Hybrid Function

A hybrid function is another minimization function that runs after the genetic
algorithm terminates. You can specify a hybrid function in the
`HybridFcn`

option. Do not use with integer problems. The
choices are

`[]`

— No hybrid function.`'fminsearch'`

— Uses the MATLAB^{®}function`fminsearch`

to perform unconstrained minimization.`'patternsearch'`

— Uses a pattern search to perform constrained or unconstrained minimization.`'fminunc'`

— Uses the Optimization Toolbox™ function`fminunc`

to perform unconstrained minimization.`'fmincon'`

— Uses the Optimization Toolbox function`fmincon`

to perform constrained minimization.

**Note**

Ensure that your hybrid function accepts your problem constraints.
Otherwise, `ga`

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

`options`

as
follows:options = optimoptions('ga',options,'HybridFcn',{@fminunc,hybridopts});

`hybridopts`

must exist before you set `options`

.See Hybrid Scheme in the Genetic Algorithm for an example. See When to Use a Hybrid Function.

`gamultiobj`

Hybrid Function

A hybrid function is another minimization function that runs after the
multiobjective genetic algorithm terminates. You can specify the hybrid function
`'fgoalattain'`

in the `HybridFcn`

option.

In use as a multiobjective hybrid function, the solver does the following:

Compute the maximum and minimum of each objective function at the solutions. For objective

*j*at solution*k*, let$$\begin{array}{c}{F}_{\mathrm{max}}(j)=\underset{k}{\mathrm{max}}{F}_{k}(j)\\ {F}_{\mathrm{min}}(j)=\underset{k}{\mathrm{min}}{F}_{k}(j).\end{array}$$

Compute the total weight at each solution

*k*,$$w(k)={\displaystyle \sum _{j}\frac{{F}_{\mathrm{max}}(j)-{F}_{k}(j)}{1+{F}_{\mathrm{max}}(j)-{F}_{\mathrm{min}}(j)}.}$$

Compute the weight for each objective function

*j*at each solution*k*,$$p(j,k)=w(k)\frac{{F}_{\mathrm{max}}(j)-{F}_{k}(j)}{1+{F}_{\mathrm{max}}(j)-{F}_{\mathrm{min}}(j)}.$$

For each solution

*k*, perform the goal attainment problem with goal vector*F*(_{k}*j*) and weight vector*p*(*j*,*k*).

For more information, see section 9.6 of Deb [3].

### Stopping Criteria Options

Stopping criteria determine what causes the algorithm to terminate. You can specify the following options:

`MaxGenerations`

— Specifies the maximum number of iterations for the genetic algorithm to perform. The default is`100*numberOfVariables`

.`MaxTime`

— Specifies the maximum time in seconds the genetic algorithm runs before stopping, 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.`FitnessLimit`

— The algorithm stops if the best fitness value is less than or equal to the value of`FitnessLimit`

. Does not apply to`gamultiobj`

.`MaxStallGenerations`

— The algorithm stops if the average relative change in the best fitness function value over`MaxStallGenerations`

is less than or equal to`FunctionTolerance`

. (If theoption is`StallTest`

`'geometricWeighted'`

, then the test is for a*geometric weighted*average relative change.) For a problem with nonlinear constraints,`MaxStallGenerations`

applies to the subproblem (see Nonlinear Constraint Solver Algorithms for Genetic Algorithm).For

`gamultiobj`

, if the geometric average of the relative change in the*spread*of the Pareto solutions over`MaxStallGenerations`

is less than`FunctionTolerance`

, and the final spread is smaller than the average spread over the last`MaxStallGenerations`

, then the algorithm stops. The geometric average coefficient is ½. The spread is a measure of the movement of the Pareto front. See gamultiobj Algorithm.`MaxStallTime`

— The algorithm stops if there is no improvement in the best fitness value for an interval of time in seconds specified by`MaxStallTime`

, as measured by`tic`

and`toc`

.`FunctionTolerance`

— The algorithm stops if the average relative change in the best fitness function value over`MaxStallGenerations`

is less than or equal to`FunctionTolerance`

. (If theoption is`StallTest`

`'geometricWeighted'`

, then the test is for a*geometric weighted*average relative change.)For

`gamultiobj`

, if the geometric average of the relative change in the*spread*of the Pareto solutions over`MaxStallGenerations`

is less than`FunctionTolerance`

, and the final spread is smaller than the average spread over the last`MaxStallGenerations`

, then the algorithm stops. The geometric average coefficient is ½. The spread is a measure of the movement of the Pareto front. See gamultiobj Algorithm.`ConstraintTolerance`

— The`ConstraintTolerance`

is not used as stopping criterion. It is used to determine the feasibility with respect to nonlinear constraints. Also,`max(sqrt(eps),ConstraintTolerance)`

determines feasibility with respect to linear constraints.

See Set Maximum Number of Generations and Stall Generations for an example.

### Output Function Options

Output functions are functions that the genetic algorithm calls at each
generation. Unlike other solvers, a `ga`

output function can not
only read the values of the state of the algorithm, but also modify those values. An
output function can also halt the solver according to conditions you set.

options = optimoptions('ga','OutputFcn',@myfun);

For multiple output functions, enter a cell array of function handles:

options = optimoptions('ga','OutputFcn',{@myfun1,@myfun2,...});

To see a template that you can use to write your own output functions, enter

`edit gaoutputfcntemplate`

at the MATLAB command line.

For an example, see Custom Output Function for Genetic Algorithm.

#### Structure of the Output Function

Your output function must have the following calling syntax:

[state,options,optchanged] = myfun(options,state,flag)

MATLAB passes the `options`

, `state`

,
and `flag`

data to your output function, and the output
function returns `state`

, `options`

, and
`optchanged`

data.

**Note**

To stop the iterations, set `state.StopFlag`

to a
nonempty character vector, such as `'y'`

.

The output function has the following input arguments:

`options`

— Options`state`

— Structure containing information about the current generation. The State Structure describes the fields of`state`

.`flag`

— Current status of the algorithm:`'init'`

— Initialization state`'iter'`

— Iteration state`'interrupt'`

— Iteration of a subproblem of a nonlinearly constrained problem for the`'auglag'`

nonlinear constraint algorithm. When`flag`

is`'interrupt'`

:The values of

`state`

fields apply to the subproblem iterations.`ga`

does not accept changes in`options`

, and ignores`optchanged`

.The

`state.NonlinIneq`

and`state.NonlinEq`

fields are not available.

`'done'`

— Final state

Passing Extra Parameters explains how to provide additional parameters to the function.

The output function returns the following arguments to
`ga`

:

`state`

— Structure containing information about the current generation. The State Structure describes the fields of`state`

. To stop the iterations, set`state.StopFlag`

to a nonempty character vector, such as`'y'`

.`options`

— Options as modified by the output function. This argument is optional.`optchanged`

— Boolean flag indicating changes to`options`

. To change`options`

for subsequent iterations, set`optchanged`

to`true`

.

#### Changing the State Structure

**Caution**

Changing the state structure carelessly can lead to inconsistent or erroneous results. Usually, you can achieve the same or better state modifications by using mutation or crossover functions, instead of changing the state structure in a plot function or output function.

`ga`

output functions can change the
`state`

structure (see The State Structure). Be careful when changing values in this
structure, as you can pass inconsistent data back to
`ga`

.

**Tip**

If your output structure changes the `Population`

field,
then be sure to update the `Score`

field, and possibly the
`Best`

, `NonlinIneq`

, or
`NonlinEq`

fields, so that they contain consistent
information.

To update the `Score`

field after changing the
`Population`

field, first calculate the fitness function
values of the population, then calculate the fitness scaling for the population.
See Fitness Scaling Options.

### Display to Command Window Options

`'Display'`

specifies how much information is displayed at the
command line while the genetic algorithm is running. The available options
are

`'final'`

(default) — The reason for stopping is displayed.`'off'`

or the equivalent`'none'`

— No output is displayed.`'iter'`

— Information is displayed at each iteration.`'diagnose'`

— Information is displayed at each iteration. In addition, the diagnostic lists some problem information and the options that have been changed from the defaults.

Both `'iter'`

and `'diagnose'`

display the
following information:

`Generation`

— Generation number`f-count`

— Cumulative number of fitness function evaluations`Best f(x)`

— Best fitness function value`Mean f(x)`

— Mean fitness function value`Stall generations`

— Number of generations since the last improvement of the fitness function

When a nonlinear constraint function has been specified, `'iter'`

and `'diagnose'`

do not display the `Mean f(x)`

,
but additionally display:

`Max Constraint`

— Maximum nonlinear constraint violation

In addition, `'iter'`

and `'diagnose'`

display
problem information before the iterative display, such as problem type and which
creation, mutation, crossover, and selection functions `ga`

or
`gamultiobj`

is using.

### Vectorize and Parallel Options (User Function Evaluation)

You can choose to have your fitness and constraint functions evaluated in serial,
parallel, or in a vectorized fashion. Set the `'UseVectorized'`

and
`'UseParallel'`

options with
`optimoptions`

.

When

`'UseVectorized'`

is`false`

(default),`ga`

calls the fitness function on one individual at a time as it loops through the population. (This assumes`'UseParallel'`

is at its default value of`false`

.)When

`'UseVectorized'`

is`true`

,`ga`

calls the fitness function on the entire population at once, in a single call to the fitness function.If there are nonlinear constraints, the fitness function and the nonlinear constraints all need to be vectorized in order for the algorithm to compute in a vectorized manner.

See Vectorize the Fitness Function for an example.

When

`UseParallel`

is`true`

,`ga`

calls the fitness function in parallel, using the parallel environment you established (see How to Use Parallel Processing in Global Optimization Toolbox). Set`UseParallel`

to`false`

(default) to compute serially.

**Note**

You cannot simultaneously use vectorized and parallel computations. If you set
`'UseParallel'`

to `true`

and
`'UseVectorized'`

to `true`

,
`ga`

evaluates your fitness and constraint functions in a
vectorized manner, not in parallel.

**How Fitness and Constraint Functions Are Evaluated**

`UseVectorized` =
`false` | `UseVectorized` =
`true` | |
---|---|---|

`UseParallel` = `false` | Serial | Vectorized |

`UseParallel` = `true` | Parallel | Vectorized |