GlobalSearch and MultiStart Properties (Options)

How to Set Properties

To create a GlobalSearch or MultiStart object with nondefault properties, use name-value pairs. For example, to create a GlobalSearch object that has iterative display and runs only from feasible points with respect to bounds and inequalities, enter

gs = GlobalSearch("Display","iter", ...
    "StartPointsToRun","bounds-ineqs");

To set a property of an existing GlobalSearch or MultiStart object, use dot notation. For example, if ms is a MultiStart object, and you want to set the Display property to "iter", enter

ms.Display = "iter";

To set multiple properties of an existing object simultaneously, use the constructor (GlobalSearch or MultiStart) with name-value arguments. For example, to set the Display property to "iter" and the MaxTime property to 100, enter

ms = MultiStart(ms,Display="iter",MaxTime=100);

For more information on setting properties, see Changing Global Options.

Properties of Both Objects

You can create a MultiStart object from a GlobalSearch object and vice-versa.

The syntax for creating a new object from an existing object is:

ms = MultiStart(gs);
or
gs = GlobalSearch(ms);

The new object contains the properties that apply of the old object. This section describes those shared properties:

Display

Values for the Display property are:

  • "final" (default) — Summary results to command line after last solver run.

  • "off" — No output to command line.

  • "iter" — Summary results to command line after each local solver run.

FunctionTolerance

The FunctionTolerance property describes how close two objective function values must be for solvers to consider them identical for creating the vector of local solutions. Set FunctionTolerance to 0 to obtain the results of every local solver run. Set FunctionTolerance to a larger value to have fewer results.

Solvers consider two solutions identical if they are within XTolerance distance of each other and have objective function values within FunctionTolerance of each other. If both conditions are not met, solvers report the solutions as distinct. The tolerances are relative, not absolute. For details, see When fmincon Runs for GlobalSearch, and Create GlobalOptimSolution Object for MultiStart.

MaxTime

The MaxTime property describes a tolerance on the number of seconds since the solver began its run. Solvers halt when they see MaxTime seconds have passed since the beginning of the run. Time means wall clock as opposed to processor cycles. The default is Inf.

OutputFcn

The OutputFcn property directs the global solver to run one or more output functions after each local solver run completes. The output functions also run when the global solver starts and ends. Include a handle to an output function written in the appropriate syntax, or include a cell array of such handles. The default is an empty entry ([]). There is one built-in output function that collects all the local solutions found. To use it, set the solver parameter OutputFcn=@savelocalsolutions. See Output Functions for GlobalSearch and MultiStart.

The syntax of an output function is:

stop = outFcn(optimValues,state)

  • stop is a Boolean. When true, the algorithm stops. When false, the algorithm continues.

    Note

    A local solver can have an output function. The global solver does not necessarily stop when a local solver output function causes a local solver run to stop. If you want the global solver to stop in this case, have the global solver output function stop when optimValues.localsolution.exitflag=-1.

  • optimValues is a structure, described in optimValues Structure.

  • state is the current state of the global algorithm:

    • "init" — The global solver has not called the local solver. The fields in the optimValues structure are empty, except for localrunindex, which is 0, and funccount, which contains the number of objective and constraint function evaluations.

    • "iter" — The global solver calls output functions after each local solver run.

    • "done" — The global solver finished calling local solvers. The fields in optimValues generally have the same values as the ones from the final output function call with state="iter". However, the value of optimValues.funccount for GlobalSearch can be larger than the value in the last function call with "iter", because the GlobalSearch algorithm might have performed some function evaluations that were not part of a local solver. For more information, see GlobalSearch Algorithm.

For an example using an output function, see Custom GlobalSearch Output Function.

Note

Output and plot functions do not run when MultiStart has the UseParallel option set to true and there is an open parpool.

optimValues Structure.  The optimValues structure contains the following fields:

  • bestx — The current best point

  • bestfval — Objective function value at bestx

  • constrviolation — Maximum constraint violation. Zero for no constraint violations.

  • funccount — Total number of function evaluations

  • localrunindex — Index of the local solver run

  • localsolution — A structure containing part of the output of the local solver call: X, Fval and Exitflag

PlotFcn

The PlotFcn property directs the global solver to run one or more plot functions after each local solver run completes. Include a handle to a plot function written in the appropriate syntax, or include a cell array of such handles. The default is an empty entry ([]).

The syntax of a plot function is the same as that of an output function. For details, see OutputFcn.

There are two predefined plot functions for the global solvers:

  • @gsplotbestf plots the best objective function value.

  • @gsplotfunccount plots the number of function evaluations.

For an example using a plot function, see MultiStart Plot Function.

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.

Note

Output and plot functions do not run when MultiStart has the UseParallel option set to true and there is an open parpool.

Note

Plot functions do not support the subplot statement, because the plot function framework manages the axes. To specify multiple subplots, write separate plot functions and pass them to the solver as a cell array:

options = optimoptions("solvername",PlotFcn={@plot1,@plot2,@plot3});

Output functions support subplot, so you can include multiple plots in one function by using an output function instead of a plot function.

StartPointsToRun

The StartPointsToRun property directs the solver to exclude certain start points from being run:

  • all — Accept all start points.

  • bounds — Reject start points that do not satisfy bounds.

  • bounds-ineqs — Reject start points that do not satisfy bounds or inequality constraints.

XTolerance

The XTolerance property describes how close two points must be for solvers to consider them identical for creating the vector of local solutions. Set XTolerance to 0 to obtain the results of every local solver run. Set XTolerance to a larger value to have fewer results. Solvers compute the distance between a pair of points with norm, the Euclidean distance.

Solvers consider two solutions identical if they are within XTolerance distance of each other and have objective function values within FunctionTolerance of each other. If both conditions are not met, solvers report the solutions as distinct. The tolerances are relative, not absolute. For details, see When fmincon Runs for GlobalSearch, and Create GlobalOptimSolution Object for MultiStart.

GlobalSearch Properties

NumTrialPoints

Number of potential start points to examine in addition to x0 from the problem structure. GlobalSearch runs only those potential start points that pass several tests. For more information, see GlobalSearch Algorithm.

Default: 1000

NumStageOnePoints

Number of start points in Stage 1. For details, see Obtain Stage 1 Start Point, Run.

Default: 200

MaxWaitCycle

A positive integer tolerance appearing in several points in the algorithm.

  • If the observed penalty function of MaxWaitCycle consecutive trial points is at least the penalty threshold, then raise the penalty threshold (see PenaltyThresholdFactor).

  • If MaxWaitCycle consecutive trial points are in a basin, then update that basin's radius (see BasinRadiusFactor).

Default: 20

BasinRadiusFactor

A basin radius decreases after MaxWaitCycle consecutive start points are within the basin. The basin radius decreases by a factor of 1–BasinRadiusFactor.

Default: 0.2

DistanceThresholdFactor

A multiplier for determining whether a trial point is in an existing basin of attraction. For details, see Examine Stage 2 Trial Point to See if fmincon Runs. Default: 0.75

PenaltyThresholdFactor

Determines increase in penalty threshold. For details, see React to Large Counter Values.

Default: 0.2

MultiStart Properties

s

The UseParallel property determines whether the solver distributes start points to multiple processors:

  • false (default) — Do not run in parallel.

  • true — Run in parallel.

For the solver to run in parallel you must set up a parallel environment with parpool. For details, see How to Use Parallel Processing in Global Optimization Toolbox.