Compute Canada

NAG libraries

Please note: The FAQ pages at the HPCVL website are continuously being revised. Some pages might pertain to an older configuration of the system. Please let us know if you encounter problems or inaccuracies, and we will correct the entries.

This is an introduction on the HPCVL installation of the Numerical Algorithms Group (NAG) libraries and associated software. The NAG libraries are a large collection of numerical routines ranging from the implementation of complex arithmetic to time series analysis. Parts of the routines are suitable for execution on both shared-memory and distributed-memory parallel computers. The documentation of the library is extensive, and this FAQ is only meant as a basic introduction to its use on HPCVL computers.

What are 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:

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.

Where do the Libraries Reside?

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.

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.

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

We do require our users to sign and return a statement to the effect that they will abide by the terms of the license agreement. Once we receive this statement, we will enter you into a "nag" Unix group and you can access the libraries and license.

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 users 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 on request. The validity of the license key is limited by the duration of our agreement with NAG, and of your access with HPCVL. Within these terms, you can freely use the libraries on an arbitrary number of machines. The software itself may be downloaded directly from the NAG website.

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

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

How do I use the NAG Fortran Library?

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

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.

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 bynagc_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 yourPATH 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 areSUBROUTINEs 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 structurein C).

For details about the usage of specific program, consult the programming examples in/opt/nag/clsol08dcl/examples/source in conjunction with the documentation.

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.

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.

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)

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.

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.

Accompanying Software: 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 .