NAG Toolbox

Calling NAG Routines From MATLAB

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 simple example

Here is an example of how to use the NAG Library to compute the solution of a real system of linear equations, AX=B, where A is an n by n matrix and X and B are n vectors. 
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.0000
Here we see that the NAG routine f07aa takes two arguments, the matrix of coefficients, A, and the vector representing the right-hand side, B (actually, since f07aa can handle multiple right-hand sides, B is really a matrix). It returns four results as follows:
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
Since info=0 we know that the algorithm succeeded. Had it been non-zero a warning would have been printed (see Errors and Warnings). An example of the use of each NAG routine in MATLAB is provided in the individual routine documents.

Optional Arguments

Many NAG routines have optional parameters. In these cases the routine will either infer a suitable value from the other inputs, or provide a default that is acceptable in most situations. A very common case is where the underlying Fortran routine requires the user to provide parameters which describe the size of a matrix, which can easily be inferred in MATLAB. For example, in the system of equations given in the previous section, it is obvious that the rank, n, of the matrix A is 4. However we can tell MATLAB that the rank is 3, in which case it will solve the system represented by the top-left 3x3 section of A, and the first three elements of B (see the section on Types for an explanation of the use of the int32 command here): 
[aOut, ipiv, bOut, info] = f07aa(a, b, 'n', int32(3));
bOut

bOut =

    4.1631
   -2.1249
    3.9737
   -6.2200
The 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.9737
To summarise:
  1. optional parameters are provided after all compulsory parameters;
  2. optional parameters are provided in pairs: a string representing the name of the parameter followed by its value;
  3. optional parameters can be provided in any order.
Another common use of optional parameters is to over-ride default values. For example, g01hb computes probabilities associated with a multivariate distribution to a relative accuracy which defaults to 0.0001: 
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.9142
We can request more or less accuracy by varying the parameter tol: 
g01hb(tail, a, b, xmu, sig,'tol',0.1)

ans =

    0.9182
Finally, 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.

Errors and Warnings

The NAG routines can throw a number of errors. The names of those errors and the circumstances under which they are likely to be encountered are as follows:
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: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:valueError
An incorrect value has been provided for a parameter.
In most cases the error message will give more precise details of how the error was triggered. For example a NAG:arrayBoundError might display the message: 

??? 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 an error or warning.
The latter is important, and means that on exit the value of the parameter ifail (or, in chapters f07 and f08, info) was non-zero on exit. For details about how to interpret this value the user should consult the relevant routine document. If the user does not wish to see a warning then they can disable it in the usual way, for example: 
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.

Types

The interfaces to NAG routines in this toolbox are quite precise about the types of their parameters. Since MATLAB assumes by default that every number is a double unless otherwise stated, this means that users need to coerce their input to the appropriate type if it is an integer, a complex number or a boolean. Similarly, in M-Files called by the NAG routine, the user must ensure that the results returned are of the appropriate type. This is to ensure the correct alignment between the MATLAB and Fortran types. Typically the user will call complex to create a complex number, and logical to create a boolean. In this version of the toolbox, the user will call int32 to create an integer. In other versions the user will call int64. The size of integers is chosen to be compatible with those used internally by MATLAB's implementation of LAPACK. There are numerous examples of type conversion in the routine documents. If an object of the incorrect type is provided then a NAG:typeError will be thrown: 
s01ea(0)

??? Parameter number 1 is not a complex scalar of class double.

Providing M-Files as Arguments

Many NAG routines expect the user to provide an M-File to evaluate a function, which might represent an integrand, the objective function in an optimization problem etc. Here is an example showing how to solve an integral: 
d01ah(0, 1, 1e-5, 'd01ah_f', int32(0))
ans =

    3.1416
The 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 Working with M-Files and 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.

Support From NAG

NAG Response Centres

The NAG Response Centres are available for general enquiries from all users and also for technical queries from users with support. The Response Centres are open during office hours, but contact is possible by fax, email and telephone (answering machine) at all times. Please see the NAG web site for contact details. When contacting one of the NAG Response Centres, it helps us to deal with your query quickly if you can quote your NAG user reference and NAG product code.

NAG Web Site

The NAG web site is an information service providing items of interest to users and prospective users of NAG products and services. The information is regularly updated and reviewed, and includes implementation availability, descriptions of products, down-loadable software, case studies, industry articles and technical reports. The NAG web site can be accessed via: