Although the NAG Library is written in Fortran, you can use it from within MATLAB as if it were a collection of native MATLAB commands. The code in the toolbox will transform your MATLAB data into a form suitable for passing to Fortran, and will transform the results into MATLAB objects on successful completion of the algorithm.

a = [ 1.80, 2.88, 2.05, -0.89; 5.25, -2.95, -0.95, -3.80; 1.58, -2.69, -2.90, -1.04; -1.11, -0.66, -0.59, 0.80]; b = [ 9.52; 24.35; 0.77; -6.22]; [aOut, ipiv, bOut, info] = f07aa(a, b); bOut bOut = 1.0000 -1.0000 3.0000 -5.0000Here we see that the NAG routine

- aOut
- the LU factorisation of A
- ipiv
- the pivot indices that describe the permutation matrix used to compute the result
- bOut
- the solution matrix
- info
- a diagnostic parameter that indicates whether the algorithm was successful or not

[aOut, ipiv, bOut, info] = f07aa(a, b, 'n', int64(3)); bOut bOut = 4.1631 -2.1249 3.9737 -6.2200The last element of bOut can be ignored. Since b was a 4x1 matrix on input, it will be a 4x1 matrix on output, even though the last element is not being used. A similar outcome can be achieved by:

[aOut, ipiv, bOut, info] = f07aa(a(1:3,1:3), b(1:3)); bOut bOut = 4.1631 -2.1249 3.9737To summarise:

- optional parameters are provided after all compulsory parameters;
- optional parameters are provided in pairs: a string representing the name of the parameter followed by its value;
- optional parameters can be provided in any order.

tail = 'c'; a = [-2; -2; -2; -2]; b = [2; 2; 2; 2]; xmu = [0; 0; 0; 0]; sig = [1.0, 0.9, 0.9, 0.9; 0.9, 1.0, 0.9, 0.9; 0.9, 0.9, 1.0, 0.9; 0.9, 0.9, 0.9, 1.0]; g01hb(tail, a, b, xmu, sig) ans = 0.9142We can request more or less accuracy by varying the parameter tol:

g01hb(tail, a, b, xmu, sig,'tol',0.1) ans = 0.9182Finally, we note that some NAG routines use a different mechanism for setting options, which involves calling an initialisation routine, a separate option setting routine, and then a computational routine. For an example of this see f12fe.

- NAG:licenceError
- A valid licence for this product could not be found.
- NAG:arrayBoundError
- An array provided to the routine is too small.
- NAG:callBackError
- An error occurred when executing an M-File passed as a parameter to the routine.
- NAG:missingInputParameters
- At least one compulsory input parameter is missing.
- NAG:optionalParameterError
- Either the optional parameters are not in name/value pairs, or the name provided does not correspond to an optional parameter. Note that this error can arise if some compulsory parameters have been omitted.
- NAG:tooManyInputParameters
- The user has requested too many input parameters.
- NAG:tooManyOutputParameters
- The user has requested too many output parameters.
- NAG:typeError
- A parameter provided to the routine or returned from an M-File called by the routine is of the wrong type. See the section on Types for more details.
- NAG:unsetCellArrayError
- A cell array has been passed without all elements being set.
- NAG:valueError
- An incorrect value has been provided for a parameter.
- NAG:error_<s><int>
- An error occurred during the execution of the routine. Details can
be found by consulting the
*Error Indicators and Warnings*section of the document for the particular routine, where <s><int> corresponds to the return value of ifail (or, in chapters f07 and f08, info) with s being 'p' for positive and 'n' for negative. See the description of nag_issue_warnings below.

```
??? The dimension of parameter 2 (A) should be at least 4
```

The NAG routines can also throw two kinds of warnings:
- NAG:truncationWarning
- A string was truncated when copying the contents of a cell array of strings into a Fortran data structure.
- NAG:warning
- The NAG routine returned a warning.

warning('off', 'NAG:warning')In this case it is vital that the user checks the value of ifail or info on exit from the routine.

In previous versions of the Toolbox all NAG:error_<s><int>'s were NAG:warnings. By default, we only use warnings in cases where the output values may be of use (for example in determining the cause of the problem, or as a "warm start" in subsequent calls to the routine), or where the routine has found a solution but there are caveats, for example as to its accuracy. In all other cases we now issue an error.

Should the user prefer to receive a warning and interrogate the return value of ifail (or, in chapters f07 and f08, info) then they can use the function nag_issue_warnings to toggle the behaviour of the Toolbox as follows:

- nag_issue_warnings(true)
- disable the use of NAG:error_<s><int> and issue warnings
- nag_issue_warnings(false)
- enable the use of NAG:error_<s><int>
- nag_issue_warnings()
- return the current setting (true or false)

```
s01ea(0)
??? Parameter number 1 is not a complex scalar of class double.
```

It should be noted that versions of MATLAB prior to 2011a do not support some operations on objects of
class *int64*, in particular the colon operator is not defined
and so they cannot be used as the start or end point of a loop.
(Prior to MATLAB 2010b arithmetic operations, on *int64* were not supported at all.)
If using these MATLAB versions it is therefore necessary to use *double* variables and just
cast to *int64* while calling the NAG function.

If users wish to write code that is portable across versions of the NAG toolbox that use both 32 and 64 bit integers, then we provide two functions as follows:

- nag_int(x)
- nag_int converts x to the integer type compatible with the current version of the NAG toolbox
- nag_int_name
- nag_int_name returns the name of the integer class compatible with the current version of the NAG toolbox

nag_int(42); n = zeros(10, nag_int_name);

`'U'`

or `'L'`

may be suppled a value
of `'Lower'`

which would be accepted as equivalent to
`'L'`

.
Note that you must ensure that any supplied strings d01ah(0, 1, 1e-5, 'd01ah_f', int64(0)) ans = 3.1416The integrand is contained in the file 'd01ah_f.m', which looks like:

function [result] = d01ah_f(x) result=4.0/(1.0+x^2);The user should consult the MATLAB documentation on Editing and Debugging M-Files for general advice. For every instance where a NAG routine expects an M-File to be provided, an example is given.

- when the argument is an existing MATLAB command;
- when the argument is a simple expression returning one value
which can be represented
as an
*anonymous function*; - when the argument is a function that is local to an m-file.

An example of the first case would be integrating the *sin*
function which can be done as follows:

[result, abserr] = d01aj(@sin, 0, pi, 1e-5, 1e-5) result = 2 abserr = 1.1102e-14

An example of the second case would be to integrate an arithmetic expression as follows:

[result, abserr] = d01aj(@(x) 4.0/(1.0+x^2), 0, 1, 1e-5, 1e-5) result = 3.1416 abserr = 1.7439e-14

An example of the third case would be a program such as solve_equations.m:

function solve_equations x = -ones(9,1); [x, ~, ifail] = c05nb(@fcn, x); if (ifail == 0) fprintf('The root of the equation is at:\n'); disp(x); end function [fvec, iflag] = fcn(n,x,iflag) fvec = zeros(n, 1); for k = 1:double(n) fvec(k) = (3.0-2.0*x(k))*x(k)+1.0; if k > 1 fvec(k) = fvec(k) - x(k-1); end if k < n fvec(k) = fvec(k) - 2*x(k+1); end end