General Overview of the NAG Libraries
The Numerical Algorithms Group mathematical libraries are on of the most
extensive and widely used collection of numerical and mathematical routines
available. They have become a standard due to their portability,
reliability and stability. The libraries offer both serial and parallel
versions of a variety of numerical algorithms, ranging from complex
arithmetic, quadrature and the numerical solution of differential equations
to linear algebra, eigenvalue problems and nonlinear optimization. The
routines are extensively documented and equipped with error-trapping and
reporting systems.
The libraries are available both as static archives and dynamic
shared-object files. They can be used from Fortran and C programs. Which
versions of the NAG software are currently in use in HPCVL machines?
The current versions of the NAG software on HPCVL machines are:
Fortran Libraries Mark 21,
C Libraries Mark 8,
F90 Libraries Release 4,
SMP Libraries Release 21,
Parallel Libraries Release 3
Iris Explorer Release 5.0
These versions are the latest releases as of September 2006. The
libraries will be updated as newer releases become available. Note that
some routines from earlier versions have been withdrawn. NAG supplies a
list of those routines and suggestions as to how to replace them.
Back to top...
Like most "optional" software on SUN systems, the libraries are located
in the /opt directory hierarchy. The directory root is:
/opt/nag/
The different library distributions are located in the directories
clsol08dcl clso608dcl explorer flso621dcl flsol21dcl
fnso604db fnsol04dcl fsso621dcl fsso621dcl license
"explorer" contains the Iris Explorer visualization software, "license"
contains the license file and manager, and the other directories contain
various libraries.
H3 class="heading-blue">How do I Setup my Environment to use
NAG?
For the libraries, no special setup is required. The required routines
are just linked to the software by the standard -l option to the compiler
(linker). However, usage of programs that were linked to the NAG libraries
requires a valid license to be present on the system. To this end a license
file needs to be located by the license manager.
For the HPCVL SunFire Cluster, this license file is
/opt/nag/license/license.dat
Some of the libraries require a separate license file called
/opt/nag/license/kusari.dat
If you intend to run programs that use the NAG libraries or the
accompanying software, you should set the environment variables
LM_LICENSE_FILE and NAG_KUSARI_FILE in your setup files to enable the
license managers to find the above files.
For csh or tcsh add this line in your .cshrc or .tcshrc file:
setenv LM_LICENSE_FILE /opt/nag/license/license.dat
setenv NAG_KUSARI_FILE /opt/nag/license/kusari.dat
For ksh, bash, etc add this line in your in .profile or .bashrc:
LM_LICENSE_FILE=/opt/nag/license/license.dat; export LM_LICENSE_FILE
NAG_KUSARI_FILE=/opt/nag/license/kusari.dat; export NAG_KUSARI_FILE
Alternatively, you may leave the setup for the NAG libraries to the
usepackage facility, and simply type
use nag
from your command prompt, or include this command in your setup files
(.login or .profile).
Using the Iris Explorer requires the execution of additional setup
files, which will be
discussed elsewhere .
Back to top...
How is the NAG Software Licensed?
HPCVL has a license agreement with the Numerical Algorithms Group. This
license allows programs that use the NAG libraries to be executed on our
machines without restrictions on the number of such processes, or the
number of CPU's involved. The license is not node-locked or limited by
seats. The library files themselves are freely accessible, so that software
development is not encumbered by license requirements.
The presence of a valid license is checked at runtime. This means that a
license manager is automatically invoked everytime a program using the NAG
routines is executed. This license manager will then check the system for a
presence of a license file which uniquely identifies the machine. If such a
file exists the execution continues, if not, a message is issued and
execution is terminated.
Our agreement with NAG includes the unique opportunity for HPCVL members
to download and use the NAG
libraries and software on their own workstations. Individual license keys
will be required for this, and will be issued by us on a temporary
basis. The validity of the license key is limited by the duration of our
agreement with NAG, and of your membership with HPCVL. Within these terms,
you can freely use the libraries on an arbitrary number of machines. Note
that we also require our users to sign a statement that
they are HPCVL members, that the license keys will not be copied and passed
on to third parties, and that the usage of the libraries will be
non-commercial and serves research purposes. Find a copy of the statement
here, and return it to us signed to be issued a license key. The software
may be downloaded directly from the NAG website.
Back to top...
The Serial NAG Libraries
What serial Libraries are there?
The original NAG Library was coded in FORTRAN and not intended for use
with multiple processors. The NAG Fortran Library is still the basic
library anc includes essentially all available routines in a serial
form. Note however, that the implementation of these routines has been
greatly modified from earlier versions, and that they are largely "thread
safe", i.e., although designed for sequential run in themselves, may be
used in combination with multi-threaded (i.e. Parallel-enabled) programs
without danger of interference.
At this point the library routines are available in three largely equivalent forms:
- The NAG Fortran Library is compatible with Standard Fortran77
- The NAG F90 Library uses the extended Fortran 95 Standard
- The NAG C Library is written in ANSI C
Back to top...
What features do the serial libraries have?
It is not possible to give a complete listing of the library features in
this FAQ. For a listing, please consult the documentation, which is
available in PDF format, at the NAG documentation website, and in hardcopy
at our Princess St. Office in Kingston.
Here we can only give a basic list of the more important features:
- Complex Arithmetic
- Roots of polynomials and transcendental equations
- Series Summation and quadrature
- Fourier Series and Transforms
- Ordinary and partial differential equations
- Numerical Differentiation
- Interpolation
- Fitting of curves and sufaces
- Optimization
- Linear Algebra: Matrices, Determinants, Eigenvalues, Linear
Equation Systems, Least-Squares,
Orthogonalization, Sparse systems
- Statistics: Correlation, Regression, Variance
Analysis,Univariate estimations,
Nonparametric statistics, Smoothing,
Contingency tables, Time series, Uni-
and multivariate estimations
- Random numbers
- Operations Research
- Sorting
- Special Functions
Back to top...
The Fortran Library is used by directly linking the static or dynamic
versions of the library to the program that uses it. Other libraries should
be used in conjunction with it, such as socket or intl. The libraries and
auxilliary files reside in /opt/nag/flsol20dal. The following lines are
typical for a compilation with the NAG libraries:
Compiling:
f90 -c -dalign -mt program.f
Linking (static):
f90 -o program.exe -dalign -mt -lsocket -lnsl -lintl -xlic_lib=sunperf \
program.o /opt/nag/flsol21dcl/lib/libnag_spl.a
Linking (dynamic):
f90 -o program.exe -dalign -mt -lsocket -lnsl -lintl -xlic_lib=sunperf \
program.o -Bdynamic -R/opt/nag/flsol21dcl/lib -L/opt/nag/flsol21dcl/lib -lnag_spl
Note that the -dalign option is necessary to avoid bus
errors. The nsl, intl, and socket libraries are
necessary only in some cases, but it is recommended to include them in the
link list. The version of the Fortran library used in the above
compilation/linking lines makes use of the Sun Performance Library
(spl) for optimized execution of basic mathematical operations. It is
recommended to use this version on the SunFire cluster of HPCVL. It is also
recommended to use the f90 compiler, since it is the one that is supported
by Sun.
For the actual usage of the routines in the library, a large number of
example programs are available in /opt/nag/flsol21dcl/examples/source.
They should be consulted together with the documentation. The routines do
not require any header files or special setup, but can be used directly.
Routines should be declared EXTERNAL in most cases. A simple example
is
A02ACF divides one complex number x=(a,b) by another y=(c,d) to yield a third z=(e,f)
To use the routine, all that needs to be done is declaring a,b,c,d,e,f
as DOUBLE PRECISION and call it.
DOUBLE PRECISION A,B,C,D,E,F
EXTERNAL A02ACF
...
CALL A02ACF(A,B,C,D,E,F)
...
Back to top...
How do I use the NAG F90 Library?
The NAG F90 library is a completely rewritten version of the Fortran
library and uses the Fortran 90 extension of Fortran on all levels. For
instance, array operations make use of the extended abilities of Fortran
90, and all programs have a modular structure. The libraries are only
available as static archives, and reside in /opt/nag/fnsol04dcl.
One consequence of the Fortran 90 modular program structure is that data
and methods residing in modules need to be compiled before they are
available for other Fortran routines via the use command. All the modules
needed for use with the NAG F90 library reside in
/opt/nag/fnsol04dcl/nagfl90_modules. Here is a typical set of
compile/link calls:
Compiling:
f90 -c -dalign -M/opt/nag/fnsol04dcl/nagfl90_modules program.f90
Linking (static):
f90 -o program.exe -dalign -M/opt/nag/fnsol04dcl/nagfl90_modules \
-lsocket -lnsl -lintl -xlic_lib=sunperf program.o /opt/nag/fnsol04dcl/lib/libnagfl90_spl.a
Linking (dynamic):
f90 -o program.exe -dalign -M/opt/nag/fnsol04dcl/nagfl90_modules \
-lsocket -lnsl -lintl -xlic_lib=sunperf program.o \
-Bdynamic -L/opt/nag/fnsol04dcl/lib -R/opt/nag/fnsol04dcl/lib -lnagfl90_spl
The -M option in the above lines serves to let the
compiler/linker know where the module files associated with the F90 library
reside.
Examples for the usage of the F90 libraries may be found in
/opt/nag/fnsol04dcl/examples/source. There is a considerable
difference in the way the F90 library is used from its Fortran
counterpart. One diference is the usage of modules. For instance, the
routine nag_gen_lin_sol solves systems of linear equations and requires the
use of several modules:
PROGRAM test
USE nag_examples_io, ONLY : nag_std_in, nag_std_out
USE nag_gen_lin_sys, ONLY : nag_gen_lin_sol
(...)
INTRINSIC KIND
(...)
REAL (wp), ALLOCATABLE :: a(:,:), b(:)
(...)
READ (nag_std_in,*)
READ (nag_std_in,*) n
READ (nag_std_in,*) trans
ALLOCATE (a(n,n),b(n))
READ (nag_std_in,*) (a(i,:),i=1,n)
READ (nag_std_in,*) b
CALL nag_gen_lin_sol(a,b,trans=trans,bwd_err=bwd_err,fwd_err=fwd_err,rcond=rcond)
(...)
DEALLOCATE (a,b)
END PROGRAM nag_gen_lin_sys_ex01
Note that the array a in the above example is dynamically allocated and
needs to be deallocated at the end of the program. I/O occurs with units
that are defined in modules. The intrinsic function kind has to be declared
as such and is used to determine the type of a given variable.
Back to top...
How do I use the NAG C Library?
The C Library is used by directly linking the static or dynamic versions
of the library to the program that uses it. Other libraries should be used
in conjunction with it, such as socket or intl. The library resides in
/opt/nag/clsol07dal. The following lines are typical for a compilation with
the NAG libraries:
Compiling:
cc -c -dalign -I/opt/nag/clsol08dcl/include program.c
Linking (static):
cc -o program.exe -dalign -lm -lsocket -lnsl -lintl -xlic_lib=sunperf -lsunmath \
program.o /opt/nag/clsol08dcl/lib/libnagc_spl.a
Linking (dynamic):
cc -o program.exe -dalign -lm -lsocket -lnsl -lintl -xlic_lib=sunperf -lsunmath program.o \
-Bdynamic -R/opt/nag/clsol08dcl/lib -L/opt/nag/clsol08dcl/lib -lnagc_spl
This is assuming that you want to use the Sun Performance Libraries from
within the NAG routines. If you prefer the generic routines (making the
code slower, but more portable), replace the reference to nagc_spl by
nagc_nag and drop the -xlic_lib=sunperf option.
Note that the -dalign option is necessary to avoid bus
errors. The nsl, intl, and socket libraries are
necessary only in some cases, but it is recommended to include them in the
link list. Make sure that cc actually refers to Sun native
C-compiler and not to another compiler that might reside on the system and
be prefered by your PATH setting. You can check by typing "which
cc" which should yield the response "/opt/studio12/SUNWspro/bin/cc"
or similar.
The NAG C-Library requires some programming conventions that are best
determined from the documentation. Header files need to be included, and as
seen in the example above, the -I option should be used to point the
compiler to the directory where they reside
(/opt/nag/clsol08dcl/include). Several of the routines that are
SUBROUTINEs in the Fortran version of the NAG library are
functions in the C-version. The names may differ as well. A simple
example is
a02cdc divides one complex number x=(a,b) by another y=(c,d) to yield a third z=(e,f)
The involved numbers need to be declared Complex in the C program, which
requires the header files nag.h and naga02.h to be included.
#include
#include
#include
#include
int main(void){
...
double a,b,c,d,e,f;
Complex x,y,z;
...
x=a02bac(a,b); y=a02bac(c,d)
z=a02cdc(x,y)
e=z.re; f=z.im
...
}
In this case, we used the routine a02bac to assign real and imaginary
parts to a Complex number, and the convention z.re and z.im
to extract the real and imaginary parts from a Complex number (which is a
structure in C).
For details about the usage of specific program, consult the programming
examples in /opt/nag/clsol08dcl/examples/source in conjunction with
the documentation.
Back to top...
The parallel NAG Libraries
What parallel NAG libraries are there?
The parallel NAG libraries consist of two contributions, namely
- The NAG Parallel Library which uses MPI to implement scalable versions
of numerical operations that lend themselves for parallel execution. This
library will typically be used on a cluster. Presently, we do not have this
library installed on our machines, as it requires a deprecated component
(the S3L libraries) of Sun ClusterTools.
- The NAG Fortran SMP Library which uses Symmetric Multiprocessor
machines for numerical operations that can make use of multiple processors
(real or virtual). This library will typically be used on a shared-memory
multiprocessor machine.
Back to top...
What features do the parallel NAG
libraries have?
Note that not all of the features of the serial libraries are suitable
for execution on multiprocessor machines or clusters. Therefore the scope
of the NAG Parallel Library is smaller than the one of the serial ones. The
Fortran SMP Library, however, is identical in content to the NAG Fortran
Library, making migration from one to the other almost trivial. What
features do the parallel libraries have?
The Parallel Library focusses strongly on linear algebra operations,
where the arrays in question (matrices and vectors) may be distributed
among processors. A few additional features (such as Fourier Transforms)
are supplied as well. Here is a basic list of features:
- Summation of Series: 1,2, and 3-D Fourier transforms
- One- and multi-dimensional numerical quadrature
- Minimization of functions using only functional evaluations
- Basic Matrix operations and distribution
- Eigenvalues and Eigenvectors and Singular-Value Decomposition
- Linear Equation Systems, partly based on ScaLAPACK
- Least-Square Problems (based on ScaLAPACK)
- Sparse Linear Algebra
- Random Number Generators suitable for distributed systems
The SMP Library has a much wider scope than the Parallel Library, but is
limited in its scaling properties. It is optimized for making use of
multiple processors on a single machine without an excessive use of
communication. Features are outlined above under the NAG Fortran Library,
with which it is functionally identical.
Back to top...
How do I use the NAG Fortran SMP Library?
The Fortran SMP Library is used essentially the same way as the Fortran
Library. However, a few additional options have to be included to enable
the features compiled into the SMP Library. Since the latter was built by
using OpenMP compiler directives, these have to be enabled in the
compilation of the calling routines as well, even if they are not used. The
library resides in /opt/nag/fss0621dcl/. The following lines are typical
for a compilation with the NAG libraries:
Compiling:
f90 -c -dalign -xopenmp -xO3 program.f
Linking (static):
f90 -o program.exe -dalign -xopenmp -xO3 -lsocket -lnsl \
-xlic_lib=sunperf program.o /opt/nag/fsso621dcl/libnagsmp.a
Linking (dynamic):
f90 -o program.exe -dalign -xopenmp -xO3 -lsocket -lnsl -xlic_lib=sunperf program.o \
-Bdynamic -L/opt/nag/fssol21dcl/lib -R/opt/nag/fssol21dcl/lib -lnagsmp
Note that the -dalign option above is necessary to avoid bus errors. The
-xopenmp option, and the optimization option -xO3 are
necessary to enable and support compiler parallelization, even if no
parallelization directives are included in the calling routines. The
nsl, socket, and sunperf libraries are necessary only
in some cases, but it is recommended to include them in the link list. The
f90 compiler must be used for compiling and linking.
The optimization and parallelization options are repeated in the link
step to ensure that all necessary information is included in the
executable. Some of them might not be necessary, but it is usually better
to err on the safe side.
As for the Fortran Library, a large number of example programs are
available under /opt/nag/fsso621dcl/examples/source. They should be
consulted together with the documentation. The routines are used in exactly
the same way as the serial versions in the Fortran Library. For an example,
see above.
The number of processors (or more accurately light-weight processes) to
be used in a program that uses the NAG Fortran SMP Library is determined by
the environment variable OMP_NUM_THREADS. At execution time this variable
is set to the number of processors to be used. Note that it is useful to
determine the scaling properties of your program with test runs and
restrict yourself to a number of processors that lies well within the range
of scaling.
setenv OMP_NUM_THREADS 8 (csh, tcsh)
OMP_NUM_THREADS=8; export OMP_NUM_THREADS (ksh, bash)
Back to top...
How do I use the NAG Parallel Library?
The NAG parallel libraries require running ClusterTools 7 (OpenMPI) to run
on Solaris clusters, which is currently not the production version on
our machines. Nevertheless, ClusterTools 7 is accessible by issuing the
use ct7
command. The NAG Parallel Library is located in /opt/nag/fdso603dm and
only available as a 64-bit version.
Compiling:
mpif77 -c -dalign -xO3 -v9 program.f
Linking (static):
mpif77 -o program.exe -dalign -xO3 -xlic_lib=sunperf program.o \
/opt/nag/fdso603dm/libnagmpi.a /opt/nag/fdso603dm/libnagmpi_spl.a
Linking (dynamic):
mpif77 -o program.exe -dalign -xO3 -xlic_lib=sunperf program.o \
-L /opt/nag/fdso603dm -R /opt/nag/fdso603dm -lnagmpi -lnagmpi_spl
Again we assume that you want to use the Sun Performance Libraries from
within the NAG routines. Replacing the reference to _spl by
one to _nag replaces the performance library routines by
the generic NAG ones. The -xlic_lib=sunperf option may then be dropped.
The mpif77 command is an MPI specific macro that calls the proper
compiler options needed to handle MPI programs, and Fortran 77 compatibility.
To run an MPI program on our system, you need to use the mpirun
command and specify how many processes you want to start, e.g.:
mpirun -np 4 program.exe
For this command to work properly, the use ct7 must have been issued first.
Back to top...
Accompanying Software
The Iris Explorer
The Iris Explorer is a powerful visualization tool that works on the
basis of modules, giving it unique flexibility. Please see our separate Iris Explorer FAQ for
a short introduction, or the online NAG
Iris Explorer Documentation for details.
Back to top...
The NAGware F95 Compiler
The NAGware F95 compiler is at this point not installed. We
recommend the use of the native Sun Studio compilers on the HPCVL
SunFire cluster.
Where can I get more help and
documentation?
The NAG libraries are very well documented. For the libraries, the
documentation can be found at the NAG documentation website
, which contains the information in HTML format (to be accessed by a
web browser), and in pdf format (for download and printing). We are holding
a hard copy of the entire doumentation at our Kingston office (993 Princess
St.) as well.
Some level of support is also part of our agreement with NAG, so if you
contact us we can forward your questions and concerns.
HPCVL also offers user support; for questions about this FAQ and the
usage of the NAG libraries on HPCVL machines contact us .
