Using the MASS Libraries on Blue Gene

Product documentation


Abstract

This document describes how to call MASS library functions from an application, compile and link an application with the MASS libraries, and how to use the vector source library. Prototypes and interfaces of the MASS functions are also provided.

Content

Using the MASS Libraries on Blue Gene/Q

For information on using the MASS libraries for Blue Gene®/Q, click on the following links:
Using the Mathematical Acceleration Subsystem libraries (C/C++)
Using the Mathematical Acceleration Subsystem libraries (Fortran)


Using the MASS Libraries on Blue Gene/L and Blue Gene/P

Calling MASS scalar library functions from an application

Because MASS does not check its environment, the scalar library must be called with the IEEE rounding mode set to round-to-nearest and with exceptions masked off (the default environment in both XL Fortran and XL C/C++). MASS may not work properly with other settings.

The library uses some global names for shared tables. The global names have the form %...$.

In Fortran, most double-precision functions have the same names as the corresponding Fortran intrinsic functions, so interface blocks are not necessary. To provide interfaces for single-precision functions and double precision functions which are not Fortran intrinsic functions, include the file mass.include in the calling program. In C/C++, to provide the prototypes for most scalar MASS functions, include the file math.h in the calling program. To provide prototypes for scalar MASS functions which are not also standard C99 functions, include the file mass.h in the calling program.

Also note that when called from C/C++ code, the functions in libmass.a will not set the global variable errno to indicate range, domain, or loss of precision errors.

The links at the bottom of the page give Fortran and C declarations for the functions. The purpose of each function is given as a comment.

Compiling and linking an application with the MASS scalar library

To use libmass.a, use -lmass in the linker command line. For example, if the library is installed in the standard directory /usr/lib, the command lines for Fortran and C would be:

xlf progf.f -o progf -lmass
xlc progc.c -o progf -lmass

If libmass.a is installed in another directory, such as in /home/somebody/mass, use the -L option to add that directory to the library search path:

xlf progf.f -o progf -L/home/somebody/mass -lmass
xlc progc.c -o progf -L/home/somebody/mass -lmass

Calling MASS vector library functions from an application

The MASS vector functions must be called with the IEEE rounding mode set to round-to-nearest and with exceptions masked off. When calling the vector functions from C/C++, only call by reference is supported, even for scalar arguments.

The vector function subroutines may be used as any Fortran, C or C++ function subroutines. The functions in the vector libraries are all of the form function_name (y,x,n), where x is the source vector, y is the target vector, and n is the vector length. The arguments y and x are assumed to be long-precision (real*8 or double) for functions whose prefix is v, and short-precision (real*4 or float) for functions with prefix vs. The three-argument subroutines are all used in the same way. For example in Fortran:

INCLUDE 'MASSV.INCLUDE'
REAL*8 X(500),Y(500)
.....
CALL VSQRT(Y,X,500)

returns a vector Y of length 500 whose elements are sqrt(X(i)); i=1,...,500.

In C:

#include "massv.h"
int const n = 500; double x[n], y[n];
...
vsqrt(y,x,&n);

returns a vector y of length 500 whose elements are sqrt(x[i]), i=0,...,499.

To obtain the vector function prototypes in C/C++ programs, include the file massv.h in the calling program. To obtain the vector function interface blocks in Fortran programs, include the file massv.include in the calling program.

The links at the bottom of the page give Fortran and C declarations for the functions. The purpose of each function is given as a comment.

Compiling and linking an application with the MASS vector libraries

To use the faster MASS libraries in an application that has been vectorized, simply use the corresponding library name in the linker command line. For instance, when the library is installed in the standard directory, the command lines for Fortran, C and C++ would be:

xlf prog.f -o prog -lmassv
xlc prog.c -o prog -lmassv -lm
xlC prog.C -o prog -lmassv -lm

If libmassv.a is installed in a different directory such as in /home/somebody/mass, use the -L option to add that directory to the library search path:

xlf prog.f -o prog -L/home/somebody/mass -lmassv
xlc prog.c -o prog -L/home/somebody/mass -lmassv -lm
xlC prog.C -o prog -L/home/somebody/mass -lmassv -lm

Using the vector source library

The recommended procedure for writing portable code that is vectorized for using the fast MASS vector libraries, is to write in ANSI standard language and use the vector functions defined by libmassv.f or libmassv.c. Then, to prepare to run on a system other than Blue Gene/P, compile the application source code together with the libmassv.f or libmassv.c source. The vector syntax to be used is visible in the libmassv.f and libmassv.c source. For Fortran, commenting out the @PROCESS lines, which are directives to the IBM XL Fortran compiler, may be necessary for full portability.

When running the application on an IBM Blue Gene/P or Blue Gene/L system, the faster MASS vector libraries can be linked as described above.

WARNING: Do not use libmassv.f or libmassv.c on IBM Blue Gene/P, Blue Gene/L, pSeries or RS/6000 systems. Use the appropriate MASS library instead. The source vector library should be used as a portable substitute for the MASS vector libraries only on non-IBM systems.


Related information

MASS C/C++ function prototypes for Blue Gene/L and Blue
MASS Fortran interface blocks for Blue Gene/L and Blue

Original publication date

2005/7/4

Cross reference information
Segment Product Component Platform Version Edition
Software Development XL C/C++ Compiler Linux
Software Development XL Fortran Compiler Linux

Rate this page:

(0 users)Average rating

Add comments

Document information


More support for:

Mathematical Acceleration Subsystem
Libraries

Software version:

4.4, 7.3

Operating system(s):

Linux

Reference #:

7005902

Modified date:

2007-11-11

Translate my page

Machine Translation

Content navigation