This document is essential reading for every user of the NAG Fortran Library
implementation specified in the title. It provides implementation-specific
detail that augments the information provided in the NAG Mark 22 Library
Manual (which we will refer to as the Library Manual).
Wherever that manual refers to the "Users' Note for
your implementation", you should consult this note.

In addition, NAG recommends that before calling any Library routine you should
read the following reference material (see
Section 5):

For best performance, we recommend that you should use the
variant of the NAG Fortran Library which is based on the
supplied AMD Core Math Library (ACML) i.e.
libnag_acml.a or libnag_acml.so.
However if you use a version of the
ACML different from the version used in creating this implementation
and you have problems when calling a NAG routine, we suggest that
you use one of the above libraries with the supplied
ACML, or one of
the self-contained libraries
libnag_nag.a or libnag_nag.so.

In this section we assume that the library has
been installed in the directory [INSTALL_DIR].

By default [INSTALL_DIR]
(see Installer's Note (in.html)) is
/opt/NAG/fll6a22dpl
or
/usr/local/NAG/fll6a22dpl
depending on your system; however it could have been changed by the
person who did the installation.
To identify [INSTALL_DIR] for this installation:

if /opt/NAG/fll6a22dpl
exists, then this is [INSTALL_DIR]

if /usr/local/NAG/fll6a22dpl
exists, then this is [INSTALL_DIR]

consult the installer for the location of the directory
[INSTALL_DIR].

To use the NAG Fortran Library and the supplied ACML libraries,
you may link in the following manner:

if the shareable library is required.
Please note the shareable library is fully resolved so that, as long as the
environment variable LD_LIBRARY_PATH is set correctly at link
time (see below), you need not link against other run-time
libraries explicitly.

However, if you prefer to link to a version of the NAG Library
which does not require the use of ACML, then
you may wish to
use the self-contained libraries as follows:

pgf90 driver.f [INSTALL_DIR]/lib/libnag_nag.a

or

pgf90 driver.f [INSTALL_DIR]/lib/libnag_nag.so

if the shareable library is required.

If the compiled libraries and the supplied ACML libraries
are pointed at by symbolic links from a directory in the search path of
the linker, such as /usr/lib, then you may alternatively link
in the following manner:

pgf90 driver.f -lnag_acml -lacml -lacml_mv

This will usually link to the shareable library in preference to the
static library if both the libraries are at the same location.
Please note the shareable library is fully resolved so that, as long as the
environment variable LD_LIBRARY_PATH is set correctly at link
time (see below), you need not link against other run-time
libraries explicitly.

To use the static library
libnag_acml.a you need the -Bstatic
compiler flag to switch static binding on and -Bdynamic to
switch dynamic binding on.

pgf90 -Bstatic driver.f -lnag_acml -lacml -lacml_mv -Bdynamic

Similarly for the self-contained libraries the commands

pgf90 driver.f -lnag_nag

or

pgf90 -Bstatic driver.f -lnag_nag -Bdynamic

may be used to link to the shared library or the static library
respectively.

If your application has been linked with the shareable NAG and ACML libraries
then the environment variable LD_LIBRARY_PATH
must be set (or extended) to allow run time linkage.

The NAG Fortran Library interface blocks define the type and arguments of each
user callable NAG Fortran Library routine. These are not essential to calling
the NAG Fortran Library from Fortran programs. Their purpose is to allow
the Fortran compiler to check that NAG Fortran Library routines are
called correctly. The interface blocks enable the compiler to check that:

(a) subroutines are called as such;
(b) functions are declared with the right type;
(c) the correct number of arguments are passed; and
(d) all arguments match in type and structure.

These interface blocks have been generated automatically by analysing the
source code for the NAG Fortran Library. As a consequence, and because these
files have been thoroughly tested, their use is recommended in preference to
writing your own declarations.

These are supplied in pre-compiled form (.mod files) and they can be accessed
by specifying the
-Ipathname
option on each compiler invocation, where
pathname ([INSTALL_DIR]/nag_interface_blocks)
is the path of the directory containing the compiled interface blocks.

In order to make use of these modules from existing Fortran 77 code, the
following changes need to be made:

Add a USE statement for each of the module files for the chapters of the NAG
Fortran Library that your program calls directly. Only one USE statement
will be required for each chapter referenced.
The interface blocks for the Basic Linear Algebra Subprograms (BLAS)
and linear algebra routines (LAPACK) are
in nag_f77_f_chapter.

Delete all EXTERNAL statements for NAG Fortran Library routines (including
BLAS and LAPACK routines). These are now declared in the module(s).

Delete the type declarations for any NAG Fortran Library functions. These are
now declared in the module(s).

The above steps need to be done for each unit (main program, function
or subroutine) in your code.

These changes are illustrated by showing the conversion of the Fortran 77
version of the example program for NAG Fortran Library routine D01DAF. Please
note that this is not exactly the same as the example program that is
distributed with this implementation. Each change is surrounded by comments
boxed with asterisks.

The example results distributed were generated at Mark 22, using the software
described in Section 2.2 of the Installer's
Note. These example results may
not be exactly reproducible if the example programs are run in a slightly
different environment (for example, a different Fortran compiler, a different
compiler library, or a different set of BLAS or LAPACK routines). The results
which are most sensitive to such differences are: eigenvectors (which may
differ by a scalar multiple, often
-1, but
sometimes complex); numbers of iterations and function evaluations; and
residuals and other "small" quantities of the same order as the machine
precision.

Note that the example material has been adapted, if necessary, from that
published in the Library Manual, so that programs are suitable for
execution with this implementation with no further changes.
The distributed example programs should be used in preference to the versions
in the Library Manual wherever possible.

nag_example_acml, to link with the NAG static library
libnag_acml.a and the supplied ACML libraries

nag_example_shar_acml, to link with the NAG shareable library
libnag_acml.so and the supplied ACML libraries

nag_example, to link with the NAG self-contained static library
libnag_nag.a

nag_example_shar, to link with the NAG self-contained shareable library
libnag_nag.so

Each command will provide you with a copy of an example program (and its data,
if any), compile the program and link it with the appropriate libraries
(showing you the compile command so that you can recompile your own
version of the program).
Finally, the executable program will be run, presenting its output
to stdout, which is redirected to a file.

The example program concerned is specified by the argument to the
command, e.g.

nag_example_acml e04ucf

will copy the example program and its data into the files
e04ucfe.f and e04ucfe.d in the current directory
and process them to produce the example program results in the file
e04ucfe.r.

The distributed example results are those obtained with the
static library libnag_acml.a,
(using the ACML BLAS and LAPACK
routines).
Running the examples with the self-contained library (using the NAG
BLAS and LAPACK routines) may give slightly different results.

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 1.0D-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.
Note that applications should reference routines by their BLAS/LAPACK
names, rather than their NAG-style names, for optimum performance.

Certain routines produce explicit error messages and advisory messages via
output units which have default values that can be reset by using X04AAF
for error messages and X04ABF for advisory messages. (The default values are
given in Section 4.) The maximum record lengths
of error messages and advisory messages (including carriage control characters)
are 80 characters, except where otherwise specified.

Any further information which applies to one or more routines in this
implementation is listed below, chapter by chapter.

F06, F07 and F08

Many LAPACK routines have a "workspace query" mechanism which allows
a caller to interrogate the routine to determine how much workspace
to supply. Note that LAPACK routines from the
ACML may require
a different amount of workspace from the equivalent NAG versions
of these routines. Care should be taken when using the workspace
query mechanism.

G02

The value of ACC, the machine-dependent constant mentioned in several documents
in the chapter, is 1.0D-13.

P01

On hard failure, P01ABF writes the error message to the error message unit
specified by X04AAF and then stops.

S07 - S21

Functions in these chapters will give error messages if called with illegal or
unsafe arguments.
The constants referred to in the NAG Fortran Library Manual have the following
values in this implementation:

(a) Contact with NAG

Queries concerning this document or the implementation generally should be
directed to NAG at one of the addresses given in the Appendix.
Users subscribing to the support service are encouraged
to contact one of the NAG Response Centres (see below).

(b) NAG Response Centres

The NAG Response Centres are available for general enquiries from all users and
also for 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 phone (answering machine) at all times.

When contacting a Response Centre, it helps us deal with your enquiry quickly
if you can quote your NAG site reference and NAG product code (in this case
FLL6A22DPL).

The NAG websites provide information about implementation availability,
descriptions of products, downloadable software, product documentation and
technical reports. The NAG websites can be accessed at the following URLs:

(d) NAG Electronic Newsletter

If you would like to be kept up to date with news from NAG then please register
to receive our free electronic newsletter, which will alert you to
announcements about new products or product/service enhancements,
technical tips,
customer stories and NAG's event diary. You can register via one of
our websites, or by contacting us at
nagnews@nag.co.uk.

(e) Product Registration

To ensure that you receive information on updates and other relevant
announcements, please register this product with us. For NAG Library
products this may be accomplished by filling in the online
registration form at
http://www.nag.co.uk/numeric/Library_Registration.asp.

Many factors influence the way that NAG's products and services evolve, and
your
ideas are invaluable in helping us to ensure that we meet your needs. If you
would like to contribute to this process, we would be delighted to receive your
comments. Please contact any of the NAG Response Centres (shown below).