NAG Toolbox: nag_glopt_bnd_pso (e05sa)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{bl}\left(\mathbf{ndim}\right)$ – double array

2:     $\mathrm{bu}\left(\mathbf{ndim}\right)$ – double array

$\mathbf{bl}$ is $\mathbf{\ell }$, the array of lower bounds, bu is $\mathbf{u}$, the array of upper bounds. The ndim entries in bl and bu must contain the lower and upper simple (box) bounds of the variables respectively. These must be provided to initialize the sample population into a finite hypervolume, although their subsequent influence on the algorithm is user determinable (see the option Boundary in Optional Parameters).

If $\mathbf{bl}\left(i\right)=\mathbf{bu}\left(i\right)$ for any $i\in \left\{1,\dots ,\mathbf{ndim}\right\}$, variable $i$ will remain locked to $\mathbf{bl}\left(i\right)$ regardless of the Boundary option selected.

It is strongly advised that you place sensible lower and upper bounds on all variables, even if your model allows for variables to be unbounded (using the option $\mathbf{Boundary}=\mathrm{ignore}$) since these define the initial search space.

Constraints:

• $\mathbf{bl}\left(\mathit{i}\right)\le \mathbf{bu}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{ndim}$;
• $\mathbf{bl}\left(i\right)\ne \mathbf{bu}\left(i\right)$ for at least one $i\in \left\{1,\dots ,\mathbf{ndim}\right\}$.

3:     $\mathrm{objfun}$ – function handle or string containing name of m-file

objfun must, depending on the value of mode, calculate the objective function and/or calculate the gradient of the objective function for a $\mathit{ndim}$-variable vector $\mathbf{x}$. Gradients are only required if a local minimizer has been chosen which requires gradients. See the option Local Minimizer for more information.

[mode, objf, vecout, user] = objfun(mode, ndim, x, objf, vecout, nstate, user)

Input Parameters

1:     $\mathrm{mode}$ – int64int32nag_int scalar

Indicates which functionality is required.

$\mathbf{mode}=0$

$F\left(\mathbf{x}\right)$ should be returned in objf. The value of objf on entry may be used as an upper bound for the calculation. Any expected value of $F\left(\mathbf{x}\right)$ that is greater than objf may be approximated by this upper bound; that is objf can remain unaltered.

$\mathbf{mode}=1$

$\mathbf{Local\; Minimizer}=\mathrm{e04uc}$ only
First derivatives can be evaluated and returned in vecout. Any unaltered elements of vecout will be approximated using finite differences.

$\mathbf{mode}=2$

$\mathbf{Local\; Minimizer}=\mathrm{e04uc}$ only
$F\left(\mathbf{x}\right)$ must be calculated and returned in objf, and available first derivatives can be evaluated and returned in vecout. Any unaltered elements of vecout will be approximated using finite differences.

$\mathbf{mode}=5$

$F\left(\mathbf{x}\right)$ must be calculated and returned in objf. The value of objf on entry may not be used as an upper bound.

$\mathbf{mode}=6$

$\mathbf{Local\; Minimizer}=\mathrm{e04dg}$ or $\mathrm{e04kz}$ only
All first derivatives must be evaluated and returned in vecout.

$\mathbf{mode}=7$

$\mathbf{Local\; Minimizer}=\mathrm{e04dg}$ or $\mathrm{e04kz}$ only
$F\left(\mathbf{x}\right)$ must be calculated and returned in objf, and all first derivatives must be evaluated and returned in vecout.

2:     $\mathrm{ndim}$ – int64int32nag_int scalar

The number of dimensions.

3:     $\mathrm{x}\left(\mathbf{ndim}\right)$ – double array

$\mathbf{x}$, the point at which the objective function and/or its gradient are to be evaluated.

4:     $\mathrm{objf}$ – double scalar

The value of objf passed to objfun varies with the argument mode.

$\mathbf{mode}=0$

objf is an upper bound for the value of $F\left(\mathbf{x}\right)$, often equal to the best value of $F\left(\mathbf{x}\right)$ found so far by a given particle. Only objective function values less than the value of objf on entry will be used further. As such this upper bound may be used to stop further evaluation when this will only increase the objective function value above the upper bound.

$\mathbf{mode}=1$, $2$, $5$, $6$ or $7$

objf is meaningless on entry.

5:     $\mathrm{vecout}\left(\mathbf{ndim}\right)$ – double array

If $\mathbf{Local\; Minimizer}=\mathrm{e04uc}$ or $\mathrm{e04uc}$, the values of vecout are used internally to indicate whether a finite difference approximation is required. See nag_opt_nlp1_solve (e04uc).

6:     $\mathrm{nstate}$ – int64int32nag_int scalar

nstate indicates various stages of initialization throughout the function. This allows for permanent global arguments to be initialized the least number of times. For example, you may initialize a random number generator seed.

$\mathbf{nstate}=3$

SMP users only. objfun is called for the first time in a parallel region on a new thread other than the master thread. You may use this opportunity to set up any thread-dependent information in user and user.

$\mathbf{nstate}=2$

objfun is called for the very first time. You may save computational time if certain data must be read or calculated only once.

$\mathbf{nstate}=1$

objfun is called for the first time by a NAG local minimization function. You may save computational time if certain data required for the local minimizer need only be calculated at the initial point of the local minimization.

$\mathbf{nstate}=0$

Used in all other cases.

7:     $\mathrm{user}$ – Any MATLAB object

objfun is called from nag_glopt_bnd_pso (e05sa) with the object supplied to nag_glopt_bnd_pso (e05sa).

Output Parameters

1:     $\mathrm{mode}$ – int64int32nag_int scalar

If the value of mode is set to be negative, then nag_glopt_bnd_pso (e05sa) will exit as soon as possible with $\mathbf{ifail}=\mathbf{3}$ and $\mathbf{inform}=\mathbf{mode}$.

2:     $\mathrm{objf}$ – double scalar

The value of objf returned varies with the argument mode.

$\mathbf{mode}=0$

objf must be the value of $F\left(\mathbf{x}\right)$. Only values of $F\left(\mathbf{x}\right)$ strictly less than objf on entry need be accurate.

$\mathbf{mode}=1$ or $6$

Need not be set.

$\mathbf{mode}=2$, $5$ or $7$

$F\left(\mathbf{x}\right)$ must be calculated and returned in objf. The entry value of objf may not be used as an upper bound.

3:     $\mathrm{vecout}\left(\mathbf{ndim}\right)$ – double array

The required values of vecout returned to the calling function depend on the value of mode.

$\mathbf{mode}=0$ or $5$

The value of vecout need not be set.

$\mathbf{mode}=1$ or $2$

vecout can contain components of the gradient of the objective function $\frac{\partial F}{\partial x_i}$ for some $i=1,2,\dots \mathbf{ndim}$, or acceptable approximations. Any unaltered elements of vecout will be approximated using finite differences.

$\mathbf{mode}=6$ or $7$

vecout must contain the gradient of the objective function $\frac{\partial F}{\partial x_i}$ for all $i=1,2,\dots \mathbf{ndim}$. Approximation of the gradient is strongly discouraged, and no finite difference approximations will be performed internally (see nag_opt_uncon_conjgrd_comp (e04dg) and nag_opt_bounds_mod_deriv_easy (e04kz)).

4:     $\mathrm{user}$ – Any MATLAB object

4:     $\mathrm{monmod}$ – function handle or string containing name of m-file

A user-specified monitoring and modification function. monmod is called once every complete iteration after a finalization check. It may be used to modify the particle locations that will be evaluated at the next iteration. This permits the incorporation of algorithmic modifications such as including additional advection heuristics and genetic mutations. monmod is only called during the main loop of the algorithm, and as such will be unaware of any further improvement from the final local minimization. If no monitoring and/or modification is required, monmod may be string nag_glopt_bnd_pso_dummy_monmod (e05sxm)nag_glopt_bnd_pso_dummy_monmod (e05sxm) .

[x, user, inform] = monmod(ndim, npar, x, xb, fb, xbest, fbest, itt, user, inform)

Input Parameters

1:     $\mathrm{ndim}$ – int64int32nag_int scalar

The number of dimensions.

2:     $\mathrm{npar}$ – int64int32nag_int scalar

The number of particles.

3:     $\mathrm{x}\left(\mathbf{ndim},\mathbf{npar}\right)$ – double array

Note: the $i$th component of the $j$th particle, $x_j\left(i\right)$, is stored in $\mathbf{x}\left(i,j\right)$.

The npar particle locations, ${\mathbf{x}}_j$, which will currently be used during the next iteration unless altered in monmod.

4:     $\mathrm{xb}\left(\mathbf{ndim}\right)$ – double array

The location, $\tilde{\mathbf{x}}$, of the best solution yet found.

5:     $\mathrm{fb}$ – double scalar

The objective value, $\tilde{f}=F\left(\tilde{\mathbf{x}}\right)$, of the best solution yet found.

6:     $\mathrm{xbest}\left(\mathbf{ndim},\mathbf{npar}\right)$ – double array

Note: the $i$th component of the position of the $j$th particle's cognitive memory, ${\hat{x}}_j\left(i\right)$, is stored in $\mathbf{xbest}\left(i,j\right)$.

The locations currently in the cognitive memory, ${\hat{\mathbf{x}}}_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,\mathbf{npar}$ (see Algorithmic Details).

7:     $\mathrm{fbest}\left(\mathbf{npar}\right)$ – double array

The objective values currently in the cognitive memory, $F\left({\hat{\mathbf{x}}}_{\mathit{j}}\right)$, for $\mathit{j}=1,2,\dots ,\mathbf{npar}$.

8:     $\mathrm{itt}\left(6\right)$ – int64int32nag_int array

Iteration and function evaluation counters (see description of itt below).

9:     $\mathrm{user}$ – Any MATLAB object

monmod is called from nag_glopt_bnd_pso (e05sa) with the object supplied to nag_glopt_bnd_pso (e05sa).

10:   $\mathrm{inform}$ – int64int32nag_int scalar

$\mathbf{inform}=\mathbf{thread\_num}$, where thread_num is the value returned by a call of the OpenMP function OMP_GET_THREAD_NUM(). If running in serial this will always be zero.

Output Parameters

1:     $\mathrm{x}\left(\mathbf{ndim},\mathbf{npar}\right)$ – double array

Note: the $i$th component of the $j$th particle, $x_j\left(i\right)$, is stored in $\mathbf{x}\left(i,j\right)$.

The particle locations to be used during the next iteration.

2:     $\mathrm{user}$ – Any MATLAB object

3:     $\mathrm{inform}$ – int64int32nag_int scalar

Setting $\mathbf{inform}<0$ will cause near immediate exit from nag_glopt_bnd_pso (e05sa). This value will be returned as inform with $\mathbf{ifail}=\mathbf{3}$. You need not set inform unless you wish to force an exit.

5:     $\mathrm{iopts}\left(:\right)$ – int64int32nag_int array

Note: the dimension of this array is dictated by the requirements of associated functions that must have been previously called. This array must be the same array passed as argument iopts in the previous call to nag_glopt_optset (e05zk).

Optional parameter array as generated and possibly modified by calls to nag_glopt_optset (e05zk). The contents of iopts must not be modified directly between calls to nag_glopt_bnd_pso (e05sa), nag_glopt_optset (e05zk) or nag_glopt_optget (e05zl).

6:     $\mathrm{opts}\left(:\right)$ – double array

Note: the dimension of this array is dictated by the requirements of associated functions that must have been previously called. This array must be the same array passed as argument opts in the previous call to nag_glopt_optset (e05zk).

Optional parameter array as generated and possibly modified by calls to nag_glopt_optset (e05zk). The contents of opts must not be modified directly between calls to nag_glopt_bnd_pso (e05sa), nag_glopt_optset (e05zk) or nag_glopt_optget (e05zl).

Optional Input Parameters

1:     $\mathrm{ndim}$ – int64int32nag_int scalar

Default: the dimension of the arrays bl, bu. (An error is raised if these dimensions are not equal.)

$\mathit{ndim}$, the number of dimensions.

Constraint: $\mathbf{ndim}\ge 1$.

2:     $\mathrm{npar}$ – int64int32nag_int scalar

Default: $\mathbf{npar}=10\times \mathbf{ndim}$

$\mathit{npar}$, the number of particles to be used in the swarm. Assuming all particles remain within bounds, each complete iteration will perform at least npar function evaluations. Otherwise, significantly fewer objective function evaluations may be performed.

Constraint: $\mathbf{npar}\ge 5\times \mathbf{num\_threads}$, where num_threads is the value returned by the OpenMP environment variable OMP_NUM_THREADS, or num_threads is $1$ for a serial version of this function.

3:     $\mathrm{user}$ – Any MATLAB object

user is not used by nag_glopt_bnd_pso (e05sa), but is passed to objfun and monmod. Note that for large objects it may be more efficient to use a global variable which is accessible from the m-files than to use user.

Output Parameters

1:     $\mathrm{xb}\left(\mathbf{ndim}\right)$ – double array

The location of the best solution found, $\tilde{\mathbf{x}}$, in $R^{\mathit{ndim}}$.

2:     $\mathrm{fb}$ – double scalar

The objective value of the best solution, $\tilde{f}=F\left(\tilde{\mathbf{x}}\right)$.

3:     $\mathrm{iopts}\left(:\right)$ – int64int32nag_int array

Note: the dimension of this array is dictated by the requirements of associated functions that must have been previously called. This array must be the same array passed as argument iopts in the previous call to nag_glopt_optset (e05zk).

Communication array, used to store information between calls to nag_glopt_bnd_pso (e05sa).

4:     $\mathrm{opts}\left(:\right)$ – double array

Note: the dimension of this array is dictated by the requirements of associated functions that must have been previously called. This array must be the same array passed as argument opts in the previous call to nag_glopt_optset (e05zk).

Communication array, used to store information between calls to nag_glopt_bnd_pso (e05sa).

5:     $\mathrm{user}$ – Any MATLAB object

6:     $\mathrm{itt}\left(6\right)$ – int64int32nag_int array

Integer iteration counters for nag_glopt_bnd_pso (e05sa).

$\mathbf{itt}\left(1\right)$

Number of complete iterations.

$\mathbf{itt}\left(2\right)$

Number of complete iterations without improvement to the current optimum.

$\mathbf{itt}\left(3\right)$

Number of particles converged to the current optimum.

$\mathbf{itt}\left(4\right)$

Number of improvements to the optimum.

$\mathbf{itt}\left(5\right)$

Number of function evaluations performed.

$\mathbf{itt}\left(6\right)$

Number of particles reset.

7:     $\mathrm{inform}$ – int64int32nag_int scalar

Indicates which finalization criterion was reached. The possible values of inform are:

inform	Meaning
$<0$	Exit from a user-supplied subroutine.
0	nag_glopt_bnd_pso (e05sa) has detected an error and terminated.
1	The provided objective target has been achieved. (Target Objective Value).
2	The standard deviation of the location of all the particles is below the set threshold (Swarm Standard Deviation). If the solution returned is not satisfactory, you may try setting a smaller value of Swarm Standard Deviation, or try adjusting the options governing the repulsive phase (Repulsion Initialize, Repulsion Finalize).
3	The total number of particles converged (Maximum Particles Converged) to the current global optimum has reached the set limit. This is the number of particles which have moved to a distance less than Distance Tolerance from the optimum with regard to the $L^2$ norm. If the solution is not satisfactory, you may consider lowering the Distance Tolerance. However, this may hinder the global search capability of the algorithm.
4	The maximum number of iterations without improvement (Maximum Iterations Static) has been reached, and the required number of particles (Maximum Iterations Static Particles) have converged to the current optimum. Increasing either of these options will allow the algorithm to continue searching for longer. Alternatively if the solution is not satisfactory, re-starting the application several times with $\mathbf{Repeatability}=\mathrm{OFF}$ may lead to an improved solution.
5	The maximum number of iterations (Maximum Iterations Completed) has been reached. If the number of iterations since improvement is small, then a better solution may be found by increasing this limit, or by using the option Local Minimizer with corresponding exterior options. Otherwise if the solution is not satisfactory, you may try re-running the application several times with $\mathbf{Repeatability}=\mathrm{OFF}$ and a lower iteration limit, or adjusting the options governing the repulsive phase (Repulsion Initialize, Repulsion Finalize).
6	The maximum allowed number of function evaluations (Maximum Function Evaluations) has been reached. As with $\mathbf{inform}=5$, increasing this limit if the number of iterations without improvement is small, or decreasing this limit and running the algorithm multiple times with $\mathbf{Repeatability}=\mathrm{OFF}$, may provide a superior result.

8:     $\mathrm{ifail}$ – int64int32nag_int scalar

$\mathbf{ifail}=\mathbf{0}$ unless the function detects an error (see Error Indicators and Warnings).

For this reason, the value $-1\text{ or }1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended; otherwise, the recommended value is $-1$. When the value $-\mathbf{1}\text{ or }1$ is used it is essential to test the value of ifail on exit.

nag_glopt_bnd_pso (e05sa) will return $\mathbf{ifail}=\mathbf{0}$ if and only if a finalization criterion has been reached which can guarantee success. This may only happen if the option Target Objective Value has been set and reached at a point within the search domain. The finalization criterion Target Objective Value is not activated using default option settings, and must be explicitly set using nag_glopt_optset (e05zk) if required.

nag_glopt_bnd_pso (e05sa) will return $\mathbf{ifail}=\mathbf{1}$ if no error has been detected, and a finalization criterion has been achieved which cannot guarantee success. This does not indicate that the function has failed, merely that the returned solution cannot be guaranteed to be the true global optimum.

The value of inform should be examined to determine which finalization criterion was reached.

Other positive values of ifail indicate that either an error or a warning has been triggered. See Error Indicators and Warnings, Accuracy and Algorithmic Details for more information.

Error Indicators and Warnings

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

W  $\mathbf{ifail}=1$

A finalization criterion was reached that cannot guarantee success.

W  $\mathbf{ifail}=2$

If the option Target Warning has been activated, this indicates that the Target Objective Value has been achieved to specified tolerances at a sufficiently constrained point, either during the initialization phase, or during the first two iterations of the algorithm. While this is not necessarily an error, it may occur if:

(i)	The target was achieved at the first point sampled by the function. This will be the mean of the lower and upper bounds.
(ii)	The target may have been achieved at a randomly generated sample point. This will always be a possibility provided that the domain under investigation contains a point with a target objective value.
(iii)	If the Local Minimizer has been set, then a sample point may have been inside the basin of attraction of a satisfactory point. If this occurs repeatedly when the function is called, it may imply that the objective is largely unimodal, and that it may be more efficient to use the function selected as the Local Minimizer directly.

Assuming that objfun is correct, you may wish to set a better Target Objective Value, or a stricter Target Objective Tolerance.

W  $\mathbf{ifail}=3$

User requested exit during call to monmod.

User requested exit during call to objfun.

   $\mathbf{ifail}=11$

Constraint: $\mathbf{ndim}\ge 1$.

   $\mathbf{ifail}=12$

Constraint: $\mathbf{npar}\ge 5\times \mathbf{num\_threads}$, where num_threads is the value returned by the OpenMP environment variable OMP_NUM_THREADS, or num_threads is $1$ for a serial version of this function.

   $\mathbf{ifail}=14$

Constraint: $\mathbf{bu}\left(i\right)\ge \mathbf{bl}\left(i\right)$ for all $i$.

On entry, $\mathbf{bl}\left(i\right)=\mathbf{bu}\left(i\right)$ for all $i$.
Constraint: $\mathbf{bu}\left(i\right)>\mathbf{bl}\left(i\right)$ for at least one $i$.

   $\mathbf{ifail}=19$

Error $\_$ occurred whilst adjusting to exterior local minimizer options.

Error $\_$ occurred whilst adjusting to interior local minimizer options.

   $\mathbf{ifail}=21$

Either the option arrays have not been initialized for nag_glopt_bnd_pso (e05sa), or they have become corrupted.

W  $\mathbf{ifail}=32$

Derivative checks indicate possible errors in the supplied derivatives. Gradient checks may be disabled by setting $\mathbf{Verify\; Gradients}=\mathrm{OFF}$.

   $\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

   $\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: e05sa_example

function e05sa_example


fprintf('e05sa example results\n\n');

bu = [ 500,  500];
bl = [-500, -500];

npar = int64(5);

x_target = [-420.9687463599820;-420.9687463599820];
f_target = -837.9657745448674;

iopts = zeros(100, 1, 'int64');
opts  = zeros(100, 1);


% Initialize the option arrays for e05sa
[iopts, opts, ifail] = e05zk('Initialize = e05sa', iopts, opts);

% Query some default option values.
[ivalue, rvalue, boundary, optype, ifail] = ...
  e05zl(...
        'Boundary', iopts, opts);
[maxits, rvalue, itsstr, optype, ifail] = ...
  e05zl(...
        'Maximum Iterations Completed', iopts, opts);
[ivalue, distol, cvalue, optype, ifail] = ...
  e05zl(...
        'Distance Tolerance', iopts, opts);
fprintf('\nDefault Option Queries:\n\n');
fprintf('Boundary                     : %s\n', boundary);
fprintf('Maximum Iterations Completed : %d (%s)\n', maxits, strtrim(itsstr));
fprintf('Distance Tolerance           : %10.4e\n', distol);

fprintf('\n1. Solution without using coupled local minimizer.\n');

% Set various options to non-default values if required.
[iopts, opts, ifail] = e05zk(...
                             'Repeatability = On', iopts, opts);
[iopts, opts, ifail] = e05zk(...
                             'Verify Gradients = Off', iopts, opts);
[iopts, opts, ifail] = e05zk(...
                             'Boundary = Hyperspherical', iopts, opts);
[iopts, opts, ifail] = e05zk(...
                             'Maximum iterations static = 150', iopts, opts);
[iopts, opts, ifail] = e05zk(...
                             'Repulsion Initialize = 30', iopts, opts);
[iopts, opts, ifail] = e05zk(...
                             'Repulsion Finalize = 30', iopts, opts);

% Catch warnings and assume ifail=1,3 give a reasonable estimate
wstat = warning();
warning('OFF');
% Call e05sa to search for the global optimum.
[xb, fb, iopts, opts, user, itt, inform, ifail] = ...
      e05sa(bl, bu, @objfun, 'e05sxm', iopts, opts, 'npar', npar);

switch ifail
  case {0,1}
    % e05sa encountered no errors during operation,
    % and will have returned the best optimum found.
    display_result(x_target, f_target, xb,fb,itt,inform);
  case 3
    % An instruction to exit was received by e05sa from objfun or monmod.
    % The exit flag will have been returned in inform.
    display_result(x_target, f_target, xb,fb,itt,inform);
  otherwise
    % An error was detected, and a warning has been displayed
end


fprintf('\n2. Solution using coupled local minimizer e04cb.\n');

% Set an objective target
optstr = sprintf('Target Objective Value = %32.16e', f_target);
[iopts, opts, ifail] = e05zk(optstr, iopts, opts);
[iopts, opts, ifail] = e05zk(...
                          'Target Objective Tolerance = 1.0e-5', iopts, opts);
[iopts, opts, ifail] = e05zk(...
                          'Target Objective Safeguard = 1.0e-8', iopts, opts);

% Set the local minimizer to be e04cb and set corresponding options
[iopts, opts, ifail] = e05zk(...
                             'Local Minimizer = e04cb', iopts, opts);
[iopts, opts, ifail] = e05zk(...
                             'Local Interior Iterations = 10', iopts, opts);
[iopts, opts, ifail] = e05zk(...
                             'Local Exterior Iterations = 20', iopts, opts);
[iopts, opts, ifail] = e05zk(...
                             'Local Interior Tolerance = 1.0e-4', iopts, opts);
[iopts, opts, ifail] = e05zk(...
                             'Local Exterior Tolerance = 1.0e-4', iopts, opts);

% Call e05sa to search for the global optimum.
[xb, fb, iopts, opts, user, itt, inform, ifail] = ...
      e05sa(...
            bl, bu, @objfun, 'e05sxm', iopts, opts, 'npar', npar);

switch ifail
  case {0,1}
    % e05sa encountered no errors during operation,
    % and will have returned the best optimum found.
    display_result(x_target, f_target, xb,fb,itt,inform);
  case 3
    % An instruction to exit was received by e05sa from objfun or monmod.
    % The exit flag will have been returned in inform.
    display_result(x_target, f_target, xb,fb,itt,inform);
  otherwise
    % An error was detected, and a warning has been displayed
end


fprintf('\n3. Solution using coupled local minimizer e04dg.\n');

% Set the local minimizer to be e04dg and set corresponding options
[iopts, opts, ifail] = e05zk(...
                             'Local Minimizer = e04dg', iopts, opts);
[iopts, opts, ifail] = e05zk(...
                             'Local Interior Iterations = 5', iopts, opts);
[iopts, opts, ifail] = e05zk(...
                             'Local Exterior Iterations = 20', iopts, opts);

%[iopts, opts, ifail] = e05zk('Verify Gradients = off', iopts, opts);
% Call e05sa to search for the global optimum.
[xb, fb, iopts, opts, user, itt, inform, ifail] = ...
      e05sa(...
            bl, bu, @objfun, 'e05sxm', iopts, opts, 'npar', npar);

switch ifail
  case {0,1}
    % e05sa encountered no errors during operation,
    % and will have returned the best optimum found.
    display_result(x_target, f_target, xb,fb,itt,inform);
  case 3
    % An instruction to exit was received by e05sa from objfun or monmod.
    % The exit flag will have been returned in inform.
    display_result(x_target, f_target, xb,fb,itt,inform);
  otherwise
    % An error was detected, and a warning has been displayed
end

warning(wstat);


function [mode, objf, vecout, user] = ...
  objfun(mode, ndim, x, objf, vecout, nstate, user)
  % Test nstate to indicate what stage of computation has been reached.
  switch nstate
    case (2)
      % objfun is called for the very first time.
    case (-1)
      % objfun is called for the first time on a new slave thread.
      % This will never happen if running in a serial context.
    case (1)
      % objfun is called on entry to a NAG local minimiser.
    case (0)
      % This will be the normal value of NSTATE.
    otherwise
      % This is extremely unlikely, and indicates that an error has
      % occurred on the system
      mode = int64(-1);
      error('*** Error detected in objfun');
  end

  % Test mode to determine whether to calculate objf and/or objgrd.
  evalobjf = false;
  evalobjg = false;
  switch mode
    case {0,5}
      % Only the value of the objective function is needed.
      evalobjf = true;
    case {1,6}
      % Only the values of the NDIM gradients are required.
      evalobjg = true;
    case {2,7}
      % Both the objective function and the NDIM gradients are required.
      evalobjf = true;
      evalobjg = true;
    otherwise
      mode = int64(-1);
      error('*** Illegal value of mode (%d) in objfun', mode);
  end

  if evalobjf
    % Evaluate the objective function.
    objf = sum(x(1:double(ndim)).*sin(sqrt(abs(x(1:double(ndim))))));
  end

  if evalobjg
    % Calculate the gradient of the objective function,
    % and return the result in vecout.
    vecout = sqrt(abs(x));
    for i=1:double(ndim)
      if abs(x(i)) < x02aj
        vecout(i) = 0;
      else
        v = vecout(i);
        vecout(i) = sin(v) + signtransfer(x(i)*cos(v)/(2*v), x(i));
      end
    end
  end

  function [r] = signtransfer(x, y)
    if y >= 0
      r = abs(x);
    else
      r = -abs(x);
    end

function [] = display_result(x_target, f_target, xb,fb,itt,inform)

  % Display final counters.
  fprintf('\nAlgorithm Statistics\n--------------------\n');
  fprintf('Total complete iterations             : %4d\n', itt(1));
  fprintf('Complete iterations since improvement : %4d\n', itt(2));
  fprintf('Total particles converged to xb       : %4d\n', itt(3));
  fprintf('Total improvements to global optimum  : %4d\n', itt(4));
  fprintf('Total function evaluations            : %4d\n', itt(5));
  fprintf('Total particles re-initialized        : %4d\n\n', itt(6));

  % Display why finalization occurred.
  switch inform
  case 0
     fprintf('Solution Status : An error was detected by e05sa\n');
  case 1
     fprintf('Solution Status : Target value achieved\n');
  case 2
     fprintf('Solution Status : Minimum swarm standard deviation obtained\n');
  case 3
     fprintf('Solution Status : Sufficient particles converged\n');
  case 4
     fprintf('Solution Status : No improvement in preset iteration limit\n');
  case 5
     fprintf('Solution Status : Maximum complete iterations attained\n');
  case 6
     fprintf('Solution Status : Maximum function evaluations exceeded\n');
  otherwise
     fprintf('User termination case:  %d\n', inform);
  end

  % Display final objective value and location.
  fprintf('\n  Known objective optimum  : %13.5f\n', f_target);
  fprintf('  Achieved objective value : %13.5f\n\n', fb);

  title = 'Comparison between known and achieved optima.';
  clabs = {'x_target'; 'xb      '};
  ncols =  int64(80);
  indent = int64(0);
  [ifail] = x04cb(...
                  'G', 'N', [x_target, xb], 'f9.2', title, 'I', clabs, ...
                  'C', clabs, ncols, indent);
  fprintf('\n');

e05sa example results


Default Option Queries:

Boundary                     : FLOATING                        
Maximum Iterations Completed : 1000 (DEFAULT)
Distance Tolerance           : 1.0000e-04

1. Solution without using coupled local minimizer.

Algorithm Statistics
--------------------
Total complete iterations             :  395
Complete iterations since improvement :  152
Total particles converged to xb       :    2
Total improvements to global optimum  :   59
Total function evaluations            : 2773
Total particles re-initialized        :    2

Solution Status : No improvement in preset iteration limit

  Known objective optimum  :    -837.96577
  Achieved objective value :    -837.96567

 Comparison between known and achieved optima.
    x_target       xb
 1   -420.97  -420.95
 2   -420.97  -420.94


2. Solution using coupled local minimizer e04cb.

Algorithm Statistics
--------------------
Total complete iterations             :   51
Complete iterations since improvement :    1
Total particles converged to xb       :    0
Total improvements to global optimum  :   12
Total function evaluations            :  537
Total particles re-initialized        :    0

Solution Status : Target value achieved

  Known objective optimum  :    -837.96577
  Achieved objective value :    -837.96577

 Comparison between known and achieved optima.
    x_target       xb
 1   -420.97  -420.97
 2   -420.97  -420.97


3. Solution using coupled local minimizer e04dg.

Algorithm Statistics
--------------------
Total complete iterations             :    8
Complete iterations since improvement :    1
Total particles converged to xb       :    0
Total improvements to global optimum  :   10
Total function evaluations            :  120
Total particles re-initialized        :    0

Solution Status : Target value achieved

  Known objective optimum  :    -837.96577
  Achieved objective value :    -837.96561

 Comparison between known and achieved optima.
    x_target       xb
 1   -420.97  -420.94
 2   -420.97  -420.98

Algorithmic Details

Optional Parameters

• Advance Cognitive
• Advance Global
• Boundary
• Distance Scaling
• Distance Tolerance
• Function Precision
• Local Boundary Restriction
• Local Exterior Iterations
• Local Exterior Major Iterations
• Local Exterior Minor Iterations
• Local Exterior Tolerance
• Local Interior Iterations
• Local Interior Major Iterations
• Local Interior Minor Iterations
• Local Interior Tolerance
• Local Minimizer
• Maximum Function Evaluations
• Maximum Iterations Completed
• Maximum Iterations Static
• Maximum Iterations Static Particles
• Maximum Particles Converged
• Maximum Particles Reset
• Maximum Variable Velocity
• Optimize
• Repeatability
• Repulsion Finalize
• Repulsion Initialize
• Repulsion Particles
• Swarm Standard Deviation
• Target Objective
• Target Objective Safeguard
• Target Objective Tolerance
• Target Objective Value
• Target Warning
• Verify Gradients
• Weight Decrease
• Weight Initial
• Weight Initialize
• Weight Maximum
• Weight Minimum
• Weight Reset
• Weight Value

Description of the Optional Parameters

• the keywords;
• a parameter value, where the letters $a$, $i$ and $r$ denote options that take character, integer and real values respectively;
• the default value, where the symbol $\epsilon$ is a generic notation for machine precision (see nag_machine_precision (x02aj)), and $\mathit{Imax}$ represents the largest representable integer value (see nag_machine_integer_max (x02bb)).

IGNORE

The box bounds are ignored. The objective function is still evaluated at the new particle position.

RESET

The particle is re-initialized inside the domain. ${\hat{\mathbf{x}}}_j$ and ${\hat{f}}_j$ are not affected.

FLOATING

The particle position remains the same, however the objective function will not be evaluated at the next iteration. The particle will probably be advected back into the domain at the next advance due to attraction by the cognitive and global memory.

HYPERSPHERICAL

The box bounds are wrapped around an $\mathit{ndim}$-dimensional hypersphere. As such a particle leaving through a lower bound will immediately re-enter through the corresponding upper bound and vice versa. The standard distance between particles is also modified accordingly.

FIXED

The particle rests on the boundary, with the corresponding dimensional velocity set to $0.0$.

ON

When a distance is calculated between $\mathbf{x}$ and $\mathbf{y}$, a scaled $L^2$ norm is used.

$$L^2\left(\mathbf{x},\mathbf{y}\right)={\left(\sum _{\left\{i|{\mathbf{u}}_i\ne {\mathbf{\ell }}_i,i\le \mathit{ndim}\right\}}{\left(\frac{x_i-y_i}{{\mathbf{u}}_i-{\mathbf{\ell }}_i}\right)}^2\right)}^{\frac{1}{2}}\text{.}$$

OFF

Distances are calculated as the standard $L^2$ norm without any rescaling.

$$L^2\left(\mathbf{x},\mathbf{y}\right)={\left(\sum _{i=1}^{\mathit{ndim}}{\left(x_i-y_i\right)}^2\right)}^{\frac{1}{2}}\text{.}$$

OFF

No local minimization will be performed in either the INTERIOR or EXTERIOR sections of the algorithm.

nag_opt_uncon_simplex (e04cb)

Use nag_opt_uncon_simplex (e04cb) as the local minimizer. This does not require the calculation of derivatives.

On a call to objfun during a local minimization, $\mathbf{mode}=5$.

nag_opt_bounds_mod_deriv_easy (e04kz)

Use nag_opt_bounds_mod_deriv_easy (e04kz) as the local minimizer. This requires the calculation of derivatives in objfun, as indicated by mode.

The box bounds forwarded to this function from nag_glopt_bnd_pso (e05sa) will have been acted upon by Local Boundary Restriction. As such, the domain exposed may be greatly smaller than that provided to nag_glopt_bnd_pso (e05sa).

Accurate derivatives must be provided to this function, and will not be approximated internally. Each iteration of this local minimizer also requires the calculation of both the objective function and its derivative. Hence on a call to objfun during a local minimization, $\mathbf{mode}=7$.

nag_opt_bounds_quasi_func_easy (e04jy)

Use nag_opt_bounds_quasi_func_easy (e04jy) as the local minimizer. This does not require the calculation of derivatives.

On a call to objfun during a local minimization, $\mathbf{mode}=5$.

The box bounds forwarded to this function from nag_glopt_bnd_pso (e05sa) will have been acted upon by Local Boundary Restriction. As such, the domain exposed may be greatly smaller than that provided to nag_glopt_bnd_pso (e05sa).

nag_opt_uncon_conjgrd_comp (e04dg)
nag_opt_uncon_conjgrd_comp (e04dg)

Use nag_opt_uncon_conjgrd_comp (e04dg) as the local minimizer.

Accurate derivatives must be provided, and will not be approximated internally. Additionally, each call to objfun during a local minimization will require either the objective to be evaluated alone, or both the objective and its gradient to be evaluated. Hence on a call to objfun, $\mathbf{mode}=5$ or $7$.

nag_opt_nlp1_solve (e04uc)
nag_opt_nlp1_solve (e04uc)

Use nag_opt_nlp1_solve (e04uc) as the local minimizer. This operates such that any derivatives of the objective function that you cannot supply, will be approximated internally using finite differences.

Either, the objective, objective gradient, or both may be requested during a local minimization, and as such on a call to objfun, $\mathbf{mode}=1$, $2$ or $5$.

The box bounds forwarded to this function from nag_glopt_bnd_pso (e05sa) will have been acted upon by Local Boundary Restriction. As such, the domain exposed may be greatly smaller than that provided to nag_glopt_bnd_pso (e05sa).

MINIMIZE

The objective function will be minimized.

MAXIMIZE

The objective function will be maximized. This is accomplished by minimizing the negative of the objective.

$r$

Once a point is found with an objective value within the Target Objective Tolerance of $r$, nag_glopt_bnd_pso (e05sa) will exit successfully with $\mathbf{ifail}=\mathbf{0}$ and $\mathbf{inform}=1$.

OFF

The current value of $r$ will remain stored, however it will not be used as a finalization criterion.

ON

The current value of $r$ stored will be used as a finalization criterion.

DEFAULT

The stored value of $r$ will be reset to its default value ($0.0$), and this finalization criterion will be deactivated.

OFF

No error will be returned, and the function will exit normally.

ON

An error will be returned if the target objective is reached prematurely, and the function will exit with $\mathbf{ifail}=\mathbf{2}$.

OFF

No gradient checking will be performed.

ON

A cheap gradient check will be performed on both the gradients corresponding to the objective through objfun.

OBJECTIVE
FULL

A more expensive gradient check will be performed on the gradients corresponding to the objective objfun.

OFF

Weights do not decrease.

INTEREST

Weights decrease through compound interest as $w_{\mathit{IT}+1}=w_{\mathit{IT}}\left(1-W_{\mathit{val}}\right)$, where $W_{\mathit{val}}$ is the Weight Value and $\mathit{IT}$ is the current number of iterations.

LINEAR

Weights decrease linearly following $w_{\mathit{IT}+1}=w_{\mathit{IT}}-\mathit{IT}\times \left(W_{\mathit{max}}-W_{\mathit{min}}\right)/{\mathit{IT}}_{\mathit{max}}$, where $\mathit{IT}$ is the iteration number and ${\mathit{IT}}_{\mathit{max}}$ is the maximum number of iterations as set by Maximum Iterations Completed.

INITIAL

Weights are re-initialized at the initial weight if set. If Weight Initial has not been set, this will be the maximum weight.

MAXIMUM

Weights are re-initialized at the maximum weight.

RANDOMIZED

Weights are uniformly distributed in $\left(W_{\mathit{min}},W_{\mathit{max}}\right)$ or $\left(W_{\mathit{ini}},W_{\mathit{max}}\right)$ if Weight Initial has been set.