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;
[aOut, ipiv, bOut, info] = f07aa(a, b);
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
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.
- the LU factorisation of A
- the pivot indices that describe the permutation matrix used to
compute the result
- the solution matrix
- a diagnostic parameter that indicates whether the algorithm was
successful or not
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));
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));
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
- optional parameters are provided after all compulsory
- 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)
We can request more or less accuracy by varying the parameter tol:
g01hb(tail, a, b, xmu, sig,'tol',0.1)
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:
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:
- A valid licence for this product could not be found.
- An array provided to the routine is too small.
- An error occurred when executing an M-File passed as a parameter
to the routine.
- At least one compulsory input parameter is missing.
- 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
- The user has requested too many input parameters.
- The user has requested too many output parameters.
- 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.
- A cell array has been passed without all elements being set.
- An incorrect value has been provided for a parameter.
- 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>
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:
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:
- A string was truncated when copying the contents of a cell array
of strings into a Fortran data structure.
- The NAG routine returned a 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
to toggle the behaviour of the Toolbox as follows:
Note that this command only effects NAG:error_<s><int>'s, not the other
kinds of errors documented above.
- disable the use of NAG:error_<s><int> and issue warnings
- enable the use of NAG:error_<s><int>
- return the current setting (true or false)
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:
??? Parameter number 1 is not a complex scalar of class double.
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
These can be used as follows:
- nag_int converts x to the integer type compatible with the current version of the
- nag_int_name returns the name of the integer class compatible with the current version
of the NAG toolbox
n = zeros(10, nag_int_name);
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
'L' may be suppled a value
'Lower' which would be accepted as equivalent to
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))
The integrand is contained in the file 'd01ah_f.m', which looks like:
function [result] = d01ah_f(x)
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)
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)
An example of the third case would be a program such as solve_equations.m:
Note that in this case the local function fcn is too complicated to be
represented as an anonymous function.
x = -ones(9,1);
[x, ~, ifail] = c05nb(@fcn, x);
if (ifail == 0)
fprintf('The root of the equation is at:\n');
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);
if k < n
fvec(k) = fvec(k) - 2*x(k+1);
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
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: