Using the vector libraries

When you compile programs with any of the following options:

the compiler automatically attempts to vectorize calls to system math functions by calling the equivalent MASS vector functions (with the exceptions of functions vdnint, vdint, vsincos, vssincos, vcosisin, vscosisin, vqdrt, vsqdrt, vrqdrt, vsrqdrt, vpopcnt4, and vpopcnt8). For automatic vectorization, the compiler uses versions of the MASS functions contained in the system library libxlopt.a; you do not need to add any special calls to the MASS functions in your code, or to link to the libxlopt library.

If you are not using any of the optimization options listed above, and/or want to explicitly call any of the MASS vector functions, you can do so by including the header massv.h in your source files and linking your application with any of the following vector library archives (information on linking is provided in Compiling and linking a program with MASS):

libmassvp4.a
Contains functions that have been tuned for the POWER4 architecture. If you are using a PPC970 machine, this library is the recommended choice.
libmassvp5.a
Contains functions that have been tuned for the POWER5 architecture.

On Linux, 32-bit and 64-bit objects must not be mixed in a single library, so a separate 64-bit version of each vector library is provided: libmassvp4_64.a, and libmassvp5_64.a.

The single-precision and double-precision floating-point functions contained in the vector libraries are summarized in Table 17. The integer functions contained in the vector libraries are summarized in Table 18. Note that in C and C++ applications, only call by reference is supported, even for scalar arguments.

With the exception of a few functions (described below), all of the floating-point functions in the vector libraries accept three parameters:

The functions are of the form function_name (y,x,n), where y is the target vector, x is the source vector, and n is the vector length. The parameters y and x are assumed to be double-precision for functions with the prefix v, and single-precision for functions with the prefix vs. As an example, the following code:

#include <massv.h>

double x[500], y[500];
int n;
n = 500;
...
vexp (y, x, &n);

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

The integer functions are of the form function_name (x[], *n), where x[] is a vector of 4-byte (for vpopcnt4) or 8-byte (for vpopcnt8) numeric objects (integral or floating-point), and *n is the vector length.

Table 17. MASS floating-point vector functions
Double-precision function Single-precision function Description Double-precision function prototype Single-precision function prototype
vacos vsacos Sets y[i] to the arccosine of x[i], for i=0,..,*n-1 void vacos (double y[], double x[], int *n); void vsacos (float y[], float x[], int *n);
vasin vsasin Sets y[i] to the arcsine of x[i], for i=0,..,*n-1 void vasin (double y[], double x[], int *n); void vsasin (float y[], float x[], int *n);
vatan2 vsatan2 Sets z[i] to the arctangent of x[i]/y[i], for i=0,..,*n-1 void vatan2 (double z[], double x[], double y[], int *n); void vsatan2 (float z[], float x[], float y[], int *n);
vcbrt vscbrt Sets y[i] to the cube root of x[i], for i=0,..,*n-1 void vcbrt (double y[], double x[], int *n); void vscbrt (float y[], float x[], int *n);
vcos vscos Sets y[i] to the cosine of x[i], for i=0,..,*n-1 void vcos (double y[], double x[], int *n); void vscos (float y[], float x[], int *n);
vcosh vscosh Sets y[i] to the hyperbolic cosine of x[i], for i=0,..,*n-1 void vcosh (double y[], double x[], int *n); void vscosh (float y[], float x[], int *n);
vcosisin vscosisin Sets the real part of y[i] to the cosine of x[i] and the imaginary part of y[i] to the sine of x[i], for i=0,..,*n-1 void vcosisin (double _Complex y[], double x[], int *n); void vscosisin (float _Complex y[], float x[], int *n);
vdint Sets y[i] to the integer truncation of x[i], for i=0,..,*n-1 void vdint (double y[], double x[], int *n);
vdiv vsdiv Sets z[i] to x[i]/y[i], for i=0,..,*n-1 void vdiv (double z[], double x[], double y[], int *n); void vsdiv (float z[], float x[], float y[], int *n);
vdnint Sets y[i] to the nearest integer to x[i], for i=0,..,n-1 void vdnint (double y[], double x[], int *n);
vexp vsexp Sets y[i] to the exponential function of x[i], for i=0,..,*n-1 void vexp (double y[], double x[], int *n); void vsexp (float y[], float x[], int *n);
vexpm1 vsexpm1 Sets y[i] to (the exponential function of x[i])-1, for i=0,..,*n-1 void vexpm1 (double y[], double x[], int *n); void vsexpm1 (float y[], float x[], int *n);
vlog vslog Sets y[i] to the natural logarithm of x[i], for i=0,..,*n-1 void vlog (double y[], double x[], int *n); void vslog (float y[], float x[], int *n);
vlog10 vslog10 Sets y[i] to the base-10 logarithm of x[i], for i=0,..,*n-1 void vlog10 (double y[], double x[], int *n); void vslog10 (float y[], float x[], int *n);
vlog1p vslog1p Sets y[i] to the natural logarithm of (x[i]+1), for i=0,..,*n-1 void vlog1p (double y[], double x[], int *n); void vslog1p (float y[], float x[], int *n);
vpow vspow Sets z[i] to x[i] raised to the power y[i], for i=0,..,*n-1 void vpow (double z[], double x[], double y[], int *n); void vspow (float z[], float x[], float y[], int *n);
vqdrt vsqdrt Sets y[i] to the fourth root of x[i], for i=0,..,*n-1 void vqdrt (double y[], double x[], int *n); void vsqdrt (float y[], float x[], int *n);
vrcbrt vsrcbrt Sets y[i] to the reciprocal of the cube root of x[i], for i=0,..,*n-1 void vrcbrt (double y[], double x[], int *n); void vsrcbrt (float y[], float x[], int *n);
vrec vsrec Sets y[i] to the reciprocal of x[i], for i=0,..,*n-1 void vrec (double y[], double x[], int *n); void vsrec (float y[], float x[], int *n);
vrqdrt vsrqdrt Sets y[i] to the reciprocal of the fourth root of x[i], for i=0,..,*n-1 void vrqdrt (double y[], double x[], int *n); void vsrqdrt (float y[], float x[], int *n);
vrsqrt vsrsqrt Sets y[i] to the reciprocal of the square root of x[i], for i=0,..,*n-1 void vrsqrt (double y[], double x[], int *n); void vsrsqrt (float y[], float x[], int *n);
vsin vssin Sets y[i] to the sine of x[i], for i=0,..,*n-1 void vsin (double y[], double x[], int *n); void vssin (float y[], float x[], int *n);
vsincos vssincos Sets y[i] to the sine of x[i] and z[i] to the cosine of x[i], for i=0,..,*n-1 void vsincos (double y[], double z[], double x[], int *n); void vssincos (float y[], float z[], float x[], int *n);
vsinh vssinh Sets y[i] to the hyperbolic sine of x[i], for i=0,..,*n-1 void vsinh (double y[], double x[], int *n); void vssinh (float y[], float x[], int *n);
vsqrt vssqrt Sets y[i] to the square root of x[i], for i=0,..,*n-1 void vsqrt (double y[], double x[], int *n); void vssqrt (float y[], float x[], int *n);
vtan vstan Sets y[i] to the tangent of x[i], for i=0,..,*n-1 void vtan (double y[], double x[], int *n); void vstan (float y[], float x[], int *n);
vtanh vstanh Sets y[i] to the hyperbolic tangent of x[i], for i=0,..,*n-1 void vtanh (double y[], double x[], int *n); void vstanh (float y[], float x[], int *n);
Table 18. MASS integer vector library functions
Function Description Prototype
vpopcnt4 Returns the total number of 1 bits in the concatenation of the binary representation of x[i], for i=0,..,*n-1, where x is a vector of 32-bit objects. unsigned int vpopcnt4 (void *x, int *n)
vpopcnt8 Returns the total number of 1 bits in the concatenation of the binary representation of x[i], for i=0,..,*n-1, where x is a vector of 64-bit objects. unsigned int vpopcnt8 (void *x, int *n)

The functions vdiv, vsincos, vpow, and vatan2 (and their single-precision versions, vsdiv, vssincos, vspow, and vsatan2) take four parameters. The functions vdiv, vpow, and vatan2 take the parameters (z,x,y,n). The function vdiv outputs a vector z whose elements are x[i]/y[i], where i=0,..,*n-1. The function vpow outputs a vector z whose elements are x[i]y[i], where i=0,..,*n-1. The function vatan2 outputs a vector z whose elements are atan(x[i]/y[i]), where i=0,..,*n-1. The function vsincos takes the parameters (y,z,x,n), and outputs two vectors, y and z, whose elements are sin(x[i]) and cos(x[i]), respectively.

Overlap of input and output vectors

In most applications, the MASS vector functions are called with disjoint input and output vectors; that is, the two vectors do not overlap in memory. Another common usage scenario is to call them with the same vector for both input and output parameters (for example, vsin (y, y, &n)). Other kinds of overlap (where input and output vectors are neither disjoint nor identical) should be avoided, since they may produce unexpected results:

Consistency of MASS vector functions

All the functions in the MASS vector libraries are consistent, in the sense that a given input value will always produce the same result, regardless of its position in the vector, and regardless of the vector length.