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.

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

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:

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.

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.

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.

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.

The type of integers used by the NAG Toolbox is chosen to be compatible with
those used internally by MATLAB's implementation of LAPACK. In this
implementation of the toolbox integers are 32 bits long, i.e. of class
int32.

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)

converts x to the integer type compatible with the current version of the
NAG toolbox

nag_int_name

returns the name of the integer class compatible with the current version
of the NAG toolbox

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:

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

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: