gaoptimset

(Not recommended) Create genetic algorithm options structure

gaoptimset is not recommended. Use optimoptions instead. For more information, see Version History.

Syntax

gaoptimset

options = gaoptimset(Name,Value)

options = gaoptimset

options = gaoptimset(@ga)

options = gaoptimset(@gamultiobj)

options = gaoptimset(oldopts,Name,Value)

options = gaoptimset(oldopts,newopts)

Description

gaoptimset with no input or output arguments displays a complete list of options with their valid values. Generally, the default values appear in brackets {}.

Note

The indicated default values are not defaults for all problem types. For an updated list, evaluate optimoptions('ga') or optimoptions('gamultiobj').

options = gaoptimset(Name,Value) creates a structure named options and sets the value of 'Name1' to Value1, 'Name2' to Value2, and so on. gaoptimset sets any unspecified options to [], meaning solvers use the default option values. You can specify an option name using only enough leading characters to define the name uniquely. gaoptimset ignores case for option names. For example, 'Display', 'display', and 'Disp' are equivalent option names.

options = gaoptimset (with no input arguments) creates a structure named options that contains the options for the genetic algorithm. In this case, gaoptimset sets all option values to [], indicating to use default values.

options = gaoptimset(@ga) or options = gaoptimset(@gamultiobj) creates an options structure containing options with explicit default values for the ga or gamultiobj solver, respectively.

options = gaoptimset(oldopts,Name,Value) creates a copy of oldopts, modifying the specified options with the specified values.

options = gaoptimset(oldopts,newopts) combines an existing options structure, oldopts, with a new options structure, newopts. Any options in newopts with nonempty values overwrite the corresponding options in oldopts.

Examples

View Genetic Algorithm Options

To see all the options available for ga and gamultiobj in an options structure, run gamultiobj with no input or output arguments.

gaoptimset

          PopulationType: [ 'bitstring'      | 'custom'    | {'doubleVector'} ]
            PopInitRange: [ matrix           | {[-10;10]} ]
          PopulationSize: [ positive scalar ]
              EliteCount: [ positive scalar  | {0.05*PopulationSize} ]
       CrossoverFraction: [ positive scalar  | {0.8} ]

          ParetoFraction: [ positive scalar  | {0.35} ]

      MigrationDirection: [ 'both'           | {'forward'} ]
       MigrationInterval: [ positive scalar  | {20} ]
       MigrationFraction: [ positive scalar  | {0.2} ]

             Generations: [ positive scalar ]
               TimeLimit: [ positive scalar  | {Inf} ]
            FitnessLimit: [ scalar           | {-Inf} ]
           StallGenLimit: [ positive scalar ]
               StallTest: [ 'geometricWeighted' | {'averageChange'} ]
          StallTimeLimit: [ positive scalar  | {Inf} ]
                  TolFun: [ positive scalar ]

                  TolCon: [ positive scalar  | {1e-6} ]

       InitialPopulation: [ matrix           | {[]} ]
           InitialScores: [ column vector    | {[]} ]

      NonlinConAlgorithm: [ 'penalty' | {'auglag'} ]
          InitialPenalty: [ positive scalar | {10} ]
           PenaltyFactor: [ positive scalar | {100} ]

             CreationFcn: [ function_handle  | @gacreationuniform | @gacreationlinearfeasible ]
       FitnessScalingFcn: [ function_handle  | @fitscalingshiftlinear  | @fitscalingprop  | 
                            @fitscalingtop   | {@fitscalingrank} ]
            SelectionFcn: [ function_handle  | @selectionremainder    | @selectionuniform | 
                            @selectionroulette | @selectiontournament   | @selectionstochunif ]
            CrossoverFcn: [ function_handle  | @crossoverheuristic  | @crossoverintermediate | 
                            @crossoversinglepoint | @crossovertwopoint | @crossoverarithmetic | 
                            @crossoverscattered ]
             MutationFcn: [ function_handle  | @mutationuniform | @mutationadaptfeasible | 
                            @mutationgaussian ]
      DistanceMeasureFcn: [ function_handle  | {@distancecrowding} ]
               HybridFcn: [ @fminsearch | @patternsearch | @fminunc | @fmincon | {[]} ]

                 Display: [ 'off' | 'iter' | 'diagnose' | {'final'} ]
              OutputFcns: [ function_handle  | {[]} ]
                PlotFcns: [ function_handle  | @gaplotbestf | @gaplotbestindiv | @gaplotdistance | 
                            @gaplotexpectation | @gaplotgenealogy | @gaplotselection | @gaplotrange | 
                            @gaplotscorediversity  | @gaplotscores | @gaplotstopping  | 
                            @gaplotmaxconstr | @gaplotrankhist | @gaplotpareto | @gaplotspread | 
                            @gaplotparetodistance |{[]} ]
            PlotInterval: [ positive scalar  | {1} ]

              Vectorized: [ 'on'  | {'off'} ]

             UseParallel: [ logical scalar | true | {false} ]

Set Nondefault Genetic Algorithm Options

Set options for ga to have a starting population that includes the point [1,1] and to use the gaplotbestf plot function.

options = gaoptimset('InitialPopulation',[1 1],...
    'PlotFcns',@gaplotbestf);

Find a local minimum of the function rastriginsfcn, which is available when you run this example, using the specified options.

rng default % For reproducibility
nvar = 2;
A = [];
b = [];
Aeq = [];
beq = [];
lb = [];
ub = [];
nlconst = [];
[x,fval] = ga(@rastriginsfcn,nvar,A,b,Aeq,beq,lb,ub,nlconst,options)

ga stopped because the average change in the fitness value is less than options.FunctionTolerance.

x = 1×2

    0.0227    0.0656

fval = 
0.9442

Create Default ga Options

Use gaoptimset to create an option structure for ga with the values set to their defaults.

options = gaoptimset(@ga)

options = struct with fields:
        PopulationType: 'doubleVector'
          PopInitRange: []
        PopulationSize: '50 when numberOfVariables <= 5, else 200'
            EliteCount: '0.05*PopulationSize'
     CrossoverFraction: 0.8000
        ParetoFraction: []
    MigrationDirection: 'forward'
     MigrationInterval: 20
     MigrationFraction: 0.2000
           Generations: '100*numberOfVariables'
             TimeLimit: Inf
          FitnessLimit: -Inf
         StallGenLimit: 50
             StallTest: 'averageChange'
        StallTimeLimit: Inf
                TolFun: 1.0000e-06
                TolCon: 1.0000e-03
     InitialPopulation: []
         InitialScores: []
    NonlinConAlgorithm: 'auglag'
        InitialPenalty: 10
         PenaltyFactor: 100
          PlotInterval: 1
           CreationFcn: []
     FitnessScalingFcn: @fitscalingrank
          SelectionFcn: []
          CrossoverFcn: []
           MutationFcn: []
    DistanceMeasureFcn: []
             HybridFcn: []
               Display: 'final'
              PlotFcns: []
            OutputFcns: []
            Vectorized: 'off'
      IntegerTolerance: 1.0000e-05
           UseParallel: 0

Modify Genetic Algorithm Options

Create genetic algorithm options to return an iterative display.

oldopts = gaoptimset('Display','iter');

Modify oldopts to include the gaplotbestf plot function and a population size of 250.

options = gaoptimset(oldopts,'PlotFcns',@gaplotbestf,...
    'PopulationSize',250)

options = struct with fields:
        PopulationType: []
          PopInitRange: []
        PopulationSize: 250
            EliteCount: []
     CrossoverFraction: []
        ParetoFraction: []
    MigrationDirection: []
     MigrationInterval: []
     MigrationFraction: []
           Generations: []
             TimeLimit: []
          FitnessLimit: []
         StallGenLimit: []
             StallTest: []
        StallTimeLimit: []
                TolFun: []
                TolCon: []
     InitialPopulation: []
         InitialScores: []
    NonlinConAlgorithm: []
        InitialPenalty: []
         PenaltyFactor: []
          PlotInterval: []
           CreationFcn: []
     FitnessScalingFcn: []
          SelectionFcn: []
          CrossoverFcn: []
           MutationFcn: []
    DistanceMeasureFcn: []
             HybridFcn: []
               Display: 'iter'
              PlotFcns: @gaplotbestf
            OutputFcns: []
            Vectorized: []
      IntegerTolerance: []
           UseParallel: []

Combine Genetic Algorithm Options

Create two sets of genetic algorithm options, oldopts and newopts. Specify an iterative display and the gaplotbestf plot function for oldopts. Specify no display and a population size of 300 for newopts.

oldopts = gaoptimset('Display','iter','PlotFcns',@gaplotbestf);
newopts = gaoptimset('Display','off','PopulationSize',300);

Combine these options with newopts taking precedence.

options = gaoptimset(oldopts,newopts)

options = struct with fields:
        PopulationType: []
          PopInitRange: []
        PopulationSize: 300
            EliteCount: []
     CrossoverFraction: []
        ParetoFraction: []
    MigrationDirection: []
     MigrationInterval: []
     MigrationFraction: []
           Generations: []
             TimeLimit: []
          FitnessLimit: []
         StallGenLimit: []
             StallTest: []
        StallTimeLimit: []
                TolFun: []
                TolCon: []
     InitialPopulation: []
         InitialScores: []
    NonlinConAlgorithm: []
        InitialPenalty: []
         PenaltyFactor: []
          PlotInterval: []
           CreationFcn: []
     FitnessScalingFcn: []
          SelectionFcn: []
          CrossoverFcn: []
           MutationFcn: []
    DistanceMeasureFcn: []
             HybridFcn: []
               Display: 'off'
              PlotFcns: @gaplotbestf
            OutputFcns: []
            Vectorized: []
      IntegerTolerance: []
           UseParallel: []

Notice that the value of the Display option is the value specified in newopts.

Input Arguments

oldopts — Optimization options

structure

Optimization options, specified as a structure, such as the output of gaoptimset.

Data Types: struct

newopts — Optimization options

structure

Optimization options, specified as a structure, such as the output of gaoptimset. Any options in newopts with nonempty values overwrite the corresponding options in oldopts in this syntax:

options = gaoptimset(oldopts,newopts)

Data Types: struct

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: options = gaoptimset('Display','off','PlotFcns',@gaplotbestf)

gaoptimset creates a structure. In the following table of option names, use the name at the bottom of the description after the phrase "For an options structure," if specified. The first listed name (Option) is for the optimoptions function, which is the recommended function for setting options. For example, to specify the tolerance on nonlinear constraint violation in optimoptions you set 'ConstraintTolerance', but for gaoptimset you set 'TolCon'.

In the following table,

• Values in braces {} denote the default value.

• {}* represents the default when the problem has linear constraints, and when MutationFcn has 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.

optimoptions hides the options listed in italics; see Options that optimoptions Hides.

Options for ga and gamultiobj

Option	Description	Values
ConstraintTolerance	Determines the feasibility with respect to nonlinear constraints. Also, max(sqrt(eps),ConstraintTolerance) determines feasibility with respect to linear constraints. For an options structure, use TolCon.	Nonnegative scalar | {1e-3}
CreationFcn	Function that creates the initial population. Specify as a name of a built-in creation function or a function handle. See Population Options.	{'gacreationuniform'} | {'gacreationlinearfeasible'}* | 'gacreationnonlinearfeasible' | {'gacreationuniformint'}I* for ga | {'gacreationsobol'}I* for gamultiobj | Custom creation function
CrossoverFcn	Function that the algorithm uses to create crossover children. Specify as a name of a built-in crossover function or a function handle. See Crossover Options.	{'crossoverscattered'} for ga, {'crossoverintermediate'}* for gamultiobj | {'crossoverlaplace'}I* | 'crossoverheuristic' | 'crossoversinglepoint' | 'crossovertwopoint' | 'crossoverarithmetic' | Custom crossover function
CrossoverFraction	The fraction of the population at the next generation, not including elite children, that the crossover function creates.	Nonnegative scalar | {0.8}
Display	Level of display.	'off' | 'iter' | 'diagnose' | {'final'}
DistanceMeasureFcn	Function that computes the distance measure of individuals. Specify as a name of a built-in distance measure function or a function handle. The value applies to the decision variable or design space (genotype) or to function space (phenotype). The default 'distancecrowding' is in function space (phenotype). For gamultiobj only. See Multiobjective Options. For an options structure, use a function handle, not a name.	{'distancecrowding'} means the same as {@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.	Nonnegative 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	Function that scales the values of the fitness function. Specify as a name of a built-in scaling function or a function handle. 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 gamultiobj, the algorithm stops when the geometric average of the relative change in value of the spread over options.MaxStallGenerations generations is less than options.FunctionTolerance, and the final spread is less than the mean spread over the past options.MaxStallGenerations generations. See gamultiobj Algorithm. For an options structure, use TolFun.	Nonnegative scalar | {1e-6} for ga, {1e-4} for gamultiobj
HybridFcn	I* Function that continues the optimization after ga terminates. Specify as a name or a function handle. Alternatively, a cell array specifying the hybrid function and its options. See ga Hybrid Function. For gamultiobj, the only hybrid function is @fgoalattain. See gamultiobj Hybrid Function. When the problem has integer constraints, you cannot use a hybrid function. See When to Use a Hybrid Function.	Function name or 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 the 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 an options structure, 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 an options structure, 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	Initial scores used to determine fitness. Has up to PopulationSize rows and 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 an options structure, use InitialScores.	Column vector for single objective | matrix for multiobjective | {[]}
MaxGenerations	Maximum number of iterations before the algorithm halts. For an options structure, use Generations.	Nonnegative 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 gamultiobj, the algorithm stops when the geometric average of the relative change in value of the spread over options.MaxStallGenerations generations is less than options.FunctionTolerance, and the final spread is less than the mean spread over the past options.MaxStallGenerations generations. See gamultiobj Algorithm. For an options structure, use StallGenLimit.	Nonnegative 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 an options structure, use StallTimeLimit.	Positive scalar | {Inf}
MaxTime	The algorithm stops after running for 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 an options structure, use TimeLimit.	Nonnegative scalar | {Inf}
MigrationDirection	Direction of migration. See Migration Options.	'both' | {'forward'}
MigrationFraction	Scalar from 0 through 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	Function that produces mutation children. Specify as a name of a built-in mutation function or a function handle. See Mutation Options.	{'mutationgaussian'} for ga without constraints | {'mutationadaptfeasible'}* for gamultiobj and for ga with constraints | {'mutationpower'}I* | 'mutationpositivebasis' | 'mutationuniform' | Custom mutation function
NonlinearConstraintAlgorithm	Nonlinear constraint algorithm. See Nonlinear Constraint Solver Algorithms for Genetic Algorithm. Option unchangeable for gamultiobj. For an options structure, use NonlinConAlgorithm.	{'auglag'} for ga, {'penalty'} for gamultiobj
OutputFcn	Functions that ga calls at each iteration. Specify as a function handle or a cell array of function handles. See Output Function Options. For an options structure, use OutputFcns.	Function handle or cell array of function handles | {[]}
ParetoFraction	Scalar from 0 through 1 specifying the fraction of individuals to keep on the first Pareto front while the solver selects individuals from higher fronts, for gamultiobj only. See Multiobjective Options.	Scalar | {0.35}
PenaltyFactor	NM I* Penalty update parameter.	Positive scalar | {100}
PlotFcn	Function that plots data computed by the algorithm. Specify as a name of a built-in plot function, a function handle, or a cell array of built-in names or function handles. See Plot Options. For an options structure, 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	Function that selects parents of crossover and mutation children. Specify as a name of a built-in selection function or a function handle. 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 in Global Optimization Toolbox.	true | {false}
UseVectorized	Specifies whether functions are vectorized. See Vectorize and Parallel Options (User Function Evaluation) and Vectorize the Fitness Function. For an options structure, use Vectorized with the values 'on' or 'off'.	true | {false}

Output Arguments

options — Optimization options

structure

Optimization options, returned as a structure.

Version History

Introduced before R2006a

R2018b: gaoptimset is not recommended

To set options, the gaoptimset, psoptimset, and saoptimset functions are not recommended. Instead, use optimoptions.

The main difference between using optimoptions and the other functions is that you include the solver name as the first argument in optimoptions. For example, to set an iterative display in ga:

options = optimoptions('ga','Display','iter');
% instead of
options = gaoptimset('Display','iter');

The other difference is that some option names have changed. You can continue to use the old names in optimoptions. For details, see Options Changes in R2016a.

optimoptions offers these advantages over the other functions:

• optimoptions provides better automatic code suggestions and completions, especially in the Live Editor.

• You can use a single option-setting function instead of a variety of functions.

There are no plans to remove gaoptimset, psoptimset, and saoptimset at this time.