vecLib Reference

Overview

The vecLib framework contains nine C header files (not counting vecLib.h which merely includes the others). Two of them, vDSP.h and vDSP_translate.h, are covered in vDSP Programming Guide and vDSP Reference.

Three of the header files are Apple’s versions of well-known libraries which are described in detail in external references:

• cblas.h and vblas.h are the interfaces to Apple’s implementations of BLAS. You can find reference documentation in BLAS Reference. Additional documentation on the BLAS standard, including reference implementations, can be found on the web starting from the BLAS FAQ page at these URLs: http://www.netlib.org/blas/faq.html and http://www.netlib.org/blas/blast-forum/blast-forum.html.

• clapack.h is the interface to Apple’s implementation of LAPACK. Documentation of the LAPACK interfaces, including reference implementations, can be found on the web starting from the LAPACK FAQ page at this URL: http://netlib.org/lapack/faq.html

This document describes the functions declared in the remaining header files: vecLibTypes.h, vfp.h, vForce.h, vBasicOps.h, vectorOps.h, and vBigNum.h. These files support the vector mathematical functions library (also called “vMathLib”), which runs on vector processing hardware (Altivec or SSE3) if available.

This library abstracts the vector processing capability so that code written for it will execute appropriate instructions for the processor available at runtime. For this reason, unless you are writing specialized code that targets a single CPU, you should generally use these functions rather than directly using vector instructions. By using these functions, your code does not have to deal with subtle differences in vector instruction availability between different microarchitectures, freeing you to focus on the problem you are trying to solve. Also, code written using vecLib tends to be easier to port to different CPU architectures (porting your core libraries to ARM on iOS, for example).

    #include <stdlib.h>

    setenv("VECLIB_MAXIMUM_THREADS", "1", true);

    unsetenv("VECLIB_MAXIMUM_THREADS");

Functions by Task

Floating-Point Arithmetic and Auxiliary Functions (from vfp.h)

• vceilf
• vcopysignf
• vdivf
• vfloorf
• vnintf
• vnextafterf
• vrecf
• vrsqrtf
• vsqrtf
• vtablelookup

Exponential and Logarithmic Functions (from vfp.h)

• vexpf
• vexpm1f
• vlogf
• vlog1pf
• vlog10f
• vlogbf
• vscalbf

Trigonometric Functions (from vfp.h)

• vsinf
• vcosf
• vsincosf
• vtanf
• vasinf
• vacosf
• vatanf
• vatan2f

Hyperbolic Functions (from vfp.h)

• vsinhf
• vcoshf
• vtanhf
• vasinhf
• vacoshf
• vatanhf

Power Functions (from vfp.h)

• vipowf
• vpowf

Remainder Functions (from vfp.h)

• vfmodf
• vremainderf
• vremquof

Inquiry Functions (from vfp.h)

• vclassifyf
• vsignbitf

Array-Oriented Arithmetic and Auxiliary Functions (from vForce.h)

• vvceil
• vvceilf
• vvcopysign
• vvcopysignf
• vvdiv
• vvdivf
• vvfabs
• vvfabsf
• vvfloor
• vvfloorf
• vvfmod
• vvfmodf
• vvint
• vvintf
• vvnextafter
• vvnextafterf
• vvnint
• vvnintf
• vvrsqrt
• vvrsqrtf
• vvsqrt
• vvsqrtf
• vvrec
• vvrecf
• vvremainder
• vvremainderf

Array-Oriented Exponential and Logarithmic Functions (from vForce.h)

• vvexp
• vvexpf
• vvexp2
• vvexp2f
• vvexpm1
• vvexpm1f
• vvlog
• vvlogf
• vvlog1p
• vvlog1pf
• vvlog2
• vvlog2f
• vvlog10
• vvlog10f
• vvlogb
• vvlogbf

Array-Oriented Power Functions (from vForce.h)

• vvpowf
• vvpow

Array-Oriented Trigonometric Functions (from vForce.h)

• vvsin
• vvsinf
• vvsinpi
• vvsinpif
• vvcos
• vvcosf
• vvcospi
• vvcospif
• vvcosisin
• vvcosisinf
• vvsincos
• vvsincosf
• vvtan
• vvtanf
• vvtanpi
• vvtanpif
• vvasin
• vvasinf
• vvacos
• vvacosf
• vvatan
• vvatanf
• vvatan2
• vvatan2f

Array-Oriented Hyperbolic Functions (from vForce.h)

• vvsinhf
• vvsinh
• vvcoshf
• vvcosh
• vvtanhf
• vvtanh
• vvasinhf
• vvasinh
• vvacoshf
• vvacosh
• vvatanhf
• vvatanh

Functions

vacosf

For each vector element, calculates the arccosine. Results are in the interval [0, pi].

vFloat vacosf (
   vFloat arg
);

vacoshf

For each vector element, calculates the inverse hyperbolic cosine of X.

vFloat vacoshf (
   vFloat X
);

vasinf

For each vector element, calculates the arcsine. Results are in the interval [-pi/2, pi/2].

vFloat vasinf (
   vFloat arg
);

vasinhf

For each vector element, calculates the inverse hyperbolic sine of X.

vFloat vasinhf (
   vFloat X
);

vatan2f

For each vector element, calculates the arctangent of arg2/arg1 in the interval [-pi,pi] using the sign of both arguments to determine the quadrant of the computed value.

vFloat vatan2f (
   vFloat arg1,
   vFloat arg2
);

vatanf

For each vector element, calculates the arctangent. Results are in the interval [-pi/2, pi/2].

vFloat vatanf (
   vFloat arg
);

vatanhf

For each vector element, calculates the inverse hyperbolic tangent of X.

vFloat vatanhf (
   vFloat X
);

vceilf

Computes the ceiling of values in a vector of floating-point values.

vFloat vceilf (
   vFloat A
);

vclassifyf

For each vector element, returns the class of the argument (one of the FP_ ... constants defined in math.h).

vUInt32 vclassifyf (
   vFloat arg
);

vcopysignf

For each vector element, produces a value with the magnitude of arg2 and sign arg1. Note that the order of the arguments matches the recommendation of the IEEE 754 floating-point standard, which is opposite from the SANE copysign function.

vFloat vcopysignf (
   vFloat arg2,
   vFloat arg1
);

vcosf

For each vector element, calculates the cosine.

vFloat vcosf (
   vFloat arg
);

vcoshf

For each vector element, calculates the hyperbolic cosine of X.

vFloat vcoshf (
   vFloat X
);

vdivf

For each vector element, calculates A/B.

vFloat vdivf (
   vFloat A,
   vFloat B
);

vexpf

For each vector element, calculates the exponential of X.

vFloat vexpf (
   vFloat X
);

vexpm1f

For each vector element, calculates ExpM1(x) = Exp(x) - 1. But, for small enough arguments, ExpM1(x) is expected to be more accurate than Exp(x) - 1.

vFloat vexpm1f (
   vFloat X
);

vfloorf

Computes the floor of values in a vector of floating-point values.

vFloat vfloorf (
   vFloat A
);

vfmodf

For each vector element, calculates X modulo Y.

vFloat vfmodf (
   vFloat X,
   vFloat Y
);

vipowf

For each vector element, calculates X to the integer power of Y.

vFloat vipowf (
   vFloat X,
   vSInt32 Y
);

vlog10f

Computes the base-10 logarithm of values in a vector.

vFloat vlog10f (
   vFloat X
);

vlog1pf

For each vector element, calculates Log1P = Log(1 + x). But, for small enough arguments, Log1P is expected to be more accurate than Log(1 + x).

vFloat vlog1pf (
   vFloat X
);

vlogbf

For each vector element, extracts the exponent of X, as a signed integral value. A subnormal argument is treated as though it were first normalized. Thus: 1 <= x * 2^(-logb(x)) < 2.

vFloat vlogbf (
   vFloat X
);

vlogf

For each vector element, calculates the natural logarithm of X.

vFloat vlogf (
   vFloat X
);

vnextafterf

For each vector element, calculates the next representable value after x in the direction of y. If x is equal to y, then y is returned.

vFloat vnextafterf (
   vFloat x,
   vFloat y
);

vnintf

Rounds to the nearest integer (nearest even for ties).

vFloat vnintf (
   vFloat A
);

vpowf

For each vector element, calculates X to the floating-point power of Y. The result is more accurate than using exp(log(X)*Y).

vFloat vpowf (
   vFloat X,
   vFloat Y
);

vrecf

Computes the reciprocal of values in a vector.

vFloat vrecf (
   vFloat A
);

vremainderf

For each vector element, calculates the remainder of X/Y, according to the IEEE 754 floating-point standard.

vFloat vremainderf (
   vFloat X,
   vFloat Y
);

vremquof

For each vector element, calculates the remainder of X/Y, according to the SANE standard. It stores into QUO the 7 low-order bits of the integer quotient, such that -127 <= QUO <= 127.

vFloat vremquof (
   vFloat X,
   vFloat Y,
   vUInt32 *QUO
);

vrsqrtf

For each vector element, calculates the inverse of the square root of X.

vFloat vrsqrtf (
   vFloat X
);

vscalbf

For each vector element, calculates x * 2^n efficiently. This is not normally done by computing 2^n explicitly.

vFloat vscalbf (
   vFloat X,
   vSInt32 n
);

vsignbitf

For each vector element, returns a non-zero value if and only if the sign of arg is negative. This includes NaNs, infinities and zeros.

vUInt32 vsignbitf (
   vFloat arg
);

vsincosf

Simultaneously computes sine and cosine of values in a vector.

vFloat vsincosf (
   vFloat arg,
   vFloat *sine_result
);

vsinf

For each vector element, calculates the sine.

vFloat vsinf (
   vFloat arg
);

vsinhf

For each vector element, calculates the hyperbolic sine of X.

vFloat vsinhf (
   vFloat X
);

vsqrtf

For each vector element, calculates the square root of X.

vFloat vsqrtf (
   vFloat X
);

vtablelookup

For each vector element of Index_Vect, returns the corresponding value from Table.

vUInt32 vtablelookup (
   vSInt32 Index_Vect,
   uint32_t *Table
);

vtanf

For each vector element, calculates the tangent.

vFloat vtanf (
   vFloat arg
);

vtanhf

For each vector element, calculates the hyperbolic tangent of X.

vFloat vtanhf (
   vFloat X
);

vvacos

For each double-precision array element, sets y to the arccosine of x.

void vvacos (
   double *,
   const double *,
   const int *
);

vvacosf

For each single-precision array element, sets y to the arccosine of x.

void vvacosf (
   float *,
   const float *,
   const int *
);

vvacosh

For each double-precision array element, sets y to the inverse hyperbolic cosine of x.

void vvacosh (
   double *,
   const double *,
   const int *
);

vvacoshf

For each single-precision array element, sets y to the inverse hyperbolic cosine of x.

void vvacoshf (
   float *,
   const float *,
   const int *
);

vvasin

For each double-precision array element, sets y to the arcsine of x.

void vvasin (
   double *,
   const double *,
   const int *
);

vvasinf

For each single-precision array element, sets y to the arcsine of x.

void vvasinf (
   float *,
   const float *,
   const int *
);

vvasinh

For each double-precision array element, sets y to the inverse hyperbolic sine of x.

void vvasinh (
   double *,
   const double *,
   const int *
);

vvasinhf

For each single-precision array element, sets y to the inverse hyperbolic sine of x.

void vvasinhf (
   float *,
   const float *,
   const int *
);

vvatan

For each double-precision array element, sets y to the arctangent of x.

void vvatan (
   double *,
   const double *,
   const int *
);

vvatan2

For each double-precision array element, sets z to the arctangent of y/x.

void vvatan2 (
   double *,
   const double *,
   const double *,
   const int *
);

vvatan2f

For each single-precision array element, sets z to the arctangent of y/x.

void vvatan2f (
   float *,
   const float *,
   const float *,
   const int *
);

vvatanf

For each single-precision array element, sets y to the arctangent of x.

void vvatanf (
   float *,
   const float *,
   const int *
);

vvatanh

For each double-precision array element, sets y to the inverse hyperbolic tangent of x.

void vvatanh (
   double *,
   const double *,
   const int *
);

vvatanhf

For each single-precision array element, sets y to the inverse hyperbolic tangent of x.

void vvatanhf (
   float *,
   const float *,
   const int *
);

vvceil

For each double-precision array element, sets y to the ceiling of x.

void vvceil (
   double *,
   const double *,
   const int *
);

vvceilf

For each single-precision array element, sets y to the ceiling of x.

void vvceilf (
   float *,
   const float *,
   const int *
);

vvcopysign

Copies an array, setting the sign of each value based on a second array.

void vvcopysign (
   double *,
   double *,
   const double *,
   const int *
);

vvcopysignf

Copies an array, setting the sign of each value based on a second array.

void vvcopysignf (
   float *,
   const float *,
   const float *,
   const int *
);

vvcos

For each double-precision array element, sets y to the cosine of x.

void vvcos (
   double *,
   const double *,
   const int *
);

vvcosf

For each single-precision array element, sets y to the cosine of x.

void vvcosf (
   float *,
   const float *,
   const int *
);

vvcosh

For each double-precision array element, sets y to the hyperbolic cosine of x.

void vvcosh (
   double *,
   const double *,
   const int *
);

vvcoshf

For each single-precision array element, sets y to the hyperbolic cosine of x.

void vvcoshf (
   float *,
   const float *,
   const int *
);

vvcosisin

For each double-precision array element, sets the real part of C to the sine of x and the imaginary part of C to the cosine of x.

void vvcosisin (
   __double_complex_t *,
   const double *,
   const int *
);

vvcosisinf

For each single-precision array element, sets the real part of C to the cosine of x and the imaginary part of C to the sine of x.

void vvcosisinf (
   __float_complex_t *,
   const float *,
   const int *
);

vvcospi

Sets each element y[i] to the sin(pi * x[i]) for i in 0..n-1.

void vvcospi (
   double *,
   const double *,
   const int *
);

vvcospif

Sets each element y[i] to the sin(pi * x[i]) for i in 0..n-1.

void vvcospif (
   float *,
   const float *,
   const int *
);

vvdiv

For each double-precision array element, sets z to y/x.

void vvdiv (
   double *,
   const double *,
   const double *,
   const int *
);

vvdivf

For each single-precision array element, sets z to y/x.

void vvdivf (
   float *,
   const float *,
   const float *,
   const int *
);

vvexp

For each double-precision array element, sets y to the exponential of x.

void vvexp (
   double *,
   const double *,
   const int *
);

vvexp2

Sets each element y[i] to 2 raised to (x[i]) for i in 0..n-1.

void vvexp2 (
   double *,
   const double *,
   const int *
);

vvexp2f

Sets each element y[i] to 2 raised to (x[i]) for i in 0..n-1.

void vvexp2f (
   float *,
   const float *,
   const int *
);

vvexpf

For each single-precision array element, sets y to the exponential of x.

void vvexpf (
   float *,
   const float *,
   const int *
);

vvexpm1

Returns (e^x)-1 for each element y[i].

void vvexpm1 (
   double *,
   const double *,
   const int *
);

vvexpm1f

Computes (e^x)-1 for each element in an array.

void vvexpm1f (
   float *,
   const float *,
   const int *
);

vvfabs

Sets each element y[i] to abs(x[i]-1) for i in 0..n-1.

void vvfabs (
   double *,
   const double *,
   const int *
);

vvfabsf

Sets each element y[i] to abs(x[i]-1) for i in 0..n-1.

void vvfabsf (
   float *,
   const float *,
   const int *
);

vvfloor

For each double-precision array element, sets y to the floor of x.

void vvfloor (
   double *,
   const double *,
   const int *
);

vvfloorf

For each single-precision array element, sets y to the floor of x.

void vvfloorf (
   float *,
   const float *,
   const int *
);

vvfmod

Sets each element y[i] to the floating point remainder of (y[i]/x[i]) for i in 0..n-1.

void vvfmod (
   double *,
   double *,
   const double *,
   const int *
);

vvfmodf

Computes the remainders after dividing values in a pair of arrays.

void vvfmodf (
   float *,
   const float *,
   const float *,
   const int *
);

vvint

For each double-precision array element, sets y to the integer truncation of x.

void vvint (
   double *,
   const double *,
   const int *
);

vvintf

For each single-precision array element, sets y to the integer truncation of x.

void vvintf (
   float *,
   const float *,
   const int *
);

vvlog

For each double-precision array element, sets y to the natural logarithm of x.

void vvlog (
   double *,
   const double *,
   const int *
);

vvlog10

For each double-precision array element, sets y to the base 10 logarithm of x.

void vvlog10 (
   double *,
   const double *,
   const int *
);

vvlog10f

For each single-precision array element, sets y to the base 10 logarithm of x.

void vvlog10f (
   float *,
   const float *,
   const int *
);

vvlog1p

Sets each element y[i] to log(1+x[i]) for i in 0..n-1.

void vvlog1p (
   double *,
   const double *,
   const int *
);

vvlog1pf

Computes the natural logarithm of a value plus 1.

void vvlog1pf (
   float *,
   const float *,
   const int *
);

vvlog2

Sets each element y[i] to the base-2 logarithm of x[i] for i in 0..n-1.

void vvlog2 (
   double *,
   const double *,
   const int *
);

vvlog2f

Sets each element y[i] to the base 2 logarithm of x[i] for i in 0..n-1.

void vvlog2f (
   float *,
   const float *,
   const int *
);

vvlogb

Sets each element y[i] to the exponent of x[i] for i in 0..n-1.

void vvlogb (
   double *,
   const double *,
   const int *
);

vvlogbf

Sets each element y[i] to the exponent of x[i] for i in 0..n-1.

void vvlogbf (
   float *,
   const float *,
   const int *
);

vvlogf

For each single-precision array element, sets y to the natural logarithm of x.

void vvlogf (
   float *,
   const float *,
   const int *
);

vvnextafter

Sets each element z[i] to the next machine-representable value from y[i] towards x[i] for i in 0..n-1.

void vvnextafter (
   double *,
   double *,
   const double *,
   const int *
);

vvnextafterf

Sets each element z[i] to the next machine-representable value from y[i] towards x[i] for i in 0..n-1.

void vvnextafterf (
   float *,
   const float *,
   const float *,
   const int *
);

vvnint

For each double-precision array element, sets y to the nearest integer to x.

void vvnint (
   double *,
   const double *,
   const int *
);

vvnintf

For each single-precision array element, sets y to the nearest integer to x.

void vvnintf (
   float *,
   const float *,
   const int *
);

vvpow

For each double-precision array element, sets z to x raised to the power of y.

void vvpow (
   double *,
   const double *,
   const double *,
   const int *
);

vvpowf

For each single-precision array element, sets z to x raised to the power of y.

void vvpowf (
   float *,
   const float *,
   const float *,
   const int *
);

vvrec

For each double-precision array element, sets y to the reciprocal of y.

void vvrec (
   double *,
   const double *,
   const int *
);

vvrecf

For each single-precision array element, sets y to the reciprocal of y.

void vvrecf (
   float *,
   const float *,
   const int *
);

vvremainder

Sets z[i] to the remainder relative to a round-to-even division of y[i]/x[i] for each i in 0..n-1.

void vvremainder (
   double *,
   double *,
   const double *,
   const int *
);

vvremainderf

Computes the remainder relative to a round-to-even division.

void vvremainderf (
   float *,
   const float *,
   const float *,
   const int *
);

vvrsqrt

For each double-precision array element, sets y to the reciprocal of the square root of x.

void vvrsqrt (
   double *,
   const double *,
   const int *
);

vvrsqrtf

For each single-precision array element, sets y to the reciprocal of the square root of x.

void vvrsqrtf (
   float *,
   const float *,
   const int *
);

vvsin

For each double-precision array element, sets y to the sine of x.

void vvsin (
   double *,
   const double *,
   const int *
);

vvsincos

For each double-precision array element, sets z to the sine of x and y to the cosine of x.

void vvsincos (
   double *,
   double *,
   const double *,
   const int *
);

vvsincosf

For each single-precision array element, sets z to the sine of x and y to the cosine of x.

void vvsincosf (
   float *,
   float *,
   const float *,
   const int *
);

vvsinf

For each single-precision array element, sets y to the sine of x.

void vvsinf (
   float *,
   const float *,
   const int *
);

vvsinh

For each double-precision array element, sets y to the hyperbolic sine of x.

void vvsinh (
   double *,
   const double *,
   const int *
);

vvsinhf

For each single-precision array element, sets y to the hyperbolic sine of x.

void vvsinhf (
   float *,
   const float *,
   const int *
);

vvsinpi

Sets y[i] to sin(pi * x[i]) for i in 0..n-1.

void vvsinpi (
   double *,
   const double *,
   const int *
);

vvsinpif

Sets y[i] to sin(pi * x[i]) for i in 0..n-1.

void vvsinpif (
   float *,
   const float *,
   const int *
);

vvsqrt

For each double-precision array element, sets y to the square root of x.

void vvsqrt (
   double *,
   const double *,
   const int *
);

vvsqrtf

For each single-precision array element, sets y to the square root of x.

void vvsqrtf (
   float *,
   const float *,
   const int *
);

vvtan

For each double-precision array element, sets y to the tangent of x.

void vvtan (
   double *,
   const double *,
   const int *
);

vvtanf

For each single-precision array element, sets y to the tangent of x.

void vvtanf (
   float *,
   const float *,
   const int *
);

vvtanh

For each double-precision array element, sets y to the hyperbolic tangent of x.

void vvtanh (
   double *,
   const double *,
   const int *
);

vvtanhf

For each single-precision array element, sets y to the hyperbolic tangent of x.

void vvtanhf (
   float *,
   const float *,
   const int *
);

vvtanpi

Sets y[i] to tan(pi * x[i]) for i in 0..n-1.

void vvtanpi (
   double *,
   const double *,
   const int *
);

vvtanpif

Sets y[i] to tan(pi * x[i]) for i in 0..n-1.

void vvtanpif (
   float *,
   const float *,
   const int *
);

Data Types

All data structures passed to vecLib must be naturally aligned. For example, a 32-bit floating-point value must be aligned to a four-byte boundary. Many routines in vecLib generate exceptions on unaligned data.

vUInt8

A 128-bit vector packed with unsigned char values.

typedef vector unsigned char vUInt8;

vSInt8

A 128-bit vector packed with signed char values.

typedef vector signed char vSInt8;

vUInt16

A 128-bit vector packed with unsigned short values.

typedef vector unsigned short vUInt16;

vSInt16

A 128-bit vector packed with signed short values.

typedef vector signed short vSInt16;

vUInt32

A 128-bit vector packed with unsigned int values.

typedef vector unsigned int vUInt32;

vSInt32

A 128-bit vector packed with signed int values.

typedef vector signed int vSInt32;

vFloat

A 128-bit vector packed with float values.

typedef vector float vFloat;

vDouble

A 128-bit vector packed with double values.

typedef double vDouble         __attribute__((__vector_size__ (16)));

vBool32

A 128-bit vector packed with bool int values.

typedef vector bool int vBool32;

__float_complex_t

A single-precision complex number type.

typedef complex float __float_complex_t;

__double_complex_t

A double-precision complex number type.

typedef complex double __double_complex_t;