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 int64 command here):

[aOut, ipiv, bOut, info] = f07aa(a, b, 'n', int64(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:

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.

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: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.

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 a 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.

The `nag_issue_warnings` command

As described above, in some circumstances the NAG routine may throw an error of the form NAG:error_<s><int> or issue a warning of the form NAG:warning. Throwing errors allows the user to use try ... catch ... end blocks in their programs which is the preferred style of error handling for many people. On the other hand, when an error is thrown then none of the output parameters of the routine are available for inspection.

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)

Note that this command only effects NAG:error_<s><int>'s, not the other kinds of errors documented above.

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 64-bit versions version of the toolbox, the user will call int64 to create an integer. In other versions the user will call int32. 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.

Integers

The type of integers used by the NAG Toolbox is chosen to be compatible with those used internally by MATLAB's implementation of LAPACK. This is, class int32 or int64 depending on the implementation.

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

These can be used as follows:

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

Strings

When handling string valued arguments, the underlying Fortran routines usually expect strings of a specified length (which is specified in the parameter description). If strings longer than this are supplied, they will be truncated to the specified length. This means that a typical string valued argument with minimum length 1 and a constraint that the value may be '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 are at least the minimum length by padding with spaces or other suitable characters if necessary.

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', int64(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 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.

Using Function Handles instead of M-Files

An alternative to providing M-Files as arguments is to use is to use function handles. These are useful in three main circumstances:

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

Note that in this case the local function fcn is too complicated to be represented as an anonymous function.

Direct and Reverse Communication Routines

Library routines that directly take a user-supplied function, as described above, are classified as direct communication routines. Some such routines also have a reverse communication alternative. Instead of obtaining the solution in one call, reverse communication routines perform one step of the solution process before returning to the calling program with an appropriate flag (irevcm) set. The value of irevcm determines whether the process has finished or whether fresh information is required. In the latter case the required information must be calculated before re-entering the reverse communication routine. Thus you have the responsibility for providing an iterative loop.

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: