NAG Fortran Library Manual, Mark 21 : Essential Introduction

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, e.g.,

Exceptionally, Chapters H and S 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, e.g.,

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, D03 and E04 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.

Chapter F06 (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., F06PAF (DGEMV). 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 and DGETRF) rather than the corresponding NAG-style names (e.g., F06PAF and F07ADF) 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:

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 routine document.

Documentation is provided in the following formats:

Advice on viewing and navigating the formats available can be found in the Online Help document.

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 for details).

An example of the output is:

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:

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:

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:

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:

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:

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:

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 Chapter Introduction.

Routines in Chapters F07 and F08 do not 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 F06 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 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. 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 and H. 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.,

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 routine parameters). 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, by setting IFAIL=-399 , 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:

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 both libraries.

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’ provide 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 routines.

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:

In a few documents (notably Chapters E04 and H) there are a further three sections:

The Chapter F06 routine documents currently consist of:

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

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 the routine.

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.

Communication Array: 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 is different.

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

For example, a Library routine might have the specification:

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

and the parameter LDB might be described as follows:

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 Fortran 77 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:

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

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:

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 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 parameters WORK and LWORK of the relevant routine documents and the Chapter Introduction.

In Chapters F06, F07 and F08, 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:

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 of precision).

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:

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:

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

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

6 References

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

1.	Purpose
2.	Specification
3.	Description
4.	References
5.	Parameters (see Section 3.3 below)
6.	Error Indicators and Warnings
7.	Accuracy
8.	Further Comments
9.	Example (see Section 3.5 below)

10.	Algorithmic Details
11.	Optional Parameters
12.	Description of Monitoring Information

1.	Purpose
2.	Specification
3.	Description
4.	References
5.	Parameters (see Section 3.3 below)
6.	Error Indicators and Warnings

real or double precision	means DOUBLE PRECISION
complex or complex*16	means COMPLEX*16 (or equivalent)
basic precision	means double precision
additional precision	means quadruple precision