Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_glopt_bnd_mcs_optset_string (e05jd)

## Purpose

nag_glopt_bnd_mcs_optset_string (e05jd) may be used to supply individual optional parameters to nag_glopt_bnd_mcs_solve (e05jb). The initialization function nag_glopt_bnd_mcs_init (e05ja) must have been called before calling nag_glopt_bnd_mcs_optset_string (e05jd).

## Syntax

[comm, ifail] = e05jd(optstr, comm)
[comm, ifail] = nag_glopt_bnd_mcs_optset_string(optstr, comm)

## Description

nag_glopt_bnd_mcs_optset_string (e05jd) may be used to supply values for optional parameters to nag_glopt_bnd_mcs_solve (e05jb). It is only necessary to call nag_glopt_bnd_mcs_optset_string (e05jd) for those parameters whose values are to be different from their default values. One call to nag_glopt_bnd_mcs_optset_string (e05jd) sets one parameter value.
Each optional parameter is defined by a single character string, of up to 72$72$ characters, consisting of one or more items. The items associated with a given optional parameter must be separated by spaces, or equals signs [ = ]$\left[=\right]$. Alphabetic characters may be upper or lower case. The string
`Static Limit = 100`
is an example of a string used to set an optional parameter. For each optional parameter the string contains one or more of the following items:
 – a mandatory keyword; – a phrase that qualifies the keyword; – a number that specifies an integer or real value. Such numbers may be up to 16$16$ contiguous characters.
For nag_glopt_bnd_mcs_optset_string (e05jd), each user-specified optional parameter is not normally printed as it is defined, but this printing may be turned on using the keyword List. Thus the statement
```[comm, ifail] = e05jd("List", comm);
```
turns on printing of this and subsequent options. Printing may be turned off again using the keyword Nolist.
Optional parameter settings are preserved following a call to nag_glopt_bnd_mcs_solve (e05jb) and so the keyword Defaults is provided to allow you to reset all the optional parameters to their default values before a subsequent call to nag_glopt_bnd_mcs_solve (e05jb).
A complete list of optional parameters, their symbolic names and default values is given in Section [Optional Parameters] in (e05jb).

None.

## Parameters

### Compulsory Input Parameters

1:     optstr – string
A string defining a single optional parameter (as described in Section [Description] and in Section [Optional Parameters] in (e05jb)). The implied data type (character, integer or real) of each value to set must match that expected by the optional parameter.
2:     comm(lcomm) – double array

None.

lcomm

### Output Parameters

1:     comm(lcomm) – double array
lcomm = 100$\mathit{lcomm}=100$.
2:     ifail – int64int32nag_int scalar
${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see [Error Indicators and Warnings]).

## Error Indicators and Warnings

Errors or warnings detected by the function:
ifail = 1${\mathbf{ifail}}=1$
Constraint: lcomm100$\mathit{lcomm}\ge 100$.
Initialization function nag_glopt_bnd_mcs_init (e05ja) has not been called.
ifail = 2${\mathbf{ifail}}=2$
The supplied optional parameter is invalid. A keyword or keyword combination was not recognized.
ifail = 3${\mathbf{ifail}}=3$
Attempt to assign an illegal value of Local Searches (lcsrch$\mathit{lcsrch}$).
Attempt to assign an illegal value of Repeatability (repeat$\mathit{repeat}$).
Attempt to assign a non-positive value of Function Evaluations Limit (nf$\mathit{nf}$):
Attempt to assign a non-positive value of Local Searches Limit (loclim$\mathit{loclim}$):
Attempt to assign a non-positive value of Static Limit (stclim$\mathit{stclim}$):
Attempt to assign an out-of-bounds value of Infinite Bound Size (infbnd$\mathit{infbnd}$):
Attempt to assign too small a value of Local Searches Tolerance (loctol$\mathit{loctol}$):
Attempt to assign too small a value of Target Objective Error (objerr$\mathit{objerr}$):
Attempt to assign too small a value of Target Objective Safeguard (objsfg$\mathit{objsfg}$):
ifail = 5${\mathbf{ifail}}=5$
The value to be set could not be parsed. Check that it specifies a valid integer or real value.
ifail = 999${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

Not applicable.

nag_glopt_bnd_mcs_optset_char (e05je), nag_glopt_bnd_mcs_optset_int (e05jf) or nag_glopt_bnd_mcs_optset_real (e05jg) may also be used to supply optional parameters to nag_glopt_bnd_mcs_solve (e05jb).

## Example

```function nag_glopt_bnd_mcs_optset_string_example
% Problem data for peaks function
prob = 'peaks';
xres = 100;
yres = 100;

bl = [-3; -3];
bu = -bl;
fglob = -6.55; % Approx.
xglob = [0.23; -1.63]; % Approx.

% Initialize nag_glopt_bnd_mcs_solve
n = length(bl);
[comm, ifail] = nag_glopt_bnd_mcs_init;

if (ifail == 0)

% Vanilla call.
disp(sprintf('\n'));
disp('Solve with no options or init.-list data');

ibound = int64(0);             % All bounds will be given;
list = zeros(n,3);             % Only need to _declare_ the init.-list
numpts = zeros(n, 1, 'int64'); % data: these will be _set_ internally.
initpt = zeros(n, 1, 'int64');

[bl, bu, listOut, numptsOut, initptOut, ...
xbest, obj, comm, userOut, ifail] = ...
nag_glopt_bnd_mcs_solve(@objective, ibound, bl, bu, list, ...
numpts, initpt, @monitor, comm);

disp(['nag_glopt_bnd_mcs_solve (no options) exited with ifail = ' num2str(ifail)]);

if (ifail == 0)
disp('xbest:');
disp(xbest);
disp(['obj = ' num2str(obj)]);
end

% Set some options. No need to reinitialize: n hasn't changed, and we
% didn't set any options above.
disp(sprintf('\n'));
disp('Solve with options and init.-list data');

% Echo the setting of opt. params.
comm = nag_glopt_bnd_mcs_optset_string('List', comm);

comm = nag_glopt_bnd_mcs_optset_string('Function Evaluations Limit = 100000', comm);
comm = nag_glopt_bnd_mcs_optset_int('Static Limit', int64(3*n), comm);

% Increase infbnd by factor of 10.
infbnd = nag_glopt_bnd_mcs_optget_real('Infinite Bound Size', comm);
comm = nag_glopt_bnd_mcs_optset_real('Infinite Bound Size', 10*infbnd, comm);

comm = nag_glopt_bnd_mcs_optset_char('Local Searches', 'on', comm);

% Set the initialization-list data.
iinit = int64(3); % We're providing the data this time:
list = zeros(n, 3);
list(:, 1) = bl; list(:, 3) = bu;
list(:, 2) = [-1; 0];
numpts = repmat(int64(3), n, 1); % 3 splitting points for each dim;
initpt = repmat(int64(2), n, 1); % 2nd pt in each row to be the 'init.' pt.

[bl, bu, listOut, numptsOut, initptOut, ...
xbest, obj, comm, userOut, ifail] = ...
nag_glopt_bnd_mcs_solve(@objective, ibound, bl, bu, list, ...
numpts, initpt, @monitor, comm, 'iinit', iinit);

disp(['nag_glopt_bnd_mcs_solve (options) exited with ifail = ' num2str(ifail)]);

if (ifail == 0)
disp('xbest:');
disp(xbest);
disp(['obj = ' num2str(obj)]);
end

end

function [f,user,inform] = objective(n,x,nstate,user)

if (n==2)
inform = int64(0);
else
inform = int64(-1);
end

if (inform >= 0)

% We're prepared to evaluate the objective at this point

if (nstate == 1)
disp(sprintf('\n'));
disp('(OBJFUN was just called for the first time)');
end

f = peaks(x(1), x(2));
end

inform = int64(0);

if (nstate == 0 || nstate == 1)
disp(sprintf('\n'))
disp('*** Begin monitoring information ***');
disp(sprintf('\n'))
end

if (nstate <= 0)
disp(['Total sub-boxes = ' num2str(icount(1))]);
disp(['Total function evaluations = ' num2str(ncall)]);
disp(['Total function evaluations used in local searches = ' num2str(icount(2))]);
disp(['Total points used in local search = ' num2str(icount(3))]);
disp(['Total sweeps through levels = ' num2str(icount(4))]);
disp(['Total splits by init. list = ' num2str(icount(5))]);
disp(['Lowest level with nonsplit boxes = ' num2str(icount(6))]);
disp(sprintf('\n'))
disp('*** End monitoring information ***');
disp(sprintf('\n'))
end
```
```

Solve with no options or init.-list data

(OBJFUN was just called for the first time)

*** Begin monitoring information ***

Total sub-boxes = 228
Total function evaluations = 197
Total function evaluations used in local searches = 88
Total points used in local search = 13
Total sweeps through levels = 12
Total splits by init. list = 5
Lowest level with nonsplit boxes = 7
Number of candidate minima in the 'shopping basket' = 2
-1.3474    0.2283
0.2045   -1.6255

*** End monitoring information ***

nag_glopt_bnd_mcs_solve (no options) exited with ifail = 0
xbest:
0.2283
-1.6255

obj = -6.5511

Solve with options and init.-list data
FUNCTION EVALUATIONS LIMIT =           100000
STATIC LIMIT =                6
INFINITE BOUND SIZE =     1.1579208923731620E+78
LOCAL SEARCHES = on

(OBJFUN was just called for the first time)

*** Begin monitoring information ***

Total sub-boxes = 146
Total function evaluations = 170
Total function evaluations used in local searches = 103
Total points used in local search = 7
Total sweeps through levels = 7
Total splits by init. list = 5
Lowest level with nonsplit boxes = 4
Number of candidate minima in the 'shopping basket' = 2
0.2283   -1.3474
-1.6255    0.2045

*** End monitoring information ***

nag_glopt_bnd_mcs_solve (options) exited with ifail = 0
xbest:
0.2283
-1.6255

obj = -6.5511

```
```function e05jd_example
% Problem data for peaks function
prob = 'peaks';
xres = 100;
yres = 100;

bl = [-3; -3];
bu = -bl;
fglob = -6.55; % Approx.
xglob = [0.23; -1.63]; % Approx.

% Initialize e05jb
n = length(bl);
[comm, ifail] = e05ja;

if (ifail == 0)

% Vanilla call.
disp(sprintf('\n'));
disp('Solve with no options or init.-list data');

ibound = int64(0);             % All bounds will be given;
list = zeros(n,3);             % Only need to _declare_ the init.-list
numpts = zeros(n, 1, 'int64'); % data: these will be _set_ internally.
initpt = zeros(n, 1, 'int64');

[bl, bu, listOut, numptsOut, initptOut, ...
xbest, obj, comm, userOut, ifail] = ...
e05jb(@objective, ibound, bl, bu, list, ...
numpts, initpt, @monitor, comm);

disp(['e05jb (no options) exited with ifail = ' num2str(ifail)]);

if (ifail == 0)
disp('xbest:');
disp(xbest);
disp(['obj = ' num2str(obj)]);
end

% Set some options. No need to reinitialize: n hasn't changed, and we
% didn't set any options above.
disp(sprintf('\n'));
disp('Solve with options and init.-list data');

% Echo the setting of opt. params.
comm = e05jd('List', comm);

comm = e05jd('Function Evaluations Limit = 100000', comm);
comm = e05jf('Static Limit', int64(3*n), comm);

% Increase infbnd by factor of 10.
infbnd = e05jl('Infinite Bound Size', comm);
comm = e05jg('Infinite Bound Size', 10*infbnd, comm);

comm = e05je('Local Searches', 'on', comm);

% Set the initialization-list data.
iinit = int64(3); % We're providing the data this time:
list = zeros(n, 3);
list(:, 1) = bl; list(:, 3) = bu;
list(:, 2) = [-1; 0];
numpts = repmat(int64(3), n, 1); % 3 splitting points for each dim;
initpt = repmat(int64(2), n, 1); % 2nd pt in each row to be the 'init.' pt.

[bl, bu, listOut, numptsOut, initptOut, ...
xbest, obj, comm, userOut, ifail] = ...
e05jb(@objective, ibound, bl, bu, list, ...
numpts, initpt, @monitor, comm, 'iinit', iinit);

disp(['e05jb (options) exited with ifail = ' num2str(ifail)]);

if (ifail == 0)
disp('xbest:');
disp(xbest);
disp(['obj = ' num2str(obj)]);
end

end

function [f,user,inform] = objective(n,x,nstate,user)

if (n==2)
inform = int64(0);
else
inform = int64(-1);
end

if (inform >= 0)

% We're prepared to evaluate the objective at this point

if (nstate == 1)
disp(sprintf('\n'));
disp('(OBJFUN was just called for the first time)');
end

f = peaks(x(1), x(2));
end
function [user,inform] = ...
boxl,boxu,nstate,user)

inform = int64(0);

if (nstate == 0 || nstate == 1)
disp(sprintf('\n'))
disp('*** Begin monitoring information ***');
disp(sprintf('\n'))
end

if (nstate <= 0)
disp(['Total sub-boxes = ' num2str(icount(1))]);
disp(['Total function evaluations = ' num2str(ncall)]);
disp(['Total function evaluations used in local searches = ' num2str(icount(2))]);
disp(['Total points used in local search = ' num2str(icount(3))]);
disp(['Total sweeps through levels = ' num2str(icount(4))]);
disp(['Total splits by init. list = ' num2str(icount(5))]);
disp(['Lowest level with nonsplit boxes = ' num2str(icount(6))]);
disp(sprintf('\n'))
disp('*** End monitoring information ***');
disp(sprintf('\n'))
end
```
```

Solve with no options or init.-list data

(OBJFUN was just called for the first time)

*** Begin monitoring information ***

Total sub-boxes = 228
Total function evaluations = 197
Total function evaluations used in local searches = 88
Total points used in local search = 13
Total sweeps through levels = 12
Total splits by init. list = 5
Lowest level with nonsplit boxes = 7
Number of candidate minima in the 'shopping basket' = 2
-1.3474    0.2283
0.2045   -1.6255

*** End monitoring information ***

e05jb (no options) exited with ifail = 0
xbest:
0.2283
-1.6255

obj = -6.5511

Solve with options and init.-list data
FUNCTION EVALUATIONS LIMIT =           100000
STATIC LIMIT =                6
INFINITE BOUND SIZE =     1.1579208923731620E+78
LOCAL SEARCHES = on

(OBJFUN was just called for the first time)

*** Begin monitoring information ***

Total sub-boxes = 146
Total function evaluations = 170
Total function evaluations used in local searches = 103
Total points used in local search = 7
Total sweeps through levels = 7
Total splits by init. list = 5
Lowest level with nonsplit boxes = 4
Number of candidate minima in the 'shopping basket' = 2
0.2283   -1.3474
-1.6255    0.2045

*** End monitoring information ***

e05jb (options) exited with ifail = 0
xbest:
0.2283
-1.6255

obj = -6.5511

```