MASS Math Library

• Introduction
• Using the Libraries
• Further Information

Introduction

The Mathematical Acceleration SubSystem (MASS) consists of libraries of tuned mathematical intrinsic functions. Version 3.0 adds 64-bit versions of all functions, except vatan2 and vsatan2. The MASS libraries can now be linked into 32-bit or 64-bit applications.

Scalar Library

The MASS scalar library, libmass.a, contains an accelerated set of frequently used math intrinsic functions:

atan
atan2
cosh
pow (x**y)
exp
log
rsqrt (recipricol square root)
cos
sin
sinh
sqrt
tan
tanh

The libmass.a library can be used with either Fortran or C applications and will run under AIX on all of the IBM pSeries and RS/6000 processors. Because MASS does not check its environment, it must be called with the IEEE rounding mode set to round-to-nearest and with exceptions masked off (the default XLF environment). MASS may not work properly with other settings.

In some cases MASS is not as accurate as the system library, and it may handle edge cases differently from libm.a (sqrt(inf), for example). The trig functions (sin, cos, tan) return NaN (Not-a-Number) for large arguments (abs(x)>2**50*pi).

Vector Libraries

The general vector library, libmassv.a, contains vector functions that will run on the entire IBM pSeries and RS/6000 families. The library libmassvp3.a contains the functions of libmassv.a, including some that have been tuned for the POWER3 architecture. See the Using section below for a detailed description.

The vector libraries libmassv.a and libmassvp3.a can be used with either FORTRAN or C applications. When calling the library functions from C, only call by reference is supported, even for scalar arguments. As with the scalar functions, the vector functions must be called with the IEEE rounding mode set to round-to-nearest and with exceptions masked off. The accuracy of the vector functions is comparable to that of the corresponding scalar functions in libmass.a, though results may not be bit-wise identical.

Making use of the vector library will likely make your code not portable to other platforms, although IBM provides a source file to aid in transferring the modified source to anothe platform. The source file, libmassv.f, includes Fortran versions of all the vector functions in the MASS vector libraries.

Using the MASS Libraries

The Scalar Library

To use libmass.a, use the MASS environment variable. The command lines for Fortran and C are:

% module load mass 
% xlf progf.f -o progf $MASS
% cc progc.c -o progf $MASS -lm

or for 64-bit applications

% module load mass_64
% xlf -q64 progf.f -o progf $MASS
% cc -q64 progc.c -o progf $MASS -lm

(Fortran links with libm.a automatically, so only MASS need to be specified on the command line. For C code, you must link both MASS and libm.a, since libmass.a includes only a subset of the functions in libm.a.).

When called from C code, the functions in libmass.a will not set the global variable errno to indicate range, domain, or loss of precision errors. For example, with libm.a, sqrt(-1) will return the value NaN (not a number) and also sets errno to 33 (EDOM -- domain error); with libmass.a, sqrt(-1) simply returns NaN, but errno is not set.

The Vector Libraries

Successful use of the MASS vector libraries is contingent on making the effort to vectorize the code. This means rewriting function calls to compute an array, for example, of sines. See below for the syntax of these new calls.

To use the faster MASS routines in a code that has been vectorized as indicated, simply use these environment variables after loading the MASS module:

% module load mass
% xlf progf.f -o progf $MASSVP3
% cc progc.c -o progf $MASSVP3 -lm

If you want both scalar and vector MASS routines, use both environment variables

The vector function subroutines may be used as any Fortran function subroutines via a CALL statement. For

vcos
vexp
vlog
vscos
vsexp
vsin
vslog
vssin
vstan
vtan
vrec (recipricol)
vrsqrt
vsqrt
vsrec
vsrsqrt (recipricol square root)
vssqrt
vdint (convert double to double having value of next lowest integer)
vdnint (convert double to double having value of nearest integer)

  .....
  REAL*8 X(500),Y(500)
  REAL*4 R(500),S(500)
  .....
  CALL VEXP(Y,X,500)
  CALL VSEXP(R,S,500)
  .....

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

vdiv
vsdiv
vsincos
vssincos
vatan2
vsatan2

The functions vdiv, vsincos, and vatan2 are of the form function_name(x,y,z,n). vdiv returns a vector x whose elements are y(I)/z(I), I=1,n. vsincos returns two vectors, x and y, whose elements are sin(z(I)) and cos(z(I)) respectively. vatan2 returns a vector x whose elements are atan(y(I)/z(I)) respectively.

vcosisin
vscosisin

In vcosisin(y,x,n), x is a vector of n real*8 elements and the function returns a vector y of n complex*16 elements of the form (cos(x(I)),sin(x(I))).

Vector Code Portability

The recommended procedure for writing a 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. Then, to prepare to run on a system other than an IBM RS/6000, compile the application source code together with the libmassv.f source (this is located in $MASSROOT/src). The vector syntax to be used is visible in the libmassv.f source.

Further Information

For further information, please see Mathematical Acceleration SubSystem (MASS) documentation at the IBM RS/6000 website. There is a discussion of accuracy issues and potential speedups that can be obtained.