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 libraries.
Content
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, the functions have the same names as the corresponding Fortran intrinsic functions, so interface blocks are not necessary. In C/C++, to provide the prototypes for the scalar MASS functions, you need to include the file math.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 or libmass_64.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 [or -q64 -lmass_64]
xlc progc.c -o progf -lmass [or -q64 -lmass_64]
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 [or -q64 -lmass_64]
xlc progc.c -o progf -L/home/somebody/mass -lmass [or -q64 -lmass_64]
Calling MASS SIMD library functions from an application
There are SIMD MASS libraries for POWER7 and POWER8 processors called libmass_simdpN.a (32-bit) or libmass_simdpN_64.a (64-bit), where N is 7 or 8 for POWER7 or POWER8, respectively. Although maximum performance is usually obtained with the vector library, the SIMD library may provide better performance in certain situations; for example, when the data is in the form of a vector float or vector double, and significant overhead would be needed to assemble these into a vector of floats or doubles suitable for the vector function; or when the vector length is very short.
As with the scalar functions, the SIMD functions must be called with the IEEE rounding mode set to round-to-nearest and with exceptions masked off.
The single-argument SIMD functions all have prototypes of the form
vector float function_namef4 (vector float x)
vector double function_named2 (vector double x),
where x is the input vector, and the result vector is returned by the function. The single-argument functions are all used in the same way. For example, in C:
vector float x, y;
x = (vector float)(1.0, 2.0, 3.0, 4.0};
y = expf4 (x);
results in a vector y with elements {exp(1.0), exp(2.0), exp(3.0), exp(4.0)}.
The functions atan2f4, divf4, hypotf4, powf4, atan2d2, divd2, hypotd2, and powd2 have two inputs and are of the form
vector float function_namef4 (vector float x, vector float y)
vector double function_named2 (vector double x, vector float y).
The functions sincosf4 and sincosd2 produce two outputs and are of the form
void sincosf4 (vector float vx, vector float *vs, vector float *vc)
void sincosd2 (vector double vx, vector double *vs, vector double *vc)
where the elements of *vs and *vc are the sine and cosine of the elements of vx, respectively.
To obtain the SIMD function prototypes in C/C++ programs, include the file mass_simd.h in the calling program. To obtain the vector function interface blocks in Fortran programs, include the file mass_simd.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 SIMD library
To use the MASS SIMD library, simply use the corresponding library name or names in the linker command line. For instance, when the library is installed in the standard directory /usr/lib/, the command lines for Fortran and C to use the libmass_simdp8.a library would be:
xlf -qarch=pwr8 progf.f -o progf -lmass_simdp8 [or -q64 -lmass_simdp8_64]
xlc -qarch=pwr8 progc.c -o progf -lmass_simdp8 [or -q64 -lmass_simdp8_64]
If libmass_simdp8.a is installed in a directory other than /usr/lib, such as in /home/somebody/mass, use the -L option to add that directory to the library search path:
xlf -qarch=pwr8 progf.f -o progf -L/home/somebody/mass -lmass_simdp8 [or -q64 -lmass_simdp8_64]
xlc -qarch=pwr8 progc.c -o progf -L/home/somebody/mass -lmass_simdp8 [or -q64 -lmass_simdp8_64]
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 to use libmassvp8.a for Fortran, C and C++ in 32-bit mode would be:
xlf prog.f -o prog -lmassvp8
xlc prog.c -o prog -lmassvp8
xlC prog.C -o prog -lmassvp8
For 64-bit mode, add the compiler option -q64 and replace -lmassvp8 with -lmassvp8_64.
If libmassvp8.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 -lmassvp8
xlc prog.c -o prog -L/home/somebody/mass -lmassvp8 -lm
xlC prog.C -o prog -L/home/somebody/mass -lmassvp8 -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 an IBM pSeries or RS/6000 system, 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 pSeries or RS/6000, the faster MASS vector libraries can be linked as described above.
WARNING: Do not use libmassv.f or libmassv.c on IBM pSeries and RS/6000 systems. Use the -lmassvpN, or -lmassvpN_64 flags instead, where N is 4, 5, 6, 7, or 8 for POWER4, POWER5, POWER6, POWER7, or POWER8, respectively. The source vector library should be used as a portable substitute for the MASS vector libraries only on non-IBM systems.
Original Publication Date
16 September 2004
Related Information
Was this topic helpful?
Document Information
Modified date:
28 January 2020
UID
swg27005471