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_fit_opt_set (e02zk)

## Purpose

nag_fit_opt_set (e02zk) either initializes or resets the optional parameter arrays or sets a single optional parameter for supported problem solving functions in Chapter E02. Currently, only nag_fit_2dspline_ts_sctr (e02jd) is supported.

## Syntax

[iopts, opts, ifail] = e02zk(optstr, iopts, opts, 'liopts', liopts, 'lopts', lopts)
[iopts, opts, ifail] = nag_fit_opt_set(optstr, iopts, opts, 'liopts', liopts, 'lopts', lopts)

## Description

nag_fit_opt_set (e02zk) has three purposes: to initialize optional parameter arrays, to reset all optional parameters to their default values or to set a single optional parameter to a user-supplied value.
Optional parameters and their values are, in general, presented as a character string, optstr, of the form ‘option = optval$\text{}=\mathit{optval}$’; alphabetic characters can be supplied in either upper or lower case. Both option and optval$\mathit{optval}$ may consist of one or more tokens separated by white space. The tokens that comprise optval$\mathit{optval}$ will normally be either an integer, real or character value as defined in the description of the specific optional argument. In addition all optional parameters can take an optval$\mathit{optval}$ ‘DEFAULT’ which resets the optional parameter to its default value.
It is imperative that optional parameter arrays are initialized before any options are set, before the relevant problem solving function is called and before any options are queried using nag_fit_opt_get (e02zl). To initialize the optional parameter arrays iopts and opts for a specific problem solving function, the option Initialize is used with optval$\mathit{optval}$ identifying the problem solving function to be called, via its short name. For example, to initialize optional parameter arrays to be passed to nag_fit_2dspline_ts_sctr (e02jd), nag_fit_opt_set (e02zk) is called as follows:
```[iopts, opts, ifail] = e02zk('Initialize = e02jd', iopts, opts);
```
Information relating to available option names and their corresponding valid values is given in Section [Optional Parameters] in (e02jd).

None.

## Parameters

### Compulsory Input Parameters

1:     optstr – string
A string identifying the option to be set.
Initialize = function name$\mathbf{Initialize}=\mathit{function name}$
Initialize the optional parameter arrays iopts and opts for use with function function name$\mathit{function name}$, where function name$\mathit{function name}$ is the short name of the problem solving function you wish to use.
Defaults$\mathbf{Defaults}$
Resets all options to their default values.
option = optval$\mathit{option}=\mathit{optval}$
See Section [Optional Parameters] in (e02jd) for details of valid values for option and optval. The equals sign ( = $=$) delimiter must be used to separate the option from its optval.
The processing of optstr does not depend on its case. Each token in the option and optval component must be separated by at least one space.
2:     iopts(liopts) – int64int32nag_int array
liopts, the dimension of the array, must satisfy the constraint unless otherwise stated in the documentation for a specific, supported, problem solving function, liopts100${\mathbf{liopts}}\ge 100$.
Optional parameter array.
If optstr has the form Initialize = function name${\mathbf{Initialize}}=\mathit{function name}$, the contents of iopts need not be set.
Otherwise, iopts must not have been altered since the last call to nag_fit_opt_set (e02zk), nag_fit_opt_get (e02zl) or the selected problem solving function or suite of functions.
3:     opts(lopts) – double array
lopts, the dimension of the array, must satisfy the constraint unless otherwise stated in the documentation for a specific, supported, problem solving function, lopts100${\mathbf{lopts}}\ge 100$.
Optional parameter array.
If optstr has the form Initialize = function name${\mathbf{Initialize}}=\mathit{function name}$, the contents of opts need not be set.
Otherwise, opts must not have been altered since the last call to nag_fit_opt_set (e02zk), nag_fit_opt_get (e02zl) or the selected problem solving function or suite of functions.

### Optional Input Parameters

1:     liopts – int64int32nag_int scalar
Default: The dimension of the array iopts.
The length of the array iopts.
Constraint: unless otherwise stated in the documentation for a specific, supported, problem solving function, liopts100${\mathbf{liopts}}\ge 100$.
2:     lopts – int64int32nag_int scalar
Default: The dimension of the array opts.
The length of the array opts.
Constraint: unless otherwise stated in the documentation for a specific, supported, problem solving function, lopts100${\mathbf{lopts}}\ge 100$.

None.

### Output Parameters

1:     iopts(liopts) – int64int32nag_int array
Dependent on the contents of optstr, either an initialized, reset or updated version of the optional parameter array.
2:     opts(lopts) – double array
Dependent on the contents of optstr, either an initialized, reset or updated version of the optional parameter array.
3:     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 = 11${\mathbf{ifail}}=11$
On entry, the optional parameter in optstr was not recognized.
ifail = 12${\mathbf{ifail}}=12$
On entry, the expected delimiter ‘ = $=$’ was not found in optstr.
ifail = 13${\mathbf{ifail}}=13$
On entry, could not convert the specified optval to an integer.
On entry, could not convert the specified optval to a real.
ifail = 14${\mathbf{ifail}}=14$
On entry, attempting to initialize the optional parameter arrays but specified function name was not valid.
ifail = 15${\mathbf{ifail}}=15$
On entry, the optval supplied for the integer optional parameter is not valid.
ifail = 16${\mathbf{ifail}}=16$
On entry, the optval supplied for the real optional parameter is not valid.
ifail = 17${\mathbf{ifail}}=17$
On entry, the optval supplied for the character optional parameter is not valid.
ifail = 21${\mathbf{ifail}}=21$
On entry, either the option arrays have not been initialized or they have been corrupted.
ifail = 31${\mathbf{ifail}}=31$
liopts is too small.
ifail = 51${\mathbf{ifail}}=51$
lopts is too small.

Not applicable.

None.

## Example

```function nag_fit_opt_set_example
xdata = [0; 0.5; 1; 1.5; 2; 2.5; 3; 4; 4.5; 5; 5.5; 6; 7; 7.5; 8];
ydata = [-1.1; -0.372; 0.431; 1.69; 2.11; 3.1; 4.23; 4.35; 4.81; 4.61; 4.79; ...
5.23; 6.35; 7.19; 7.97];
wdata = [1; 1; 1.5; 1; 1; 1; 1; 1; 1; 1; 1; 1; 1; 1; 1];
cstart = 'c';
sfac  = 0.001;
x     = [6.5178; 7.2463; 1.0159; 7.3070; 5.0589; 0.7803; 2.2280; 4.3751; ...
7.6601; 7.7191; 1.2609; 7.7647; 7.6573; 3.8830; 6.4022; 1.1351; ...
3.3741; 7.3259; 6.3377; 7.6759];
nest  = int64(numel(xdata) + 4);
ixloc = zeros(numel(x), 1, 'int64');
wrk   = zeros(4*numel(xdata) + 16*nest + 41, 1);
iwrk1 = zeros(nest, 1, 'int64');
iwrk2 = zeros(3+3*numel(x), 1, 'int64');
lamda = zeros(nest, 1);
xord  = int64(0);
start = int64(0);
deriv = int64(3);

% Generate the data to fit.
[x, y, f, lsminp, lsmaxp, nxcels, nycels] = generate_data();

% Initialize the options arrays and set/get some options.
[iopts, opts] = handle_options();

% Compute the spline coefficients.
[coefs, iopts, opts, ifail] = ...
nag_fit_2dspline_ts_sctr(x, y, f, lsminp, lsmaxp, nxcels, nycels, iopts, opts);

% pmin and pmax form the bounding box of the spline. We must not attempt to
% evaluate the spline outside this box.
pmin = [min(x); min(y)];
pmax = [max(x); max(y)];

% Evaluate the approximation at a vector of values.
evaluate_at_vector(coefs, iopts, opts, pmin, pmax);

% Evaluate the approximation on a mesh.
evaluate_on_mesh(coefs, iopts, opts, pmin, pmax);

function [x, y, f, lsminp, lsmaxp, nxcels, nycels] = generate_data()
% Generates an x and a y vector of n pseudorandom uniformly distributed
% values on (0,1]. These are passed to the bivariate function of R. Franke
% to create the data set to fit.  The remaining input data for
% nag_fit_2dspline_ts_sctr are set to suitable values for this problem,
% as discussed by Davydov and Zeilfelder.

n = int64(100);

% Initialize the generator to a repeatable sequence
[state, ifail] = nag_rand_init_repeat(int64(1), int64(0), int64(32958));

% Generate x values
[state, x, ifail] = nag_rand_dist_uniform01(n, state);

% Generate y values
[state, y, ifail] = nag_rand_dist_uniform01(n, state);

% Ensure that the bounding box stretches all the way to (0,0) and (1,1)
x(1) = 0;
y(1) = 0;
x(n) = 1;
y(n) = 1;

f = 0.75*exp(-((9*x(:)-2).^2+(9*y(:)-2).^2)/4)+0.75*exp(-(9*x(:)+ 1).^2/49 ...
-(9*y(:)+1)/10) + 0.5*exp(-((9*x(:)-7).^2+(9*y(:)- 3).^2)/4) - ...
0.2*exp(-(9*x(:)- 4).^2-(9.*y(:)-7).^2);

% Grid size for the approximation
nxcels = int64(6);
nycels = int64(6);

% Identify the computation.
fprintf('\nComputing the coefficients of a C^1 spline approximation to Franke''s function\n');
fprintf(' Using a %d by %d grid\n', nxcels, nycels);

% Local-approximation control parameters.
lsminp = int64(3);
lsmaxp = int64(100);
function [iopts, opts] = handle_options()
% Initialize the options arrays and demonstrate how to set and get
% optional parameters.
opts  = zeros(100, 1);
iopts = zeros(100, 1, 'int64');

[iopts, opts, ifail] = ...
nag_fit_opt_set('Initialize = nag_fit_2dspline_ts_sctr', iopts, opts);

%  Set some non-default parameters for the local approximation method.
optstr = strcat('Minimum Singular Value LPA = ', num2str(1/32));
[iopts, opts, ifail] = nag_fit_opt_set(optstr, iopts, opts);
[iopts, opts, ifail] = ...
nag_fit_opt_set('Polynomial Starting Degree = 3', iopts, opts);

% Set a non-default parameter for the global approximation method.
[iopts, opts, ifail] = nag_fit_opt_set('Averaged Spline = Yes', iopts, opts);

% As an example of how to get the value of an optional parameter,
% display whether averaging of local approximations is in operation.
[~, ~, cvalue, ~, ifail] = nag_fit_opt_get('Averaged Spline', iopts, opts);
if strcmp(cvalue, 'YES')
fprintf(' Using an averaged local approximation\n');
end
function evaluate_at_vector(coefs, iopts, opts, pmin, pmax)
% Evaluates the approximation at a (in this case trivial) vector of values.

xevalv = [0];
yevalv = [0];

% Force the points to be within the bounding box of the spline'
for i = 1:numel(xevalv)
xevalv(i) = max(xevalv(i),pmin(1));
xevalv(i) = min(xevalv(i),pmax(1));
yevalv(i) = max(yevalv(i),pmin(2));
yevalv(i) = min(yevalv(i),pmax(2));
end

[fevalv, ifail] = nag_fit_2dspline_ts_evalv(xevalv, yevalv, coefs, iopts, opts);

fprintf('\n Values of computed spline at (x_i,y_i):\n\n');
fprintf('         x_i          y_i   f(x_i,y_i)\n');
for i = 1:numel(xevalv)
fprintf('%12.2f %12.2f %12.2f\n', xevalv(i),yevalv(i),fevalv(i));
end
function evaluate_on_mesh(coefs,iopts,opts,pmin,pmax)
% Evaluates the approximation on a mesh of n_x * n_y values.
nxeval = 101;
nyeval = 101;

% Define the mesh by its lower-left and upper-right corners.
ll_corner = [0; 0];
ur_corner = [1; 1];

% Set the mesh spacing and the evaluation points.
% Force the points to be within the bounding box of the spline.
h = [(ur_corner(1)-ll_corner(1))/(nxeval-1); ...
(ur_corner(2)-ll_corner(2))/(nyeval-1)];

xevalm = ll_corner(1) + [0:nxeval-1]*h(1);
yevalm = ll_corner(2) + [0:nyeval-1]*h(2);

% Ensure that the evaluation points are in the bounding box
xevalm = max(pmin(1), xevalm);
xevalm = min(pmax(1), xevalm);
yevalm = max(pmin(2), yevalm);
yevalm = min(pmax(2), yevalm);

% Evaluate
[fevalm, ifail] = nag_fit_2dspline_ts_evalm(xevalm, yevalm, coefs, iopts, opts);

print_mesh = false;

if print_mesh
fprintf('\nValues of computed spline at (x_i,y_j):\n\n');
fprintf('         x_i          y_i   f(x_i,y_i)\n');
for i = 1:nxeval
for j=1:nyeval
fprintf('%12.2f %12.2f %12.2f\n', xevalm(i),yevalm(j),fevalm(i, j));
end
end
else
fprintf('\nOutputting of the function values on the mesh is disabled\n');
end
```
```

Computing the coefficients of a C^1 spline approximation to Franke's function
Using a 6 by 6 grid
Using an averaged local approximation

Values of computed spline at (x_i,y_i):

x_i          y_i   f(x_i,y_i)
0.00         0.00         0.76

Outputting of the function values on the mesh is disabled

```
```function e02zk_example
xdata = [0; 0.5; 1; 1.5; 2; 2.5; 3; 4; 4.5; 5; 5.5; 6; 7; 7.5; 8];
ydata = [-1.1; -0.372; 0.431; 1.69; 2.11; 3.1; 4.23; 4.35; 4.81; 4.61; 4.79; ...
5.23; 6.35; 7.19; 7.97];
wdata = [1; 1; 1.5; 1; 1; 1; 1; 1; 1; 1; 1; 1; 1; 1; 1];
cstart = 'c';
sfac  = 0.001;
x     = [6.5178; 7.2463; 1.0159; 7.3070; 5.0589; 0.7803; 2.2280; 4.3751; ...
7.6601; 7.7191; 1.2609; 7.7647; 7.6573; 3.8830; 6.4022; 1.1351; ...
3.3741; 7.3259; 6.3377; 7.6759];
nest  = int64(numel(xdata) + 4);
ixloc = zeros(numel(x), 1, 'int64');
wrk   = zeros(4*numel(xdata) + 16*nest + 41, 1);
iwrk1 = zeros(nest, 1, 'int64');
iwrk2 = zeros(3+3*numel(x), 1, 'int64');
lamda = zeros(nest, 1);
xord  = int64(0);
start = int64(0);
deriv = int64(3);

% Generate the data to fit.
[x, y, f, lsminp, lsmaxp, nxcels, nycels] = generate_data();

% Initialize the options arrays and set/get some options.
[iopts, opts] = handle_options();

% Compute the spline coefficients.
[coefs, iopts, opts, ifail] = ...
e02jd(x, y, f, lsminp, lsmaxp, nxcels, nycels, iopts, opts);

% pmin and pmax form the bounding box of the spline. We must not attempt to
% evaluate the spline outside this box.
pmin = [min(x); min(y)];
pmax = [max(x); max(y)];

% Evaluate the approximation at a vector of values.
evaluate_at_vector(coefs, iopts, opts, pmin, pmax);

% Evaluate the approximation on a mesh.
evaluate_on_mesh(coefs, iopts, opts, pmin, pmax);

function [x, y, f, lsminp, lsmaxp, nxcels, nycels] = generate_data()
% Generates an x and a y vector of n pseudorandom uniformly distributed
% values on (0,1]. These are passed to the bivariate function of R. Franke
% to create the data set to fit.  The remaining input data for
% e02jd are set to suitable values for this problem,
% as discussed by Davydov and Zeilfelder.

n = int64(100);

% Initialize the generator to a repeatable sequence
[state, ifail] = g05kf(int64(1), int64(0), int64(32958));

% Generate x values
[state, x, ifail] = g05sa(n, state);

% Generate y values
[state, y, ifail] = g05sa(n, state);

% Ensure that the bounding box stretches all the way to (0,0) and (1,1)
x(1) = 0;
y(1) = 0;
x(n) = 1;
y(n) = 1;

f = 0.75*exp(-((9*x(:)-2).^2+(9*y(:)-2).^2)/4)+0.75*exp(-(9*x(:)+ 1).^2/49 ...
-(9*y(:)+1)/10) + 0.5*exp(-((9*x(:)-7).^2+(9*y(:)- 3).^2)/4) - ...
0.2*exp(-(9*x(:)- 4).^2-(9.*y(:)-7).^2);

% Grid size for the approximation
nxcels = int64(6);
nycels = int64(6);

% Identify the computation.
fprintf('\nComputing the coefficients of a C^1 spline approximation to Franke''s function\n');
fprintf(' Using a %d by %d grid\n', nxcels, nycels);

% Local-approximation control parameters.
lsminp = int64(3);
lsmaxp = int64(100);
function [iopts, opts] = handle_options()
% Initialize the options arrays and demonstrate how to set and get
% optional parameters.
opts  = zeros(100, 1);
iopts = zeros(100, 1, 'int64');

[iopts, opts, ifail] = ...
e02zk('Initialize = e02jd', iopts, opts);

%  Set some non-default parameters for the local approximation method.
optstr = strcat('Minimum Singular Value LPA = ', num2str(1/32));
[iopts, opts, ifail] = e02zk(optstr, iopts, opts);
[iopts, opts, ifail] = ...
e02zk('Polynomial Starting Degree = 3', iopts, opts);

% Set a non-default parameter for the global approximation method.
[iopts, opts, ifail] = e02zk('Averaged Spline = Yes', iopts, opts);

% As an example of how to get the value of an optional parameter,
% display whether averaging of local approximations is in operation.
[~, ~, cvalue, ~, ifail] = e02zl('Averaged Spline', iopts, opts);
if strcmp(cvalue, 'YES')
fprintf(' Using an averaged local approximation\n');
end
function evaluate_at_vector(coefs, iopts, opts, pmin, pmax)
% Evaluates the approximation at a (in this case trivial) vector of values.

xevalv = [0];
yevalv = [0];

% Force the points to be within the bounding box of the spline'
for i = 1:numel(xevalv)
xevalv(i) = max(xevalv(i),pmin(1));
xevalv(i) = min(xevalv(i),pmax(1));
yevalv(i) = max(yevalv(i),pmin(2));
yevalv(i) = min(yevalv(i),pmax(2));
end

[fevalv, ifail] = e02je(xevalv, yevalv, coefs, iopts, opts);

fprintf('\n Values of computed spline at (x_i,y_i):\n\n');
fprintf('         x_i          y_i   f(x_i,y_i)\n');
for i = 1:numel(xevalv)
fprintf('%12.2f %12.2f %12.2f\n', xevalv(i),yevalv(i),fevalv(i));
end
function evaluate_on_mesh(coefs,iopts,opts,pmin,pmax)
% Evaluates the approximation on a mesh of n_x * n_y values.
nxeval = 101;
nyeval = 101;

% Define the mesh by its lower-left and upper-right corners.
ll_corner = [0; 0];
ur_corner = [1; 1];

% Set the mesh spacing and the evaluation points.
% Force the points to be within the bounding box of the spline.
h = [(ur_corner(1)-ll_corner(1))/(nxeval-1); ...
(ur_corner(2)-ll_corner(2))/(nyeval-1)];

xevalm = ll_corner(1) + [0:nxeval-1]*h(1);
yevalm = ll_corner(2) + [0:nyeval-1]*h(2);

% Ensure that the evaluation points are in the bounding box
xevalm = max(pmin(1), xevalm);
xevalm = min(pmax(1), xevalm);
yevalm = max(pmin(2), yevalm);
yevalm = min(pmax(2), yevalm);

% Evaluate
[fevalm, ifail] = e02jf(xevalm, yevalm, coefs, iopts, opts);

print_mesh = false;

if print_mesh
fprintf('\nValues of computed spline at (x_i,y_j):\n\n');
fprintf('         x_i          y_i   f(x_i,y_i)\n');
for i = 1:nxeval
for j=1:nyeval
fprintf('%12.2f %12.2f %12.2f\n', xevalm(i),yevalm(j),fevalm(i, j));
end
end
else
fprintf('\nOutputting of the function values on the mesh is disabled\n');
end
```
```

Computing the coefficients of a C^1 spline approximation to Franke's function
Using a 6 by 6 grid
Using an averaged local approximation

Values of computed spline at (x_i,y_i):

x_i          y_i   f(x_i,y_i)
0.00         0.00         0.76

Outputting of the function values on the mesh is disabled

```