## Product documentation

## Abstract

This document describes how to call MASS library functions from an AIX application, compile and link an application with the MASS libraries, and how to use the vector source library.

## Content

**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, except rsqrt, all the functions have the same names as the corresponding Fortran intrinsic functions, so interface blocks are not necessary. Since rsqrt is not a Fortran intrinsic function, you need to include the file mass.include in the calling program to provide the appropriate interface block.

In C/C++, to provide the prototypes for all the scalar MASS functions, include the files math.h and 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. For instance, with libm.a sqrt(-1) will return the value NaN (not a number) and will set errno to 33 (EDOM -- domain error); with libmass.a sqrt(-1) simply returns NaN but does not set errno.

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 cc progc.c -o progf -lmass `

If libmass.a is installed in a directory other than in /usr/lib, 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 cc progc.c -o progf -L/home/somebody/mass -lmass `

**Selective compiling and linking with the MASS scalar library**

If you wish to use libmass.a for some functions and the normal libm.a for the remainder, you can use an export list with the ld command. For instance, to select only the fast tangent routine from libmass.a for use with the C program sample.c:

1. Create an export list containing the names of the desired functions. In this case, the file fast_tan.exp will contain only one line:

** **tan

2. Pull the exported routines into an object file using the ld command with libmass.a.

` ld -bexport:fast_tan.exp -o fast_tan.o -bnoentry -lmass -bmodtype:SRE `** **

(or, if libmass.a is not in /usr/lib)

` ld -bexport:fast_tan.exp -o fast_tan.o -bnoentry -L/some/other/path -lmass -bmodtype:SRE `

(or, if you want the 64-bit versions of the exported functions)

`ld -bexport:fast_tan.exp -o fast_tan.o -b64 -bnoentry -lmass -bmodtype:SRE `

3. Archive the object file into a library with the ar command.

` ar -q libfasttan.a fast_tan.o`

4. Create the final executable using cc, specifying fast_tan.o *before* the standard math library, libm.a. This will link only the tan routine from MASS (now in fast_tan.o) and the remainder of the math subroutines from the standard system library:

` cc sample.c -o sample -lfasttan -lm`

(Note: The routines sin and cos, and atan and atan2, are coded together, so selecting fast sin will also automatically link in fast cos; selecting atan will also link atan2.)

**Calling MASS SIMD library functions from an application**

There is a SIMD MASS library for POWER7 called libmass_simdp7.a. 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_simdp7.h in the calling program. To obtain the vector function interface blocks in Fortran programs, include the file mass_simdp7.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_simdp7.a library would be:

** **`xlf -qarch=pwr7 progf.f -o progf -lmass_simdp7 xlc -qarch=pwr7 progc.c -o progf -lmass_simdp7`

If libmass_simdp7.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=pwr7 progf.f -o progf -L/home/somebody/mass -lmass_simdp7 xlc -qarch=pwr7 progc.c -o progf -L/home/somebody/mass -lmass_simdp7`

**Calling MASS vector library functions from an application**

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. 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 C, C++ or Fortran subroutines. Except for vdiv, vsincos, vcosisin, vatan2, vdfloat, vidint, and vdsign, the functions in libmassv.a, libmassvp3.a, and libmassvp4.a 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) for functions with the prefix *v*, and short-precision (real*4) for functions with the prefix *vs*. The three-argument subroutines are all used in the same way. For example, in Fortran:

` ..... DIMENSION X(500),Y(500) ..... CALL VEXP(Y,X,500) ..... `

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

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

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

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 library**

To use the faster MASS libraries in an application that has been vectorized, 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 libmassvp4.a library would be:

** **** **`xlf progf.f -o progf -lmassv``p4 `

`cc progc.c -o progf -lmassvp4`

If libmassv.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 progf.f -o progf -L/home/somebody/mass -lmassv``p4 `

`cc progc.c -o progf -L/home/somebody/mass -lmassvp4`

**Using the vector source libraries**

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 System p® and Power Architecture®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. In libmassv.f, commenting out one line of the vrsqrt subroutine, which is a directive to the IBM XL Fortran compiler, may be necessary for full portability.

When running the application on an IBM System p or Power Architecture system, the faster MASS vector libraries can be linked as described above.

**NOTE:** The vector source libraries are intended merely as a portability aid, not to provide high performance. Therefore, do not use libmassv.f or libmassv.c on IBM System p and Power Architecture systems. Use the -lmassv, -lmassvp3, -lmassvp4, -lmassvp5, -lmassvp6, or -lmassvp7 flags instead. The vector source 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 AIX

MASS Fortran interface blocks for AIX

Segment | Product | Component | Platform | Version | Edition |
---|---|---|---|---|---|

pSeries Unix Servers (incl pSeries Intellistation) | pSeries - Enterprise Servers | ||||

RS/6000 (Servers and Workstations) | RS/6000 Enterprise Servers | ||||

Operating Systems | AIX family | AIX | All Versions | ||

Software Development | XL C Enterprise Edition for AIX | Not Applicable | AIX | All Versions | |

Software Development | VisualAge C++ | AIX | All versions | ||

Software Development | XL C/C++ | AIX, AIX5L, AIXL | All Versions | ||

Software Development | XL Fortran | AIX, AIXL | All versions |