NAG FL Interface
Introduction

The NAG FL Interface is a standard set of interfaces that utilise only simple types, making them suitable for calling from a wide range of languages, including Fortran, C, C++, VBA and others. These interfaces include NAG's traditional Fortran Library interfaces.

The NAG Library Manual is the principal documentation for the NAG Library. The Library Manual provides you with information to support this interface. Full details of how to use the NAG Library are provided in How to Use the NAG Library and if you are a new user you are strongly advised to read this document.

The following information is specific to the NAG FL Interface.

The Guide to the NAG Library Documentation provides general information on how to use the NAG Library documentation; the following sections are specific to the NAG FL Interface.

The specification of routines in routine documents (see Section 2 in d03pdf/​d03pda) includes the C Header interface which can be used to call a NAG Library routine from C or C++; the name used for this interface is the Fortran Interface name appended by an underscore (e.g., d03faf_ corresponds to d03faf). For routines with 'a' and 'f' versions, the same approach also applies to the 'a' version (e.g., d03pda_ corresponds to d03pda).

In the rare case where a routine interface contains a procedure argument (callback) which itself contains a character argument (e.g., monfun in g02eff), the C Header interface specification of the user supplied callback places the required additional character length argument at the end of the callback argument list. This is correct for all implementations of NAG Library other than a 32-bit Windows implementation using the stdcall calling convention, for which the extra length arguments should immediately follow the corresponding character argument. Note that the specification of the main routine C header interface is correct for all implementations as any extra arguments are automatically moved, if required, by preprocessor macros supplied in nag.h.

Arguments are classified as follows.

Input: you must assign values to these arguments on or before entry to the routine, and these values are unchanged on exit from the routine.

Output: you need not assign values to these arguments before entry to the routine; the routine may assign values to them.

Input/Output: you must assign values to these arguments before entry to the routine, and the routine may then change these values.

Workspace: array arguments which are used as workspace by the routine. You must supply arrays of the correct type and dimension. In general, you need not be concerned with their contents.

Communication Array: arguments which are used to communicate data from one routine call to another.

External Procedure: a routine which must be supplied (e.g., to evaluate an integrand or to print intermediate output). Usually it must be supplied as part of your calling program, in which case its specification includes full details of its argument list and specifications of its arguments (all enclosed in a box). Its arguments are classified in the same way as those of the Library routine, but because you must write the procedure rather than call it, the significance of the classification is different.

• Input: values may be supplied on entry, which your procedure must not change.
• Output: you may or must assign values to these arguments before exit from your procedure.
• Input/Output: values may be supplied on entry, and you may or must assign values to them before exit from your procedure.

Occasionally, as mentioned in Section 6, the procedure can be supplied from the NAG Library, and then you only need to know its name.

User Workspace: array arguments which are passed by the Library routine to an external procedure argument. They are not used by the routine, but you may use them to pass information between your calling program and the external procedure.

Dummy: a simple variable which is not used by the routine. A variable or constant of the correct type must be supplied, but its value need not be set. (A dummy argument is usually an argument which was required by an earlier version of the routine and is retained in the argument list for compatibility.)

The word ‘Constraint:’ or ‘Constraints:’ in the specification of an Input argument introduces a statement of the range of valid values for that argument, e.g.,

• Constraint: $\mathbf{n}>0$.

If the routine is called with an invalid value for the argument (e.g., $\mathbf{n}=0$), the routine will usually take an error exit, returning a nonzero value of ifail (see Section 4).

Constraints on arguments of type Character only list upper case alphabetic characters, e.g.,

• Constraint: $\mathbf{check}=\text{'N'}$.

In practice, all routines with Character arguments will permit the use of lower case characters.

Occasionally, an enhancement of an existing routine at a given Mark may weaken some constraints on some arguments, this will not change the behaviour of existing code that calls the routine, but will allow new code to take advantage of enhanced functionality.

The phrase ‘Suggested value:’ introduces a suggestion for a reasonable initial setting for an Input argument (e.g., accuracy or maximum number of iterations) in case you are unsure what value to use; you should be prepared to use a different setting if the suggested value turns out to be unsuitable for your problem.

Most array arguments have dimensions which depend on the size of the problem. In Fortran terminology they have ‘adjustable dimensions’: the dimensions occurring in their declarations are integer variables which are also arguments of the Library routine.

For example, a Library routine might have the specification:

Subroutine <name> (m, n, a, b, ldb)
Integer            m, n, a(n), b(ldb,n), ldb

For a one-dimensional array argument, such as a in this example, the specification would begin

• a(n) – Integer array

You must ensure that the dimension of the array, as declared in your calling (sub)program, is at least as large as the value you supply for n. It may be larger, but the routine uses only the first n elements.

For a two-dimensional array argument, such as b in the example, the specification might be

• b(ldb,n) – Integer array
• On entry: the $m$ by $n$ matrix $B$.

and the argument ldb might be described as follows:

• ldb – Integer
• On entry: the first dimension of the array b as declared in the (sub)program from which <name> is called.
• Constraint: $\mathbf{ldb}\ge \mathbf{m}$.

You must supply the first dimension of the array b, as declared in your calling (sub)program, through the argument ldb, even though the number of rows actually used by the routine is determined by the argument m. You must ensure that the first dimension of the array is at least as large as the value you supply for m. The extra argument ldb is needed to allow the routine to act on subarrays of a larger two-dimensional array, e.g., factorizing a diagonal submatrix of a larger matrix.

You must also ensure that the second dimension of the array, as declared in your calling (sub)program, is at least as large as the value you supply for n. It may be larger, but the routine uses only the first n columns.

A program to call the hypothetical routine used as an example in this section might include the statements:

Integer aa(100), bb(100,50)
ldb = 100
.
.
.
m = 80
n = 20
Call <name>(m,n,aa,bb,ldb)

Integer Allocatable :: aa(:), bb(:,:)
Integer             :: m, n, ldb
.
.
.
Read(5,*) m, n
ldb = m
Allocate (aa(m),bb(ldb,n))
Call <name>(m,n,aa,bb,ldb)

Many NAG routines contain array arguments declared with the ‘assumed size’ array dimension, and would be given as

Integer        a(*), b(ldb,*)

However, the original declaration of an array in your calling program must always have dimensions, greater than or equal to the minimum value documented. The advantage of using allocatable arrays is that they can be dynamically allocated to be of a correct size not known at compile time.

Consult an expert or a textbook on Fortran if you have difficulty in calling NAG routines with array arguments.

In order to support all implementations of the Library, the Manual has adopted a convention of using bold italics to distinguish terms which have different interpretations in different implementations.

One bold italicised term is machine precision, which denotes the relative precision to which real floating-point numbers are stored in the computer, e.g., in an implementation with approximately 16 decimal digits of precision, machine precision has a value of approximately ${10}^{\mathrm{-16}}$.

The precise value of machine precision is given by the routine x02ajf. Other routines in Chapter X02 return the values of other implementation-dependent constants, such as the overflow threshold, or the largest representable integer. Refer to the X02 Chapter Introduction for more details.

The bold italicised term block size is used only in Chapters F07 and F08. It denotes the block size used by block algorithms in these chapters. You only need to be aware of its value when it affects the amount of workspace to be supplied – see the arguments work and lwork of the relevant routine documents and the appropriate Chapter Introduction.

For each implementation of the Library, a separate Users' Note is published. This is a short document, revised at each mark. At most installations it is available in machine-readable form. It gives any necessary additional information which applies specifically to that implementation, in particular:

• the values returned by Chapter X02 routines;
• the default unit numbers for output (see Section 5);
• the meanings of the precision arguments nag_rp (reduced precision), nag_wp (basic precision) and nag_hp (additional precision).

The example program in Section 10 of most routine documents illustrates a simple call of the routine. The programs are designed so that they can be fairly easily modified, and so serve as the basis for a simple program to solve your problem.

For each implementation of the Library, NAG distributes the example programs in machine-readable form, with all necessary modifications already applied. Many sites make the programs accessible to you in this form. Generic forms of the programs, without implementation-specific modifications, may be obtained directly from the NAG website. The Users' Note for your implementation will mention any special changes which need to be made to the example programs.

Note that the results obtained from running the example programs may not be identical in all implementations and may not agree exactly with the results in the Manual.

For many routine documents, a plot of the example program results is also provided. In some cases the example program has been modified slightly to produce larger sets of results to give a more representative plot of the solution profile produced.

From a Fortran subprogram, the Use of the nag_library MODULE will help detect or prevent some common errors. For example, when using this, incorrect parameter types will be caught at compile time and using KIND=nag_wp in the type of real and complex variables will maintain consistency with the Library.

Otherwise, if a call to a Library routine results in an unexpected error message from the system (or possibly from within the Library), check the following:

• Have some actual array arguments been passed as different dummy arguments (i.e., an array appears more than once in the argument list with different INTENTs)?
• Have all array arguments been dimensioned correctly?

Avoid the use of NAG-type names for your own program units or COMMON blocks: in general, do not use names which contain a three-character NAG chapter name embedded in them; they may clash with named program units used by the NAG Library.

If the Library is called from a Fortran program then it is possible to use alternative names for user-callable routines. This can be done via the ‘Use nag_library’ statement at the start of the (sub)program in which the Library routine is called. For example, you wish to use the name ‘BesselJ0’ instead of the Library name s17aef. In this case the line

Use nag_library, Only: s17aef

would be replaced by

Use nag_library, Only: BesselJ0 => s17aef

The (sub)program would then use the name ‘BesselJ0’ in place of s17aef and call it with the identical interface.

If Library routines are called from other environments then many such environments offer ways of ‘aliasing’ a routine name by a preferred alternative name.

For many of the Library routines with more complex interfaces it is likely that only a subset of the functionality is required and that some parameter values will always remain unchanged or will not be referenced. In such cases it may be preferable to write your own wrapper to the Library routine with a much simpler interface and with a preferred alternative name. For example, if you wish to integrate a system of stiff ordinary differential equations without root finding or intermediate output, you could create the simple interface wrapper to the more complicated d02ejf interface.

Subroutine BDFsolve(xend,y)
Use nag_library, Only: nag_wp, d02ejf, d02ejw, d02ejx, d02ejy
Real(kind=nag_wp) :: xend, y(:)
Real(kind=nag_wp) :: tol, xstart
Integer           :: ifail, iw, n
Character         :: relabs
Real(kind=nag_wp), Allocatable :: w(:)

n = Size(y)
tol = 1.0e-3_nag_wp
relabs = 'M'
iw = (12+n)*n + 50
Allocate(w(iw))
ifail = 0
xstart = 0.0_nag_wp
Call d02ejf(xstart,xend,n,y,fcn,d02ejy,tol,relabs,d02ejx, &
            d02ejw,w,iw,ifail)
Return
End Subroutine BDFsolve

The above example of a user-defined wrapper would be compiled and linked with a main program that would include the simple call:

Call BDFsolve(xend,y)

The Fortran environment for the NAG Library FL Interface is defined by the nag_library MODULE. Certain routines require you to Use this to access named constants (e.g., nag_wp). It is recommended that you also Use the MODULE to enable checking of INTERFACEs in the Library.

The exact location of nag_library.mod is installation dependent; please see the Users' Note for your implementation.

The C/C++ environment when using the NAG Library FL Interface is defined within the NAG C header file nag.h. NAG defined types such as Integer and Charlen are defined in this header, as are the prototypes for C and C++ interfaces as given in the Specification section of individual routine documents.

The error, failure or warning conditions considered here are those that can be detected by explicit coding in a Library routine. Such conditions must be anticipated by the author of the routine. They should not be confused with run-time errors detected by the compilation system, e.g., detection of overflow or failure to assign an initial value to a variable.

In the rest of this document we use the word ‘error’ to cover all types of error, failure or warning conditions detected by the routine. They fall roughly into three classes.

1. (i)On entry to the routine the value of an argument is out of range. This means that it is not useful, or perhaps even meaningful, to begin computation.
2. (ii)During computation the routine decides that it cannot yield the desired results, and indicates a failure condition. For example, a matrix inversion routine will indicate a failure condition if it considers that the matrix is singular and so cannot be inverted.
3. (iii)Although the routine completes the computation and returns results, it cannot guarantee that the results are completely reliable; it therefore returns a warning. For example, an optimization routine may return a warning if it cannot guarantee that it has found a local minimum.

All three classes of errors are handled in the same way by the Library.

Each error which can be detected by a Library routine is associated with a number. Some numbers such as those associated with a failure in dynamic memory allocation (see Section 9) or detecting a valid licence (Section 8) are the same for all Library routines and may not be listed in individual routine documents. Recently added routines have standardized on using the same number for unexpected error exits (Section 7). All other numbers, with explanations of the errors, are listed in Section 6 (Error Indicators and Warnings) in the routine document. Unless the document specifically states to the contrary, you should not assume that the routine necessarily tests for the occurrence of the errors in their order of error number, i.e., the detection of an error does not imply that other errors have or have not been detected.

Most of the NAG FL Interface routines which can be called directly have an argument called ifail. This argument is concerned with the NAG Library error trapping mechanism (and, for some routines, with controlling the output of error messages and advisory messages).

ifail has two purposes:

1. (i)to allow you to specify what action the Library routine should take if an error is detected;
2. (ii)to inform you of the outcome of the call of the routine.

For purpose (i), you must assign a value to ifail before the call to the Library routine. Since ifail is reset by the routine for purpose (ii), the argument must be the name of a variable, not a literal or constant.

The value assigned to ifail before entry should be either $0$ (hard fail option), or $1$ or $-1$ (soft fail option). If after completing its computation the routine has not detected an error, ifail is reset to $0$ to indicate a successful call. Control returns to the calling program in the normal way. If the routine does detect an error, its action depends on whether the hard or soft fail option was chosen. If ifail is set to any value other than $\mathrm{-1}$, $0$ or $1$ before calling the Library routine, a default of ifail$=1$ is assumed.

If you set ifail to $0$ before calling the Library routine, execution of the program will terminate if the routine detects an error. Before the program is stopped, this error message is output:

** ABNORMAL EXIT from NAG Library routine XXXXXX: ifail = n
** NAG hard failure - execution terminated

where XXXXXX is the routine name, and n is the number associated with the detected error. An explanation of error number n is given in Section 6 of the routine document XXXXXX.

In addition, most routines output explanatory error messages immediately before the standard termination message shown above.

The hard fail option should be selected if you are in any doubt about continuing the execution of the program after an unsuccessful call to a NAG Library routine. For environments where it might be inappropriate to halt program execution when an error is detected it is recommended that the hard fail option is not used.

To select this option, you must set ifail to $1$ or $-1$ before calling the Library routine. Note that ifail$=1$ is assumed when ifail is set to an invalid value before calling the Library routine.

If the routine detects an error, ifail is reset to the associated error number; further computation within the routine is suspended and control returns to the calling program.

If you set ifail to $1$, then no error message is output (silent exit). If the output of error messages is undesirable, then silent exit is recommended.

If you set ifail to $-1$ (noisy exit), then before control is returned to the calling program, the following error message is output:

** ABNORMAL EXIT from NAG Library routine XXXXXX: ifail = n
** NAG soft failure - control returned

In addition, most routines output explanatory error messages immediately before the above standard message.

It is most important to test the value of ifail on exit if the soft fail option is selected. A nonzero exit value of ifail implies that the call was not successful so it is imperative that your program be coded to take appropriate action. That action may simply be to print ifail with an explanatory caption and then terminate the program. Many of the example programs in Section 10 of the routine documents have ifail-exit tests of this form. In the more ambitious case, where you wish your program to continue, it is essential that the program can branch to a point at which it is sensible to resume computation.

The soft fail option puts the onus on you to handle any errors detected by the Library routine. With the proviso that you are able to implement it properly, it is clearly more flexible than the hard fail option since it allows computation to continue in the case of errors. In particular there are at least two cases where its flexibility is useful:

1. (i)where additional information about the error or the progress of computation is returned via some of the other arguments;
2. (ii)in some routines, ‘partial’ success can be achieved, e.g., a probable solution found but not all conditions fully satisfied, so the routine returns a warning. On the basis of the advice in Section 6 and elsewhere in the routine document, you may decide that this partially successful call is adequate for certain purposes.

The notation $⟨\mathit{\text{value}}⟩$ appearing in the documented error message is a place holder that will be populated by the value of a variable, argument name or some other piece of information when that error message is displayed.

A few routines (introduced mainly at Marks 7 and 8) use ifail in a nonstandard way to control the output of error messages, and also of advisory messages (see Chapter X04). In those routines ifail is regarded as an integer of the form $100c+10b+a$, where $a$ and $b$ are either $0$ or $1$ and have the following significance:

Details are given in the documents of the relevant routines; for those routines this alternative use of ifail remains valid.

Most NAG Library routines perform no output to an external file, except possibly to output an error message. All error messages are written to a logical error message unit. This unit number (which is set by default to 6, stdout in C, in most implementations) can be changed by calling the Library routine x04aaf.

Some NAG Library routines may optionally output their final results, or intermediate results to monitor the course of computation. In general, output other than error messages is written to a logical advisory message unit. This unit number (which is also set by default to 6 in most implementations) can be changed by calling the Library routine x04abf. Although it is logically distinct from the error message unit, in practice the two unit numbers may be the same. Suites of routines with an option setting facility usually allow this unit number to be specified directly as an option.

All output from the Library is appropriately formatted.

There are only a few Library routines which perform input from an external file. These examples occur in Chapters E04, E05 and H. The unit number of the external file is an argument to the routine, and all input is formatted.

You must ensure that the relevant unit numbers are associated with the desired external files by one of: a call to x04acf, an OPEN statement in your calling Fortran program, operating system commands.

In addition to those Library routines which are documented and are intended to be called directly, the Library also contains many auxiliary routines.

In general, you need not be concerned with them at all, although you may be made aware of their existence if, for example, you examine a memory map of an executable program which calls NAG routines. The only exception is that when calling some NAG Library routines you may be required or allowed to supply the name of an auxiliary routine from the NAG Library as an external procedure argument. The routine documents give the necessary details. In such cases, you only need to supply the name of the routine; you never need to know details of its argument list.

NAG auxiliary routines have names which are similar to the name of the documented routine(s) to which they are related, but with last letter ‘Z’, ‘Y’, and so on, e.g.,

• g13afz is an auxiliary routine called by g13aff.

A few chapters contain auxiliary routines whose names are obtained by adding 50 to the second and third characters of the chapter name. For instance, Chapter E04 has an auxiliary routine with the name e54nfu which is normally used as the actual argument for the qphess argument of e04nfa; the corresponding name to be used with e04nff/​e04nfa is e04nfu/​e54nfu.

Internal calls to Library routines are checked for error exits even when these exits are not to be expected. Should an unexpected error exit occur the routine will set an error condition by setting ifail and exit with an appropriate error message. Historically, the number returned in ifail was particular to that routine and differing numbers could be used for this purpose. However, recently added routines have standardized by setting $\mathbf{ifail}=-99$ for unexpected error detection.

If your implementation is licence managed then your local site will have details on how the licence management is implemented; please contact your site installer for details. To determine whether a valid licence is available on your machine run the example program for a00acf.

Should a valid licence not be found when calling licence-managed routines from the Library then the routine will set an error condition, by setting $\mathbf{ifail}=-399$, and exit with an appropriate error message. On Unix-based systems, the appropriate environment variables should then be checked (e.g., NAG_KUSARI_FILE) to make sure this points to the licence file containing a valid licence, and the licence file should be checked for any obvious errors (e.g., the licence refers to a different implementation). If everything appears to be correct then please contact NAG (see NAG Technical Support Service for details).

Some NAG Library routines perform dynamic memory allocation to simplify their interfaces. Where possible, the amount of memory allocated by a routine will be given in the routine document (usually as a function of routine arguments). All memory allocated by NAG routines is usually deallocated before exit of that routine. In some cases deallocation is performed by a routine, from the same suite of routines, designed specifically to free memory allocation within the suite.

In the case where a routine detects a failure to dynamically allocate sufficient memory, the routine will set an error condition, by setting $\mathbf{ifail}=-999$, and exit with an appropriate error message.

In general the NAG Library can be called from other computer languages (such as C and Visual Basic) provided that appropriate mappings exist between their data types.

Section 3.3 describes calling the NAG FL Interface routines from C and C++. The Specification section of each routine document may optionally show the C and/or C++ specifications for that routine, via options described in Section 5 in the Guide to the NAG Library Documentation.

The Dynamic Link Libraries (DLLs) within Windows implementations can be called in a straightforward manner from a number of languages and environments, e.g., Visual Basic, Visual Basic for Applications (Excel), Fortran, C and C++. Guidance on this is provided in the Users' Note and on the NAG Web sites.

ACM (1960–1976) Collected algorithms from ACM index by subject to algorithms

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia https://www.netlib.org/lapack/lug

ANSI/IEEE (1985) IEEE standard for binary floating-point arithmetic Std 754-1985 IEEE, New York

Dongarra J J, Du Croz J J, Hammarling S and Hanson R J (1988) An extended set of FORTRAN basic linear algebra subprograms ACM Trans. Math. Software 14 1–32