NAG Library Routine Document

e05sbf (nlp_pso)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

1:     $\mathbf{ndim}$ – IntegerInput

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

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

2:     $\mathbf{ncon}$ – IntegerInput

On entry: $\mathit{ncon}$, the number of constraints, not including box constraints.

Constraint: $\mathbf{ncon}\ge 0$.

3:     $\mathbf{npar}$ – IntegerInput

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

Suggested value: $\mathbf{npar}=10\times \mathbf{ndim}$.

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 routine.

4:     $\mathbf{xb}\left(\mathbf{ndim}\right)$ – Real (Kind=nag_wp) arrayOutput

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

5:     $\mathbf{fb}$ – Real (Kind=nag_wp)Output

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

6:     $\mathbf{cb}\left(\mathbf{ncon}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: the constraint violations of the best solution found, $\tilde{\mathbf{e}}=\mathbf{e}\left(\tilde{\mathbf{x}}\right)$. These may have been deemed to be acceptable given the tolerance and scaling of the constraints. See Sections 11 and 12.

7:     $\mathbf{bl}\left(\mathbf{ndim}+\mathbf{ncon}\right)$ – Real (Kind=nag_wp) arrayInput

8:     $\mathbf{bu}\left(\mathbf{ndim}+\mathbf{ncon}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: $\mathbf{bl}$ is $\mathbf{\ell }$, the array of lower bounds, bu is $\mathbf{u}$, the array of upper bounds. The first 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 Section 12).

The next ncon entries must contain the lower and upper bounds for any general constraints respectively.

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 and constraints, even if your model allows for unbounded variables or constraints.

Constraints:

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

9:     $\mathbf{xbest}\left(\mathbf{ndim},\mathbf{npar}\right)$ – Real (Kind=nag_wp) arrayInput/Output

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

On entry: if using $\mathbf{Start}=\mathrm{WARM}$, the initial particle positions, ${\hat{\mathbf{x}}}_j^0$.

On exit: the best positions found, ${\hat{\mathbf{x}}}_j$, by the npar particles in the swarm.

10:   $\mathbf{fbest}\left(\mathbf{npar}\right)$ – Real (Kind=nag_wp) arrayInput/Output

On entry: if using $\mathbf{Start}=\mathrm{WARM}$, objective function values, ${\hat{f}}_j^0=F\left({\hat{\mathbf{x}}}_j^0\right)$, corresponding to the npar particle locations stored in xbest.

On exit: objective function values, ${\hat{f}}_j=F\left({\hat{\mathbf{x}}}_j\right)$, corresponding to the locations returned in xbest.

11:   $\mathbf{cbest}\left(\mathbf{ncon},\mathbf{npar}\right)$ – Real (Kind=nag_wp) arrayInput/Output

Note: the $k$th constraint violation of the $j$th particle is stored in $\mathbf{cbest}\left(k,j\right)$.

On entry: if using $\mathbf{Start}=\mathrm{WARM}$, the initial constraint violations, ${\hat{\mathbf{e}}}_j^0=\mathbf{e}\left({\hat{\mathbf{x}}}_j^0\right)$, corresponding to the npar particle locations.

On exit: the final constraint violations, ${\hat{\mathbf{e}}}_j$, corresponding to the locations returned in xbest.

12:   $\mathbf{objfun}$ – Subroutine, supplied by the user.External Procedure

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.

The specification of objfun is:

Fortran Interface

Subroutine objfun ( mode, ndim, x, objf, vecout, nstate, iuser, ruser) Integer, Intent (In) :: ndim, nstate Integer, Intent (Inout) :: mode, iuser(*) Real (Kind=nag_wp), Intent (In) :: x(ndim) Real (Kind=nag_wp), Intent (Inout) :: objf, vecout(ndim), ruser(*)

C Header Interface

#include <nagmk26.h> void  objfun (Integer *mode, const Integer *ndim, const double x[], double *objf, double vecout[], const Integer *nstate, Integer iuser[], double ruser[])

1:     $\mathbf{mode}$ – IntegerInput/Output

On entry: 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{e04ucf}$ 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{e04ucf}$ 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{e04dgf}$ or $\mathrm{e04kzf}$ only
All first derivatives must be evaluated and returned in vecout.

$\mathbf{mode}=7$

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

On exit: if the value of mode is set to be negative, e05sbf will exit as soon as possible with $\mathbf{ifail}=\mathbf{3}$ and $\mathbf{inform}=\mathbf{mode}$.

2:     $\mathbf{ndim}$ – IntegerInput

On entry: the number of dimensions.

3:     $\mathbf{x}\left(\mathbf{ndim}\right)$ – Real (Kind=nag_wp) arrayInput

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

4:     $\mathbf{objf}$ – Real (Kind=nag_wp)Input/Output

On entry: 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 constraint penalised value of $F\left(\mathbf{x}\right)$ found so far by a given particle if the objective function is strictly positive (see Section 11). 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.

On exit: 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.

5:     $\mathbf{vecout}\left(\mathbf{ndim}\right)$ – Real (Kind=nag_wp) arrayInput/Output

On entry: if $\mathbf{Local\; Minimizer}=\mathrm{e04ucf}$ or $\mathrm{e04uca}$, the values of vecout are used internally to indicate whether a finite difference approximation is required. See e04ucf/e04uca.

On exit: the required values of vecout returned to the calling routine 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 e04dgf/e04dga and e04kzf).

6:     $\mathbf{nstate}$ – IntegerInput

On entry: nstate indicates various stages of initialization throughout the routine. 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 iuser and ruser.

$\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 routine. 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:     $\mathbf{iuser}\left(*\right)$ – Integer arrayUser Workspace

8:     $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) arrayUser Workspace

objfun is called with the arguments iuser and ruser as supplied to e05sbf. You should use the arrays iuser and ruser to supply information to objfun.

objfun must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which e05sbf is called. Arguments denoted as Input must not be changed by this procedure.

Note: objfun should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by e05sbf. If your code inadvertently does return any NaNs or infinities, e05sbf is likely to produce unexpected results.

13:   $\mathbf{confun}$ – Subroutine, supplied by the NAG Library or the user.External Procedure

confun must calculate any constraints other than the box constraints. If no constraints are required, confun may be the dummy constraint routine e05szm. (e05szm is included in the NAG Library). For information on how a NAG local minimizer will use confun see the documentation for e04uca.

The specification of confun is:

Fortran Interface

Subroutine confun ( mode, ncon, ndim, ldcj, needc, x, c, cjac, nstate, iuser, ruser) Integer, Intent (In) :: ncon, ndim, ldcj, needc(ncon), nstate Integer, Intent (Inout) :: mode, iuser(*) Real (Kind=nag_wp), Intent (In) :: x(ndim) Real (Kind=nag_wp), Intent (Inout) :: cjac(ldcj,ndim), ruser(*) Real (Kind=nag_wp), Intent (Out) :: c(ncon)

C Header Interface

#include <nagmk26.h> void  confun (Integer *mode, const Integer *ncon, const Integer *ndim, const Integer *ldcj, const Integer needc[], const double x[], double c[], double cjac[], const Integer *nstate, Integer iuser[], double ruser[])

1:     $\mathbf{mode}$ – IntegerInput/Output

On entry: indicates which values must be assigned during each call of confun. Only the following values need be assigned, for each value of $k\in \left\{1,\dots ,\mathbf{ncon}\right\}$ such that $\mathbf{needc}\left(k\right)>0$:

$\mathbf{mode}=0$

the constraint values $c_k\left(\mathbf{x}\right)$.

$\mathbf{mode}=1$

rows of the constraint Jacobian, $\frac{\partial c_k}{\partial x_{\mathit{i}}}\left(\mathbf{x}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{ndim}$.

$\mathbf{mode}=2$

the constraint values $c_k\left(\mathbf{x}\right)$ and the corresponding rows of the constraint Jacobian, $\frac{\partial c_k}{\partial x_{\mathit{i}}}\left(\mathbf{x}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{ndim}$.

On exit: may be set to a negative value if you wish to terminate the solution to the current problem. In this case e05sbf will terminate with $\mathbf{ifail}=\mathbf{3}$ and $\mathbf{inform}=\mathbf{mode}$ as soon as possible.

2:     $\mathbf{ncon}$ – IntegerInput

On entry: the number of constraints, not including box bounds.

3:     $\mathbf{ndim}$ – IntegerInput

On entry: the number of variables.

4:     $\mathbf{ldcj}$ – IntegerInput

On entry: the first dimension of the array cjac as declared in the (sub)program from which e05sbf is called.

5:     $\mathbf{needc}\left(\mathbf{ncon}\right)$ – Integer arrayInput

On entry: the indices of the elements of c and/or cjac that must be evaluated by confun. If $\mathbf{needc}\left(k\right)>0$, the $k$th element of c, corresponding to the values of the $k$th constraint, and/or the available elements of the $k$th row of cjac, corresponding to the derivatives of the $k$th constraint, must be evaluated at $\mathbf{x}$ (see argument mode).

6:     $\mathbf{x}\left(\mathbf{ndim}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: $\mathbf{x}$, the vector of variables at which the constraint functions and/or the available elements of the constraint Jacobian are to be evaluated.

7:     $\mathbf{c}\left(\mathbf{ncon}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: if $\mathbf{needc}\left(k\right)>0$ and $\mathbf{mode}=0$ or $2$, $\mathbf{c}\left(k\right)$ must contain the value of $c_k\left(\mathbf{x}\right)$. The remaining elements of c, corresponding to the non-positive elements of needc, need not be set.

8:     $\mathbf{cjac}\left(\mathbf{ldcj},\mathbf{ndim}\right)$ – Real (Kind=nag_wp) arrayInput/Output

Note: the derivative of the $k$th constraint with respect to the $i$th component, $\frac{\partial c_k}{\partial x_{\mathrm{i}}}$, is stored in $\mathbf{cjac}\left(k,i\right)$.

On entry: the elements of cjac are set to special values which enable e05sbf to detect whether they are changed by confun.

On exit: if $\mathbf{needc}\left(k\right)>0$ and $\mathbf{mode}=1$ or $2$, the elements of cjac corresponding to the $k$th row of the constraint Jacobian should contain the available elements of the vector $\nabla c_k$ given by

$$\nabla c_k=\left(\frac{\partial c_k}{\partial x_1},\frac{\partial c_k}{\partial x_2},\dots ,\frac{\partial c_k}{\partial x_n}\right)\text{,}$$

where $\frac{\partial c_k}{\partial x_i}$ is the partial derivative of the $k$th constraint with respect to the $i$th variable, evaluated at the point $\mathbf{x}$; elements of cjac that remain unaltered will be approximated internally using finite differences. The remaining rows of cjac, corresponding to non-positive elements of needc, need not be set.

It must be emphasized that unassigned elements of cjac are not treated as constant; they are estimated by finite differences, at nontrivial expense. An interval for each element of $\mathbf{x}$ is computed automatically at the start of the optimization. The automatic procedure can usually identify constant elements of cjac, which are then computed once only by finite differences.

9:     $\mathbf{nstate}$ – IntegerInput

On entry: nstate indicates various stages of initialization throughout the routine. This allows for permanent global arguments to be initialized a minimum number of times. For example, you may initialize a random number generator seed. Note that unless the option $\mathbf{Optimize}=\mathrm{CONSTRAINTS}$ has been set, objfun will be called before confun.

$\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 iuser and ruser.

$\mathbf{nstate}=2$

confun is called for the very first time. This argument setting allows you to save computational time if certain data must be read or calculated only once.

$\mathbf{nstate}=1$

confun is called for the first time during a NAG local minimization routine. This argument setting allows you to 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.

10:   $\mathbf{iuser}\left(*\right)$ – Integer arrayUser Workspace

11:   $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) arrayUser Workspace

confun is called with the arguments iuser and ruser as supplied to e05sbf. You should use the arrays iuser and ruser to supply information to confun.

confun must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which e05sbf is called. Arguments denoted as Input must not be changed by this procedure.

Note: confun should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by e05sbf. If your code inadvertently does return any NaNs or infinities, e05sbf is likely to produce unexpected results.

confun should be tested separately before being used in conjunction with e05sbf.

14:   $\mathbf{monmod}$ – Subroutine, supplied by the NAG Library or the user.External Procedure

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 the dummy monitoring routine e05sym. (e05sym is included in the NAG Library) .

The specification of monmod is:

Fortran Interface

Subroutine monmod ( ndim, ncon, npar, x, xb, fb, cb, xbest, fbest, cbest, itt, iuser, ruser, inform) Integer, Intent (In) :: ndim, ncon, npar, itt(7) Integer, Intent (Inout) :: iuser(*), inform Real (Kind=nag_wp), Intent (In) :: xb(ndim), fb, cb(ncon), xbest(ndim,npar), fbest(npar), cbest(ncon,npar) Real (Kind=nag_wp), Intent (Inout) :: x(ndim,npar), ruser(*)

C Header Interface

#include <nagmk26.h> void  monmod (const Integer *ndim, const Integer *ncon, const Integer *npar, double x[], const double xb[], const double *fb, const double cb[], const double xbest[], const double fbest[], const double cbest[], const Integer itt[], Integer iuser[], double ruser[], Integer *inform)

1:     $\mathbf{ndim}$ – IntegerInput

On entry: the number of dimensions.

2:     $\mathbf{ncon}$ – IntegerInput

On entry: the number of constraints.

3:     $\mathbf{npar}$ – IntegerInput

On entry: the number of particles.

4:     $\mathbf{x}\left(\mathbf{ndim},\mathbf{npar}\right)$ – Real (Kind=nag_wp) arrayInput/Output

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

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

On exit: the particle locations to be used during the next iteration.

5:     $\mathbf{xb}\left(\mathbf{ndim}\right)$ – Real (Kind=nag_wp) arrayInput

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

6:     $\mathbf{fb}$ – Real (Kind=nag_wp)Input

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

7:     $\mathbf{cb}\left(\mathbf{ncon}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: the constraint violations, $\tilde{\mathbf{e}}=\mathbf{e}\left(\tilde{\mathbf{x}}\right)$, of the best solution yet found.

8:     $\mathbf{xbest}\left(\mathbf{ndim},\mathbf{npar}\right)$ – Real (Kind=nag_wp) arrayInput

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)$.

On entry: the locations currently in the cognitive memory, ${\hat{\mathbf{x}}}_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,\mathbf{npar}$ (see Section 11).

9:     $\mathbf{fbest}\left(\mathbf{npar}\right)$ – Real (Kind=nag_wp) arrayInput

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

10:   $\mathbf{cbest}\left(\mathbf{ncon},\mathbf{npar}\right)$ – Real (Kind=nag_wp) arrayInput

Note: the $k$th constraint violation of the $j$th particle's cognitive memory is stored in $\mathbf{cbest}\left(k,j\right)$.

On entry: the constraint violations currently in the cognitive memory, $\hat{\mathbf{e}}=\mathbf{e}\left({\hat{\mathbf{x}}}_{\mathit{j}}\right)$, for $\mathit{j}=1,2,\dots ,\mathbf{npar}$, evaluated at ${\hat{\mathbf{x}}}_j$.

11:   $\mathbf{itt}\left(7\right)$ – Integer arrayInput

On entry: iteration and function evaluation counters (see description of itt below).

12:   $\mathbf{iuser}\left(*\right)$ – Integer arrayUser Workspace

13:   $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) arrayUser Workspace

monmod is called with the arguments iuser and ruser as supplied to e05sbf. You should use the arrays iuser and ruser to supply information to monmod.

14:   $\mathbf{inform}$ – IntegerInput/Output

On entry: $\mathbf{inform}=\mathbf{thread\_num}$, where thread_num is the value returned by a call of x06adf. If running in serial this will always be zero.

On exit: setting $\mathbf{inform}<0$ will cause near immediate exit from e05sbf. This value will be returned as inform with $\mathbf{ifail}=\mathbf{3}$. You need not set inform unless you wish to force an exit.

monmod must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which e05sbf is called. Arguments denoted as Input must not be changed by this procedure.

15:   $\mathbf{iopts}\left(*\right)$ – Integer arrayCommunication 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 e05zkf.

On entry: optional parameter array as generated and possibly modified by calls to e05zkf. The contents of iopts must not be modified directly between calls to e05sbf, e05zkf or e05zlf.

16:   $\mathbf{opts}\left(*\right)$ – Real (Kind=nag_wp) arrayCommunication 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 e05zkf.

On entry: optional parameter array as generated and possibly modified by calls to e05zkf. The contents of opts must not be modified directly between calls to e05sbf, e05zkf or e05zlf.

17:   $\mathbf{iuser}\left(*\right)$ – Integer arrayUser Workspace

iuser is not used by e05sbf, but is passed directly to objfun, confun and monmod and may be used to pass information to these routines.

With care, you may also write information back into iuser. This might be useful, for example, should there be a need to preserve the state of a random number generator.

With SMP-enabled versions of e05sbf the array iuser provided are classified as OpenMP shared memory. Use of iuser has to take account of this in order to preserve thread safety whenever information is written back to either of these arrays.

18:   $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) arrayUser Workspace

ruser is not used by e05sbf, but is passed directly to objfun, confun and monmod and may be used to pass information to these routines.

With care, you may also write information back into ruser. This might be useful, for example, should there be a need to preserve the state of a random number generator.

With SMP-enabled versions of e05sbf the array ruser provided are classified as OpenMP shared memory. Use of ruser has to take account of this in order to preserve thread safety whenever information is written back to either of these arrays.

19:   $\mathbf{itt}\left(7\right)$ – Integer arrayOutput

On exit: integer iteration counters for e05sbf.

$\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.

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

Number of violated constraints at completion. Note this is always calculated using the $L^1$ norm and a nonzero result does not necessarily mean that the algorithm did not find a suitably constrained point with respect to the single norm used.

20:   $\mathbf{inform}$ – IntegerOutput

On exit: indicates which finalization criterion was reached. The possible values of inform are:

inform	Meaning
$<0$	Exit from a user-supplied subroutine.
0	e05sbf 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.
7	A feasible point has been found. The objective has not been minimized, although it has been evaluated at the final solutions given in xb and xbest ($\mathbf{Optimize}=\mathrm{CONSTRAINTS}$).

If you wish to continue from the final position gained from a previous simulation with adjusted options, you may set the option $\mathbf{Start}=\mathrm{WARM}$, and pass back in the returned arrays xbest, fbest, and cbest. You should either record the returned values of xb, fb and cb for comparison, as these will not be re-used by the algorithm, or include them in xbest, fbest and cbest respectively by overwriting the entries corresponding to one particle with the relevant information.

21:   $\mathbf{ifail}$ – IntegerInput/Output

On entry: ifail must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.

On exit: the most common exit will be $\mathbf{ifail}=\mathbf{1}$.

For this reason, the value $-1\text{ or }1$ is recommended. If the output of error messages is undesirable, 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.

e05sbf returns $\mathbf{ifail}=\mathbf{0}$ if and only if a finalization criterion has been reached which can guarantee success. This may only happen if:

(i)	The option Target Objective Value has been set and has been reached at a sufficiently constrained point within the search domain.
(ii)	The option $\mathbf{Optimize}=\mathrm{CONSTRAINTS}$ has been set, and a sufficiently constrained point has been found within the search domain.

These finalization criteria are not active using default option settings, and must be explicitly set using e05zkf if required.

e05sbf 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 routine 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 Sections 6, 7 and 11 for more information.

6

Error Indicators and Warnings

$\mathbf{ifail}=1$

A finalization criterion was reached that cannot guarantee success.
On exit, $\mathbf{inform}=〈\mathit{\text{value}}〉$.

$\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 routine. 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 routine is called, it may imply that the objective is largely unimodal, and that it may be more efficient to use the routine 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.

$\mathbf{ifail}=3$

User requested exit $〈\mathit{\text{value}}〉$ during call to confun.

User requested exit $〈\mathit{\text{value}}〉$ during call to monmod.

User requested exit $〈\mathit{\text{value}}〉$ during call to objfun.

$\mathbf{ifail}=4$

Unable to locate strictly feasible point. $〈\mathit{\text{value}}〉$ constraints remain violated. This exit may be suppressed using the option Constraint Warning.

$\mathbf{ifail}=11$

On entry, $\mathbf{ndim}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ndim}\ge 1$.

$\mathbf{ifail}=12$

On entry, $\mathbf{npar}=〈\mathit{\text{value}}〉$.
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 routine.

$\mathbf{ifail}=13$

On entry, $\mathbf{ncon}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ncon}\ge 0$.

$\mathbf{ifail}=14$

On entry, $\mathbf{bl}\left(〈\mathit{\text{value}}〉\right)=〈\mathit{\text{value}}〉$ and $\mathbf{bu}\left(〈\mathit{\text{value}}〉\right)=〈\mathit{\text{value}}〉$.
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 box bounds $i$.
Constraint: $\mathbf{bu}\left(i\right)>\mathbf{bl}\left(i\right)$ for at least one box bound $i$.

$\mathbf{ifail}=17$

e05sbf has been called with $\mathbf{ncon}>0$ and the dummy constraint function e05szm. Only use e05szm with $\mathbf{ncon}=0$.

$\mathbf{ifail}=18$

The option $\mathbf{Optimize}=\mathrm{CONSTRAINTS}$ is active, however $\mathbf{ncon}=0$.

$\mathbf{ifail}=19$

Error $〈\mathit{\text{value}}〉$ occurred whilst adjusting to exterior local minimizer options.

Error $〈\mathit{\text{value}}〉$ occurred whilst adjusting to interior local minimizer options.

$\mathbf{ifail}=21$

Either the option arrays have not been initialized for e05sbf, or they have become corrupted.

$\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}=51$

Multiple SMP threads have been detected; however, the option SMP Callback Thread Safe has not been set.
Set $\mathbf{SMP\; Callback\; Thread\; Safe}=\mathrm{YES}$ if the provided callbacks are thread safe.
Set $\mathbf{SMP\; Callback\; Thread\; Safe}=\mathrm{NO}$ if the provided callbacks are not thread safe, to force serial execution.

$\mathbf{ifail}=-99$

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

See Section 3.9 in How to Use the NAG Library and its Documentation for further information.

$\mathbf{ifail}=-399$

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

See Section 3.8 in How to Use the NAG Library and its Documentation for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

Program Text (e05sbfe.f90)

10.2

Program Data

10.3

Program Results

Program Results (e05sbfe.r)

11

Algorithmic Details

12

Optional Parameters

• Advance Cognitive
• Advance Global
• Boundary
• Constraint Norm
• Constraint Scale Maximum
• Constraint Scaling
• Constraint Superiority
• Constraint Tolerance
• Constraint Warning
• 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
• Objective Scale
• Objective Scaling
• Optimize
• Repeatability
• Repulsion Finalize
• Repulsion Initialize
• Repulsion Particles
• Seed
• SMP Callback Thread Safe
• SMP Local Minimizer External
• SMP Monitor
• SMP Monmod
• SMP Subswarm
• SMP Thread Overrun
• Start
• 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

12.1

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 x02ajf), and $\mathit{Imax}$ represents the largest representable integer value (see x02bbf).

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$, ${\hat{f}}_j$ and ${\hat{\mathbf{e}}}_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$.

L1

The $L^1$ norm will be used, ${‖\mathbf{e}‖}_1=\frac{1}{\mathbf{ncon}}{\displaystyle \sum _1^{\mathbf{ncon}}}\left|e_k\right|$

L2

The $L^2$ norm will be used, ${‖\mathbf{e}‖}_2=\frac{1}{\mathbf{ncon}}\sqrt{{\displaystyle \sum _1^{\mathbf{ncon}}}{e}_k^2}$

L2SQ

The square of the $L^2$ norm will be used, ${‖\mathbf{e}‖}_{2^2}=\frac{1}{\mathbf{ncon}}{\displaystyle \sum _1^{\mathbf{ncon}}}{e}_k^2$

LMAX

The $L^{\infty }$ norm will be used, ${‖\mathbf{e}‖}_{\infty }={\displaystyle \underset{0<k\le \mathbf{ncon}}{\max }}\left(\left|e_k\right|\right)$

OFF

Neither the constraint violations nor the objective will be scaled automatically. This should only be used if the constraints and objective are similarly scaled everywhere throughout the domain.

INITIAL

The maximum of the initial cognitive memories, ${\hat{f}}_j$ and ${\hat{\mathbf{e}}}_j$, will be used to scale the objective function and constraint violations respectively.

ADAPTIVE

Initially, the maximum of the initial cognitive memories, ${\hat{f}}_j$ and ${\hat{\mathbf{e}}}_j$, will be used to scale the objective function and constraint violations respectively. If a significant change is detected in the behaviour of the constraints or the objective, these will be rescaled with respect to the current state of the cognitive memory.

OFF

No error will be returned.

ON

An error will be returned if any constraints are sufficiently violated at the end of the simulation.

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.

e04cbf

Use e04cbf as the local minimizer. This does not require the calculation of derivatives.

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

e04kzf

Use e04kzf as the local minimizer. This requires the calculation of derivatives in objfun, as indicated by mode.

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

Accurate derivatives must be provided to this routine, 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$.

e04jyf

Use e04jyf 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 routine from e05sbf will have been acted upon by Local Boundary Restriction. As such, the domain exposed may be greatly smaller than that provided to e05sbf.

e04dgf
e04dga

Use e04dga 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$.

e04ucf
e04uca

Use e04uca as the local minimizer. This operates such that any derivatives of either the objective function or the constraint Jacobian, which 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 routine from e05sbf will have been acted upon by Local Boundary Restriction. As such, the domain exposed may be greatly smaller than that provided to e05sbf.

MAXIMUM

The objective is rescaled with respect to the maximum absolute value of the objective in the cognitive and global memory.

MEAN

The objective is rescaled with respect to the mean absolute value of the objective in the cognitive and global memory.

USER

The scale remains fixed at the value set using Objective Scale.

MINIMIZE

The objective function will be minimized.

MAXIMIZE

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

CONSTRAINTS

The objective function will be ignored, and the algorithm will attempt to find a feasible point given the provided constraints. The objective function will be evaluated at the best point found with regards to constraint violations, and the final positions returned in xbest. The objective will be calculated at the best point found in terms of constraints only. Should a constrained point be found, e05sbf will exit with $\mathbf{ifail}=\mathbf{0}$ and $\mathbf{inform}=6$.

$r$

Once a point is found with an objective value within the Target Objective Tolerance of $r$, e05sbf 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 routine will exit normally.

ON

An error will be returned if the target objective is reached prematurely, and the routine 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 and those provided via the constraint Jacobian through confun.

OBJECTIVE

A more expensive gradient check will be performed on the gradients corresponding to the objective objfun. The gradients of the constraints will not be checked.

CONSTRAINTS

A more expensive check will be performed on the elements of cjac provided via confun. The objective gradient will not be checked.

FULL

A more expensive check will be performed on both the gradient of the objective and the constraint Jacobian.

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.

12.2

Description of the SMP optional parameters

YES

The callback routines have been programmed in a thread safe way. The algorithm will use OMP_NUM_THREADS threads.

NO

The callback routines are not thread safe. Setting this option will force the algorithm to run on a single thread only, and is advisable only for debugging purposes, or if you wish to parallelize your callback functions.

WARNING

This will cause an immediate exit from e05sbf with $\mathbf{ifail}=\mathbf{51}$ if multiple threads are detected. This is to inform you that you have not declared the callback functions either to be thread safe, or that they are thread unsafe and you wish the algorithm to run in serial.

MASTER

Only the master thread will attempt to find any improvement. The local minimization will be launched from the best known solution. All other threads will remain effectively idle.

ALL

The master thread will perform a local minimization from the best known solution, while all other threads will perform a local minimization from randomly generated perturbations of the best known solution, increasing the chance of an improvement. Assuming all local minimizations will take approximately the same amount of computation, this will be effectively free in terms of real time. It will however increase the number of function evaluations performed.

SINGLE

Only one thread will invoke monmod, after all threads have performed at least one sub-iteration.

ALL

Each thread will invoke monmod each time it completes a sub-iteration. If you wish to alter x using monmod you should use this option, as monmod will only receive the arrays x, xbest, fbest and cbest private to the calling thread.