Note: this document is essential reading for any prospective user of the Library.
1 The Library and its Documentation
1.1 Structure of the Library
The NAG Fortran Library is a comprehensive collection of routines for the solution of numerical and statistical problems.
The NAG SMP Library is the same collection of routines as those available in the NAG Fortran Library, many of which have been
specially tuned to maximize their performance on Symmetric Multiprocessor (SMP) machines. The document entitled ‘Introduction to the NAG SMP Library
’ is essential
reading for NAG SMP Library users.
The Library is divided into chapters, each devoted to a branch of numerical analysis or statistics. Each chapter has a three-character name and a title,
Exceptionally, Chapters H
have one-character names. (The chapters and their names are based on the ACM modified SHARE classification index (see ACM (1960–1976)
All documented routines in the Library have six-character names, beginning with the characters of the chapter name,
Note that the second and third characters are digits
, not letters; e.g., 0 is the digit zero, not the letter O. The last letter of each routine name almost always appears as
‘F’ in the documentation. Chapters C05
have some routines whose last letter is ‘A’ rather than ‘F’. An ‘A’ version is always paired with an ‘F’ routine, the ‘A’
version being safe to use in a multithreaded environment, but otherwise having identical functionality to the ‘F’ version.
(Linear Algebra Support Routines
) contains all the Basic Linear Algebra Subprograms, BLAS, with NAG-style names as well as with the actual BLAS names, e.g.,
. The names in brackets are the equivalent double precision BLAS names. Chapter F07
(Linear Equations (LAPACK)
) and Chapter F08
(Least-squares and Eigenvalue Problems (LAPACK)
) contain routines derived from the LAPACK project. Like the BLAS, these routines have NAG-style names as well as LAPACK
names, e.g., F07ADF (DGETRF)
. Details regarding these alternate names can be found in the relevant Chapter Introductions.
In order to take full advantage of machine-specific versions of BLAS and LAPACK routines provided by some computer hardware
vendors, you are encouraged to use the BLAS and LAPACK names (e.g., DGEMV
) rather than the corresponding NAG-style names (e.g., F06PAF
) wherever possible in your programs.
1.2 Structure of the Documentation
The NAG Fortran Library Manual is the principal documentation for both the NAG Fortran Library and the NAG SMP Library.
It has the same chapter structure as the Library: each chapter of routines in the Library has a corresponding chapter (of
the same name) in the Manual. The chapters occur in alphanumeric order. General introductory documents appear at the beginning
of the Manual.
Each chapter consists of the following documents:
- Chapter Contents, e.g., Chapter D01;
- Chapter Introduction, e.g., the D01 Chapter Introduction;
- Routine Documents, one for each documented routine in the chapter.
A routine document has the same name as the routine which it describes. Within each chapter, routine documents occur in alphanumeric
order. For those chapters that have both ‘A’ and ‘F’ versions of a routine, the routine descriptions are combined into one
Documentation is provided in the following formats:
- PDF+HTML, a full PDF manual which can be browsed using HTML index files; and
- PDF, a full PDF manual browsed using the PDF bookmarks.
Advice on viewing and navigating the formats available can be found in the Online Help
The most up-to-date version of the documentation is accessible via the NAG web site
(see Section 4
1.3 Implementations of the Library
The Library is available on many different computer systems. For each distinct system, an implementation of the Library is prepared by NAG, e.g., the Sun Solaris 32-bit implementation. The implementation is distributed to sites
as a tested compiled library.
An implementation is usually specific to a range of machines (e.g., the Sparc systems); it may also be specific to a particular
operating system, Fortran compiler, or compiler option (such as scalar or vector mode or thread safe).
Essentially the same facilities are provided in all implementations of the Library, but, because of differences in arithmetic
behaviour and in the compilation system, routines cannot be expected to give identical results on different systems, especially
for sensitive numerical problems.
The documentation supports all implementations of the Library, with the help of a few simple conventions, and a small amount
of implementation-dependent information, which is published in a separate Users' Note
for each implementation (see Section 3.4
1.4 Library Identification
Periodically a new Mark of the NAG Fortran Library is released: new routines are added, corrections and/or improvements are made to existing routines;
and occasionally routines are withdrawn if they have been superseded by improved routines.
You must know which implementation
, which precision
and which mark
of the Library you are using or intend to use. To find out which implementation, precision and mark of the Library is available
at your site, you can run a program which calls the NAG Library routine A00AAF
The program could be:
Alternatively, the example program for A00AAF
can be run using the nagexample
scripts supplied with your implementation (see the Users' Note
An example of the output is:
*** Start of NAG Library implementation details ***
Implementation title: IA32, Linux, Intel Fortran
Precision: FORTRAN double precision
Product Code: FLLUX21DC
*** End of NAG Library implementation details ***
1.5 Fortran Language Standards
All routines in the Library conform to the ISO Fortran 95 Standard (ISO (1997)
), except for the use of a double precision complex data type (usually COMPLEX*16).
2 Using the Library
2.1 General Advice
A NAG Fortran Library routine cannot be guaranteed to return meaningful results irrespective of the data supplied to it. Care and thought must be exercised in:
- formulating the problem;
- programming the use of library routines;
- assessing the significance of the results.
The Foreword to the Manual provides some further discussion of points (a) and (c); the remainder of Section 2
is concerned with (b).
2.2 Programming Advice
The Library and its documentation are designed on the assumption that you know how to write a calling program in Fortran.
When programming a call to a routine, read the routine document carefully, especially the description of the Parameters
. This states clearly which parameters must have values assigned to them on entry to the routine, and which return useful
values on exit. See Section 3.3
for further guidance.
The most common types of programming error in using the Library are:
- incorrect parameters in a call to a Library routine;
- calling the Library from a single precision program.
Therefore 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:
- Has the NAG routine been called with the correct number of parameters?
- Do the parameters all have the correct type?
- Have all array parameters been dimensioned correctly?
- Does your program pass the correct precision parameters to the NAG Library routines?
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 the names of an auxiliary routine or COMMON block used
by the NAG Library.
2.3 Error Handling and the Parameter IFAIL
NAG Fortran Library routines may detect various kinds of error, failure or warning conditions. Such conditions are handled
in a systematic way by the Library. They fall roughly into three classes:
- an invalid value of a parameter on entry to a routine;
- a numerical failure during computation (e.g., approximate singularity of a matrix, failure of an iteration to converge);
- a warning that, although the computation has been completed, the results cannot be guaranteed to be completely reliable.
All three classes are handled in the same way by the Library, and are all referred to here simply as ‘errors’.
The error-handling mechanism uses the parameter IFAIL, which occurs as the last parameter in the calling sequence of most NAG Library routines. IFAIL serves two purposes:
- it allows you to specify what action a Library routine should take if it detects an error;
- it reports the outcome of a call to a Library routine, either ‘success’ (IFAIL=0) or ‘failure’ (IFAIL≠0, with different values indicating different reasons for the failure, as explained in Section 6 of the routine documents).
For the first purpose IFAIL must be assigned a value before calling the routine; since IFAIL is reset by the routine, it must be passed as a variable, not as an integer constant. Allowed values on entry are:
- IFAIL=0: an error message is output, and execution is terminated (‘hard failure’);
- IFAIL=+1: execution continues without any error message;
- IFAIL=-1: an error message is output, and execution continues.
The settings IFAIL=±1 are referred to as ‘soft failure’.
The safest choice is to set IFAIL to 0, but this is not always convenient: some routines return useful results even though a failure (in some cases merely
a warning) is indicated. However, if IFAIL is set to ±1 on entry, it is essential for the program to test its value on exit from the routine, and to take appropriate action.
The specification of IFAIL in Section 5 of a routine document suggests a suitable setting of IFAIL for that routine.
For a full description of the error-handling mechanism, see the P01
Routines in Chapters F07
use the usual error handling mechanism; in order to preserve complete compatibility with LAPACK software, they have a diagnostic
output parameter INFO which need not be set before entry. See the relevant Chapter Introduction for further details.
Some routines in Chapter F06
output an error message if an illegal input parameter is detected, then terminate program execution immediately. See the
Chapter Introduction for further details.
2.4 Input/output in the Library
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 in most implementations) can be changed by calling the Library routine
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
. Although it is logically distinct from the error message unit, in practice the two unit numbers may be the same. A few
routines in Chapter E04
allow this unit number to be specified directly as an option.
All output from the Library is formatted.
There are only a few Library routines which perform input from an external file. These examples occur in Chapters E04
. The unit number of the external file is a parameter to the routine, and all input is formatted.
You must ensure that the relevant Fortran unit numbers are associated with the desired external files, either by an OPEN statement
in your calling program, or by operating system commands.
2.5 Auxiliary Routines
In addition to those Library routines which are documented and are intended to be called by yourself, 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 parameter. 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 parameter 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.,
- D01BAZ is an auxiliary routine called by D01BAF.
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 E54UCZ.
2.6 Dynamic Memory Allocation
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
All memory allocated by NAG routines is deallocated before exit.
In the case where a routine detects a failure to dynamically allocate sufficient memory, the routine will set an error condition
and return IFAIL=-999.
2.7 License Management
If your implementation is license managed then your local site will have details on how the license management is implemented;
please contact your site installer for details. To determine whether a valid license is available on your machine run the
example program for A00ACF
Should a valid license not be found when calling managed routines from the Library then the routine will set an error condition,
, and exit with an appropriate error message.
2.8 Thread Safety
Some implementations of the Library facilitate the use of threads; that is, you can call routines from the Library from within
a multithreaded application. Fully thread safe libraries are provided for several platforms — for more information please
contact your local Response Centre (see Section 4
). See the Thread Safety
document for more detailed guidance on using the Library in a multithreaded context. You may also need to refer to the Users' Note
for details of whether your implementation of the Library has been compiled in a manner that facilitates the use of threads.
Note that in some implementations, the Library is linked with one or more vendor libraries to provide, for example, efficient
BLAS routines. NAG cannot guarantee that any such vendor library is thread safe.
2.9 Calling the Library from Other Languages
In general the NAG Fortran Library can be called from other computer languages (such as C and Visual Basic) provided that
appropriate mappings exist between their data types.
NAG has produced C Header Files which comprise of a set of header files indicating the match between C and Fortran data types
for various compilers, documentation and examples. The documentation, examples and C Header Files are available from the
NAG Web sites (see Section 4
The Dynamic Link Library (DLL) implementation can be called in a straightforward manner from a number of languages and environments,
e.g., Visual Basic, Visual Basic for Applications (Excel), Delphi, C and C++. Guidance on this is provided as part of NAG
Fortran Library DLLs. Further details can be found on the NAG Web sites.
3 Using the Documentation
3.1 Using the Manual
The Manual is designed to serve the following functions
for both the NAG Fortran Library and the NAG SMP Library:
- to give background information about different areas of numerical and statistical computation;
- to advise on the choice of the most suitable NAG Library routine or routines to solve a particular problem;
- to give all the information needed to call a NAG Library routine correctly from a Fortran program, and to assess the results.
At the beginning of the Manual are some general introductory documents which provide some background and additional information.
There are a small number of documents which are specific to the NAG Fortran Library and specific to the NAG SMP Library and
you need not read those not specific the library you are using. All other general introductory documents are relevant to
The document entitled ‘Introduction to the NAG SMP Library
’ is essential
reading for NAG SMP Library users.
The documents entitled ‘Mark 21 News – NAG Fortran Library
’ and ‘Mark 21 News – NAG SMP Library
details of new routines added, details of documents scheduled for withdrawal and details of documents withdrawn at this mark.
The Mark 21 News – NAG SMP Library
also provides details of routines which have been tuned or enhanced at this mark; a full list of such routines is available
in the document ‘Tuned and Enhanced Routines in the NAG SMP Library
The document entitled ‘Library Contents
’ (a structured list of routines in the Library, by chapter) may help you to find the chapter, and possibly the routine, which
you need to solve your problem.
The document entitled ‘Withdrawn Routines
’ provides full details of all routines withdrawn from the NAG Fortran Library and the document entitled ‘Advice on Replacement Calls for Withdrawn/Superseded Routines
’ provides details of the minimum change necessary to allow you to take full advantage of new functionality provided by replacement
The online documentation provides you with a fully linked HTML Keyword Index
(a keyword index to routines) and GAMS Classification Index
(a list of NAG routines classified according to the GAMS scheme).
Having found a likely chapter or routine, you should read the corresponding Chapter Introduction, which gives background information about that area of numerical computation, and recommendations on the choice of a routine,
including indexes, tables or decision trees.
When you have chosen a routine, you must consult the routine document. Each routine document is essentially self-contained (it may, however, contain references to related documents). It includes
a description of the method, detailed specifications of each parameter, explanations of each error exit, remarks on accuracy,
and (in most cases) an example program to illustrate the use of the routine.
3.2 Structure of Routine Documents
All routine documents have the same structure,
with the exception of Chapter F06
consisting of nine numbered sections:
||Parameters (see Section 3.3 below)
||Error Indicators and Warnings
||Example (see Section 3.5 below)
In a few documents (notably Chapters E04
) there are a further three sections:
||Description of Monitoring Information
The Chapter F06
routine documents currently consist of:
||Parameters (see Section 3.3 below)
||Error Indicators and Warnings
3.3 Specification of Parameters
Section 5 of each routine document contains the specification of the parameters, in the order of their appearance in the parameter
3.3.1 Classification of parameters
Parameters are classified as follows.
Input: you must assign values to these parameters on or before entry to the routine, and these values are unchanged on exit from
Output: you need not assign values to these parameters before entry to the routine; the routine may assign values to them.
Input/Output: you must assign values to these parameters before entry to the routine, and the routine may then change these values.
Workspace: array parameters 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.
array parameters which are used to communicate data from one subroutine call to another.
External Procedure: a subroutine or function 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 parameter
list and specifications of its parameters (all enclosed in a box). Its parameters 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
- Input: values may be supplied on entry, which your procedure must not change.
- Output: you may or must assign values to these parameters 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 2.5
, the procedure can be supplied from the NAG Library, and then you only need to know its name.
User Workspace: array parameters which are passed by the Library routine to an external procedure parameter. 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 parameter is usually a parameter which was required by an earlier version of the routine and
is retained in the parameter list for compatibility.)
3.3.2 Constraints and suggested values
The word ‘Constraint:’ or ‘Constraints:’ in the specification of an Input parameter introduces a statement of the range of valid values for that parameter, e.g.,
If the routine is called with an invalid value for the parameter
(e.g., N = 0
), the routine will usually take an error exit, returning a non-zero value of IFAIL
(see Section 2.3
In newer routine documents, constraints on parameters of type CHARACTER only list upper case alphabetic characters, e.g.,
In practice, all routines with CHARACTER parameters will permit the use of lower case characters.
The phrase ‘Suggested Values:’ introduces a suggestion for a reasonable initial setting for an Input parameter (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.
3.3.3 Array parameters
Most array parameters 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 parameters of the Library
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 parameter, such as A in this example, the specification would begin
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 parameter, 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 parameter 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: LDB ≥ M.
You must supply the first dimension of the array B, as declared in your calling (sub)program, through the parameter LDB, even though the number of
rows actually used by the routine is determined by the parameter 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 parameter LDB is needed because
does not allow information about the dimensions of array parameters to be passed automatically to a routine.
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
Fortran 77 requires that the dimensions which occur in array declarations must be greater than zero. Many NAG routines are
designed so that they can be called with a parameter like N in the above example set to 0 (in which case they would usually
exit immediately without doing anything). If so, the declarations in the Library routine would use the ‘assumed size’ array
dimension, and would be given as
INTEGER M, N, A(*), B(LDB,*), LDB
However, the original declaration of an array in your calling program must always have constant dimensions, greater than or
equal to 1.
Consult an expert or a textbook on Fortran if you have difficulty in calling NAG routines with array parameters.
3.4 Implementation-dependent Information
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.
The most important bold italicised terms and their interpretation are as follows:
|real or double precision
||means DOUBLE PRECISION
|complex or complex*16
||means COMPLEX*16 (or equivalent)
||means double precision
||means quadruple precision
For historical reasons documents for some older Library routines typically use the convention real or complex, to identify implementation-dependent types, whereas newer routine documents use the equivalent double precision and complex*16 respectively.
Another important bold italicised term is machine precision, which denotes the relative precision to which double precision 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-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
. 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 parameters WORK and LWORK of the relevant routine documents and the Chapter
In Chapters F06
, alternate routine names are available for BLAS and LAPACK derived routines. For details of the alternate routine names please
refer to the relevant 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 interpretation of bold italicised terms;
- the values returned by X02 routines;
- the default unit numbers for output (see Section 2.4);
- details of name changes for Library routines (see Section 2.5).
3.5 Example Programs and Results
The example program in Section 9 of each routine document illustrates a simple call of the routine. The programs are designed so that they can
fairly easily be 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 Web site.
Note that the results from running the example programs may not be identical in all implementations, and may not agree exactly
with the results in the Manual and which were obtained from a double precision implementation (with approximately 16 digits
The Users' Note
for your implementation will mention any special changes which need to be made to the example programs, and any significant
differences in the results.
3.6 Summary for New Users
If you are unfamiliar with this library and are thinking of using a routine from it, please follow these instructions:
- read the whole of this Essential Introduction;
- consult the Library Contents list to select an appropriate chapter or routine;
- or search through the Keyword Index or GAMS Classification Index or via an online search facility;
- read the relevant Chapter Introduction;
- choose a routine, and read the routine document. If the routine does not after all meet your needs, return to step (b), (c) or (d);
- read the Users' Note for your implementation;
- consult local documentation, which should be provided by your local support staff, about access to the Library on your computing
- obtain an online copy of the example program for the particular routine of interest and experiment with it.
You should now be in a position to include a call to the routine in a program, and to attempt to compile and run it. You may
of course need to refer back to the relevant documentation in the case of difficulties, for advice on assessment of results,
and so on.
As you become familiar with the Library, some of steps (a) to (h) can be omitted, but it is always essential to:
- be familiar with the Chapter Introduction;
- read the routine document;
- be aware of the Users' Note for your implementation.
4 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
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 Users' Note
or 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:
5 Background to NAG
Various aspects of the design and development of the NAG Library, and NAG's technical policies and organisation are given
in Ford (1982)
, Ford et al. (1979)
, Ford and Pool (1984)
, and Hague et al. (1982)
ACM (1960–1976) Collected algorithms from ACM index by subject to algorithms
ANSI (1966) USA standard Fortran Publication X3.9 American National Standards Institute
ANSI (1978) American National Standard Fortran Publication X3.9 American National Standards Institute
ANSI/IEEE POSIX (1995) POSIX Standard Thread Library ANSI/IEEE POSIX 1003.1c:1995
Ford B (1982) Transportable numerical software Lecture Notes in Computer Science 142 128–140 Springer–Verlag
Ford B, Bentley J, Du Croz J J and Hague S J (1979) The NAG Library ‘machine’ Softw. Pract. Exper. 9 (1) 65–72
Ford B and Pool J C T (1984) The evolving NAG Library service Sources and Development of Mathematical Software (ed W Cowell) 375–397 Prentice–Hall
Hague S J, Nugent S M and Ford B (1982) Computer-based documentation for the NAG Library Lecture Notes in Computer Science 142 91–127 Springer–Verlag
ISO (1997) ISO Fortran 95 programming language (ISO/IEC 1539–1:1997)
ISO/IEC (1990) Information technology – Programming Language C Current C Language Standard ISO/IEC 9899:1990
Kernighan B W and Ritchie D M (1988) The C Programming Language (2nd Edition) Prentice–Hall
© The Numerical Algorithms Group Ltd, Oxford, UK. 2006