hide long namesshow long names
hide short namesshow short names
Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int
PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

NAG Toolbox: nag_glopt_optget (e05zl)

▸▿ Contents

    1  Purpose
    2  Syntax
    3  Description
    4  References
▸▿ 5  Parameters
    6  Error Indicators and Warnings
    7  Accuracy
    8  Further Comments
    9  Example

Purpose

nag_glopt_optget (e05zl) is used to query the value of optional parameters available to supported problem solving functions in Chapter E05. Currently the following routines are supported:

Syntax

[ivalue, rvalue, cvalue, optype, ifail] = e05zl(optstr, iopts, opts)
[ivalue, rvalue, cvalue, optype, ifail] = nag_glopt_optget(optstr, iopts, opts)

Description

nag_glopt_optget (e05zl) is used to query the current values of options. It is necessary to initialize optional parameter arrays using nag_glopt_optset (e05zk) before any options are queried.
nag_glopt_optget (e05zl) will normally return either an integer, real or character value dependent upon the type associated with the optional parameter being queried. Some real and integer options also return additional information in cvalue. Whether the option queried is of integer, real or character type, and whether additional information is returned in cvalue, is indicated by the returned value of optype.
Information on optional parameter names and whether these options are real, integer or character can be found in Optional Parameters in nag_glopt_bnd_pso (e05sa), nag_glopt_nlp_pso (e05sb), nag_glopt_nlp_multistart_sqp (e05uc) and nag_glopt_nlp_multistart_sqp_lsq (e05us).

References

None.

Parameters

Compulsory Input Parameters

1:     optstr – string
A string identifying the option whose current value is required. See Optional Parameters in nag_glopt_bnd_pso (e05sa) and nag_glopt_nlp_pso (e05sb) for information on valid options. In addition, the following is a valid option:
Identify
nag_glopt_optget (e05zl) returns in cvalue the function name supplied to nag_glopt_optset (e05zk) when the optional parameter arrays iopts and opts were initialized.
2:     iopts: – 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).
3:     opts: – 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 Input Parameters

None.

Output Parameters

1:     ivalue – int64int32nag_int scalar
If the optional parameter supplied in optstr is an integer valued argument, ivalue will hold its current value.
2:     rvalue – double scalar
If the optional parameter supplied in optstr is a real valued argument, rvalue will hold its current value.
3:     cvalue – string
Note: the string returned in cvalue will never exceed 40 characters in length.
If the optional parameter supplied in optstr is a character valued argument, cvalue will hold its current value. cvalue will also contain additional information for some integer and real valued arguments, as indicated by optype.
4:     optype – int64int32nag_int scalar
Indicates whether the optional parameter supplied in optstr is an integer, real or character valued argument and hence which of ivalue, rvalue or cvalue holds the current value.
optype=1
optstr is an integer valued optional parameter, its current value has been returned in ivalue.
optype=2
optstr is a real valued optional parameter, its current value has been returned in rvalue.
optype=3
optstr is a character valued optional parameter, its current value has been returned in cvalue.
optype=4
optstr is an integer valued optional parameter, its current value has been returned in ivalue. Additional information has been returned in cvalue.
optype=5
optstr is a real valued optional parameter, its current value has been returned in rvalue. Additional information has been returned in cvalue.
5:     ifail – int64int32nag_int scalar
ifail=0 unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

Errors or warnings detected by the function:
   ifail=11
On entry, the option in optstr has not been recognized.
   ifail=41
On entry, optstr indicates a character optional parameter, but cvalue is too short to hold the stored value. The returned value will be truncated.
   ifail=61
The arrays iopts and opts have either not been initialized, have become corrupted, or are not compatible with this option setting function.
   ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
   ifail=-399
Your licence key may have expired or may not have been installed correctly.
   ifail=-999
Dynamic memory allocation failed.

Accuracy

Not applicable.

Further Comments

Some options have default values which are problem dependent. For example the option Maximum Iterations Completed for nag_glopt_bnd_pso (e05sa) has the default value 1000×ndim. If options such as this are queried before being set, or before the problem solving function has been called, they will return misleading information in ivalue or rvalue. In some cases, the value of cvalue will be set to DEFAULT to indicate that the real or integer valued optional parameter supplied in optstr is at its default value.

Example

See the example programs associated with the problem solving function you wish to use for a demonstration of how to use nag_glopt_optget (e05zl) to query options.

Open in the MATLAB editor: e05zl_example

function e05zl_example


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

npar = int64(5);
bu = [ 500,  500];
bl = [-500, -500];

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, itstr, optype, ifail] = ...
  e05zl(...
        'Maximum Iterations Completed', iopts, opts);
[ivalue, distol, cvalue, optype, ifail] = ...
  e05zl(...
        'Distance Tolerance', iopts, opts);

fprintf('\nDefault Option Queries:\n\n');
itstr = strtrim(itstr);
fprintf('Boundary                     : %s\n', boundary);
fprintf('Maximum Iterations Completed : %d (%s)\n', maxits, strtrim(cvalue));
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 good 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)
      vi = vecout(i);
      xi = x(i);
      if abs(xi) < x02aj
        vecout(i) = 0;
      else
        vecout(i) = sin(vi) + signtransfer(xi*cos(vi)/(2.0*vi), xi);
      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');

e05zl example results


Default Option Queries:

Boundary                     : FLOATING                        
Maximum Iterations Completed : 1000 ()
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
PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox
© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015