This document is essential reading for any prospective user of the Library.
The information provided in this product is suitable for users of both the NAG Fortran Library, Mark 19 and the NAG Fortran SMP Library. Please note, however, that a small number of routines are specific to one particular product. Thus new routines introduced into the NAG Fortran Library at Mark 19 have an explanatory note at the beginning of the routine description; routines specific to the NAG Fortran SMP Library are contained in a special chapter called SMP: Fortran SMP Library Specific Documentation. Users should check which Library they are using before attempting to call these Library-specific routines.
The NAG Fortran Library is a comprehensive collection of Fortran routines for the solution of numerical and statistical problems. The word "routine" is used to denote "subroutine" or "function".
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.,
D01 - QuadratureExceptionally, two chapters (Chapter H and Chapter S) have one-character names. (The chapters and their names are based on the ACM modified SHARE classification index [1].)
All documented routines in the Library have six-character names, beginning with the characters of the chapter name, e.g.,
D01AJFNote 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 always appears as "F" in the documentation, but may be changed to "E" in some single precision implementations (see Precision of the Library).
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., F06AAF (SROTG/DROTG). The names in brackets are the equivalent single and double precision BLAS names respectively. 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 (SGETRF/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., SROTG/DROTG and SGETRF/DGETRF) rather than the corresponding NAG-style names (e.g., F06AAF and F07ADF) wherever possible in your programs.
The NAG Fortran Library Manual is the principal printed form of documentation for the NAG Fortran 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 and indexes are placed in Volume 1 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. Exceptionally, two chapters (Chapter X01, Chapter X02) do not have individual routine documents; instead, all the routines are described together in the Chapter Introduction. Another exception is Chapter A00, which contains neither a Chapter Introduction nor any routine documents. It does however contain a user-callable support routine that identifies which version of the Library is available at your site (see Library Identification).
In addition to the full printed Manual, NAG produces a printed Introductory Guide, which contains all the introductory material from the Manual, together with all the Chapter Contents and Chapter Introductions.
NAG also provides machine-based documentation. The ability to display mathematics and symbols has now reached a stage whereby it is possible to produce a satisfactory full HTML version of the Library documentation that will provide ready access to users via standard Web browsers. This HTML version will replace the current hypertext version (TextWare), but will retain many of the features of that product. The aim is to have an HTML version of Mark 19 of the Fortran Library documentation ava lable for distribution with the Library software. It will also be accessible via the NAG Web site. Future releases may take advantage of technology that is currently being developed (e.g., MathML).
Periodically a new Mark of the NAG Fortran Library is released: new routines are added, corrections or improvements are made to existing routines; occasionally routines are withdrawn if they have been superseded by improved routines.
At each Mark, the documentation of the Library is updated. You must make sure that your documentation has been updated to the same Mark as the Library software that you are using.
Marks are numbered, e.g., 16, 17, 18. The current Mark is 19.
The Library software may be updated between Marks to an intermediate maintenance level, in order to incorporate corrections. Maintenance levels are indicated by a letter following the Mark number, e.g., 19A, 19B, and so on (Mark 19 documentation supports all these maintenance levels).
The NAG Fortran Library is available on many different computer systems. For each distinct system, an implementation of the Library is prepared by NAG, e.g., the Cray C-90 Unicos 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 DEC VAX range); it may also be specific to a particular operating system, Fortran compiler, or compiler option (e.g., scalar or vector mode).
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 Implementation-dependent Information).
The NAG Fortran Library is developed in both single precision and double precision versions. REAL variables and arrays in the single precision version are replaced by DOUBLE PRECISION variables and arrays in the double precision version.
On most systems only one precision of the Library is available; the precision chosen is that which is considered most suitable in general for numerical computation (double precision on most systems).
On some systems both precisions are provided: in this case, the double precision routines have names ending in "F" (as in the documentation), and the single precision routines have names ending in "E". Thus in DEC VAX/VMS implementations:
Whatever the precision, INTEGER variables (and elements of arrays) always occupy one numeric storage unit, that is the Library is not implemented using non-standard [7] integer storage, e.g., INTEGER*2.
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 (or A00AAE in most single precision implementations). This routine has no parameters; it simply outputs text to the NAG Library advisory message unit (see Input/output in the Library). An example of the output is:
*** Start of NAG Library implementation details ***
Implementation title: Sun(SPARC) Solaris
Precision: double
Product Code: FLSOL19D
Mark: 19
*** End of NAG Library implementation details ***
(The product code can be ignored, except possibly when communicating with NAG; see Support from NAG.)
All routines in the Library conform to the ISO Fortran 90 Standard [8], except for the use of a double precision complex data type (usually COMPLEX*16) in some routines in Fortran 77 compiled double precision implementations of the Library - there is no provision for this data type in the old ANSI Standard Fortran 77 [7].
Many of the routines in the Library were originally written to conform to the earlier Fortran 66 standard [6], and their calling sequences may contain a few parameters which are not strictly necessary in Fortran 77.
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 NAG Fortran 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 Specification of Parameters for further guidance.
The most common types of programming error in using the Library are:
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.
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:
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:
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 Chapter P01.
Routines in Chapter F07 and Chapter 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 F07 Chapter Introduction or F08 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 F06 Chapter Introduction for further details.
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 Chapter E04 and Chapter 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.
In addition to those Library routines which are documented and are intended to be called by users, the Library also contains many auxiliary routines. Details of all the auxiliary routines which are called directly or indirectly by any documented NAG Library routine are supplied to sites in machine-readable form with the Library software.
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.In a single precision implementation in which the names of documented routines end in "E", the names of auxiliary routines have their first three and last three characters interchanged, e.g.,
BAZD01 is an auxiliary routine (corresponding to D01BAZ) called by D01BAE.
Some implementations of the Library facilitate the use of threads; that is, you can call routines from the Library from within a multi-threaded application. You should note however that Mark 19 is not fully thread safe. See the document "Thread Safety" for more detailed guidance on using the Library in a multi-threaded 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.
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.
As part of its Library service, NAG provides a C Header Files service which comprises a set of header files indicating the match between C and Fortran data types for various compilers, documentation and examples. The documentation and examples are available from the NAG Web site.
The Dynamic Link Library (DLL) version can be called in a straightforward manner from Visual Basic. Guidance on this is provided as part of the NAG Fortran Library DLLs. Further details can be found on the NAG Web site.
The Manual is designed to serve the following functions:
| Library Contents | -- | a structured list of routines in the Library, by chapter; |
| KWIC Index | -- | a keyword index to chapters and routines; |
| GAMS Index | -- | a list of NAG routines classified according to the GAMS scheme. |
When you have chosen a routine, you must consult the routine document. Each routine document is essentially self-contained (it may 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.
All routine documents have the same structure, consisting of nine numbered sections:
| 1. | Purpose | |
| 2. | Specification | |
| 3. | Description | |
| 4. | References | |
| 5. | Parameters | (see Specification of Parameters below) |
| 6. | Error Indicators and Warnings | |
| 7. | Accuracy | |
| 8. | Further Comments | |
| 9. | Example | (see Example Programs and Results below) |
| 10. | Algorithmic Details |
| 11. | Optional Parameters |
| 12. | Description of Monitoring Information |
Section 5 of each routine document contains the specification of the parameters, in the order of their appearance in the parameter list.
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 on or before entry to the routine; the routine may assignvalues to them.
Input/Output: you must assign values to these parameters on or 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.
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 Auxiliary Routines, 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.)
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.,
Constraint: N > 0.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 Error Handling and the Parameter IFAIL).
In newer routine documents, constraints on parameters of type CHARACTER only list upper case alphabetic characters, e.g.,
Constraint: STRING = 'A' or 'B'.In practice, all routines with CHARACTER parameters will permit the use of lower case characters.
The phrase "Suggested Value:" 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.
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:
SUBROUTINE <name> (M, N, A, B, LDB) INTEGER M, N, A(N), B(LDB,N), LDBFor a one-dimensional array parameter, such as A in this example, the specification would begin:
A(N) - INTEGER arrayYou 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 arrayand the parameter LDB might be described as follows:On entry: the m by n matrix B.
LDB - INTEGER InputYou 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 does not allow information about the dimensions of array parameters to be passed automatically to a routine.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 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)Fortran 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,*), LDBHowever, 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.
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 are the following; their interpretation depends on whether the implementation is in single precision or double precision.
| real | means | REAL | or | DOUBLE PRECISION |
| complex | means | COMPLEX | or | COMPLEX*16 (or equivalent) |
| basic precision | means | single precision | or | double precision |
| additional precision | means | double precision | or | quadruple precision |
The precise value of machine precision is given by the function X02AJF. Other functions in Chapter X02 return the values of other implementation-dependent constants, such as the overflow threshold, or the largest representable integer. Refer to X02 Chapter Introduction for more details.
The bold italicised term block size is used only in Chapter F07 and Chapter 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.
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 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.
Bold italicised terms are used in the printed text of the example program to denote precision-dependent features in the code. The correct Fortran code must therefore be substituted before the program can be run. In addition to the terms real and complex, which were explained in Implementation-dependent Information, the following terms are used in the example programs:
| Intrinsic Functions: | real | means | REAL | or | DBLE |
|
| imag | means | AIMAG | or | DIMAG | ||
| cmplx | means | CMPLX | or | DCMPLX | ||
| conjg | means | CONJG | or | DCONJG | ||
| Edit Descriptor: | e | means | E | or | D | (in FORMAT statements) |
| Exponent Letter: | e | means | E | or | D | (in constants) |
The examples in Chapter F07 and Chapter F08 use the precision-dependent LAPACK routine names, as mentioned in Implementation-dependent Information.
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. They may also 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 which are printed 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.
If you are unfamiliar with the NAG Library and are thinking of using a routine from it, please follow these instructions:
As you become familiar with the Library, some of steps (a) to (f) can be omitted, but it is always essential to:
NAG places considerable emphasis on providing high quality user support. In addition to comprehensive documentation we offer a variety of services to support our users.
The Response Centres are available to answer technical queries from sites with an annually licensed product or Support Service.
The Response Centres are open during office hours, but contact is possible by fax, email and telephone (answering machine) at all times. You can find the contact details for your local Response Centre in the Support Documentation supplied with this product.
However, general queries concerning this library should be directed initially to any local advisory service your site may provide.
The NAG web sites provide a valuable resource for product information, technical documentation and demonstrations, as well as articles of more general interest. The sites can be accessed at:
www.nag.co.uk or www.nag.com
NAG organises workshops and training courses at various locations throughout the world. Information about forthcoming courses is posted on the NAG web sites. If you have a particular training requirement please contact us.
As well as offering these services to users, NAG values feedback to ensure that we continue to develop products that meet your needs. We welcome your comments.
Various aspects of the design and development of the NAG Library, and NAG's technical policies and organisation are given in references [2], [3], [4], and [5].
[1] (1960--1976) Collected algorithms from ACM index by subject to algorithms
[6] (1966) USA standard Fortran Publication X3.9 American National Standards Institute
[7] (1978) American National Standard Fortran Publication X3.9 American National Standards Institute
[8] ISO Fortran 90 programming language (ISO 1539:1991)