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):
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.
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); |
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.
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:
The vectors x[0:n-1] and y[0:n-1] must be either disjoint or identical, or unexpected results may be obtained.
The previous restriction applies to both pairs of vectors y, x1 and y, x2. That is, y[0:n-1] and x1[0:n-1] must be either disjoint or identical; and y[0:n-1] and x2[0:n-1] must be either disjoint or identical.
The above restriction applies to both pairs of vectors y1, x and y2, x. That is, y1[0:n-1] and x[0:n-1] must be either disjoint or identical; and y2[0:n-1] and x[0:n-1] must be either disjoint or identical. Also, the vectors y1[0:n-1] and y2[0:n-1] must be disjoint.
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.